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

DefenseClaw combina un CLI operatore Python, un sidecar gateway Go e un plugin TypeScript OpenClaw. Insieme applicano una semplice regola operativa: le capacità degli agenti non fidati vengono analizzate, governate, registrate e bloccate quando la policy le considera non sicure.

Punti salienti

• Controllo degli accessi - analizza skill, server MCP, plugin e codice prima che vengano eseguiti.
• Protezioni runtime - ispeziona prompt, completamenti e chiamate agli strumenti con regole regex, policy, giudice LLM opzionale e ispezione Cisco AI Defense.
• CodeGuard - controlli statici integrati per segreti, esecuzione pericolosa, deserializzazione non sicura, crittografia debole, pattern di injection e accesso ai file rischioso.
• Supporto sandbox OpenShell - configurazione sandbox Linux con controlli di rete, filesystem, syscall e policy.
• Registries - importa cataloghi esterni di skill / MCP (YAML HTTPS aziendale, smithery.ai, skills.sh, git, ClawHub) con protezioni SSRF, verdetti basati su scanner e promozione automatica nella policy degli asset. Vedi docs/REGISTRIES.md.
• Audit e osservabilità - un unico grafico config-v8 per la raccolta bucket, cronologia SQLite obbligatoria, oscuramento centralizzato e destinazioni indipendenti JSONL, OTLP, Prometheus, Splunk HEC, Galileo, HTTP, console e Grafana/Splunk locali.
• UX operatore - un CLI e TUI per configurazione, controlli di integrità, avvisi, liste blocco/consenti, risultati scanner e flussi di policy.

Ambito e limitazioni

DefenseClaw è un livello di enforcement e prove per distribuzioni AI agentiche. Migliora la sicurezza combinando risultati scanner, ispezione runtime, decisioni di policy, controlli sandbox e tracce di audit, ma non dimostra che un agente, skill, plugin o interazione con il modello sia privo di rischi.

Le distribuzioni ad alto rischio dovrebbero abbinare DefenseClaw a revisione umana, credenziali con privilegi minimi, sandboxing, gate CI e monitoraggio di produzione. In modalità osservazione, i risultati vengono registrati senza blocco. In modalità azione, i risultati configurati come ALTI e CRITICI possono bloccare prompt, chiamate agli strumenti o ammissione di componenti.

Documentazione

La documentazione Markdown del progetto è centralizzata in docs/. I README specifici dei pacchetti rimangono accanto a bundle o esempi che necessitano di contesto locale.

Installazione

Prerequisiti

Build da sorgente (solo sviluppatori)

Scegli il comando in base all'intento:

I target sorgente e `scripts/install-dev.sh` sono strumenti di sviluppo, non un
percorso di aggiornamento. I target di installazione diretta rifiutano di sovrascrivere un'installazione
gestita da una release o una di proprietà di un altro checkout. `make all` è il flusso di lavoro
esplicito di reinstallazione sulla macchina dello sviluppatore: quando la CLI installata punta già
esattamente al checkout corrente, può recuperare lo stato sorgente senza marcatore o di release
precedente e registra un marcatore di proprietà rigoroso dopo la ricostruzione. Questo può
eseguire le migrazioni correnti del checkout sullo stato dello sviluppatore e non deve essere
usato come aggiornamento di release. Le installazioni gestite da release devono usare il
risolutore di proprietà della release `scripts/upgrade.sh` o `scripts/upgrade.ps1`.
`make install`, `make dev-install` e `scripts/install-dev.sh` sono strumenti di basso livello
rigorosi per un ambiente di sviluppo nuovo o isolato; non sono il normale comando di sviluppo
ripetuto.

### Installa con lo script di release```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

Per passaggi specifici per piattaforma, consulta docs/INSTALL.md.

Su Windows nativo x64, utilizza il Setup EXE nativo e il percorso del connettore hook-only nella Guida per Windows nativo. WSL non è supportato. Codex CLI e Claude Code sono gli unici connettori Windows certificati.

Avvio Rapido```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

Esegui il guardrail in modalità observe durante la messa a punto:```bash
defenseclaw setup guardrail --mode observe --restart

Passa alla modalità azione quando la policy è pronta per bloccare:```bash defenseclaw setup guardrail --mode action --restart

Vedi [docs/QUICKSTART.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/QUICKSTART.md) per la procedura completa.

---

## Architettura

| Componente | Runtime | Ruolo |
|-----------|---------|------|
| Python CLI | Python | Comandi operatore, orchestrazione scanner, configurazione setup, bundle locali |
| Gateway sidecar | Go | API REST, ponte WebSocket, motore di policy, proxy di guardrail, archivio audit, telemetria |
| Plugin OpenClaw | TypeScript | Intercettazione fetch, hook di ispezione chiamate strumenti, comandi slash, integrazione sidecar |
| Policy | YAML/Rego | Decisioni di ammissione, azioni di guardrail, comportamento sandbox/firewall, profili scanner |
| Documentazione | Markdown/JSON | Documentazione centralizzata, README locali al pacchetto e configurazione DeepWiki |

Il gateway espone API REST locali per la CLI e il plugin, si connette a OpenClaw tramite WebSocket, ispeziona il traffico LLM attraverso un proxy locale e registra le decisioni in un archivio audit durevole.```text
Agent runtime -> OpenClaw plugin -> DefenseClaw gateway -> policy + scanners + audit
                                    |
                                    +-> guardrail proxy -> LLM provider
                                    +-> OTLP / Splunk / webhooks / JSONL

Per diagrammi e flussi dettagliati, leggi docs/ARCHITECTURE.md.

Scansione e Guardrail

DefenseClaw avvolge gli scanner Cisco AI Defense e le policy locali in un unico flusso di ammissione:

Le policy degli scanner si trovano in policies/scanners/. I pacchetti di regole Guardrail si trovano in policies/guardrail/.

Osservabilità

DefenseClaw registra le prove di enforcement e runtime attraverso diversi canali:

Config v8 mantiene il sorgente conciso compilando le omissioni in un piano efficace completo:```yaml config_version: 8 observability: {}

Tale impostazione predefinita raccoglie ogni log, trace e metrica registrati e conserva ogni log raccolto non oscurato nel database SQLite locale obbligatorio. Nessun export remoto avviene finché non viene aggiunta una destinazione. Una destinazione abilitata senza `send` o `routes` riceve ogni bucket e ogni segnale supportato dal suo tipo, non oscurato: OTLP generale riceve logs/traces/metrics, Splunk HEC riceve logs, Prometheus riceve metrics e il preset Galileo riceve traces. Destinazioni multiple ricevono copie indipendenti.

Rivedi la policy estesa e le legs non oscurate con:```bash
defenseclaw config show --effective --section observability
defenseclaw observability plan

Utilizza profili di redazione centralizzati none, sensitive, content, strict, o personalizzati basati sui campi profili di redazione per bucket o destinazione. I valori predefiniti a piena fedeltà possono includere prompt, output, argomenti/risultati degli strumenti, evidenze, percorsi e identificatori, quindi configura un profilo di redazione prima di esportare attraverso un confine di fiducia che non deve ricevere quel contenuto.

Modifica il bucket e la politica di redazione nel file sorgente, validala prima che il gateway la veda, e ispeziona il risultato compilato anziché copiare il riferimento generato riferimento integrale:```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

Non riavviare dopo un fallimento di validazione. Ripristina il backup privato, correggi la fonte e valida di nuovo. Un profilo di redazione globale o per bucket si applica anche alla proiezione SQLite locale generata. Per mantenere la cronologia locale a piena fedeltà mentre si redige solo un confine di fiducia remoto, lascia il profilo globale/bucket a `none` e imposta `send.redaction_profile` o un profilo di rotta su quella destinazione remota.

Avvia l'osservabilità locale con:```bash
defenseclaw setup local-observability up
defenseclaw-gateway start
defenseclaw setup local-observability status

Il vuoto della dashboard non è un singolo stato: 0 significa che il segnale strumentato ha avuto zero eventi corrispondenti, Nessun dato significa che non esiste alcuna serie/log/traccia corrispondente per l'intervallo e i filtri selezionati, e Non riportato significa che il connettore/provider non ha fornito un valore opzionale come token o costo. I pannelli condizionali come HITL, viste solo errori e una cascata di trace prima che venga selezionato un Trace ID dovrebbero mostrare Nessun dato. Un test di destinazione verifica solo la connettività e non crea traffico ordinario della dashboard; genera un nuovo turno reale dell'agente, una chiamata strumento, una scansione o un'approvazione per convalidare i pannelli corrispondenti.

Il grafo dei nodi di Agent360 è un DAG del ciclo di vita basato su Loki: la creazione della sessione è un ancoraggio separato, un nodo Prompt inputs per radice conta i fatti distinti di model.request a profondità zero nell'intervallo, e la delega da genitore a figlio alimenta i riepiloghi per agente di modello, strumento, approvazione, aggiornamento, esito del turno e terminali. Gli input dei prompt deduplicano per turno, richiesta modello, richiesta, operazione, quindi ID occorrenza; le viste ordinate/grezze mantengono i singoli record iniziali e successivi. Gli ancoraggi di sessione e spawn possono essere recuperati dalle precedenti 24 ore, in modo che le finestre di confine rimangano renderizzabili; uno spawn recuperato viene conservato solo quando quel figlio ha attività idonea al grafo nell'intervallo selezionato. Le chiamate modello ripetute sono raggruppate per agente proprietario, provider e modello. Le chiamate strumento ripetute sono raggruppate per agente proprietario in Bash, MCP, Skills, Collaboration, File edits, Web/browser, Visual o Task control; uno strumento non riconosciuto mantiene il nome riportato. Le richieste esatte di collaboration.send_message sono escluse dalla famiglia generica Collaboration, quindi appaiono solo come gruppi di messaggi; gli altri strumenti di collaborazione rimangono in quella famiglia. I record delle richieste sono inclusi anche quando non è arrivata alcuna controparte terminale. Il loro totale raggruppato è un conteggio delle richieste, non un'affermazione che ogni richiesta sia ancora in sospeso; lo stato terminale rimane disponibile nei record grezzi collegati. La profondità 0 è la radice e i figli ricorsivi possono essere riportati fino alla profondità 64; il dettaglio al clic identifica se ogni bordo della discendenza è stato riportato dal connettore o inferito da DefenseClaw. I clic sui nodi espongono conteggi esatti e identità stabile di agente/radice/genitore, con collegamenti filtrati agli eventi OTEL grezzi dietro ogni gruppo. I campi opzionali di sessione corrente/radice/genitore rimangono sulle superfici ciclo di vita, sessione, ordinata e grezza; non sono chiavi di raggruppamento dei nodi agente, quindi metadati di sessione mancanti o tardivi non possono suddividere il totale di un agente.

Le dashboard non oscurano, mascherano o nascondono nuovamente i campi. DefenseClaw applica l'oscuramento centralizzato v8 prima dell'esportazione OTEL canonica; Grafana mostra o collega ogni campo effettivamente presente in quella proiezione, incluso il contenuto quando il produttore lo ha esportato. Un campo rimosso o trasformato prima dell'esportazione non può essere recuperato dallo stack locale. I bordi di aggiornamento provengono solo da record di strumenti collaboration.send_message effettivi. Per ogni mittente, i target /root e /root/* si condensano in un nodo Messages to root il cui ID agente target si risolve nella radice esportata. I percorsi e le chiamate esatte delle attività radice rimangono nei drill-down ordinati/grezzi. I target non radice rimangono esplicitamente raggruppati per percorso esatto dell'attività e non vengono inventati come unioni opache di ID agente quando il connettore non ha riportato quella mappatura. Gli eventi di compatibilità generici non vengono mai rietichettati come aggiornamenti.

Le destinazioni opzionali possiedono code limitate indipendenti. I valori predefiniti sono 2.048 record e 64 MiB per coda; i batch di push predefiniti sono 512 record, 8 MiB e 5 secondi (1 secondo per il ritardo preimpostato Galileo omesso). L'overflow della coda elimina il tentativo di accodamento più recente senza espellere il lavoro FIFO più vecchio o influenzare le destinazioni obbligatorie SQLite e le destinazioni sorelle. Campi esatti, limiti e differenze di adattatore sono in docs/OBSERVABILITY.md.

Aggiungi Galileo Cloud o Galileo self-hosted senza sostituire la route locale:```bash export GALILEO_API_KEY='...' defenseclaw setup galileo --project defenseclaw --logstream production defenseclaw setup galileo test

Vedi [docs/OBSERVABILITY.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/OBSERVABILITY.md), la [guida di Galileo](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs-site/content/docs/observability/galileo.mdx), e [mappa di proprietà dello schema](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/schemas/README.md). La configurazione specifica per Splunk si trova in [docs/SPLUNK_APP.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/SPLUNK_APP.md).

Ogni installazione POSIX esistente supportata, inclusa una già su `0.8.4`, supera il taglio netto `0.8.5` con l'asset autenticato `defenseclaw-upgrade.sh` della release target in modalità latest, senza sovrascrittura di versione. Il parser integrato immutabile `0.8.4` non può accettare il manifesto target veritiero la cui matrice bridge Windows è vuota. Non eseguire alcun suggerimento obsoleto raw-network stampato da una CLI integrata congelata. Il resolver di proprietà della release esegue `source → 0.8.4 bridge → fresh 0.8.4 controller → 0.8.5 hard cut` come una singola transazione. La migrazione esegue il backup e converte atomicamente la configurazione, preserva il comportamento più stretto di routing/redazione e la compatibilità con root/subagent Agent360, aggiorna le dashboard locali di proprietà senza resettare i volumi, e non richiede mai un comando apply separato. Vedi [CLI Reference — upgrade](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/CLI.md#upgrade) per il bootstrap del resolver autenticato.

Per Splunk Observability Cloud, usa il bundle di dashboard in [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

Sviluppo```bash

Build all components

make build

Run primary test suites

make test

Run lint checks

make lint

Guide mirate per test e sviluppo si trovano in [docs/TESTING.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/TESTING.md) e [docs/CONTRIBUTING.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/CONTRIBUTING.md).

---

## Contributi

I contributi sono benvenuti. Inizia con [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) e le guide mirate per l'area che stai modificando.

## Sicurezza

Segnala le vulnerabilità tramite il processo descritto in [SECURITY.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/SECURITY.md).

## Licenza

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

Copyright 2026 Cisco Systems, Inc. e affiliate.