nuguard

# NuGuard Open Source

NuGuard ist ein Open-Source-Sicherheits-Toolkit für KI-Anwendungen. Ziel ist es, die umfassendsten Redteam- und Verhaltensvalidierungen für agentische KI-Anwendungen bereitzustellen.

Mit NuGuard können KI-Entwickler sich auf die Entwicklung ihrer Anwendungen konzentrieren, während NuGuard diese kontinuierlich gegen eine breite Palette von Sicherheitsrisiken testet und validiert, darunter Supply-Chain-Angriffe, Prompt Injection, MCP-Tool-Missbrauch, API-Angriffe, Datendiebstahl (Data Exfiltration) und mehr. NuGuard ermöglicht es Entwicklern, ihre Sicherheitsworkflows zu beschleunigen und mit mehr Vertrauen schneller in die Produktion zu gehen.

Eine kommerzielle Version von NuGuard ist als SaaS-Produkt mit zusätzlichen Funktionen und Support verfügbar. Weitere Informationen finden Sie unter http://nuguard.ai.

## Was es tut

- Generiert eine KI-SBOM aus einer lokalen Codebasis oder einem Git-Repository
- Analysiert die SBOM auf strukturelle KI-Sicherheitsrisiken und Supply-Chain-Probleme
- Schlägt eine KI-Verhaltensrichtlinie (Behavioral Policy) basierend auf der SBOM vor
- Führt statische und Laufzeit-Verhaltenstests durch, die speziell auf die KI-SBOM und die Verhaltensrichtlinie zugeschnitten sind
- Redteam-Tests einer sandboxed KI-Anwendung: umfangreichster und aktuellster Katalog von Angriffsvektoren plus individuell erstellte Szenarien. Dies umfasst Prompt Injection, Tool-Missbrauch, Datendiebstahl und verwandte Angriffsszenarien, die die verschiedenen Sub-Agenten, Tools und Fähigkeiten des Zielsystems trainieren.
- Automatisierte Behebungsvorschläge für Befunde, einschließlich Code-Snippets und Richtlinienanpassungen
- Export von Befunden in Text-, JSON-, Markdown- und SARIF-orientierten Workflows

## Aktuelle CLI-Oberfläche

Heute implementiert und nutzbar:

- `nuguard sbom`
- `nuguard analyze`
- `nuguard scan`
- `nuguard policy`
- `nuguard behavior`
- `nuguard redteam`

## Anforderungen

- Python 3.12+
- `uv` für den empfohlenen lokalen Workflow

## Installation

**Python-CLI:**

```bash
pip install nuguard
```

Die folgenden Schritte beschreiben, wie Sie eine lokale Entwicklungsumgebung einrichten. Dies wird empfohlen, wenn Sie den neuesten Code ausführen, zum Projekt beitragen oder die CLI mit LLM-gestützten Funktionen verwenden möchten, die eine lokale Konfiguration von Umgebungsvariablen erfordern.

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

Führen Sie die CLI aus mit:

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

Oder aus der virtuellen Umgebung:

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

### Claude-Nutzer können Plugin-Befehle verwenden.
Befolgen Sie die Anweisungen in [docs/plugin-guide.md](https://github.com/nuguardai/nuguard/blob/develop/docs/plugin-guide.md), um das NuGuard-Plugin für Claude einzurichten und damit Befehle wie `/nuguard-sbom`, `/nuguard-analyze` und `/nuguard-redteam` direkt aus Ihren Unterhaltungen mit Claude auszuführen.

## Schnellstart

### 1. Eine KI-SBOM generieren

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

Sie können auch ein entferntes Repository scannen:

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

### 2. Statische Analyse ausführen

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

Typische Ausgaben:

- `markdown` für die menschliche Überprüfung
- `json` für die Automatisierung
- `sarif` für Code-Scanning-Pipelines

### 3. Verhaltenstests

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

### 4. Redteam-Tests einer Live-App

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

Für eine umfangreichere Redteam-Abdeckung können Sie außerdem angeben:

- eine kognitive Richtlinie mit `--policy`
- Canary-Werte mit `--canary`
- eine Konfigurationsdatei mit `--config`

### 5. Die einheitliche Pipeline ausführen

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

Standardmäßig führt dies die SBOM-Generierung plus statische Analyse in einem Durchgang aus. Um Richtlinien- und Redteam-Validierungen einzuschließen, aktivieren Sie diese Schritte und geben die erforderlichen Eingaben an:

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

## Konfiguration

NuGuard unterstützt die Projektkonfiguration über `nuguard.yaml`. Ein bearbeitungsfertiges Beispiel befindet sich unter [`nuguard.yaml.example`](https://github.com/nuguardai/nuguard/blob/develop/nuguard.yaml.example).

Wichtige Bereiche in der Beispielkonfiguration:

- `sbom`: Pfad zu einer vorhandenen SBOM
- `source`: Quellverzeichnis für die Generierung
- `policy`: Pfad zur kognitiven Richtlinie
- `llm`: Modelleinstellungen für LLM-gestützte Funktionen
- `behavior`: Ziel-URL, Endpunkt und Testprofileinstellungen für Verhaltenstests
- `redteam`: Ziel-URL, Endpunkt, Canary-Datei, Profile, Szenariofilter, Einstellungen für geführte Unterhaltungen und Steuerung der Befundauslöser (`finding_triggers.*`)
- `analyze`: Mindestschweregrad (Minimum Severity Threshold)
- `database`: Speichereinstellungen für SQLite oder Postgres
- `output`: Ausgabeformat und Fehlerschwelle

CLI-Flags haben Vorrang vor `nuguard.yaml`, das wiederum Vorrang vor Umgebungsvariablen und integrierten Standardwerten hat.

## Red-Team-Canaries

NuGuard kann während dynamischer Tests nach eingebetteten Canary-Werten suchen, um hochsichere Exfiltration-Befunde zu erzeugen. Beginnen Sie mit [`canary.example.json`](https://github.com/nuguardai/nuguard/blob/develop/canary.example.json), erstellen Sie Ihre lokale `canary.json`, betten Sie diese Werte in das Zielsystem ein und weisen Sie dann `nuguard redteam` mit `--canary` auf diese Datei.

Weitere Details finden Sie in [`docs/redteam-engine.md`](https://github.com/nuguardai/nuguard/blob/develop/docs/redteam-engine.md).

## Entwicklung

Dev-Abhängigkeiten installieren:

```bash
make dev
```

Tests ausführen:

```bash
make test
```

Linting und Typprüfungen ausführen:

```bash
make lint
```

Codebasis formatieren:

```bash
make fmt
```

## Veröffentlichung

Dieses Repository enthält GitHub-Actions-Workflows für Trusted Publishing zu TestPyPI und 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)

Bevor die Workflows veröffentlichen können, konfigurieren Sie Trusted Publisher in TestPyPI und PyPI für das Projekt `nuguard` mit:

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

Empfohlener Release-Ablauf:

1. Führen Sie den TestPyPI-Workflow manuell über GitHub Actions aus.
2. Überprüfen Sie die Paketinstallation und das CLI-Verhalten von TestPyPI.
3. Erstellen Sie ein GitHub-Release, um den PyPI-Publish-Workflow auszulösen.

### Pre-Publish-Sanity-Checks

Vor der Veröffentlichung auf TestPyPI oder PyPI führen Sie das schnelle Multi-App-Sanity-Gate aus.

Einmaliger Runner:

```bash
bash tests/apps/prepublish-sanity.sh
```

Dieser Runner führt Folgendes aus:

- Einen schnellen Repo-Smoke-Check (`nuguard --help` plus kritische lokale Tests)
- Verhaltensläufe im dynamischen Modus mit dem `intent_happy_path`-Workflow
- Redteam-Läufe mit `profile: ci`
- Artefakt- und Qualitäts-Gates (nicht-leere Berichte, nicht-null ausgeführte Szenarien, strenge Endpunkt-Quellprüfungen und Transportfehler-Schutzmaßnahmen)

Vom Runner verwendete Prepublish-Konfigurationsdateien:

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

Manuell pro App ausführen (falls erforderlich):

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

Wichtig:

- Verwenden Sie bei Publish-Gating-Läufen kein `|| true`.
- Exit-Code `2` kann auf Befunde oder Richtlinien-Gates hinweisen; behandeln Sie ihn als Signal und verlassen Sie sich bei der Entscheidung über Bestehen/Nichtbestehen auf die Berichtsqualitätsprüfungen.

## Repo-Hinweise

- Das Repository enthält derzeit Beispielausgaben und Benchmark-Fixtures unter `tests/output/`
- Einige Redteam- und Benchmark-Tests sind opt-in und durch Umgebungsvariablen gesteuert
- LLM-gestützte Funktionen hängen davon ab, dass Anbieter-Anmeldeinformationen über Umgebungsvariablen verfügbar sind

## Lizenz

Lizenzinformationen finden Sie in der Datei [LICENSE](https://github.com/nuguardai/nuguard/blob/develop/LICENSE).