create-dataflow-approximation

スキル：データフローの近似を作成する

データフロー近似とは、アナライザーが追跡できないメソッドを通じたデータの流れを表すコードです。エンジンがメソッド本体を確認できないため、汚染情報を失ってしまう不透明な呼び出しが対象です。入力から出力への実際の伝播を再現する小さな代替コードを記述し、アナライザーがそのメソッドを通じて汚染情報を追跡できるようにします。準備済みのテストプロジェクトで実行し、サンプルがパスするまで調整します。

入力

呼び出し元から提供されます。省略された場合はデフォルト値を使用します。必須入力が欠けており、妥当なデフォルト値もない場合に限り、問い合わせてください。

• project-root（任意）— 対象プロジェクトのルートです。Opentaint はすべての解析成果物を固定の <project-root>/.opentaint/ ディレクトリに保存するため、以下の .opentaint/... パスはすべてそこを基準に解決されます。デフォルト：現在のディレクトリ
• language（必須）— このプロジェクトの対象言語と言語固有の指示です
• batch（必須）— .opentaint/tracking/approximations/<batch>.yaml にモデル化する dataflow メソッドが記載され、追跡状態が保持されるバッチです
• methods（任意）— バッチ内のデータフローメソッドのうち、モデル化または再モデル化する対象のサブセットです。デフォルトは、まだ build.done に記載されていないすべてのメソッドです

ワークフロー

1. 伝播を理解する

各データフローメソッドの実際のソースを見つけて読みます。build.done にまだ記載されていないメソッド、または修正対象として明示的に渡されたメソッド（すでにビルド済みの場合も含む）を対象にします。明示的なサブセットに含まれないビルド済みメソッドとその近似ソースは変更しないでください。アプリ内部のメソッドはプロジェクト独自のソースにあり、ライブラリメソッドのソースは依存関係から取得します（取得方法は言語リファレンスを参照）。ソースを読み、メソッドの入力（レシーバー、引数）から出力（戻り値、書き込み先の引数、保存する状態）へデータがどう流れるかを確認し、関数の動作を理解するために必要なコンテキストをすべて集めます。

2. 近似を記述する

言語リファレンスの成果物レイアウトに従い、.opentaint/dataflow/<batch> の下に言語固有のコード形式で伝播を再現します。割り当てられたすべての呼び出し可能なバリアントを網羅し、明示的に渡された呼び出し可能要素は既存のソース内で修正し、新しいものはファイルを書き換えずにそこへ追加します。エンジンはフィールドに依存した解析を行い、汚染情報をフィールドごとに追跡します。そのため、オブジェクト全体を汚染するのではなく、ソースと同じようにフィールド間でデータを流してください。テストプロジェクトのネガティブサンプル（ある場合）は、あるフィールドに汚染情報を保存し、別のフィールドを読み取ることでこれを検証します。範囲を広げすぎたモデルでは、これらのサンプルが検出されます。具体的な構文とパターンは言語リファレンスを参照してください。

3. テストプロジェクトでテストする

近似テストは、フォアグラウンドでブロックするコマンドとして直接実行し、終了するまで待機してください。バックグラウンドで実行したり、Monitor を使用したりしてはいけません。このバッチのソースを適用し、サンプルがパスするまで反復します。フィードバックループ：サンプルが失敗する原因として、モデルの対象型／メンバーまたはシグネチャがアナライザーの認識と一致していない場合や、本体で実際のソースからモデル化された出力へ汚染情報が流れていない場合があります。不一致を診断して修正し、再実行してください。結果が出ないことを正当化してはいけません。原因が明らかでない場合は、さらに推測する前に references/debugging.md に従い、ファクト到達可能性トレースで汚染情報が失われる箇所を特定してください。パスした場合は、build.done にまだ記載されていないメソッドに限り、Tracking に従って追記します。修正したメソッドは引き続き記録に残します。

4. エスカレーションする

約3回修正してもサンプルが収束しない場合は、それ以上再試行しないでください。忠実なモデルを使っても伝播できないことがトレースで示されている場合（エンジンが処理できるはずの通常の命令で汚染情報が途切れるなど、エンジンの制限がある場合）も、原因が不明なままの場合も同様です。新しいメソッドを build.done に追加したり、修正済みメソッドの既存の追跡エントリを変更したりせず、見つかった原因を簡潔に報告してください（Output に従います）。オーケストレーターがエスカレーションします。

出力

成果物

• .opentaint/dataflow/<batch> — スキャンで使用される、言語固有のコード近似成果物です。パスと、使用したテストコマンドを正確に記載してください
• バッチファイルの build.done に記録されている合格済みメソッド（新規メソッドは追記し、修正済みメソッドは Tracking に従って記録済みの状態を維持します）

概要

• モデル化したメソッドとテストのステータス（合格／収束しない）

Tracking

.opentaint/tracking/approximations/<batch>.yaml は、1 つのバッチの呼び出し可能要素の分類を記録します。<batch> はプランのファイル名の拡張子を除いた部分です。各呼び出し可能要素は、プランに記載された言語固有の method と signature をそのままキーとして使う 1 つの判定バケットにのみ属し、異なるバリアントが別々に保たれるようにします。

• passthrough、dataflow — モデル化されたキャリア。それぞれのエントリーは { method, signature } です
• skipped — 終端の非キャリア。それぞれのエントリーは { method, signature, reason } です
• engine_issues — エンジンが伝播できないことを確実に確認できたキャリア（ビルドされても伝播時に除外されるもの）専用のバケットです。それぞれのエントリーは { method, signature, reason } です。終端として扱われ、skipped と同様に処理されます。違いは理由だけです。merge-skipped は、この情報を skipped.yaml に移し、通常の methods と並ぶ独立した engine_issues グループとして記録します。

dependencies には、データフローテストプロジェクトで必要な依存関係 ID を列挙します。build ブロックではビルドを追跡します。test_project には各データフローメソッドのテストプロジェクトでの状態を記録します（サンプルがバッチのテストプロジェクトに書き込まれた場合は done、書き込み可能なサンプルがなく、そのメソッドがテストプロジェクトから除外された場合は failed）。done には完了した { method, signature } を記録します。コメントから状態が明確に分かるようにしてください。

passthrough:
  - { method: "<qualified-member-a>", signature: "<language-signature-a>" }
dataflow:
  - { method: "<qualified-member-b>", signature: "<language-signature-b>" }
skipped:
  - { method: "<qualified-member-c>", signature: "<language-signature-c>", reason: "retains none of its input data" }
engine_issues: []
dependencies: []
build:
  test_project:
    - { method: "<qualified-member-b>", signature: "<language-signature-b>", status: done }
  done: []

このスキルは、サンプルがテストに合格した各メソッドについて、まだ登録されていない場合に { method, signature } として build.done に追記します。新たに割り当てられたメソッドのうち、依然としてテストに失敗するもの、またはエンジンが伝播できないことを確実に確認できたものは、build.done には追加せず、報告します（Output に従います）。明示的に修正されたメソッドは、既存のエントリーを変更しません。分類バケット（passthrough／dataflow／skipped／engine_issues）には触れず、build.done にすでにあるエントリーも編集しないでください。

制約

OpenTaint は、プログラム全体を対象とする、手続き間かつフィールド依存のエイリアス解析エンジンです。可視のアプリケーションコード、呼び出し、エイリアス、および個々のフィールドを通じた伝播には、すでに対応しています。カスタムルールと近似は、割り当てられたソース、シンク、または不透明なメソッド境界のみをモデル化します。コンパイル時定数とリテラルには汚染が伝播しないため、出力が定数のみのソースやキャリアからは何も生じません。

• 検証はテストプロジェクトで近似テストを実行する場合に限ります
• テストプロジェクトのサンプルソースは固定入力です。テストを通すために編集したり再コンパイルしたりしないでください。忠実なモデルでテストに合格できない場合は、そのメソッドを対象外のままにして報告します（Output に従います）
• バッチに記載されたすべてのデータフローメソッドとオーバーロードをモデル化します。サンプルがあるものだけに限定しないでください