または、自分でvenvを管理したくない場合は、`pipx run` で実行してください。PEP-668の強制がない古いシステムでは、単純に `python3 sparkplug-fuzzer.py --setup` が直接動作します。

`--setup` は以下の処理を行います：
1. pip依存関係をインストールします (`paho-mqtt`, `protobuf`)
2. 特定のタグで固定された [Eclipse Tahu](https://github.com/eclipse/tahu) リポジトリをクローンします（スクリプト内の `TAHU_REF` を参照）
3. ヘルパーモジュール `sparkplug_b.py` と `array_packer.py` をコピーします
4. `sparkplug_b.proto` をPythonバインディングにコンパイルします（利用可能な場合は `protoc` を使用し、それ以外は `grpcio-tools` にフォールバック）
5. Tahuのクローンをクリーンアップします

セットアップ後、ディレクトリには次のものが含まれているはずです：```
sparkplug-fuzzer.py     # The fuzzer
sparkplug_b.py          # Sparkplug B helper module (from Tahu)
array_packer.py         # Array packing helper (from Tahu)
sparkplug_b_pb2.py      # Generated protobuf bindings
requirements.txt        # Python dependencies

これは以下のことを行います:

1. `localhost:1883` のブローカーに接続
2. 10秒間待機して既存のSparkplugデバイスを検出
3. ファザーをSparkplugノード/デバイスとして確立
4. 12のファズカテゴリ（約635以上のテストケース）を実行
5. 発見されたデバイスをスプーフィングされたメッセージで標的に
6. 結果を `sparkplug_fuzz.jsonl` に書き込み

## 使用方法

### コマンドラインオプション```
python3 sparkplug-fuzzer.py [OPTIONS]

**`ps`内で認証情報を露出させずに渡す:**```bash
# Via environment
MQTT_USERNAME=admin MQTT_PASSWORD=secret python3 sparkplug-fuzzer.py -H broker.local

# Or read password from stdin (getpass — no echo)
python3 sparkplug-fuzzer.py -H broker.local -u admin -P -

**パッシブ認証評価 + アクティブ書き込みプローブ:**```bash
python3 sparkplug-fuzzer.py -H 10.0.1.30 --probe-anon-write -v

**低速ペーシングによる拡張ディスカバリー（ブローカ負荷最小化）：**```bash
python3 sparkplug-fuzzer.py -H 192.168.1.100 --discovery-time 60 --delay 0.5

**別のターミナルでブローカのトラフィックを監視:**```bash
mosquitto_sub -h <broker_host> -p 1883 -t 'spBv1.0/#' -F '%I %t %x'

**実行ごとの出力レイアウト:**```bash
# Default — directory is auto-named under ./sparkplug-runs/
python3 sparkplug-fuzzer.py -H broker.local
# -> creates ./sparkplug-runs/2026-05-05_1830_broker.local/sparkplug_fuzz.jsonl

# Explicit directory:
python3 sparkplug-fuzzer.py -H broker.local --output-dir ./fuzz-runs/acme-2026Q2

ファザーは起動時に `[+] Extra string payloads: loaded N from <path>` を出力し、各ペイロードは `STRING_FUZZ_VALUES` を反復するすべての場所（主に `string` カテゴリ、ただし型不一致ジェネレータの文字列型ケースも含む）を通じて送出されます。

ハード制限: ファイルサイズ10 MB、ペイロード数10,000。もっと必要で（実行時間の予算が合うなら）、スクリプト先頭の `MAX_EXTRA_PAYLOADS_FILE_SIZE` / `MAX_EXTRA_PAYLOADS_COUNT` を調整してください。

## v0.2 リリースノート

- `--output-dir` フラグと自動生成されるデフォルト `./sparkplug-runs/<UTC-ts>_<host>/` — 各実行は独自のディレクトリに配置されるため、成果物が実行間で衝突しません。
- `--setup` 用の `--tahu-path` フラグ — 外部への `git clone` がブロックされているエアギャップテスト環境向けに、`eclipse/tahu` のローカルクローンを指定します。ローカルソースはクリーンアップ時に削除されません。
- コンソールおよび JSONL のタイムスタンプは強制的に UTC とし、明示的な `Z` サフィックスを付与することで、ブローカーログとの相互相関がタイムゾーン計算不要になります。
- `paho.mqtt` ロガーはデフォルトで WARNING に抑制。`-v` で INFO、`-vv` で DEBUG で表示されます。パケットごとのクライアントテレメトリがファズ信号を埋もれさせなくなりました。
- `tests/` 下の pytest テストハーネス — FuzzLogger、トピックヘルパー、出力パス解決、`--tahu-path` 検証をカバーする23のテスト。[テストの実行](#running-the-tests) を参照。

## テストの実行

テストハーネスはネットワークに依存しない表面（ロガーの正確性、トピックビルダー、出力パス解決、`--tahu-path` 解析）をカバーし、ブローカー、paho-mqtt、protobuf がインストールされていなくても実行できます。```bash
pip install -r requirements-dev.txt
pytest tests/

### Network Discovery

発見フェーズでは、ファザーは`spBv1.0/#`にサブスクライブし、すべてのSparkplugトラフィックをリッスンします。`DeviceTracker`コンポーネントは、観測されたメッセージを解析してライブネットワークマップを構築します：

- **NBIRTH** メッセージはエッジノードとそのメトリック定義（名前、エイリアス、データ型）を明らかにします。
- **DBIRTH** メッセージはデバイスとそのメトリックスキーマを明らかにします。
- **NDEATH/DDEATH** メッセージはノード/デバイスのライフサイクル状態を追跡します。
- **STATE** メッセージはホストアプリケーションとそのオンライン/オフラインステータスを明らかにします。

このマップは、ターゲットファジングフェーズで使用され、実際のメトリックスキーマを持つ実際のデバイスに対してコンテキストに関連した攻撃を送信します。

### Authentication Assessment

ファザーが`-u/-P`なしで接続し（かつ`MQTT_USERNAME`/`MQTT_PASSWORD`が設定されていない場合）、パッシブディスカバリのみからブローカーの認証状態を推定します。これにより、ログに1つの`AUTH_ASSESSMENT`イベントが生成され、以下の要約が出力されます：

| Signal | 意味 | 導出方法 |
|---|---|---|
| `anon_connect_accepted` | ブローカーが認証情報なしでCONNECTを受け入れた | ファザー自身のCONNECTが成功 |
| `anon_subscribe_accepted` | ブローカーが匿名クライアントに`spBv1.0/#` / `STATE/#`を転送する | リスンウィンドウ中に少なくとも1つのRXメッセージが到着 |
| `anon_publish_accepted` | ブローカーが匿名クライアントからのPUBLISHを受け入れる | `--probe-anon-write`が渡された場合のみ設定; QoS=1プローブ + PUBACK待機 |
| `unauth_endpoints` | 認証なしで観測可能なノード/デバイス/ホストアプリケーション | 発見されたネットワークマップ内のすべてのエンティティ（認証は生成されなかった） |

QoS=1プローブはオプトインです。なぜなら、パッシブからアクティブに移行するからです。QoS=0では、ブローカーは拒否するメッセージを黙ってドロップするため、書き込み受け入れを確認するにはPUBACKを読み取る必要があります。

MQTT/Sparkplugにはエンドポイントごとの認証はありません。認証はブローカーレベルの問題です。したがって、「認証なしで観測可能なエンドポイント」は、エンドポイント自体のプロパティとしてではなく、*コストゼロで到達可能なターゲット*のリストとして報告されます。

### Targeted Fuzzing

体系的なファジングの後、ツールは発見された各デバイスを次の方法でターゲットにします：

1. **偽装された死亡通知** — NDEATH/DDEATHを公開し、サブスクライバーにデバイスがオフラインになったと思わせる
2. **偽装された誕生証明書** — NBIRTH/DBIRTHを公開し、発見されたノード/デバイスになりすます
3. **コマンドインジェクション** — 既知の各メトリックに対して境界値を持つNCMD/DCMDメッセージを送信し、ターゲットが受信コマンドを検証するかテストする
4. **再誕生コマンド** — `Node Control/Rebirth` NCMDを送信し、デバイスに誕生メッセージを再公開させる

## Output and Log Analysis

### Log Format

ログファイルはJSON-lines形式（`.jsonl`）を使用します — 1行に1つのJSONオブジェクトで、`jq`、Python、その他のJSON対応ツールでの分析に適しています。

64 KiBを超えるペイロードは16進数インライン化されません。代わりに`payload_hex`は`sha256:<digest>+len=<n>`を保持するため、非常に大きなファズケースでもログは制限されたままです。`payload_len`は常に存在します。

**TXレコード**（送信ファズメッセージ）：```json
{
  "ts": "2026-04-10T15:30:00.123456Z",
  "dir": "TX",
  "case_id": "BOUNDARY-0042",
  "category": "boundary",
  "topic": "spBv1.0/Sparkplug B Devices/DDATA/FuzzNode/FuzzDevice",
  "payload_hex": "0800120a0a06...",
  "payload_len": 28,
  "payload_decoded": {"timestamp": 1712345678000, "metrics": [{"name": "fuzz/boundary/Int32", "datatype": 3, "int_value": 2147483647}]},
  "description": "Boundary Int32 = 2147483647 (int_value)"
}

**イベントレコード** (システムイベント):```json
{
  "ts": "2026-04-10T15:29:50.000000Z",
  "dir": "EVENT",
  "event": "DISCOVERY_COMPLETE",
  "details": {"groups": ["Production"], "node_count": 3, "device_count": 7, "targets": 10}
}

**すべての文字列インジェクションケースを抽出する:**```bash
jq 'select(.category == "string")' sparkplug_fuzz.jsonl

**ブローカー切断を引き起こしたケースを見つける:**```bash
jq 'select(.event == "UNEXPECTED_DISCONNECT" or .event == "RECONNECT_FAIL")' sparkplug_fuzz.jsonl

**認証なしで到達可能なエンドポイントを一覧表示：**```bash
jq -r 'select(.event == "AUTH_ASSESSMENT") | .details.unauth_endpoints[] | [.kind, .group, .node, .device, .host_id, .status] | @tsv' sparkplug_fuzz.jsonl

**公開されたすべてのトピックをエクスポート先:**```bash
jq -r 'select(.dir == "TX") | .topic' sparkplug_fuzz.jsonl | sort -u

## プロトコルカバレッジ

### メッセージタイプ

全9種類のSparkplug Bメッセージタイプがテストされています：

| メッセージタイプ | トピックパターン | 説明 | ファザーの使用目的 |
|---|---|---|---|
| NBIRTH | `spBv1.0/{group}/NBIRTH/{node}` | ノード誕生証明書 | ファザーの存在を確立；発見されたノードに対して偽装；順序テスト |
| NDEATH | `spBv1.0/{group}/NDEATH/{node}` | ノード死亡通知 | MQTT遺言；発見されたノードに対して偽装；順序テスト |
| DBIRTH | `spBv1.0/{group}/DBIRTH/{node}/{device}` | デバイス誕生証明書 | ファザーのデバイスを確立；発見されたデバイスに対して偽装；順序テスト |
| DDEATH | `spBv1.0/{group}/DDEATH/{node}/{device}` | デバイス死亡通知 | 発見されたデバイスに対して偽装；順序テスト；孤立テスト |
| NDATA | `spBv1.0/{group}/NDATA/{node}` | ノードデータ更新 | 境界値；シーケンス番号；順序テスト |
| DDATA | `spBv1.0/{group}/DDATA/{node}/{device}` | デバイスデータ更新 | ほとんどのファズカテゴリの主要な手段 |
| NCMD | `spBv1.0/{group}/NCMD/{node}` | ノードコマンド | 標的型ファジング（再誕コマンド）；孤立テスト |
| DCMD | `spBv1.0/{group}/DCMD/{node}/{device}` | デバイスコマンド | 発見されたデバイスのメトリクスに対する標的型ファジング；孤立テスト |
| STATE | `STATE/{host_id}` | ホストアプリケーション状態（JSON） | 不正なJSONインジェクション |

### データタイプ

全19種類のSparkplug Bメトリックデータタイプがタイプ固有の境界値でテストされています：

| コード | タイプ | Protobufフィールド | テストされた境界値 |
|------|------|---------------|----------------------|
| 1 | Int8 | int_value | 0, -128, 127, 128（オーバーフロー）, -129（アンダーフロー） |
| 2 | Int16 | int_value | 0, -32768, 32767, オーバーフロー/アンダーフロー |
| 3 | Int32 | int_value | 0, -2^31, 2^31-1, オーバーフロー/アンダーフロー |
| 4 | Int64 | long_value | 0, -2^63, 2^63-1, オーバーフロー |
| 5 | UInt8 | int_value | 0, 255, 256, -1 |
| 6 | UInt16 | int_value | 0, 65535, 65536, -1 |
| 7 | UInt32 | int_value | 0, 4294967295, -1 |
| 8 | UInt64 | long_value | 0, 2^64-1, -1 |
| 9 | Float | float_value | 0.0, -0.0, 最大値, 最小値, inf, -inf, NaN |
| 10 | Double | double_value | 0.0, -0.0, 最大値, 最小値, inf, -inf, NaN |
| 11 | Boolean | boolean_value | True, False；さらに生の整数値（0, 1, 2, 255）でもテスト |
| 12 | String | string_value | 空文字、長文（最大64KB）、インジェクションペイロード |
| 13 | DateTime | long_value | エポック、最大値、遠い未来/過去 |
| 14 | Text | string_value | Stringと同じインジェクションペイロード |
| 15 | UUID | string_value | 空文字、有効、無効な形式、インジェクション |
| 16 | DataSet | dataset_value | データセットカテゴリによる構造違反 |
| 17 | Bytes | bytes_value | 空、ヌルバイト、ランダム、大規模 |
| 18 | File | bytes_value | 空、マジックバイト、大規模 |
| 19 | Template | template_value | 未定義の参照、孤立テンプレート |

### フィールドカバレッジ

ファザーは87以上のユニークなProtobufフィールドパスをカバーしています：

- **ペイロードルートフィールド**: timestamp, seq, uuid, body, metrics
- **メトリックフィールド**: name, alias, timestamp, datatype, is_historical, is_transient, is_null, metadata, properties、およびすべてのvalue oneofバリアント
- **メタデータフィールド**: is_multi_part, content_type, size, seq, file_name, file_type, md5, description
- **PropertySet/PropertyValue**: keys, values, type, is_null, recursive propertyset_value, propertysets_value
- **DataSet**: num_of_columns, columns, types, rows, elements、すべてのDataSetValueバリアント
- **Template**: version, template_ref, is_definition, nested metrics, parameters

## アーキテクチャ

ファザーは単一のPythonファイルで構成され、以下のコンポーネントに整理されています：```
sparkplug-fuzzer.py
    |
    +-- Constants / ALL_METRIC_TYPES / STRING_FUZZ_VALUES
    |       Type definitions and fuzz value tables
    |
    +-- FuzzLogger
    |       JSON-lines file logging + console output
    |       Protobuf payload decoding
    |
    +-- DeviceTracker
    |       Passive network discovery
    |       Tracks groups, nodes, devices, metrics
    |
    +-- PayloadBuilder
    |       Valid payload construction (sparkplug_b helpers)
    |       Raw payload construction (sparkplug_b_pb2 direct)
    |       Binary corruption (truncate, flip, append)
    |
    +-- 12 Fuzz Generators
    |       Each is a Python generator yielding (topic, bytes, desc)
    |       Covers boundary, string, type, seq, timestamp, alias,
    |       orphan, ordering, recursive, dataset, malformed, topic
    |
    +-- SparkplugFuzzer
    |       Orchestration: connect, discover, fuzz, target, report
    |       Centralized publish with logging
    |       Auto-reconnect on disconnect
    |
    +-- CLI (argparse) + main()
            Argument parsing and entry point