dépôt open source pour valider les applications d'IA agentique : redteam, comportement, chaîne d'approvisionnement, analyse statique
# NuGuard Open Source NuGuard est une boîte à outils open source de sécurité des applications d'IA. Son objectif est de fournir la validation comportementale et le redteaming les plus étendus des applications d'IA agentiques. Avec NuGuard, les développeurs d'IA peuvent se concentrer sur la création de leurs applications pendant que NuGuard les teste et les valide en continu face à un large éventail de risques de sécurité, notamment les attaques de la chaîne d'approvisionnement, l'injection de prompts, le mésusage des outils MCP, les attaques d'API, l'exfiltration de données, et plus encore. NuGuard permet aux développeurs d'accélérer leurs workflows de sécurité et d'atteindre la production plus rapidement en toute confiance. Une version commerciale de NuGuard est disponible en tant que produit SaaS avec des fonctionnalités et un support supplémentaires ; consultez-la sur http://nuguard.ai. ## Ce qu'il fait - Générer un AI-SBOM à partir d'une base de code locale ou d'un dépôt Git - Analyser le SBOM pour détecter les risques structurels de sécurité de l'IA et les problèmes de chaîne d'approvisionnement - Proposer une politique comportementale de l'IA basée sur le SBOM - Effectuer des tests comportementaux statiques et à l'exécution, conçus spécifiquement autour de l'AI-SBOM et de la politique comportementale - Mener un redteam sur une application d'IA sandboxée : catalogue de vecteurs d'attaque le plus étendu et le plus à jour, plus des scénarios sur mesure. Cela inclut l'injection de prompts, l'abus d'outils, l'exfiltration de données et les scénarios d'attaque associés qui exercent les différents sous-agents, outils et capacités du système cible. - Suggestions de remédiation automatisées pour les constats, incluant des extraits de code et des ajustements de politique - Exporter les constats dans des workflows orientés texte, JSON, Markdown et SARIF ## Surface CLI actuelle Implémenté et utilisable aujourd'hui : - `nuguard sbom` - `nuguard analyze` - `nuguard scan` - `nuguard policy` - `nuguard behavior` - `nuguard redteam` ## Prérequis - Python 3.12+ - `uv` pour le workflow local recommandé ## Installation **CLI Python :** ```bash pip install nuguard ``` Les étapes ci-dessous décrivent comment configurer un environnement de développement local. Cela est recommandé si vous souhaitez exécuter le code le plus récent, contribuer au projet ou exécuter la CLI avec des fonctionnalités assistées par LLM qui nécessitent une configuration locale des variables d'environnement. ```bash uv sync --dev ``` Exécutez la CLI avec : ```bash uv run nuguard --help ``` Ou, depuis l'environnement virtuel : ```bash . .venv/bin/activate nuguard --help ``` ### Les utilisateurs de Claude peuvent utiliser les commandes du plugin. Suivez les instructions dans [docs/plugin-guide.md](https://github.com/nuguardai/nuguard/blob/develop/docs/plugin-guide.md) pour configurer le plugin NuGuard pour Claude et l'utiliser pour exécuter des commandes telles que `/nuguard-sbom`, `/nuguard-analyze` et `/nuguard-redteam` directement depuis vos conversations avec Claude. ## Démarrage rapide ### 1. Générer un AI-SBOM ```bash nuguard sbom generate --source . --output app.sbom.json ``` Vous pouvez également analyser un dépôt distant : ```bash nuguard sbom generate \ --from-repo https://github.com/org/repo \ --ref main \ --output app.sbom.json ``` ### 2. Exécuter l'analyse statique ```bash nuguard analyze --sbom app.sbom.json --format markdown ``` Sorties typiques : - `markdown` pour la revue humaine - `json` pour l'automatisation - `sarif` pour les pipelines d'analyse de code ### 3. Tests comportementaux ```bash nuguard behavior \ --sbom app.sbom.json \ --target http://localhost:3000 \ --format markdown ``` ### 4. Faire du Red-Team sur une application en production ```bash nuguard redteam \ --config nuguard.yaml \ --output reports/redteam.md \ --format markdown ``` Pour une couverture red-team plus riche, vous pouvez également fournir : - une politique cognitive avec `--policy` - des valeurs canary avec `--canary` - un fichier de configuration avec `--config` ### 5. Exécuter le pipeline unifié ```bash nuguard scan \ --source . \ --output-dir nuguard-reports ``` Par défaut, cela exécute la génération de SBOM ainsi que l'analyse statique en une seule passe. Pour inclure les validations de politique et de red-team, activez ces étapes et fournissez les entrées requises : ```bash nuguard scan \ --source . \ --steps sbom,analyze,policy,redteam \ --policy cognitive_policy.md \ --target http://localhost:3000 \ --output-dir nuguard-reports ``` ## Configuration NuGuard prend en charge la configuration du projet via `nuguard.yaml`. Un exemple prêt à être modifié se trouve dans [`nuguard.yaml.example`](https://github.com/nuguardai/nuguard/blob/develop/nuguard.yaml.example). Principaux domaines dans l'exemple de configuration : - `sbom` : chemin du SBOM existant - `source` : répertoire source pour la génération - `policy` : chemin de la politique cognitive - `llm` : paramètres du modèle pour les fonctionnalités assistées par LLM - `behavior` : URL cible, endpoint et paramètres de profil de test pour les tests comportementaux - `redteam` : URL cible, endpoint, fichier canary, profils, filtres de scénarios, paramètres de conversation guidée et contrôles de déclenchement de détection (`finding_triggers.*`) - `analyze` : seuil de gravité minimal - `database` : paramètres de stockage basé sur SQLite ou Postgres - `output` : format de sortie et seuil d'échec Les options CLI ont priorité sur `nuguard.yaml`, qui a priorité sur les variables d'environnement et les valeurs par défaut intégrées. ## Canaries Red-Team NuGuard peut surveiller les valeurs canary pré-injectées pendant les tests dynamiques afin de produire des détections d'exfiltration à haute confiance. Partez de [`canary.example.json`](https://github.com/nuguardai/nuguard/blob/develop/canary.example.json), créez votre `canary.json` local, injectez ces valeurs dans le système cible, puis pointez `nuguard redteam` vers ce fichier avec `--canary`. Plus de détails sont disponibles dans [`docs/redteam-engine.md`](https://github.com/nuguardai/nuguard/blob/develop/docs/redteam-engine.md). ## Développement Installez les dépendances de développement : ```bash make dev ``` Exécuter les tests : ```bash make test ``` Exécuter le linting et les vérifications de types : ```bash make lint ``` Formatez la base de code : ```bash make fmt ``` ## Publication Ce dépôt inclut des workflows GitHub Actions pour la publication de confiance (Trusted Publishing) vers TestPyPI et PyPI : - [publish-testpypi.yml](https://github.com/nuguardai/nuguard/blob/develop/.github/workflows/publish-testpypi.yml) - [publish-pypi.yml](https://github.com/nuguardai/nuguard/blob/develop/.github/workflows/publish-pypi.yml) Avant que les workflows puissent publier, configurez les Trusted Publishers dans TestPyPI et PyPI pour le projet `nuguard` avec : - owner/org : `NuGuardAI` - repository : `nuguard` - workflow file : `publish-testpypi.yml` ou `publish-pypi.yml` - environment : `testpypi` ou `pypi` Flux de publication recommandé : 1. Exécutez manuellement le workflow TestPyPI depuis GitHub Actions. 2. Vérifiez l'installation du paquet et le comportement de la CLI depuis TestPyPI. 3. Créez une release GitHub pour déclencher le workflow de publication PyPI. ### Vérifications de cohérence avant publication Avant de publier vers TestPyPI ou PyPI, exécutez la vérification rapide de cohérence multi-applications. Exécuteur en une seule commande : ```bash bash tests/apps/prepublish-sanity.sh ``` Ce runner effectue : - Une vérification rapide du dépôt (`nuguard --help` ainsi que les tests locaux critiques) - Des exécutions de comportement en mode dynamique avec le workflow `intent_happy_path` - Des exécutions Redteam avec `profile: ci` - Des contrôles d'artefacts et de qualité (rapports non vides, scénarios exécutés non nuls, vérifications strictes de la source des endpoints et garde-fous contre les erreurs de transport) Fichiers de configuration de prépublication utilisés par le runner : - `tests/apps/openai-cs-agents-demo/nuguard.prepublish.yaml` - `tests/apps/Gemini-Auto-app/nuguard.prepublish.yaml` - `tests/apps/pinnacle-bank-app/nuguard-azure.prepublish.yaml` Exécution manuelle par application (si nécessaire) : ```bash # OpenAI CS agents demo uv run nuguard sbom generate --config tests/apps/openai-cs-agents-demo/nuguard.prepublish.yaml --format json -o tests/apps/openai-cs-agents-demo/openai-cs.sbom.json uv run nuguard behavior --config tests/apps/openai-cs-agents-demo/nuguard.prepublish.yaml --mode dynamic --format json --format markdown --output tests/apps/openai-cs-agents-demo/reports/openai-cs-prepublish-behavior --verbose uv run nuguard redteam --config tests/apps/openai-cs-agents-demo/nuguard.prepublish.yaml --format json --format markdown --output tests/apps/openai-cs-agents-demo/reports/openai-cs-prepublish-redteam --verbose # Gemini Auto app uv run nuguard sbom generate --config tests/apps/Gemini-Auto-app/nuguard.prepublish.yaml --format json -o tests/apps/Gemini-Auto-app/gemini-auto.sbom.json uv run nuguard behavior --config tests/apps/Gemini-Auto-app/nuguard.prepublish.yaml --mode dynamic --format json --format markdown --output tests/apps/Gemini-Auto-app/reports/gemini-auto-prepublish-behavior --verbose uv run nuguard redteam --config tests/apps/Gemini-Auto-app/nuguard.prepublish.yaml --format json --format markdown --output tests/apps/Gemini-Auto-app/reports/gemini-auto-prepublish-redteam --verbose # Pinnacle Bank app uv run nuguard sbom generate --config tests/apps/pinnacle-bank-app/nuguard-azure.prepublish.yaml --format json -o tests/apps/pinnacle-bank-app/pinnacle-bank.sbom.json uv run nuguard behavior --config tests/apps/pinnacle-bank-app/nuguard-azure.prepublish.yaml --mode dynamic --format json --format markdown --output tests/apps/pinnacle-bank-app/reports/pinnacle-bank-prepublish-behavior --verbose uv run nuguard redteam --config tests/apps/pinnacle-bank-app/nuguard-azure.prepublish.yaml --format json --format markdown --output tests/apps/pinnacle-bank-app/reports/pinnacle-bank-prepublish-redteam --verbose ``` Important : - N'utilisez pas `|| true` dans les exécutions de validation de publication. - Le code de sortie `2` peut indiquer des résultats ou des barrières de politique ; traitez-le comme un signal et appuyez-vous sur les contrôles de qualité des rapports pour décider de la réussite ou de l'échec. ## Notes sur le dépôt - Le dépôt contient actuellement des exemples de sorties et des fixtures de benchmark sous `tests/output/` - Certains tests red-team et de benchmark sont optionnels et conditionnés par des variables d'environnement - Les fonctionnalités assistées par LLM dépendent de la disponibilité des identifiants du fournisseur via des variables d'environnement ## Licence Les informations de licence sont disponibles dans le fichier [LICENSE](https://github.com/nuguardai/nuguard/blob/develop/LICENSE).