NuGuard Open Source

NuGuard è un toolkit di sicurezza open source per applicazioni AI. Il suo obiettivo è fornire il red teaming più esteso e la validazione comportamentale delle applicazioni AI Agentiche.

Con NuGuard, gli sviluppatori AI possono concentrarsi sulla creazione delle loro applicazioni mentre NuGuard le testa e le valida continuamente contro un'ampia gamma di rischi di sicurezza, inclusi attacchi alla supply chain, prompt injection, uso improprio degli strumenti MCP, attacchi API, esfiltrazione di dati e altro ancora. NuGuard consente agli sviluppatori di accelerare i flussi di lavoro di sicurezza e arrivare in produzione più rapidamente e con fiducia.

Una versione commerciale di NuGuard è disponibile come prodotto SaaS con funzionalità aggiuntive e supporto, consultabile all'indirizzo http://nuguard.ai.

Cosa fa

• Genera un AI-SBOM da un codebase locale o da un repository Git
• Analizza l'SBOM per rischi strutturali di sicurezza AI e problemi di supply chain
• Propone una policy comportamentale AI basata sull'SBOM
• Esegue test comportamentali statici e runtime specificamente progettati attorno all'AI-SBOM e alla policy comportamentale
• Effettua red teaming di un'applicazione AI in sandbox: il catalogo più esteso e aggiornato di vettori di attacco più scenari personalizzati. Ciò include prompt injection, abuso di strumenti, esfiltrazione di dati e scenari di attacco correlati che esercitano i vari sotto-agenti, strumenti e capacità del sistema target.
• Suggerimenti automatizzati di remediation per i risultati, inclusi frammenti di codice e modifiche alle policy
• Esportazione dei risultati in flussi di lavoro basati su testo, JSON, Markdown e SARIF

Superficie CLI attuale

Implementato e utilizzabile oggi:

• nuguard sbom
• nuguard analyze
• nuguard scan
• nuguard policy
• nuguard behavior
• nuguard redteam

Requisiti

• Python 3.12+
• uv per il flusso di lavoro locale consigliato

Installazione

CLI Python:

pip install nuguard

I passaggi seguenti descrivono come configurare un ambiente di sviluppo locale. Ciò è consigliato se si desidera eseguire il codice più recente, contribuire al progetto o eseguire la CLI con funzionalità assistite da LLM che richiedono la configurazione di variabili d'ambiente locali.

uv sync --dev

Esegui la CLI con:

uv run nuguard --help

Oppure, dall'ambiente virtuale:

. .venv/bin/activate
nuguard --help

Gli utenti di Claude possono utilizzare i comandi plugin.

Segui le istruzioni in docs/plugin-guide.md per configurare il plugin NuGuard per Claude e usarlo per eseguire comandi come /nuguard-sbom, /nuguard-analyze e /nuguard-redteam direttamente dalle tue conversazioni con Claude.

Avvio rapido

1. Genera un AI-SBOM

nuguard sbom generate --source . --output app.sbom.json

Puoi anche scansionare un repository remoto:

nuguard sbom generate \
  --from-repo https://github.com/org/repo \
  --ref main \
  --output app.sbom.json

2. Esegui analisi statica

nuguard analyze --sbom app.sbom.json --format markdown

Output tipici:

• markdown per la revisione umana
• json per l'automazione
• sarif per pipeline di scansione del codice

3. Test comportamentali

nuguard behavior \
  --sbom app.sbom.json \
  --target http://localhost:3000 \
  --format markdown

4. Red-team su un'applicazione live

nuguard redteam \
  --config nuguard.yaml \
  --output reports/redteam.md \
  --format markdown

Per una copertura di red team più ricca, puoi anche fornire:

• una policy cognitiva con --policy
• valori canarino con --canary
• un file di configurazione con --config

5. Esegui la pipeline unificata

nuguard scan \
  --source . \
  --output-dir nuguard-reports

Per impostazione predefinita, esegue la generazione dell'SBOM più l'analisi statica in un unico passaggio. Per includere le validazioni di policy e red team, opta per questi passaggi e fornisci gli input richiesti:

nuguard scan \
  --source . \
  --steps sbom,analyze,policy,redteam \
  --policy cognitive_policy.md \
  --target http://localhost:3000 \
  --output-dir nuguard-reports

Configurazione

NuGuard supporta la configurazione del progetto tramite nuguard.yaml. Un esempio pronto per la modifica si trova in nuguard.yaml.example.

Aree chiave nella configurazione di esempio:

• sbom: percorso dell'SBOM esistente
• source: directory di origine per la generazione
• policy: percorso della policy cognitiva
• llm: impostazioni del modello per le funzionalità assistite da LLM
• behavior: URL target, endpoint e impostazioni del profilo di test per i test comportamentali
• redteam: URL target, endpoint, file canarino, profili, filtri degli scenari, impostazioni della conversazione guidata e controlli di attivazione dei risultati (finding_triggers.*)
• analyze: soglia di severità minima
• database: impostazioni di archiviazione basata su SQLite o Postgres
• output: formato di output e soglia di fallimento

I flag CLI hanno la precedenza su nuguard.yaml, che a sua volta ha la precedenza sulle variabili d'ambiente e sui valori predefiniti incorporati.

Canarini per il Red Team

NuGuard può monitorare valori canarino seminati durante i test dinamici per produrre risultati di esfiltrazione ad alta confidenza. Parti da canary.example.json, crea il tuo canary.json locale, semina quei valori nel sistema target, quindi punta nuguard redteam a quel file con --canary.

Maggiori dettagli sono disponibili in docs/redteam-engine.md.

Sviluppo

Installa le dipendenze di sviluppo:

make dev

Esegui i test:

make test

Esegui linting e controlli di tipo:

make lint

Formatta il codebase:

make fmt

Pubblicazione

Questo repository include flussi di lavoro GitHub Actions per Trusted Publishing su TestPyPI e PyPI:

• publish-testpypi.yml
• publish-pypi.yml

Prima che i flussi di lavoro possano pubblicare, configura Trusted Publishers in TestPyPI e PyPI per il progetto nuguard con:

• owner/org: NuGuardAI
• repository: nuguard
• workflow file: publish-testpypi.yml o publish-pypi.yml
• environment: testpypi o pypi

Flusso di rilascio consigliato:

1. Esegui manualmente il workflow TestPyPI da GitHub Actions.
2. Verifica l'installazione del pacchetto e il comportamento della CLI da TestPyPI.
3. Crea una release GitHub per attivare il workflow di pubblicazione su PyPI.

Controlli di integrità pre-pubblicazione

Prima di pubblicare su TestPyPI o PyPI, esegui il gate di integrità rapido multi-app.

Esecutore one-shot:

bash tests/apps/prepublish-sanity.sh

Questo esecutore esegue:

• Un controllo rapido del repository (nuguard --help più test locali critici)
• Esecuzioni behavior in modalità dinamica con flusso di lavoro intent_happy_path
• Esecuzioni redteam con profile: ci
• Gate di integrità degli artefatti e della qualità (report non vuoti, scenari eseguiti non zero, controlli rigorosi di origine-endpoint e guardrail per errori di trasporto)

File di configurazione prepublish utilizzati dall'esecutore:

• 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

Esegui manualmente per app (se necessario):

# 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

Importante:

• Non usare || true nelle esecuzioni di gate di pubblicazione.
• Il codice di uscita 2 può indicare risultati o gate di policy; trattalo come un segnale e affidati ai controlli di qualità dei report per decidere superato/non superato.

Note sul repository

• Il repository contiene attualmente output di esempio e fixture di benchmark in tests/output/
• Alcuni test di red team e benchmark sono opzionali e controllati da variabili d'ambiente
• Le funzionalità assistite da LLM dipendono dalla disponibilità delle credenziali del provider tramite variabili d'ambiente

Licenza

Le informazioni sulla licenza sono disponibili nel file LICENSE.