____         ____                       ____  _
    / __ \  ___  / __/___   ___   ___  ___  / ___|| | __ _ __      __
   / / / / / _ \/ /_// _ \ / _ \ / __|/ _ \| |    | |/ _` |\ \ /\ / /
  /_/ /_/ /  __/ __//  __/| | | |\__ \  __/| |___ | | (_| | \ V  V /
 /_____/  \___/_/   \___/ |_| |_||___/\___| \____||_|\__,_|  \_/\_/

DefenseClaw combine une CLI opérateur Python, un sidecar passerelle Go et un plugin OpenClaw TypeScript. Ensemble, ils imposent une règle de fonctionnement simple : les capacités d’agent non fiables sont analysées, gouvernées, journalisées et bloquées lorsque la politique les juge dangereuses.

Points forts

• Contrôle d’admission – analysez les compétences, les serveurs MCP, les plugins et le code avant leur exécution.
• Garde-fous en cours d’exécution – inspectez les invites, les complétions et les appels d’outils avec des règles regex, des politiques, un juge LLM optionnel et l’inspection Cisco AI Defense.
• CodeGuard – vérifications statiques intégrées pour les secrets, l’exécution dangereuse, la désérialisation non sécurisée, la cryptographie faible, les motifs d’injection et l’accès aux fichiers risqué.
• Prise en charge du sandbox OpenShell – configuration du sandbox Linux avec contrôles réseau, système de fichiers, appels système et politiques.
• Registres – ingestion de catalogues de compétences / MCP externes (YAML HTTPS d’entreprise, smithery.ai, skills.sh, git, ClawHub) avec protections SSRF, verdicts basés sur l’analyseur et promotion automatique dans la politique d’actifs. Voir docs/REGISTRIES.md.
• Audit et observabilité – un seul graphe V8 pour la collecte par buckets, historique SQLite obligatoire, rédaction centralisée, et destinations indépendantes JSONL, OTLP, Prometheus, Splunk HEC, Galileo, HTTP, console, Grafana/Splunk locales.
• Expérience opérateur – une CLI et TUI pour la configuration, les vérifications de santé, les alertes, les listes de blocage/approbation, les résultats d’analyseurs et les workflows de politique.

Portée et limites

DefenseClaw est une couche de mise en application et de preuve pour les déploiements d’IA agentique. Il améliore la sécurité en combinant les résultats d’analyseurs, l’inspection en cours d’exécution, les décisions politiques, les contrôles de sandbox et les pistes d’audit, mais il ne prouve pas qu’un agent, une compétence, un plugin ou une interaction de modèle est exempt de risque.

Les déploiements à haut risque doivent associer DefenseClaw à une relecture humaine, des identifiants à moindre privilège, un sandboxing, des portes CI et une surveillance de production. En mode observation, les constatations sont journalisées sans blocage. En mode action, les constatations configurées comme HAUTES ou CRITIQUES peuvent bloquer les invites, les appels d’outils ou l’admission de composants.

Documentation

La documentation en Markdown du projet est centralisée sous docs/. Les READMEs propres aux packages restent à côté des bundles ou exemples qui nécessitent un contexte local.

Installation

Prérequis

Construction depuis les sources (développeurs uniquement)

Choisissez la commande selon l’intention :

### Installer avec le script de version

Les cibles source et `scripts/install-dev.sh` sont des outils de développement, pas un chemin de mise à niveau. Les cibles d'installation directe refusent d'écraser une installation gérée par une version ou une installation appartenant à un autre checkout. `make all` est le flux de travail explicite de réinstallation sur la machine de développement : lorsque la CLI installée pointe déjà exactement vers le checkout actuel, elle peut récupérer l'état source sans marqueur ou d'une version précédente et enregistre un marqueur de propriété strict après la reconstruction. Cela peut exécuter les migrations actuelles du checkout sur l'état de développement et ne doit pas être utilisé comme une mise à niveau de version. Les installations gérées par une version doivent utiliser le résolveur appartenant à la version `scripts/upgrade.sh` ou `scripts/upgrade.ps1`. `make install`, `make dev-install` et `scripts/install-dev.sh` sont une plomberie stricte de bas niveau pour un environnement de développement frais ou isolé ; ils ne sont pas la commande normale de développement répété.```bash
VERSION=0.8.6
INSTALL_URL="https://raw.githubusercontent.com/cisco-ai-defense/defenseclaw/${VERSION}/scripts/install.sh"
curl -LsSf "$INSTALL_URL" | VERSION="$VERSION" bash
defenseclaw init --enable-guardrail

Pour les étapes spécifiques à la plateforme, voir docs/INSTALL.md.

Sur Windows x64 natif, utilisez le programme d'installation EXE natif et le chemin de connecteur hook-only dans le guide Windows natif. WSL n'est pas pris en charge. Codex CLI et Claude Code sont les seuls connecteurs Windows certifiés.

Démarrage rapide```bash

Check the local install and dependencies

defenseclaw doctor

Initialize config, scanner defaults, and guardrail plumbing

defenseclaw init --enable-guardrail

Scan installed agent capabilities

defenseclaw skill scan all defenseclaw mcp list defenseclaw plugin scan extensions/defenseclaw

Start the Go gateway sidecar

defenseclaw-gateway start

Open the operator dashboard

defenseclaw tui

Exécutez le garde-fou en mode observation pendant le réglage :```bash
defenseclaw setup guardrail --mode observe --restart

Passer en mode action lorsque la politique est prête à bloquer :```bash defenseclaw setup guardrail --mode action --restart

Voir [docs/QUICKSTART.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/QUICKSTART.md) pour la procédure complète.

---

## Architecture

| Composant | Runtime | Rôle |
|-----------|---------|------|
| Python CLI | Python | Commandes de l'opérateur, orchestration du scanner, configuration, bundles locaux |
| Gateway sidecar | Go | API REST, pont WebSocket, moteur de politiques, proxy de garde-fou, stockage d'audit, télémétrie |
| Plugin OpenClaw | TypeScript | Interception de fetch, hooks d'inspection d'appels d'outils, commandes slash, intégration sidecar |
| Politiques | YAML/Rego | Décisions d'admission, actions de garde-fou, comportement sandbox/firewall, profils de scanner |
| Documentation | Markdown/JSON | Documentation centralisée, READMEs locaux aux paquets, et configuration DeepWiki |

La passerelle expose des API REST locales pour le CLI et le plugin, se connecte à OpenClaw via WebSocket, inspecte le trafic LLM via un proxy local, et enregistre les décisions dans un store d'audit durable.```text
Agent runtime -> OpenClaw plugin -> DefenseClaw gateway -> policy + scanners + audit
                                    |
                                    +-> guardrail proxy -> LLM provider
                                    +-> OTLP / Splunk / webhooks / JSONL

Pour les diagrammes et les flux détaillés, lisez docs/ARCHITECTURE.md.

Scan et Garde-fous

DefenseClaw enveloppe les scanners Cisco AI Defense et la politique locale dans un seul flux d'admission :

Les politiques de scanner se trouvent dans policies/scanners/. Les packs de règles de garde-fou se trouvent dans policies/guardrail/.

Observabilité

DefenseClaw enregistre les preuves d'application et d'exécution à travers plusieurs canaux :

La configuration v8 garde la source concise tout en compilant les omissions en un plan effectif complet :```yaml config_version: 8 observability: {}

Cette valeur par défaut collecte chaque log, trace et métrique enregistrés et conserve chaque log collecté non expurgé dans la base SQLite locale obligatoire. Aucun export distant n'a lieu tant qu'une destination n'est pas ajoutée. Une destination activée sans paramètre `send` ni `routes` reçoit chaque seau et chaque signal que son type supporte, non expurgés : OTLP général reçoit logs/traces/métriques, Splunk HEC reçoit les logs, Prometheus reçoit les métriques, et le préréglage Galileo reçoit les traces. Plusieurs destinations reçoivent des copies indépendantes.

Consultez la politique étendue et les branches non expurgées avec :```bash
defenseclaw config show --effective --section observability
defenseclaw observability plan

Utilisez des profils de rédaction centralisés none, sensitive, content, strict ou personnalisés et tenant compte des champs, par bucket ou destination. Les paramètres par défaut en pleine fidélité peuvent inclure des invites, sorties, arguments/résultats d'outils, preuves, chemins et identifiants, alors configurez un profil de rédaction avant d'exporter à travers une frontière de confiance qui ne doit pas recevoir ce contenu.

Modifiez le bucket et la politique de rédaction dans le fichier source, validez-la avant que la passerelle ne la voie, et inspectez le résultat compilé plutôt que de copier la référence générée en gros :```bash umask 077 cp "$HOME/.defenseclaw/config.yaml"
"$HOME/.defenseclaw/config.yaml.before-observability-edit" ${EDITOR:-vi} "$HOME/.defenseclaw/config.yaml"

defenseclaw config validate &&
defenseclaw config show --effective --section observability &&
defenseclaw observability plan &&
defenseclaw-gateway restart &&
defenseclaw doctor

Ne redémarrez pas après un échec de validation. Restaurez la sauvegarde privée, corrigez la source et validez à nouveau. Un profil de rédaction global ou de bucket s'applique également à la projection SQLite locale générée. Pour conserver un historique local en haute fidélité tout en rédigeant uniquement une limite de confiance distante, laissez le profil global/bucket sur `none` et définissez `send.redaction_profile` ou un profil de route sur cette destination distante.

Démarrez l'observabilité locale avec :```bash
defenseclaw setup local-observability up
defenseclaw-gateway start
defenseclaw setup local-observability status

Le vide du tableau de bord n'est pas un état unique : 0 signifie que le signal instrumenté n'a eu aucun événement correspondant, Aucune donnée signifie qu'aucune série/log/trace correspondante n'existe pour la plage et les filtres sélectionnés, et Non rapporté signifie que le connecteur/le fournisseur n'a pas fourni une valeur optionnelle comme les jetons ou le coût. Les panneaux conditionnels tels que HITL, les vues d'échec uniquement, et une cascade de traces avant qu'un ID de trace ne soit sélectionné, sont censés afficher Aucune donnée. Un test de destination vérifie uniquement la connectivité et ne crée pas de trafic de tableau de bord ordinaire ; générez un nouveau tour d'agent réel, un appel d'outil, une analyse ou une approbation pour valider les panneaux correspondants.

Le graphe de nœuds d'Agent360 est un DAG de cycle de vie soutenu par Loki : la création de session est une ancre séparée, un nœud Entrées d'invite par racine compte les faits model.request distincts de profondeur zéro dans la plage, et la délégation parent-enfant alimente les résumés par agent de modèle, d'outil, d'approbation, de mise à jour, de résultat de tour et de terminal. Les entrées d'invite dédupliquent par tour, requête de modèle, demande, opération, puis ID d'occurrence ; les vues ordonnées/brutes conservent les enregistrements individuels initiaux et de suivi. Les ancres de session et de génération peuvent être récupérées des 24 heures précédentes afin que les fenêtres de limite restent rendues ; une génération récupérée n'est conservée que lorsque cet enfant a une activité éligible au graphe dans la plage sélectionnée. Les appels de modèle répétés sont regroupés par agent propriétaire, fournisseur et modèle. Les appels d'outil répétés sont regroupés par agent propriétaire en Bash, MCP, Compétences, Collaboration, Éditions de fichiers, Web/navigateur, Visuel ou Contrôle de tâche ; un outil non reconnu conserve son nom rapporté. Les requêtes exactes collaboration.send_message sont exclues de la famille générique Collaboration afin qu'elles apparaissent uniquement comme des groupes de messages ; les autres outils de collaboration restent dans cette famille. Les enregistrements de requêtes sont inclus même lorsqu'aucun homologue terminal n'est arrivé. Leur total groupé est un nombre de requêtes, pas une affirmation que chaque requête est toujours en attente ; le statut terminal reste disponible dans les enregistrements bruts liés. La profondeur 0 est la racine et les enfants récursifs peuvent être rapportés jusqu'à la profondeur 64 ; le détail du clic identifie si chaque arête de lignée a été rapportée par le connecteur ou inférée par DefenseClaw. Les clics sur les nœuds exposent les comptes exacts et l'identité stable de l'agent/racine/parent, avec des liens filtrés vers les événements OTEL bruts derrière chaque groupe. Les champs optionnels de session courante/racine/parent restent sur les surfaces de cycle de vie, de session, ordonnée et brute ; ils ne sont pas des clés de regroupement de nœuds d'agent, donc des métadonnées de session manquantes ou tardives ne peuvent pas diviser le total d'un agent.

Les tableaux de bord ne rédactent, masquent ou cachent pas les champs à nouveau. DefenseClaw applique une rédaction centralisée v8 avant l'exportation canonique OTEL ; Grafana affiche ou lie chaque champ réellement présent dans cette projection, y compris le contenu lorsque le producteur l'a exporté. Un champ supprimé ou transformé avant l'exportation ne peut pas être récupéré par la pile locale. Les arêtes de mise à jour proviennent uniquement des enregistrements d'outil réels collaboration.send_message. Pour chaque expéditeur, les cibles /root et /root/* se réduisent en un seul nœud Messages vers la racine dont l'ID d'agent cible se résout en la racine exportée. Les chemins de tâches racine exacts et les appels restent dans les analyses descendantes ordonnées/brutes. Les cibles non racine restent explicitement groupées par chemin de tâche exact et ne sont pas inventées comme des jointures opaques d'ID d'agent lorsque le connecteur n'a pas rapporté ce mappage. Les événements de compatibilité génériques ne sont jamais reétiquetés comme mises à jour.

Les destinations optionnelles possèdent des files d'attente limitées indépendantes. Les valeurs par défaut sont 2 048 enregistrements et 64 Mio par file ; les lots push par défaut sont de 512 enregistrements, 8 Mio et 5 secondes (1 seconde pour le délai préréglé Galileo omis). Le débordement de file d'attente supprime la tentative d'enfilement la plus récente sans évincer les travaux FIFO plus anciens ni affecter les destinations SQLite et frères obligatoires. Les champs exacts, les limites et les différences d'adaptateur sont dans docs/OBSERVABILITY.md.

Ajoutez Galileo Cloud ou Galileo auto-hébergé sans remplacer la route locale :```bash export GALILEO_API_KEY='...' defenseclaw setup galileo --project defenseclaw --logstream production defenseclaw setup galileo test

Voir [docs/OBSERVABILITY.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/OBSERVABILITY.md), le [Guide Galileo](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs-site/content/docs/observability/galileo.mdx), et le [plan de propriété des schémas](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/schemas/README.md). La configuration spécifique à Splunk se trouve dans [docs/SPLUNK_APP.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/SPLUNK_APP.md).

Toute installation POSIX existante prise en charge, y compris celle déjà sur `0.8.4`, franchit la coupure nette `0.8.5` avec l'actif authentifié de version cible `defenseclaw-upgrade.sh` en mode dernier, sans substitution de version. L'analyseur intégré immuable `0.8.4` ne peut pas accepter le manifeste cible véridique dont la matrice de pont Windows est vide. N'exécutez aucun indice réseau brut obsolète imprimé par une CLI intégrée figée. Le résolveur appartenant à la version effectue `source → 0.8.4 bridge → fresh 0.8.4 controller → 0.8.5 hard cut` en une seule transaction. La migration sauvegarde et convertit atomiquement la configuration, préserve le comportement de routage/rédaction plus restreint et la compatibilité root/sous-agent Agent360, rafraîchit les tableaux de bord locaux possédés sans réinitialiser les volumes, et ne nécessite jamais une commande apply séparée. Voir [Référence CLI — mise à niveau](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/CLI.md#upgrade) pour l'amorçage du résolveur authentifié.

Pour Splunk Observability Cloud, utilisez le pack de tableaux de bord à [bundles/splunk_o11y_dashboards/README.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/bundles/splunk_o11y_dashboards/README.md):```bash
defenseclaw setup splunk dashboards apply \
  --api-url <api-endpoint> \
  --o11y-api-token <api-access-token> \
  --with-detectors \
  --enable-detectors \
  --yes

Développement```bash

Build all components

make build

Run primary test suites

make test

Run lint checks

make lint

Des conseils ciblés sur les tests et le développement se trouvent dans [docs/TESTING.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/TESTING.md) et [docs/CONTRIBUTING.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/CONTRIBUTING.md).

---

## Contribuer

Les contributions sont les bienvenues. Commencez par [CONTRIBUTING.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/CONTRIBUTING.md), [docs/CONTRIBUTING.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/CONTRIBUTING.md), et la documentation ciblée pour le domaine que vous modifiez.

## Sécurité

Veuillez signaler les vulnérabilités via le processus décrit dans [SECURITY.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/SECURITY.md).

## Licence

Apache 2.0 - voir [LICENSE](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/LICENSE).

Copyright 2026 Cisco Systems, Inc. et ses affiliés.