Démarrage rapide : après l'Installation, exécutez la Démo — elle fonctionne immédiatement sans configuration de données. config.example.yaml, couvert plus loin dans Configuration, est un modèle pour vos propres résultats/artefacts et ne s'exécutera pas tant que vous ne l'aurez pas modifié.

Installation

Définissez la clé API :

Pour un proxy LiteLLM d'organisation, utilisez config.litellm.example.yaml à la place — il est commenté en ligne. Les identifiants et les valeurs d'en-tête personnalisées sont lus à partir des variables d'environnement et ne sont jamais stockés dans la configuration SAFE ou les fichiers de résultats.

Démo

demo/ contient trois petits artefacts d'exemple entièrement synthétiques — aucun dérivé ou correspondant à un quelconque artefact de recherche publié réel — un par étiquette de taxonomie, afin que les évaluateurs puissent exercer le pipeline complet sans aucune donnée externe :

• demo-contextual-risk/ — un agrégateur de points de contrôle d'apprentissage fédéré jouet qui désérialise un point de contrôle téléchargé depuis une URL fournie par l'appelant avec torch.load. Une entrée non fiable provenant du réseau atteint un puits de désérialisation non sécurisé, que SAFE est censé classer CONTEXTUAL_RISK.
• demo-hardening-recommendation/ — un harnais de benchmark jouet qui exécute subprocess.run(..., shell=True) sur des lignes de commande qui sont toutes des littéraux Python codés en dur, sans aucune entrée contrôlée par l'appelant. SAFE est censé classer ceci HARDENING_RECOMMENDATION : le modèle shell est réel et mérite d'être signalé, mais rien d'externe ne peut l'atteindre ou l'influencer.
• demo-false-positive/ — un générateur de fixtures de test épinglé à une version plus ancienne de Pillow avec un avis hypothétique de bombe de décompression. Le code crée uniquement de nouvelles images en mémoire et n'ouvre jamais de données externes, donc le chemin de code réel de l'avis n'est jamais atteint. SAFE est censé classer ceci FALSE_POSITIVE.

demo/findings.csv contient un résultat par artefact, et demo/demo-zero-shot.yaml / demo/demo-agentic.yaml sont des configurations prêtes à l'emploi (artifact_root: . se résout relativement au fichier de configuration, donc exécutez depuis l'intérieur de demo/) :

Les résultats atterrissent respectivement dans demo/runs/demo-zero-shot/ et demo/runs/demo-agentic/ (voir Sortie).

Trois étiquettes

• CONTEXTUAL_RISK
• HARDENING_RECOMMENDATION
• FALSE_POSITIVE

Aucune catégorie supplémentaire et aucune règle déterministe de changement d'étiquette n'est utilisée. Un mécanisme de recherche/sécurité documenté et isolé dans le code propre d'un artefact est classé HARDENING_RECOMMENDATION, car la pratique sous-jacente reste réelle même lorsque l'isolement limite l'exploitabilité réaliste.

Classes binaires

• SECURITY_RELEVANT : un risque contextuel valide ou une préoccupation de durcissement, y compris un comportement de recherche en sécurité intentionnel et isolé.
• NON_SECURITY : un résultat faux, non concordant, non applicable, absent ou manifestement inutilisé concernant une fonctionnalité affectée.

L'évaluateur dérive également une vue binaire des prédictions multiclasses : FALSE_POSITIVE devient NON_SECURITY ; chaque autre étiquette multiclasse devient SECURITY_RELEVANT. Les résultats binaires directs et dérivés restent explicitement séparés.

Structure d'entrée

Le mappage est exact : artifact_id = artifact_001 se résout en artifacts/artifact_001/.

Colonnes CSV requises :

Colonnes facultatives :

Une colonne d'index initiale sans nom est ignorée. Les colonnes supplémentaires sont préservées par le modèle d'entrée.

Exemple :

Générer des résultats à partir d'une nouvelle base de code

scripts/run_scanners.py et scripts/build_findings_csv.py produisent le findings.csv et la disposition des artefacts décrits ci-dessus directement à partir de votre propre code, en utilisant Semgrep et Trivy.

Installez Semgrep (fonctionne de la même manière sur tout système d'exploitation, y compris Linux) :

Installez Trivy sur Linux — soit le dépôt apt (Debian/Ubuntu) :

ou le script d'installation officiel, qui fonctionne sur toute distribution Linux et installe une version binaire dans /usr/local/bin (aucun paquet root requis au-delà de sudo pour ce répertoire) :

Vérifiez que les deux sont sur PATH avant de continuer :

Ensuite, disposez un répertoire par artefact sous un artifact_root/ et exécutez :

La première commande exécute Semgrep et Trivy (analyse des vulnérabilités et des secrets) contre chaque répertoire d'artefact et enregistre le JSON brut des scanners. La seconde analyse ce JSON dans un findings.csv compatible SAFE (les colonnes correspondent à la Structure d'entrée ; file est rapporté relativement à chaque répertoire d'artefact). Passez --skip-semgrep/--skip-trivy à l'un ou l'autre script pour exécuter un seul outil. --config sur run_scanners.py épingle un ensemble de règles Semgrep spécifique au lieu du auto par défaut, ce qui est pratique mais non reproductiblement épinglé.

Configuration

Cette section concerne l'exécution de SAFE contre votre propre CSV de résultats et vos dossiers d'artefacts (voir Structure d'entrée ci-dessus). Si vous voulez simplement voir SAFE s'exécuter, utilisez la Démo à la place — config.example.yaml ci-dessous est un modèle et ne s'exécutera pas tel quel.

Copiez config.example.yaml :

Ensuite, modifiez input_csv et artifact_root (et éventuellement paper_root) pour pointer vers vos propres données avant d'exécuter.

Paramètres clés :

• model / provider : identifiant exact du modèle OpenAI (ou alias LiteLLM), et openai ou litellm avec l'URL du proxy et le nom de la variable d'environnement des identifiants.
• analysis_mode : zero_shot ou agentic.
• classification_task : binary ou multiclass ; indépendant de analysis_mode.
• max_agent_steps : requis uniquement dans une configuration agentique.
• max_workers / max_output_tokens / max_schema_retries : concurrence, plafond de sortie par réponse et budget de nouvelles tentatives d'appel de modèle pour les réponses invalides au schéma.
• resume / resume_policy : incomplete réessaie les échecs, les artefacts manquants et les résultats non tentés ; failed_only réessaie uniquement les échecs tout en conservant les succès enregistrés.
• cost : comptabilité des coûts en direct facultative et terminaison max_run_cost_usd.

Le modèle par défaut est gpt-5.6-sol. Changez-le explicitement si la disponibilité, le coût ou les exigences de latence diffèrent.

Exécuter l'analyse

Ou sans installer la commande console :

Pour une comparaison appariée exécutable contre les données synthétiques incluses, voir Démo (demo/demo-zero-shot.yaml et demo/demo-agentic.yaml). Elles ne diffèrent que par analysis_mode et run_name. Le mode zero-shot effectue un appel de modèle sur les preuves de base. Le mode agentique part des mêmes preuves et peut appeler des outils de dépôt en lecture seule limités avant de renvoyer le même résultat structuré.

Sortie

results.csv est destiné à l'analyse. results.jsonl préserve les enregistrements structurés complets. Les preuves et les sorties brutes du modèle prennent en charge l'audit et l'analyse des erreurs. Les deux sont canoniques : ils ne contiennent que le dernier enregistrement pour chaque résultat, tandis que logs/result_attempts.jsonl est en ajout seul et préserve chaque résultat historique.

Lors de la reprise, SAFE ré-analyse d'abord les réponses brutes enregistrées de chaque résultat en échec avec l'analyseur strict actuel ; une classification valide unique est récupérée sans appel API. Seuls les échecs irrécupérables sont planifiés pour l'inférence du modèle. Pour une continuation en échec uniquement d'une exécution partiellement terminée, conservez le même output_root et run_name et définissez :

Pour évaluer les prédictions contre un CSV doré étiqueté (avec une colonne security_label ou security_class) :

Tests

La suite de tests utilise un fournisseur factice et ne nécessite donc pas de clé API.