discover-attack-surface

スキル：攻撃対象領域の特定

プロジェクトで使用されている依存関係メンバーの割り当てられた一部分を調査し、その中から汚染源、つまり信頼できないデータが最初に入るメソッドを選び出します。以下のワークフローで使用する具体的な調査コマンドと識別子の形式は、割り当てられた言語のリファレンスで定義されています。

入力

呼び出し元から提供されます。省略された場合はデフォルト値を使用します。必須の入力が不足しており、妥当なデフォルト値もない場合に限り、確認を求めてください。

• project-root（任意） — 対象プロジェクトのルート。Opentaint はすべての解析成果物を固定の <project-root>/.opentaint/ ディレクトリ配下に保持するため、以下の .opentaint/... パスはすべてその場所を指します。デフォルト：現在のディレクトリ
• language（必須） — このプロジェクトの対象言語と言語固有の指示
• plan（必須） — このエージェントの分割計画 .opentaint/tracking/rules/plans/<id>.yaml のパス。分類対象となる、プロジェクトで使用されている依存関係メンバーが記載されています。

ワークフロー

作業を始める前に references/<language>.md を読みます。番号付きの手順に、以下のワークフローに関する言語固有の詳細が記載されています。

1. 計画に含まれるメンバーを調査する

割り当てられた計画の scopes には、抽出済みで、まだ判定が必要なプロジェクト使用の依存関係メンバーが含まれています。それらのメンバーのみを調査します。依存関係の識別情報と正確なシグネチャを確認してから、アプリケーションのソースコード、依存関係のソースコードと API ドキュメント、代表的な使用例、関連するフレームワーク設定を読み、データがプロジェクトに入る経路を把握します。

2. 計画に含まれるメンバーを分類する

ソースとは、ネットワーク、永続化、シリアライズ、メッセージング、実行、またはその他の外部チャネルから信頼できないデータが最初に入る、正確な境界です。呼び出し可能なメンバーについては、攻撃者が制御するデータを返すか、別の形で公開するかを判断します。渡されたデータを単に中継するメンバーは、プロパゲーターであり、ソースではありません。

パッケージ名やクラス名ではなく、動作に基づいて分類します。個々のメンバーについて判断が難しいソースは、不確実性を記録したうえでソースとして扱うことを優先してください。後のスキャンとトリアージで誤検出を除外できますが、記録されなかったソースによる偽陰性は取り返せません。

3. 判定とソースユニットを記録する

言語リファレンスで指定された形式で、計画のソースリストを完成させます。発見したソースはすべて計画に記録し、tag: untrusted-data-source を付けてソースユニットを作成します。そのユニットを既存または新規のルールに対応付ける作業は、後の create-rule で行います。ソースではないメンバーのユニットは作成しません。結果が空の場合は、エージェントから応答がなかった計画と区別できるよう、空であることを明示します。所有するユニットがすでに存在する場合は、新しいエントリを追加し、既存のエントリやステージを書き換えないでください。

4. 返却前に検証する

割り当てられた範囲全体を再確認し、分類を検証します。却下したメンバーをすべて読み直し、外部入力境界を形成していないことを確かめます。すべてのソースが完成済みの計画とそのソースユニットの両方に記載されていること、却下したメンバーにユニットが作成されていないこと、保留または null の判定が残っていないことを確認します。

出力

実施内容を簡潔に報告します。

成果物：

• .opentaint/tracking/rules/sources/<unit>.yaml — 完成済みの計画で必要となる各ソースユニット
• 発見したソースを source の下に記録した、割り当て済みの計画

概要：

• 発見したソースメンバーを1行に1つずつ記載
• 作業を妨げた事項、または不確実なまま残った事項

トラッキング

.opentaint/tracking/rules/sources/<package-kebab>.yaml — パッケージごとに1つのソース単位（依存関係が複数のパッケージにまたがる場合があります）。ファイル名はそのパッケージ名の . を - に置き換えたものです。tag は常に再利用可能な untrusted-data-source グループです。dependencies にはそのパッケージの由来となる依存関係を記載し、sources には各エントリポイントを { method, signature, note, rule_id } として記載します（method と signature には計画にある言語固有の識別子をそのまま使います）。stages ではルール作成における単位の進捗を追跡し、単位をパスさせられない場合は、その下に blocker 文字列を追加します。コメントからも明確に分かるようにしてください

dependencies:
  - <dependency-id>
tag: untrusted-data-source
sources:
  - { method: "<qualified-member>", signature: "<language-signature>", note: untrusted message payload, rule_id: null }
stages:
  test_project: pending
  tests_passing: pending

このスキルでは tag: untrusted-data-source を設定し、dependencies を埋め、ソースごとに { method, signature, note, rule_id } エントリを1つ追加します。計画から method と signature をコピーし、note ではデータが信頼できない理由を説明します。rule_id: null とルール作成用のステージはそのままにしてください。

計画 .opentaint/tracking/rules/plans/<id>.yaml — scopes マップから担当メンバーを読み取り、見つかったソースをトップレベルの source リストに記録します。その後、結合処理で source と safe（メンバー − source）が台帳に記録されます。キーには正確な method と signature を使い、異なる呼び出し可能なバリアントが別々に保たれるようにします。これは再生成・破棄可能なものであり、永続状態ではありません。

id: lib-001
scopes:
  <package-kebab>:
    - { method: "<qualified-member-a>", signature: "<language-signature-a>" }
    - { method: "<qualified-member-b>", signature: "<language-signature-b>" }
source:
  - { method: "<qualified-member-a>", signature: "<language-signature-a>" }

source: null は、生成された計画が未処理であることを示すセンチネルです。完了したら、見つかった正確なソースに置き換えるか、該当するものがなければ source: [] に置き換えます。mark-safe は null の計画を再割り当て用に残します。そうすることで、すべてのメンバーを誤って safe と分類するのを防ぎます。ソースとして記載したすべてのメンバーは、そのソース単位にも記載する必要があります。

制約

OpenTaint はプログラム全体を対象とする、手続き間・フィールドセンシティブなエイリアス解析エンジンです。可視のアプリケーションコード、呼び出し、エイリアス、個々のフィールドをすでに追跡します。カスタムルールと近似は、割り当てられたソース、シンク、または不透明メソッドの境界だけをモデル化します。コンパイル時定数とリテラルには taint がないため、出力が定数のみのソースやキャリアは何も導入しません。

• この段階ではソースのみを特定します。ソースとは、信頼できないデータが入ってくる境界です。シンクは後で taint フロンティアから特定します
• 自分の計画と、それに対応するソース単位のみを対象とします。他のエージェントの計画や単位、共有のカバレッジ／分類状態、tags.yaml には決して手を加えないでください。計画では言語リファレンスに従って書き込みの担当範囲を分割しています
• 保存後に読み戻すデータを使った二次インジェクションは、エンジン自体がモデル化します。読み戻し用のソースや、保存から読み戻しまでのパス用のプロパゲーターは記録しないでください