scan-results-bridge

CompleteTech セキュリティチェッカーの JSON レポートを SARIF 2.1.0 または NDJSON にオフライン変換します。プライバシーを保護するデフォルトのプロジェクションを備えています。

目次

• 概要
• 要件
• クイックスタート
• オフラインワークフロー
• 使用方法
• 入力コントラクト
• 出力フォーマット
• プライバシーとエビデンス
• 制限事項
• 結果の解釈
• 開発
• コントリビューションとセキュリティ
• ライセンスとブランドアセット

概要

scan_results_bridge.py は既存のローカル JSON レポートを読み取り、SARIF 2.1.0 または NDJSON を書き出します。これはオプションであり、個々のチェッカーはこれに依存しません。

• オフライン。 ターゲットのスキャン、コードの実行、パッケージの読み込み、認証情報の読み取り、データのアップロードは一切行いません。HEC/syslog トランスポートや認証情報の設定は実装されていません。
• メタデータのみ。 提供されたローカルエビデンスを変換します。すべての観測結果は exploitability: not_tested を保持します。出力される内容は悪用を裏付けるものではなく、報告された修正バージョンは、検証済みのデプロイ済みパッチや安全性の主張では決してありません。
• デフォルトでプライベート。 相対ソースパスの公開を明示的に選択しない限り、アセットラベル、URL、パス、エビデンスの文章などの値は SHA-256 識別子に置き換えられます。プライバシーとエビデンスを参照してください。
• フェイルクローズド。 サポートされていないツールやバージョン、不正または矛盾する入力は、部分的な変換を生成するのではなく、終了コード 2 で終了します。

要件

• Python 3.10 以降（CI は Linux、Windows、macOS で 3.10 と 3.14 を実行）。
• インストール不要: 標準ライブラリのみを使用する単一のスタンドアロンファイル。
• jsonschema は、出力された SARIF のオプションの開発用チェックにのみ必要です。

クイックスタート

同梱のサンプルは合成データです。

# Convert a report to SARIF (the output file must not already exist)
python scan_results_bridge.py --input examples/report.json --format sarif --output report.sarif

# NDJSON to stdout, publishing reported relative source paths
python scan_results_bridge.py --input examples/report.json --format ndjson --include-relative-paths

# A legacy node2shell-check report (placeholder file name), failing CI on findings or unknowns
python scan_results_bridge.py --input node-report.json --input-schema node2shell-v1 --fail-on either

# Run the tests and show all options
python -m unittest -v
python scan_results_bridge.py --help

無関係なレポートをコミットに含めないでください。

オフラインワークフロー

このツールは提供されたローカルの証拠のみを使用します。対象に接触したり、評価対象のソフトウェアを実行したりすることはありません。

使用方法

python scan_results_bridge.py --input REPORT [--input REPORT ...]
    [--input-schema PROFILE] [--format {sarif,ndjson}] [--include-relative-paths]
    [--fail-on {none,findings,unknown,either}] [--output FILE [--force]]

オプション

オプション	意味
--input FILE	必須。既存のレポート JSON ファイル。最大 20 個の入力まで繰り返し指定可能。
--input-schema PROFILE	入力コントラクト。デフォルトは contract-v1.0。1 つのプロファイルが呼び出し内のすべての入力に適用されます。
--format {sarif,ndjson}	出力形式。デフォルトは sarif。
--include-relative-paths	有効な報告済みソースパスの公開をオプトインします。インベントリ由来のロケーションは決して公開されません。プライバシーと証拠を参照してください。
--fail-on {none,findings,unknown,either}	正常な出力後にポリシー終了コード 1 を返します。デフォルトは none。終了コードを参照してください。
--output FILE	stdout の代わりに新しいファイルへ書き込みます。
--force	既存の --output ファイルをアトミックに置き換えます。入力やチェッカー自体を置き換えることは決してありません。

出力と中断

• 出力はデフォルトで stdout です。既存の --output ファイルは、 --force が指定されない限り拒否されます。
• チェッカーとすべての入力は、シンボリックリンクやハードリンクのエイリアスを 経由する場合も含め、--force があっても上書きから保護されます。
• レポート全体がレンダリングされてから公開され、ファイル出力は アトミックに公開されます。
• 不正な形式、未サポート、または上限超過の入力は、出力前に拒否されます。
• 中断時は 130 で終了し、出力は再試行されません。中断された stdout、または ファイルコミット境界での中断は、不完全または不定の公開状態を残す可能性があります。 検証するか破棄してください。

終了コード

コード	意味
0	変換が成功し、すべての入力が complete: true を報告し、選択された --fail-on ポリシーが満たされました。
1	変換は成功して書き込まれましたが、--fail-on に一致しました。
2	運用上の失敗: 不正な形式、未サポート、または上限超過の入力、保護された、または書き込み不能な出力、あるいは complete: false を報告する入力。不完全な入力は終了前に変換・書き込みされ、出力内で不完全としてマークされます。
130	中断されました。

--fail-on ポリシー:

ポリシー	出力に以下が含まれる場合に終了コード 1
none (デフォルト)	決して該当しません。
findings	potentially_affected、precondition_present、または likely_exposed。
unknown	unknown、unsupported_runtime、または source_discrepancy。
either	上記のいずれか。

ポリシーによる終了が結果を抑制することは決してありません。終了コード 2 は 1 より優先されます。 運用上の失敗は評価結果とは区別されます。

入力コントラクト

プロファイルは --input-schema で明示的に選択します。1 つのプロファイルが呼び出し内の すべての入力に適用されます。未サポートのツールやバージョン、および不正な形式または 矛盾する正規の証拠は、終了コード 2 でフェイルクローズします。正規のバリデータは Sharp の共通コントラクト から同じコードライセンスの下でバンドルされており、インストール済みの共有パッケージは 必要ありません。

プロファイル	入力
contract-v1.0 (デフォルト)	tool/rules/results を含む完全なスキーマ 1.0 オブジェクト。意味論的な証拠参照の検証を含みます。
node2shell-v1	レガシーのバージョンなし node2shell-check tool_version 1.0.0 JSON。名前付きアダプターのみで、汎用スキーマではありません。
copyescape-v1.1	copyescape-check schema_version 1.1
vm2-v1.1	vm2-nesting-check report_schema_version 1.1
simplegit-v1.1	simplegit-rce-check report_schema_version 1.1
atlassian-v1	atlassian-cve-2026-21589-check 整数 schema_version 1
flowise-v1	flowise-cve-2026-69254-check 整数 schema_version 1。version_status は正規化されたステータスにマッピングされます。

すべてのプロファイルに共通:

• 公開されるツールバージョンは、正規のレポートや空の実行を含め、公開されている数値形式の major.minor.patch を使用しなければなりません。自由形式のバージョンラベルは、プライベートなメタデータを含む可能性があるため、出力前に拒否されます。
• すべての結果は exploitability: not_tested を持たなければなりません。脅威メタデータはそれとは別に保持され、いかなる入力ステータスも確認済みの悪用にはなりません。
• 信頼度は、その語彙が一致する場合に保持され、それ以外の場合は unknown になります。
• 元の証拠は、ローカルでの照合のために決定論的ダイジェストを受け取ります。
• 正規のバージョン評価は明示的に保持されます。
• レガシーアダプターは、消費されるエンベロープ、ステータス、悪用可能性、バージョンの各フィールドを検証します。未使用のレガシーレポートのすべてのフィールドの検証を主張するものではありません。

出力形式

出力は決定論的です。結果、ルール、レポートエンベロープは安定した順序で並び、タイムスタンプは生成されず、すべての出力は JSON エスケープされます。非有限数（JSON 指数のオーバーフローを含む）は公開前に失敗します。

SARIF

• ツールとバージョンごとに 1 つの実行があり、それぞれが独自の統合された完了状態を持ちます。これには、入力レポートに結果行がないツールも含まれます。不完全な実行は、失敗した呼び出しでマークされます。
• トリアージレベル: potentially_affected、precondition_present、likely_exposed には warning、unknown、未サポート、修正済み、または緩和済みの観測には note。これはトリアージレベルであり、CVSS スコアや悪用可能性の主張ではありません。
• 元のステータス、信頼度、完了状態は結果のプロパティに残ります。
• ソースの場所は、適格な証拠が存在し、パスがオプトインされている場合にのみ出力されます。有効な Unicode パスは URI 内でパーセントエンコードされます。
• 各結果は checkerIdentity/v1 の部分フィンガープリントを持ちます。

NDJSON

観測ごとに 1 つの JSON オブジェクトがあり、その後に明示的な summary レコードが続きます。これは空または不完全な変換でも書き込まれます。サマリーには complete、result_count、observation_count、およびレポートエンベロープ（reports）が含まれます。

レポートエンベロープ

検証済みの各入力は、その結果行とは独立してレポートエンベロープにも寄与します。SARIF はこれらを一致する各実行の properties.input_reports の下に保存し、NDJSON サマリーはそれらを reports に保存します。

エンベロープは以下を保持します:

• 公開ツール、バージョン、入力プロファイル
• 明示的な完了状態
• report_sha256（完全に正規化された入力のダイジェスト）
• evidence_sha256（レポートレベルのメタデータのダイジェスト）
• プライバシー投影された evidence オブジェクト