SAFE

SAFEは、研究アーティファクトにおけるSemgrepおよびTrivyの検出結果に対して、リポジトリを認識した制御されたセキュリティ評価を実行します。

これは、binary直接予測（SECURITY_RELEVANTまたはNON_SECURITY）と、詳細なmulticlassコンテキスト分類法（3つのラベル — 3つのラベルを参照）という2つの独立した分類タスクをサポートします。各タスクは、ゼロショットモードまたはエージェントモードで実行できます。

必要なものは以下のみです：

1. セミコロン区切りの検出結果CSV。
2. artifact_idごとに1つの研究アーティファクトフォルダを含むディレクトリ。
3. オプションで、artifact_idをキーとする論文PDF/テキストコレクション。
4. OpenAI APIキー、または組織のLiteLLMプロキシへのアクセス。

SAFEは、ラベル付き評価データに対して学習やチューニングを行いません。ラベル付きデータは推論後に予測を評価するためだけに使用され、分類器が参照することはありません。SAFEはアーティファクトのコードを実行することはありません。リポジトリのテキストは信頼できない証拠として扱われ、命令としては扱われません。

このリリースには、完全なsafe_auditソース、CLI、テストに加えて、外部データを一切必要とせずにエンドツーエンドで実行できる3つの完全に合成されたサンプルアーティファクトを含む自己完結型のdemo/が含まれています。論文で使用された実際の研究アーティファクトコーパス、グラウンドトゥルースラベル、評価用検出結果は含まれていません。

クイックスタート： インストールの後、デモを実行してください — データ設定なしですぐに動作します。設定で後述するconfig.example.yamlは、独自の検出結果/アーティファクト用のテンプレートであり、編集するまで実行されません。

インストール

cd path/to/safe-artifact-auditor
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

APIキーを設定します：

export OPENAI_API_KEY="your-key"

組織のLiteLLMプロキシの場合は、代わりにconfig.litellm.example.yamlを使用してください — インラインでコメントが付いています。認証情報とカスタムヘッダー値は環境変数から読み取られ、SAFEの設定ファイルや結果ファイルに保存されることはありません。

デモ

demo/には、3つの小さな完全に合成されたサンプルアーティファクトが含まれています — 実際の公開研究アーティファクトから派生したものや対応するものは一切ありません — 分類法の各ラベルに1つずつあり、レビュアーが外部データなしで完全なパイプラインを実行できるようになっています：

• demo-contextual-risk/ — 呼び出し元が指定したURLからダウンロードしたチェックポイントをtorch.loadでデシリアライズする、おもちゃの連合学習チェックポイント集約器。信頼できないネットワーク由来の入力が安全でないデシリアライズシンクに到達し、SAFEがCONTEXTUAL_RISKに分類することが期待されます。
• demo-hardening-recommendation/ — すべてハードコードされたPythonリテラルであるコマンドラインに対してsubprocess.run(..., shell=True)を実行するおもちゃのベンチマークハーネス。呼び出し元が制御する入力はありません。SAFEはこれをHARDENING_RECOMMENDATIONに分類することが期待されます：シェルパターンは実際に存在しフラグを立てる価値がありますが、外部から到達したり影響を与えたりすることはできません。
• demo-false-positive/ — 仮想的な解凍ボム勧告を持つ古いPillowバージョンに固定されたテストフィクスチャジェネレーター。コードは新しいインメモリイメージを作成するだけで、外部データを開くことはないため、勧告の実際のコードパスに到達することはありません。SAFEはこれをFALSE_POSITIVEに分類することが期待されます。

demo/findings.csvにはアーティファクトごとに1つの検出結果が含まれ、demo/demo-zero-shot.yaml / demo/demo-agentic.yamlはすぐに実行できる設定です（artifact_root: .は設定ファイルからの相対パスで解決されるため、demo/内から実行してください）：

cd demo
safe-audit run --config demo-zero-shot.yaml
safe-audit run --config demo-agentic.yaml

結果はそれぞれdemo/runs/demo-zero-shot/とdemo/runs/demo-agentic/に出力されます（出力を参照）。

3つのラベル

• CONTEXTUAL_RISK
• HARDENING_RECOMMENDATION
• FALSE_POSITIVE

追加のカテゴリや決定的なラベル変更ルールは使用されません。アーティファクト自身のコードにおける文書化された隔離された研究/セキュリティメカニズムはHARDENING_RECOMMENDATIONに分類されます。隔離によって現実的な悪用可能性が制限される場合でも、基盤となる慣行は依然として実際に存在するためです。

バイナリクラス

• SECURITY_RELEVANT：意図的で隔離されたセキュリティ研究行動を含む、有効なコンテキストリスクまたはハードニングの懸念。
• NON_SECURITY：偽、不一致、非該当、不存在、または実証的に未使用の影響を受ける機能の検出結果。

評価器はマルチクラス予測からバイナリビューも導出します：FALSE_POSITIVEはNON_SECURITYになり、他のすべてのマルチクラスラベルはSECURITY_RELEVANTになります。直接および導出されたバイナリ結果は明示的に分離されたままです。

入力構造

project/
├── config.yaml
├── data/
│   └── findings.csv
└── artifacts/
    ├── artifact_001/
    ├── artifact_002/
    └── artifact_003/

マッピングは正確です：artifact_id = artifact_001はartifacts/artifact_001/に解決されます。

必須のCSV列：

artifact_id;tool;finding_id

オプションの列：

artifact_id;tool;finding_id;category;severity_raw;file;line;message;package;version;cwe;cvss;scanner_applicable

最初の名前のないインデックス列は無視されます。追加の列は入力モデルによって保持されます。

例：

artifact_id;tool;finding_id;category;severity_raw;file;line;message;package;version;cwe;cvss;scanner_applicable
artifact_001;semgrep;python.lang.security.audit.subprocess-shell-true;code;HIGH;src/probe.py;42;Shell command uses shell=True;;;;CWE-78;;yes
artifact_002;trivy;DEMO-CVE-0001;dependency;HIGH;;;Affected package (illustrative, not a real CVE);example-lib;1.2.0;CWE-502;8.1;yes

新しいコードベースから検出結果を生成する

scripts/run_scanners.pyとscripts/build_findings_csv.pyは、SemgrepとTrivyを使用して、上記のfindings.csvとアーティファクトレイアウトを独自のコードから直接生成します。

Semgrepをインストールします（Linuxを含むすべてのOSで同じように動作します）：

pip install semgrep

LinuxにTrivyをインストールします — aptリポジトリ（Debian/Ubuntu）を使用する場合：

sudo apt-get install wget gnupg
wget -qO - https://aquasecurity.github.io/trivy-repo/deb/public.key | gpg --dearmor | sudo tee /usr/share/keyrings/trivy.gpg > /dev/null
echo "deb [signed-by=/usr/share/keyrings/trivy.gpg] https://aquasecurity.github.io/trivy-repo/deb generic main" | sudo tee -a /etc/apt/sources.list.d/trivy.list
sudo apt-get update
sudo apt-get install trivy

または、公式インストールスクリプトを使用します。これは任意のLinuxディストリビューションで動作し、バイナリリリースを/usr/local/binにインストールします（そのディレクトリに対するsudo以外のルートパッケージは不要です）：

curl -sfL https://raw.githubusercontent.com/aquasecurity/trivy/main/contrib/install.sh | sudo sh -s -- -b /usr/local/bin

続行する前に両方がPATH上にあることを確認します：

semgrep --version
trivy --version

次に、artifact_root/の下にアーティファクトごとに1つのディレクトリを配置し、以下を実行します：

python scripts/run_scanners.py artifact_root --output scan-output
python scripts/build_findings_csv.py scan-output --output data/findings.csv

最初のコマンドは、各アーティファクトディレクトリに対してSemgrepとTrivy（脆弱性およびシークレットスキャン）を実行し、生のスキャナーJSONを保存します。2番目のコマンドは、そのJSONをSAFE互換のfindings.csvに解析します（列は入力構造と一致し、fileは各アーティファクトディレクトリからの相対パスで報告されます）。どちらかのスクリプトに--skip-semgrep/--skip-trivyを渡すと、1つのツールのみを実行できます。run_scanners.pyの--configは、デフォルトのautoの代わりに特定のSemgrepルールセットを固定します。これは便利ですが、再現可能に固定されているわけではありません。

設定

このセクションは、独自の検出結果CSVとアーティファクトフォルダに対してSAFEを実行するためのものです（上記の入力構造を参照）。SAFEの実行を確認したいだけの場合は、代わりにデモを使用してください — 以下のconfig.example.yamlはテンプレートであり、そのままでは実行されません。

config.example.yamlをコピーします：

cp config.example.yaml config.yaml

次に、実行前にinput_csvとartifact_root（およびオプションでpaper_root）を独自のデータを指すように編集します。

主要な設定：

• model / provider：正確なOpenAIモデル識別子（またはLiteLLMエイリアス）、およびopenaiまたはlitellm（プロキシURLと認証情報の環境変数名を含む）。
• analysis_mode：zero_shotまたはagentic。
• classification_task：binaryまたはmulticlass。analysis_modeとは独立しています。
• max_agent_steps：エージェント設定でのみ必要です。
• max_workers / max_output_tokens / max_schema_retries：並行性、応答ごとの出力上限、およびスキーマ無効な応答に対するモデル呼び出しの再試行予算。

デフォルトのモデルはgpt-5.6-solです。可用性、コスト、またはレイテンシの要件が異なる場合は、明示的に変更してください。

分析の実行

safe-audit run --config config.yaml

または、コンソールコマンドをインストールせずに：

PYTHONPATH=src python -m safe_audit.cli run --config config.yaml

含まれている合成データに対する実行可能な一致比較については、デモを参照してください（demo/demo-zero-shot.yamlおよびdemo/demo-agentic.yaml）。これらはanalysis_modeとrun_nameのみが異なります。ゼロショットは基本エビデンスに対して1回のモデル呼び出しを行います。エージェントモードは同じエビデンスから開始し、同じ構造化結果を返す前に、制限付きの読み取り専用リポジトリツールを呼び出す場合があります。

出力

runs/<run_name>/
├── config.resolved.yaml
├── run_metadata.json
├── summary.json
├── results.jsonl
├── results.csv
├── profiles/
├── evidence/
├── raw/<finding_uid>/
│   ├── 0001-request.json
│   ├── 0001-response.json (or 0001-error.json)
│   └── final-output.txt
└── logs/
    ├── events.jsonl
    ├── result_attempts.jsonl
    └── run_sessions.jsonl

results.csvは分析用です。results.jsonlは完全な構造化レコードを保持します。エビデンスと生のモデル出力は、監査とエラー分析をサポートします。両方とも正規のものです：各検出結果の最新レコードのみが含まれますが、logs/result_attempts.jsonlは追記専用であり、すべての履歴結果を保持します。

再開時、SAFEはまず現在の厳密なパーサーで失敗した各検出結果の保存された生の応答を再解析します。一意に有効な分類はAPI呼び出しなしで回復されます。回復不可能な失敗のみがモデル推論のためにスケジュールされます。部分的に完了した実行の失敗のみの継続の場合は、同じoutput_rootとrun_nameを維持し、以下を設定します：

resume: true
resume_policy: failed_only

ラベル付きゴールドCSV（security_labelまたはsecurity_class列を持つ）に対して予測を評価するには：

safe-audit evaluate --results runs/<run_name>/results.jsonl --gold GOLD.csv --output runs/<run_name>/evaluation.json

テスト

PYTHONPATH=src python -m unittest discover -s tests -v

テストスイートはフェイクプロバイダーを使用するため、APIキーは必要ありません。