tracewatch

tracewatch

Security Wave 向けの可観測性、追跡、根本原因分析。

Security Wave のツール（hookcheck、actionpin、injectcheck、mcpvet、depguard、flowcheck）は、「今回のこの 1 回のスキャンで、今何が問題なのか」に答えます。tracewatch は Security Wave のメモリーであり、ストップウォッチです。これらのツールの JSON レポートを時系列で取り込み、インシデントの対応で実際に問われる次の疑問に答えます。

• 前回のスキャンから何が変わりましたか？ピン留めがいつの間にか変更可能なタグに戻っていませんか？すでにピン留めされたアクションの ref が移動していませんか？この移動は 2025 年 3 月の tj-actions のパターンです。そのタグを信頼していたすべてのリポジトリでタグが付け替えられ、スキャンを 1 回しか実行したことがない人には見えませんでした。
• この検出結果はどこから来ましたか？tracewatch は、検出結果を、それを導入したコミット（検出結果自体の内容に対する git pickaxe）と、それを含むプルリクエストに関連付けます。また、すべての記述に「確認済み」「推定」「未立証」のラベルを付けます。
• どれくらい早く検知できますか？ウォッチモードでは、新しい問題、PR、ファイル、ツリーの変更を到着時にスキャンし、それぞれの検知までの時間を記録するため、「早期検知」を数値で測定できます。比較対象は重要です。ホスト型 AI ファイアウォールが検知するのはプロンプト時点であり、エージェントがすでにコンテンツを読み込んだ後です。tracewatch は、エージェントセッションが始まる前に、保存時および到着時に検知します。
• 全体として改善していますか？リポジトリごとに、スキャン履歴全体を対象とした判定の推移、ツールおよび重大度別の未解決の検出結果、解決済みの検出結果の平均未解決期間、検知遅延の統計を確認できます。

決定論的で、オフライン優先の、ローカルに保存するデータは grep で検索できます。ホスト型バックエンド、アカウント、テレメトリはありません。

インストール

npx -y @reneturcios/tracewatch --version
npm install -g @reneturcios/tracewatch
docker run -i --rm ghcr.io/cloudcorprecords/tracewatch mcp

クイックスタート

# scan a repo with all six tools and start tracking it
tracewatch ingest ~/src/myrepo

# what changed since the previous scan?
tracewatch diff myrepo

# where did this finding come from?
tracewatch blame myrepo --finding tw_0123456789abcdef

# health over time
tracewatch report myrepo

# watch a directory and scan new content on arrival
tracewatch watch ~/src/myrepo --interval 30

追跡する内容

取り込みごとに、1 件のスキャン記録（タイムスタンプ、ツールのバージョン、判定、git HEAD）と、検出結果ごとに 1 件の観測記録を保存します。検出結果には安定した ID が付与されます。これは、ツール、ルール、正規化された場所、コンテンツのシグネチャのハッシュです。同じ検出結果は、スキャンやツールのバージョンが変わっても同じ ID を保持します。コンテンツが編集された場合も ID は保持されますが、ID バージョンが変わり、差分レポートでは CHANGED として報告されます。

差分のグループ：NEW、RESOLVED、CHANGED（フィールド単位の変更前と変更後を含む）、判定の移行、REF EVENTS。ref イベントは、アクションの ref または分類が変わるたびに発生し、両方の値を明記します。

• pin-regression：PINNED から MUTABLE または BRANCH へ
• pin-improvement：MUTABLE または BRANCH から PINNED へ
• ref-move：同じ分類内で ref が変化（ピン留めされたアクションの場合、SHA 自体が変化）

Blame（根本原因）

tracewatch blame myrepo --rule CURL-PIPE-SH --file package.json
tracewatch blame myrepo --finding tw_0123456789abcdef --json

証拠にはラベルを付け、決して混在させません。

• CONFIRMED：ローカルクローン内で、検出結果の needle に対する git log -S で見つかった導入コミット、git blame で見つかった現在の行のコミット、クローンに GitHub リモートがある場合は GitHub API（commits/{sha}/pulls）による PR の関連付け、ストア自体に記録された ref の履歴と初回・最終確認時刻です。
• INFERRED：状況証拠に基づく記述で、推定として記載します（たとえば、導入コミットと現在の行のコミットが異なる場合、その行は後から書き換えられたものの、コンテンツ自体は導入されていません）。
• NOT ESTABLISHED：クローンが記録されていない、GitHub リモートがない、API に到達できないなど、立証できなかった内容とその理由です。ページを埋めるために出所を推測することはありません。

監視と検出時間

tracewatch watch ~/src/myrepo --interval 60 --alerts alerts.jsonl
tracewatch watch owner/repo --path ~/src/myrepo-clone --interval 60

ローカルモードではディレクトリをポーリングします。新規または変更されたテキストファイルは、検出されたポーリングサイクルでinjectcheckによってスキャンされます。git HEADが移動すると、全件の取り込みと差分処理が実行されます。GitHubモードでは、owner/repoスラッグをポーリングします。新しいissueとPRは検出時にスキャンされ、HEADの移動は記録されます（--pathでローカルクローンを渡した場合はスキャンも実行されます）。検出のたびに、検出時間からコンテンツ自体の作成時間（issueのcreated_at、コミット時刻、ファイルの作成時刻）を引いた検出時間を含むレコードが書き込まれます。各サイクル後に状態のチェックポイントを保存するため、監視を再開しても過去のアラートが再通知されることはありません。アラートはJSONLとして標準出力と--alertsファイルにストリーミングされます。

ポーリングは、移植性の高い代替手段です。最速の方法は、CIでイベント駆動にすることです。

name: tracewatch-issues
on:
  issues:
    types: [opened, edited]
  pull_request:
    types: [opened, edited, synchronize]
permissions:
  contents: read
jobs:
  scan-new-content:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
        with:
          node-version: 24
      - name: Scan the new issue or PR body on arrival
        env:
          BODY: ${{ github.event.issue.body || github.event.pull_request.body }}
        run: |
          printf '%s' "$BODY" > /tmp/body.md
          npx -y @reneturcios/injectcheck file /tmp/body.md --json > /tmp/report.json
          npx -y @reneturcios/tracewatch import ${{ github.repository }} --report injectcheck=/tmp/report.json

既知の制限について、率直に説明します。GitHub監視モードはローカルのghapiヘルパーを通じて読み取りますが、その出力は長いレスポンスを切り詰めます。完全に解析できないissueのポーリング結果は監視メモとして記録され、部分的な内容を信頼することなく次のサイクルで再試行されます。上記のCIパターンにはこの制限がなく、issueスキャンに推奨される本番環境向けの方法です。

レポート

tracewatch report myrepo          # human
tracewatch report myrepo --json   # machine
tracewatch findings myrepo --tool hookcheck --status open

ヘルスレポートには、すべてのスキャンにわたる判定の推移、ツールと重大度別の未解決の検出事項、解決済みの件数、解決済みの検出事項が未解決だった平均時間（最初に検出されたスキャンから、その検出事項が見つからなくなったスキャンまで）、すべてのrefイベント、検出遅延の統計（件数、中央値、最大値、種類別）が含まれます。

MCP

tracewatch mcpは、7つのツールを備えたstdio MCP サーバーを提供します。

ツール	機能
ingest_scan	ローカルパスで6つのツールを実行し、スキャンを保存します
diff_scans	2つのスキャン間のNEW / RESOLVED / CHANGED、判定の変化、refイベント
finding_provenance	1つの検出事項について、導入したコミット、現在の行のコミット、PR、refの履歴を表示します
repo_health	判定の推移、未解決の検出事項、未解決期間の平均、検出遅延
watch_status	追跡中のすべてのリポジトリについて、スキャン、最終スキャン、未解決の検出事項、TTDの中央値を表示します
list_findings	ツール、重大度、ステータスで追跡中の検出事項を絞り込みます
explain_finding	1つの検出事項について、実際の対応に活用できる証拠一式を提示します

ストア

~/.tracewatch以下に追記専用のJSONLとして保存されます（--store

またはTRACEWATCH_STOREで変更可能）。内容はscans.jsonl、findings.jsonl、detections.jsonl、alerts.jsonl、およびwatch-state.jsonのチェックポイントです。意図的にプレーンテキストを採用しています。検出事項のステータスは、保存された可変状態として扱うのではなく、読み取りのたびに観測系列から導出されるため、ストア内で内容が食い違うことはありません。同一のストア状態からは、常に同一の差分とレポートが出力されます。

終了コード：0は成功または変更なし、1は差分に変更あり、2は使用方法の誤りまたは全面的な失敗、141はレポートの配信前に読み取り側が出力パイプを閉じたことを示します。

誠実さに関する原則

• 判定はスキャン結果であり、安全性を保証するものではありません。tracewatchは6つのツールが検出した内容とその時刻を報告しますが、リポジトリがクリーンであると認定するものではありません。
• 検出時間はコンテンツ自体のタイムスタンプを基準に測定し、検出ごとに記録されます。レポートには最良のケースではなく、分布が表示されます。
• blameでは、確認済みの証拠と推論を分け、「立証されていません」と明示します。

depguard のスコープに関する注記

depguard の検出結果は、依存関係がベースと比較して追加、削除、または変更された場合にのみ存在します。tracewatch は、そのコンテキストを最初から最後まで保持します。すべての depguard の検出結果には、ベース（git ref、ディレクトリパス、またはなし）、ヘッドパス、実行モード、および検出結果ごとの変更種別とバージョンの移行が含まれ、スキャンレコードにもスキャンレベルで同じコンテキストが含まれるため、差分から何が何に対して変更されたかが分かります。

直接実行による取り込み（tracewatch ingest）では、depguard をベアターゲットに対するオフラインスナップショットモードで実行します。これにより、ベースは none として記録され、マニフェストとロックファイルの検出結果（タイポスクワットの疑いがあるものを含む）が明らかになります。ベアターゲットには指定されていないベースが必要なため、ベースとヘッドの完全な比較を行うには、depguard を自分で --base <ref> または --base-path <dir> を指定して実行し、レポートをインポートしてください（tracewatch import <repo> --report depguard=<file>）。差分のコンテキストは検出結果とともにストアに保存されます。

MIT。Security Wave の一部です。hookcheck（永続化フック）、actionpin（Actions のピン留め）、injectcheck（エージェントが読み込むコンテンツ内のプロンプトインジェクション）、mcpvet（MCP サーバーとスキルの審査）、depguard（依存関係変更ガード）、flowcheck（ワークフローの権限強化）、tracewatch（可観測性と根本原因）。