nuguard

# 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:**

```bash
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.

```bash
uv sync --dev
```

Esegui la CLI con:

```bash
uv run nuguard --help
```

Oppure, dall'ambiente virtuale:

```bash
. .venv/bin/activate
nuguard --help
```

### Gli utenti di Claude possono utilizzare i comandi plugin.
Segui le istruzioni in [docs/plugin-guide.md](https://github.com/nuguardai/nuguard/blob/develop/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

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

Puoi anche scansionare un repository remoto:

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

### 2. Esegui analisi statica

```bash
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

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

### 4. Red-team su un'applicazione live

```bash
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

```bash
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:

```bash
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`](https://github.com/nuguardai/nuguard/blob/develop/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`](https://github.com/nuguardai/nuguard/blob/develop/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`](https://github.com/nuguardai/nuguard/blob/develop/docs/redteam-engine.md).

## Sviluppo

Installa le dipendenze di sviluppo:

```bash
make dev
```

Esegui i test:

```bash
make test
```

Esegui linting e controlli di tipo:

```bash
make lint
```

Formatta il codebase:

```bash
make fmt
```

## Pubblicazione

Questo repository include flussi di lavoro GitHub Actions per Trusted Publishing su TestPyPI e 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)

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
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):

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

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](https://github.com/nuguardai/nuguard/blob/develop/LICENSE).