SAFE

SAFE führt eine kontrollierte, repository-bewusste Sicherheitsbewertung von Semgrep- und Trivy-Befunden in Forschungsartefakten durch.

Es unterstützt zwei unabhängige Klassifikationsaufgaben: direkte binäre Vorhersage (SECURITY_RELEVANT oder NON_SECURITY) und die detaillierte multiclass-kontextuelle Taxonomie (drei Labels — siehe Drei Labels). Jede Aufgabe kann im Zero-Shot- oder Agentic-Modus ausgeführt werden.

Es erwartet lediglich:

1. Eine semikolongetrennte Befunde-CSV.
2. Ein Verzeichnis, das einen Forschungsartefakt-Ordner pro artifact_id enthält.
3. Optional eine Papier-PDF-/Textsammlung, die nach artifact_id verschlüsselt ist.
4. Einen OpenAI-API-Schlüssel oder Zugriff auf einen Organisations-LiteLLM-Proxy.

Es trainiert nicht mit oder optimiert gegen gelabelte Bewertungsdaten. Gelabelte Daten werden nur nach der Inferenz verwendet, um Vorhersagen zu bewerten, und werden vom Klassifikator nie gesehen. SAFE führt niemals Artefaktcode aus; Repository-Text wird als nicht vertrauenswürdige Evidenz behandelt, nicht als Anweisungen.

Diese Veröffentlichung enthält den vollständigen safe_audit-Quellcode, die CLI und Tests sowie ein eigenständiges demo/ mit drei vollständig synthetischen Beispielartefakten, die Sie ohne externe Daten Ende-zu-Ende ausführen können. Sie schließt das reale Forschungsartefakt-Korpus, Ground-Truth-Labels und Bewertungsbefunde aus, die im Papier verwendet wurden.

Schnellstart: Führen Sie nach der Installation die Demo aus — sie funktioniert sofort ohne Dateneinrichtung. config.example.yaml, das später unter Konfiguration behandelt wird, ist eine Vorlage für Ihre eigenen Befunde/Artefakte und wird erst nach der Bearbeitung ausgeführt.

Installation

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

Legen Sie den API-Schlüssel fest:

export OPENAI_API_KEY="your-key"

Für einen Organisations-LiteLLM-Proxy verwenden Sie stattdessen config.litellm.example.yaml — es ist inline kommentiert. Anmeldeinformationen und benutzerdefinierte Header-Werte werden aus Umgebungsvariablen gelesen und niemals in SAFE-Konfigurations- oder Ergebnisdateien gespeichert.

Demo

demo/ enthält drei kleine, vollständig synthetische Beispielartefakte — keines davon abgeleitet von oder entsprechend einem realen veröffentlichten Forschungsartefakt — eines pro Taxonomie-Label, sodass Gutachter die vollständige Pipeline ohne externe Daten ausführen können:

• demo-contextual-risk/ — ein Spielzeug-Federated-Learning-Checkpoint-Aggregator, der einen von einer aufruferseitig bereitgestellten URL heruntergeladenen Checkpoint mit torch.load deserialisiert. Nicht vertrauenswürdige, netzwerkbezogene Eingaben erreichen eine unsichere Deserialisierungs-Senke, die SAFE voraussichtlich als CONTEXTUAL_RISK klassifiziert.
• demo-hardening-recommendation/ — eine Spielzeug-Benchmark-Harness, die subprocess.run(..., shell=True) gegen Befehlszeilen ausführt, die alle hartcodierte Python-Literale sind, ohne aufruferkontrollierte Eingaben. SAFE wird voraussichtlich als HARDENING_RECOMMENDATION klassifiziert: Das Shell-Muster ist real und erwähnenswert, aber nichts Externes kann es erreichen oder beeinflussen.
• demo-false-positive/ — ein Test-Fixture-Generator, der an eine ältere Pillow-Version mit einer hypothetischen Dekompressionsbomben-Advisory gebunden ist. Der Code erstellt nur neue In-Memory-Bilder und öffnet niemals externe Daten, sodass der tatsächliche Codepfad der Advisory nie erreicht wird. SAFE wird voraussichtlich als FALSE_POSITIVE klassifiziert.

demo/findings.csv enthält einen Befund pro Artefakt, und demo/demo-zero-shot.yaml / demo/demo-agentic.yaml sind sofort ausführbare Konfigurationen (artifact_root: . löst relativ zur Konfigurationsdatei auf, führen Sie sie also aus demo/ heraus aus):

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

Ergebnisse landen in demo/runs/demo-zero-shot/ bzw. demo/runs/demo-agentic/ (siehe Ausgabe).

Drei Labels

• CONTEXTUAL_RISK
• HARDENING_RECOMMENDATION
• FALSE_POSITIVE

Es wird keine zusätzliche Kategorie und keine deterministische Label-Änderungsregel verwendet. Ein dokumentierter, isolierter Forschungs-/Sicherheitsmechanismus im eigenen Code eines Artefakts wird als HARDENING_RECOMMENDATION klassifiziert, da die zugrunde liegende Praxis auch dann real ist, wenn die Isolation die realistische Ausnutzbarkeit einschränkt.

Binäre Klassen

• SECURITY_RELEVANT: ein gültiges kontextuelles Risiko oder Härtungsbedenken, einschließlich absichtlichem, isoliertem Sicherheitsforschungsverhalten.
• NON_SECURITY: ein falscher, nicht übereinstimmender, nicht anwendbarer, fehlender oder nachweislich ungenutzter betroffener-Funktions-Befund.

Der Bewerter leitet auch eine binäre Ansicht aus Mehrklassen-Vorhersagen ab: FALSE_POSITIVE wird zu NON_SECURITY; jedes andere Mehrklassen-Label wird zu SECURITY_RELEVANT. Direkte und abgeleitete binäre Ergebnisse bleiben explizit getrennt.

Eingabestruktur

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

Die Zuordnung ist exakt: artifact_id = artifact_001 löst zu artifacts/artifact_001/ auf.

Erforderliche CSV-Spalten:

artifact_id;tool;finding_id

Optionale Spalten:

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

Eine anfängliche unbenannte Indexspalte wird ignoriert. Zusätzliche Spalten werden vom Eingabemodell beibehalten.

Beispiel:

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

Befunde aus einer neuen Codebasis generieren

scripts/run_scanners.py und scripts/build_findings_csv.py erzeugen die oben beschriebene findings.csv und Artefaktstruktur direkt aus Ihrem eigenen Code, unter Verwendung von Semgrep und Trivy.

Semgrep installieren (funktioniert auf jedem Betriebssystem gleich, einschließlich Linux):

pip install semgrep

Trivy unter Linux installieren — entweder über das apt-Repository (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

oder über das offizielle Installationsskript, das auf jeder Linux-Distribution funktioniert und eine Binärversion in /usr/local/bin installiert (keine Root-Pakete erforderlich, außer sudo für dieses Verzeichnis):

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

Stellen Sie sicher, dass beide auf PATH sind, bevor Sie fortfahren:

semgrep --version
trivy --version

Legen Sie dann ein Verzeichnis pro Artefakt unter einem artifact_root/ an und führen Sie aus:

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