appsec-agent

AppSec エージェント

OpenTaint によるエンドツーエンドのセキュリティ分析をオーケストレーションします。時間のかかるプロジェクトのビルドと、プロジェクト全体を対象とするすべてのスキャンはこのメインセッションで行います。対象範囲が限定されたソース、近似、シンク、トリアージ、PoC の各ステージはそれぞれ orchestrate-stage サブエージェントに委任します。このサブエージェントが、担当するリーフのファンアウトと集約を行います。

OpenTaint は、プログラム全体を対象とする、手続き間・フィールドセンシティブなエイリアス解析 SAST です。この実行では、確認済みの脆弱性と、プロジェクト固有の再利用可能なルールおよび近似を、プロジェクトルートにある自己完結型の .opentaint/ ディレクトリに生成します。

セットアップ

1. ツールチェーンを確認する

opentaint -v を実行して、opentaint が PATH 上にあることを確認します。見つからない場合は、何も告げずに先へ進まず、ユーザーに伝えて、利用するプラットフォームに応じたインストールコマンドを提示します。インストールは、明示的な確認を得てから実行してください。

• macOS / Linux（順番に実行）：brew install --cask seqra/tap/opentaint · npm install -g @seqra/opentaint
• Windows：npm install -g @seqra/opentaint

インストール後、opentaint health を実行して、すべての設定が解決されていることを確認します。

2. エージェントのネストを確認する

このワークフローでは、2 段階のサブエージェントが必要です。MAIN → ステージオーケストレーター → リーフ。開始前に、ハーネスで深さ 2 が許可されていることを確認します。許可されていない場合は、有効にするようユーザーに依頼します。

3. 言語を特定する

プロジェクトのビルドファイルを読み、対象言語を特定します。Maven/Gradle → java、go.mod → go などです。ブートストラップ時に記録し、ステージオーケストレーターから言語に依存するリーフへ渡します。

4. ワークフローを選択する

ユーザーに両方のレベルをまとめて確認します。

1. スキャンレベル — lite · normal · deep
   • lite — ビルド + スキャン（既存の成果物がある場合に想定）
   • normal — ビルド + スキャン + カスタム近似
   • deep — ビルド + スキャン + カスタム近似 + カスタムルール
   • ディスク上の状態に応じて推奨します。初回実行（.opentaint の成果物がない）→ deep、前回実行の成果物がすでにある → lite
2. トリアージレベル — static · dynamic
   • static — アプリを実行せず、モデルから検出結果を分類します
   • dynamic — static + 確認済み TP ごとの PoC。ユーザーのマシンでいくつかのテストサービス（ローカルインスタンスとポート）を起動し、実行終了時に停止します。この点を選択肢で明確に伝えます

5. ブートストラップ

選択したレベルと言語を使用して、実行状態と作業ツリーを初期化します。

uv run <skill-dir>/scripts/generate.py init --scan-level <lite|normal|deep> --triage-level <static|dynamic> --language <lang>

state.yaml を書き込み、history.yaml を初期化し、.opentaint/ ツリーを作成して、tracking/rules/tags.yaml を生成します。新しいツリーでは組み込みライブラリタグの一覧を作成し、再開するツリーでは組み込みタグと .opentaint/rules から一覧を更新します。generate.py tags は、そのレジストリを明示的に復元する場合にのみ使用します。

ワークフロー

実行は固定のパイプラインで、選択したレベルによって対象となるフェーズが決まります。uv run <skill-dir>/scripts/get_status.py を使用して、次のアクションを選択します。

build                       → MAIN: build
discover / source_rules     → stage subagent: sources
scan                        → MAIN: scan
approximations              → stage subagent: approx-round, then MAIN: rescan; repeat
sink_rules                  → stage subagent: sinks, then MAIN: rescan
triage                      → stage subagent: triage
poc                         → stage subagent: poc

MAIN でのビルド

ステータスが build を示している場合、このメインセッションで build-project スキルを読み込み、それに従います。state.yaml にすでにある言語固有のビルドフィールドを build-hints として渡します。ハーネスのメインセッション用バックグラウンドコマンド機能を通じて、時間のかかるビルドコマンドを実行し、完了イベントを待ちます。

ビルドの成功後、選択した build-project リファレンスで指定されている言語固有のビルドフィールドを .opentaint/tracking/state.yaml に書き込みます。ソースファイルに未コミットの変更がない場合に限り、完全な HEAD を model_commit に記録します。それ以外の場合は null に設定します。ビルドが収束しない場合、モデルなしでは後続のフェーズに進めないため、実行を中断します。

MAIN でのスキャン

ステータスが scan を報告した場合、またはステージから再スキャンが保留中の状態で戻った場合は、メインセッションで run-scan スキルを読み込み、手順に従ってください。ハーネスのメインセッション用バックグラウンドコマンド機能でスキャンを開始し、エンジンの自己タイムアウトは維持したうえで、外側のバックストップとして 1200 秒を追加し、プロセス完了イベントを待ちます。

有効な .opentaint/results/report.sarif があれば、エンジンのタイムアウト後に終了コード 254 となった場合も含め、スキャンは完了しています。スキャンでメモリを増やす必要があった場合は max_memory: 16G を記録し、以降のスキャンでも再利用してください。許可された再試行／バックストップ後も SARIF が存在しない場合、形式不正なルール／近似に対しては以下の修復手順に従ってください。それ以外の場合は、stage: escalation とスキャンの setup を指定して orchestrate-stage をディスパッチし、スキャン全体に関わるリソースの問題を記録させてから停止してください。

スキャンまたは後続のステージで、形式不正な近似、読み込み不能な作成済みルール、効果のない結合、または作成済みルールによる誤検知／見逃しが報告された場合は、「ディスパッチ」の手順に従い、正確な診断内容と成果物のパス／ID を担当ステージエージェントに伝え、MAIN で再度スキャンしてください。

ビルド、スキャン、またはステージから戻るたびに、uv run <skill-dir>/scripts/get_status.py を一度実行して次のアクションを判断してください。実行開始時、再開時、または簡易出力で判断がつかない場合は --full を使用してください。

ディスパッチ

各ステージの呼び出しにつき、ステージオーケストレーターのサブエージェントを正確に 1 つディスパッチしてください。

Invoke the Skill orchestrate-stage first, then follow its instructions precisely
Inputs:
  stage: <sources|approx-round|sinks|triage|poc|escalation>

deep 近似ラウンドでは、sinks: true も渡してください。サブエージェントにはプロジェクトのルートディレクトリが作業ディレクトリとして引き継がれるため、project-root は省略してください。

ステージのコンテキスト：

• sources — 依存関係のソースを特定し、タグごとに分類したソースルールを作成します
• approx-round — 破棄されたメソッドのフロンティアを 1 つ分類して構築します。新しいフロンティアごとに新しいエージェントを使用してください
• sinks — 分類済みのシンクルールを作成し、結合を接続します
• triage — 最新の検出結果を分類し、脆弱性レポートを更新します
• poc — 確認済みの検出結果を再現し、その結果をレポートに追加します
• escalation — ステージ成果物を修復または確定するか、スキャン全体に関わる SARIF 不在の失敗を報告します

各エージェントの ID は、その成果物が次のスキャンで検証されるまで保持してください。ステージが所有するエラーが発生した場合は、そのエージェントに stage: escalation、正確なエラー、成果物のパス／ID を渡して再開してください。そのエージェントのスレッドを利用できない場合は、その診断内容を添えて、再入可能な orchestrate-stage エージェントを開始してください。

各サブエージェントは新規にディスパッチし、コンテキストをフォークして渡さないでください。その後はネイティブに待機し、毎分監視したりポーリングしたりしないでください。ハーネスによって待機がタイムアウトする場合は、タイムアウトを約 1 時間に設定し、戻ってきたら再度待機してください。

状態と再開

作業とスキャンエラーの振り分けには、次の所有権マップを使用してください。

.opentaint/
  project/             MAIN build
  results/             MAIN scan
  rules/               sources or sinks stage
  pass-through/        approximation stage
  dataflow/            approximation stage
  tracking/state.yaml  MAIN run knobs
  tracking/            stage agents, leaves, and join scripts otherwise
  vulnerabilities.md   triage / PoC stage
  issues/               escalation stage

ツリーは長期間保持されます。再開時には DONE 成果物を再利用してください。次のフェーズは get_status.py がディスク上の状態から判定します。既存のルールと近似は、すべてのスキャンに適用されます。

state.yaml の形式：

scan_level: deep
triage_level: dynamic
language: <language>
model_commit: 0123456789abcdef0123456789abcdef01234567
max_memory: null

選択した build-project の言語リファレンスで追加のビルドフィールドが定義されている場合は、再開時にもそれらを保持し、build-hints として渡してください。

主な制約

• パイプラインの状態は手作業ではなく <skill-dir>/scripts/get_status.py で読み取ってください。.opentaint/tracking、results、または *.yaml を対象にした glob／grep／python3 -c／YAML のスキャンで状態を再導出しないでください。また、進捗を確認するだけの目的で検出結果／ユニット／SARIF ファイルを開かないでください。出力だけでは判断がつかない場合は、ファイルを開く前に --full を付けて再実行してください
• ステージが所有する成果物やトラッキング情報を作成・編集しないでください。MAIN が state.yaml に書き込めるのは、model_commit、max_memory、および選択した build-project リファレンスで定義されているビルドフィールドのみです
• 実行中に生成するプロジェクトモデルは 1 つだけにしてください。解析の途中で手作業で編集したり置き換えたりしないでください。新しい実行を開始する前に、ビルドを修正して再ビルドしてください