reverse-engineer-rpi

/reverse-engineer-rpi

製品をリバースエンジニアリングし、機械的に検証可能な機能インベントリ、レジストリ、仕様セットを作成します。オプションでセキュリティ監査の成果物や検証ゲートも作成できます。

厳格なガードレール（必須）

• 所有しているコード／バイナリ、または分析について明示的な書面による許可を得ているコード／バイナリのみを対象にしてください。
• 保護機能や利用規約を回避する手順、またはサードパーティ製品からプロプライエタリなソースコード／システムプロンプトを抽出する手順は提供しないでください。
• バイナリから再構成したプロプライエタリなソースコードや埋め込みプロンプトを出力しないでください（インデックスのみを作成し、レポートでは編集して伏せてください）。
• 秘密情報／トークン／キーが見つかった場合は伏せてください。出力に対して秘密情報スキャンのゲートを実行してください。
• 常に「ドキュメントに記載」「コードで確認」「ホスト型／コントロールプレーン」を区別してください。

1 コマンドの例

python3 skills/reverse-engineer-rpi/scripts/reverse_engineer_rpi.py ao \
  --authorized \
  --mode=binary \
  --binary-path="$(command -v ao)" \
  --output-dir=".agents/research/ao/"

そのバイナリを分析する明示的な書面による許可がない場合は、上記を実行しないでください。代わりに、同梱のデモ用フィクスチャを使用してください（下記のセルフテストを参照）。

リポジトリのみの例（バイナリは不要）：

python3 skills/reverse-engineer-rpi/scripts/reverse_engineer_rpi.py cc-sdd \
  --mode=repo \
  --upstream-repo="https://github.com/gotalab/cc-sdd.git" \
  --output-dir=".agents/research/cc-sdd/"

ピン留めしたクローン（再現可能）：

python3 skills/reverse-engineer-rpi/scripts/reverse_engineer_rpi.py cc-sdd \
  --mode=repo \
  --upstream-repo="https://github.com/gotalab/cc-sdd.git" \
  --upstream-ref=v1.0.0 \
  --output-dir=".agents/research/cc-sdd/"

呼び出し契約

必須：

• product_name

オプション：

• --docs-sitemap-url（利用可能な場合は推奨。https://... と file:///... に対応）
• --docs-features-prefix（デフォルト：auto。最適なローカルドキュメントのプレフィックスを検出し、見つからない場合は docs/features/ を使用）
• --upstream-repo（オプション）
• --upstream-ref（特定のコミット、タグ、またはブランチにクローンをピン留めします。解決された SHA は clone-metadata.json に記録されます）
• --local-clone-dir（デフォルト：.tmp/<product_name>）
• --output-dir（デフォルト：.agents/research/<product_name>/）
• --mode（デフォルト：repo。指定可能な値：repo|binary|both）
• --binary-path（--mode に binary が含まれる場合は必須）
• --no-materialize-archives（許可された場合のみ。バイナリモードではデフォルトで埋め込み ZIP を展開します。このオプションを指定すると展開を無効にし、インデックスのみを保持します）

セキュリティ監査フラグ（オプション）：

• --security-audit（セキュリティ成果物とゲートを有効にします）
• --sbom（可能な場合は SBOM と依存関係リスクレポートを生成します。注記を出して何も行わない場合があります）
• --fuzz（安全なハーネスが存在する場合のみ。時間制限あり）

必須のガードレールフラグ：

• --authorized（バイナリモードで必須。指定しない場合はバイナリ分析の実行を拒否します）

上流リファレンスのピン留め（--upstream-ref）

--upstream-ref を使用して、リポジトリモードのクローンを特定のコミット、タグ、またはブランチにピン留めします。これにより分析の再現性が確保され、既知のベースラインに対してゴールデンフィクスチャを差分比較できます。

# Pin to a tag (reproducible)
python3 skills/reverse-engineer-rpi/scripts/reverse_engineer_rpi.py cc-sdd \
  --mode=repo \
  --upstream-repo="https://github.com/gotalab/cc-sdd.git" \
  --upstream-ref=v1.0.0 \
  --output-dir=".agents/research/cc-sdd/"

# Pin to a specific commit SHA
python3 skills/reverse-engineer-rpi/scripts/reverse_engineer_rpi.py cc-sdd \
  --mode=repo \
  --upstream-repo="https://github.com/gotalab/cc-sdd.git" \
  --upstream-ref=abc1234 \
  --output-dir=".agents/research/cc-sdd/"

--upstream-ref を指定した場合：

• git fetch --depth=1 origin <ref> でフェッチし、FETCH_HEAD をチェックアウトします。
• トレーサビリティのため、解決されたコミット SHA が output_dir/clone-metadata.json に記録されます。
• --upstream-ref を指定しない場合は、デフォルトブランチの HEAD を --depth=1 でシャロークローンします。

clone-metadata.json のスキーマ：

{
  "upstream_repo": "https://github.com/gotalab/cc-sdd.git",
  "upstream_ref": "v1.0.0",
  "resolved_commit": "<full SHA>",
  "clone_date": "YYYY-MM-DD"
}

契約出力（output_dir/）

リポジトリモードの分析では、output_dir/ 以下に機械検証可能な契約ファイルが書き込まれます。これらのファイルでは相対パスのみを使用し、リストはソートされ、キーは安定しているため、ゴールデンフィクスチャとしてコミットし、実行間で差分比較できます。絶対パスや実行ごとに異なるタイムスタンプは含まれません。

主要な契約ファイル：

ファイル	説明
feature-registry.yaml	CLI、設定／環境変数、成果物のサーフェスを機械的に抽出した、構造化された機能インベントリ
cli-surface-contracts.txt	CLI のサーフェス：コマンド、フラグ、ヘルプテキスト、フレームワーク、言語
docs-features.txt	ドキュメントから抽出した機能（ドキュメントに記載されている内容とコードで確認できる内容）
clone-metadata.json	上流リポジトリの URL、ピン留めしたリファレンス、解決されたコミット SHA、クローン日時

feature-registry.yaml の構造例：

schema_version: 1
product_name: cc-sdd
upstream_commit: "abc1234..."
features:
  - name: cli-entry
    cli:
      language: node
      bin:
        cc-sdd: dist/cli.js
      help_text: "Usage: cc-sdd [options] ..."
  - name: config-surface
    config_env:
      config_file: ".cc-sdd/config.json"
      env_vars:
        - name: CC_SDD_TOKEN
          evidence: ["src/config.ts"]

注：契約出力は --mode=repo（または --mode=both）で書き込まれます。バイナリモードの出力（binary-analysis.md、binary-symbols.txt など）は、引き続き output_dir/ 直下に保存されます。

フィクスチャテストのワークフロー

ゴールデンフィクスチャを使うと、回帰を検出できます。既知の正常なフィクスチャスナップショット（契約ファイルとピン留めした clone-metadata.json）をコミットし、以降の実行結果との差分を比較します。

フィクスチャーテストの実行

bash skills/reverse-engineer-rpi/scripts/repo_fixture_test.sh

このスクリプト（ag-w77.3 で実装されています）は、次の処理を行います。

1. skills/reverse-engineer-rpi/fixtures/cc-sdd-v2.1.0/clone-metadata.json を読み込み、固定された上流リファレンスを特定します。
2. そのリファレンスを指定して、リポジトリモードで reverse_engineer_rpi.py を実行し、一時出力ディレクトリに出力します。
3. 生成された出力を、コミット済みのゴールデンフィクスチャー（feature-registry.yaml、cli-surface-contracts.txt、docs-features.txt）と比較します。
4. 一致する場合は 0 で終了し、差異がある場合は統合差分を表示して 0 以外で終了します。

テストでは、上流リポジトリのクローンにネットワークアクセスが必要です。

フィクスチャーの更新

契約に正当な変更があった場合（新しいフラグや環境変数、スキーマのバージョンアップなど）は、ゴールデンフィクスチャーを更新します。

# 1. Re-run with the pinned ref to generate fresh contracts
python3 skills/reverse-engineer-rpi/scripts/reverse_engineer_rpi.py cc-sdd \
  --mode=repo \
  --upstream-repo="https://github.com/gotalab/cc-sdd.git" \
  --upstream-ref=<new-tag-or-sha> \
  --output-dir=".tmp/cc-sdd-refresh/"

# 2. Copy contracts into the fixture directory
cp .tmp/cc-sdd-refresh/feature-registry.yaml \
  skills/reverse-engineer-rpi/fixtures/cc-sdd-v2.1.0/feature-registry.yaml

# 3. Update the pinned clone metadata
cp .tmp/cc-sdd-refresh/clone-metadata.json \
  skills/reverse-engineer-rpi/fixtures/cc-sdd-v2.1.0/clone-metadata.json

# 4. Commit the updated fixtures
git add skills/reverse-engineer-rpi/fixtures/cc-sdd-v2.1.0/
git commit -m "fix(reverse-engineer-rpi): update cc-sdd golden fixtures to <new-tag-or-sha>"

テストに合格するには、次のフィクスチャーファイルをコミットする必要があります。

• skills/reverse-engineer-rpi/fixtures/cc-sdd-v2.1.0/clone-metadata.json
• skills/reverse-engineer-rpi/fixtures/cc-sdd-v2.1.0/feature-registry.yaml
• skills/reverse-engineer-rpi/fixtures/cc-sdd-v2.1.0/cli-surface-contracts.txt
• skills/reverse-engineer-rpi/fixtures/cc-sdd-v2.1.0/docs-features.txt

スクリプト駆動のワークフロー

実行します。

python3 skills/reverse-engineer-rpi/scripts/reverse_engineer_rpi.py <product_name> --authorized [flags...]

これにより、必要な出力が output_dir/ 以下に生成され、該当する場合は .agents/council/ および .agents/learnings/ にも生成されます。

出力（必ず生成すること）

output_dir/ 以下のコア出力：

1. feature-inventory.md
2. feature-registry.yaml
3. validate-feature-registry.py
4. feature-catalog.md
5. spec-architecture.md
6. spec-code-map.md
7. spec-cli-surface.md（Node、Python、または Go の CLI が検出された場合。検出されない場合は spec-code-map.md に注記が記載されます）
8. spec-clone-vs-use.md
9. spec-clone-mvp.md（元の MVP 仕様。対象からコピーしないでください）
10. clone-metadata.json（--upstream-repo を使用した場合。解決済みのコミット SHA を記録します）

バイナリモードの追加出力：

• binary-analysis.md（ベストエフォートの概要）
• binary-embedded-archives.md（インデックスのみ。ダンプは作成しません）

リポジトリモードの追加出力：

• spec-artifact-surface.md（ベストエフォート。テンプレート／マニフェストに基づくインストール対象）
• artifact-registry.json（ベストエフォート。マニフェストまたはテンプレートが存在する場合に、ハッシュ付きのテンプレート一覧を作成します）

--security-audit を指定した場合は、output_dir/security/ も作成します。

• threat-model.md
• attack-surface.md
• dataflow.md
• crypto-review.md
• authn-authz.md
• findings.md
• reproducibility.md
• validate-security-audit.sh

セルフテスト（受け入れ基準）

エンドツーエンドのフィクスチャー（埋め込み ZIP を含む、安全で自分が所有するデモバイナリ）：

bash skills/reverse-engineer-rpi/scripts/self_test.sh

次の結果を確認できる必要があります。

• フィーチャーインベントリが生成される
• レジストリが生成される
• レジストリバリデーターが 0 で終了する
• セキュリティモードでは、validate-security-audit.sh が 0 で終了し、シークレットスキャンに合格する

例

シナリオ：リポジトリモードでオープンソース CLI をリバースエンジニアリングする

ユーザーの入力： /reverse-engineer-rpi cc-sdd --mode=repo --upstream-repo="https://github.com/gotalab/cc-sdd.git" --upstream-ref=v1.0.0

実行内容：

1. スクリプトは、固定されたタグ v1.0.0 で上流リポジトリを浅くクローンし、解決済みの SHA を clone-metadata.json に記録します。
2. リポジトリ内の CLI エントリーポイント、設定／環境変数の対象範囲、スキーマファイル、アーティファクトマニフェストをスキャンし、出力ディレクトリに feature-inventory.md、feature-registry.yaml、契約 JSON、およびすべての仕様ファイルを書き込みます。

結果： 完全なフィーチャーカタログと、機械的に検証可能な feature-registry.yaml が .agents/research/cc-sdd/ 以下に生成され、ゴールデンフィクスチャーとの差分比較ができる状態になります。

シナリオ: セキュリティ監査を伴うバイナリ分析

ユーザーが入力する内容: /reverse-engineer-rpi ao --authorized --mode=binary --binary-path="$(command -v ao)" --security-audit

何が起こるか:

1. スクリプトは ao バイナリに対して静的解析（ファイルメタデータ、リンクされたライブラリ、埋め込みアーカイブのシグネチャ）を実行し、binary-analysis.md と binary-embedded-archives.md を書き出します。
2. output_dir/security/ 配下に完全なセキュリティ監査スイート（threat-model.md、attack-surface.md、findings.md など）を生成し、すべての出力に対してシークレットスキャンゲートを実行します。

結果: バイナリ分析の成果物に加えて、検証済みのセキュリティ監査が生成されます。validate-security-audit.sh が終了コード 0 で終了し、すべてのセキュリティ成果物が存在し、シークレットが含まれていないことが確認されます。

トラブルシューティング

問題	原因	解決策
スクリプトがバイナリ分析の実行を拒否する	--authorized フラグが指定されていない	バイナリを分析するための明示的な書面による許可があることを確認するために、--authorized を追加してください。
clone-metadata.json が生成されない	--upstream-repo が指定されていない	クローンメタデータの追跡を有効にするために、--upstream-repo（および任意で --upstream-ref）を渡してください。
フィクスチャテストの差分が予期せず失敗する	上流リポジトリが変更された、またはゴールデンフィクスチャが古くなっている	固定された ref で再実行し、新しいコントラクトを fixtures/ にコピーして、更新されたゴールデンファイルをコミットしてください（フィクスチャの更新を参照）。
spec-cli-surface.md が生成されない	リポジトリ内に認識可能な CLI フレームワーク（Node/Python/Go）が検出されなかった	対象リポジトリに発見可能な CLI エントリポイントがあることを確認してください。そうでない場合、CLI サーフェスは代わりに spec-code-map.md に文書化されます。
リポジトリのクローン中にネットワークエラーが発生する	ファイアウォール、VPN、または GitHub のレート制限がシャロークローンをブロックしている	ネットワーク接続を確認し、リポジトリがプライベートの場合は gh auth login で認証するか、--local-clone-dir を使用してクローン済みのディレクトリを指定してください。

参照ドキュメント

• references/reverse-engineer-rpi.feature — 実行可能な仕様: リポジトリモードの機能カタログ + コードマップ、バイナリモードのセキュリティ監査、永続的な仕様成果物（soc-qk4b）