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:

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.

uv sync --dev

Führen Sie die CLI aus mit:

uv run nuguard --help

Oder aus der virtuellen Umgebung:

. .venv/bin/activate
nuguard --help

Claude-Nutzer können Plugin-Befehle verwenden.

Befolgen Sie die Anweisungen in 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

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

Sie können auch ein entferntes Repository scannen:

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

2. Statische Analyse ausführen

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

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

4. Redteam-Tests einer Live-App

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

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:

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.

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, 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.

Entwicklung

Dev-Abhängigkeiten installieren:

make dev

Tests ausführen:

make test

Linting und Typprüfungen ausführen:

make lint

Codebasis formatieren:

make fmt

Veröffentlichung

Dieses Repository enthält GitHub-Actions-Workflows für Trusted Publishing zu TestPyPI und PyPI:

• publish-testpypi.yml
• 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 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):

# 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.