NuGuard CLI Reference

Generates a nuguard.yaml config file with sensible defaults for the current project. Auto-detects existing SBOM files, Cognitive Policy docs, and canary seeds, and pre-fills paths so the file is ready to use with minimal editing.

Also creates companion starter files (canary.example.json, cognitive-policy.md) if they do not already exist.

nuguard init                                    # write ./nuguard.yaml
nuguard init --path ./config/nuguard.yaml       # write to a specific path
nuguard init --target http://localhost:8080
nuguard init --target http://localhost:8080 --source ./src --force
nuguard init --target http://localhost:8080 --llm   # LLM-drafted cognitive policy

✨ Auto-detection: if an existing SBOM (*.sbom.json), policy (cognitive-policy.md, cognitive_policy.md, policy.md, nuguard-policy.md), or canary (canary.json) is found in the target directory, the generated nuguard.yaml pre-fills those paths and the post-init "Next steps" list skips the corresponding steps.

SBOM generation, validation, and management.

Subcommands

🟣 nuguard sbom generate

nuguard sbom generate --source ./my-app --output app.sbom.json
nuguard sbom generate --from-repo https://github.com/org/repo --ref main
nuguard sbom generate --source . --llm --format cyclonedx

Either --source or --from-repo is required (or source: in nuguard.yaml).

The SBOM includes container images (base image, OS, packages), deployed workloads (replicas, ports, exposure, identity), and the relationships between workloads, images, endpoints, and gateways. sbom_generation.scan_images and sbom_generation.max_image_packages (default 200) in nuguard.yaml control image scanning and the per-image package cap. See SBOM schema.

🟣 nuguard sbom validate

nuguard sbom validate --file app.sbom.json

🟣 nuguard sbom register / nuguard sbom show

Register an SBOM in NuGuard's local SQLite database (~/.nuguard/nuguard.db) and retrieve it later by ID.

nuguard sbom register --file app.sbom.json
nuguard sbom show --sbom-id <id-printed-by-register>

🟣 nuguard sbom schema

Print the bundled aibom.schema.json JSON Schema to stdout — no flags.

nuguard sbom schema > aibom.schema.json

🟣 nuguard sbom plugin

Run a toolbox plugin against an existing SBOM or list available plugins.

nuguard sbom plugin list

# SARIF findings export
nuguard sbom plugin run sarif_export --sbom app.sbom.json --output results.sarif

# SPDX 3.0.1 JSON-LD export
nuguard sbom plugin run spdx_export --sbom app.sbom.json --output app.spdx.json

# CycloneDX 1.6 standard BOM
nuguard sbom plugin run cyclonedx_export --sbom app.sbom.json --output app.cdx.json

# CycloneDX 1.6 with AI-specific extensions
nuguard sbom plugin run cyclonedx_ext_export --sbom app.sbom.json --output app.cdx-ext.json

# Markdown report
nuguard sbom plugin run markdown_export --sbom app.sbom.json

Static risk analysis from an AI-SBOM — no running application required.

Runs up to seven scanners in sequence. External scanners are silently skipped when their binary is absent or there's nothing for them to scan:

NGA rules always run. Use --nga to run only NGA rules and skip everything else, including the MITRE ATLAS annotation pass.

nuguard analyze --sbom app.sbom.json
nuguard analyze --sbom app.sbom.json --nga                              # NGA rules only (fast)
nuguard analyze --sbom app.sbom.json --config nuguard.yaml              # load min_severity from config
nuguard analyze --sbom app.sbom.json --format sarif --output results.sarif
nuguard analyze --sbom app.sbom.json --source . --llm
nuguard analyze --sbom app.sbom.json --no-grype --no-trivy --min-severity high
nuguard analyze --sbom app.sbom.json --supply-chain-profile full --source .
nuguard analyze --sbom app.sbom.json --format json --format markdown --output reports/analyze

Source path resolution for Checkov: When --source is provided, IaC file paths found in SBOM nodes are resolved relative to that directory. If no IaC nodes exist, Checkov scans the entire source directory. The SBOM target field is used as a fallback when --source is not set.

Exit codes

Unified pipeline that chains SBOM generation, static analysis, and optional policy and red-team validation into a single command. The default step list is sbom,analyze; add policy and redteam explicitly when you want those validations to run.

nuguard scan --source .
nuguard scan --source . --steps sbom,analyze
nuguard scan --source . --steps sbom,analyze,policy,redteam --policy cognitive_policy.md --target http://localhost:3000
nuguard scan --source . --llm --output-dir reports/
nuguard scan --source . --supply-chain-profile full

💡 Gotcha: supplying --policy or --target does not change the step list by itself. Add --steps sbom,analyze,policy,redteam to actually run those steps.

Exit codes

Cognitive policy linting, SBOM cross-checking, and compliance assessment. Cognitive Policies are human-readable Markdown documents that define guardrails for AI application behavior, architecture, and components — usable for documentation, internal governance, or as enforceable policies in CI or runtime gates. nuguard init creates a cognitive-policy.md template with common sections.

Subcommands

🟣 nuguard policy compile

Compile a Cognitive Policy Markdown document into a structured JSON controls file. The compiled JSON is consumed by policy check and behavior for faster, LLM-optional assessment.

nuguard policy compile --policy cognitive_policy.md --output policy.controls.json
nuguard policy compile --policy policy.md --llm --output policy.controls.json

🟣 nuguard policy validate

Lint a Cognitive Policy Markdown file for completeness and common mistakes.

nuguard policy validate --file cognitive_policy.md

Exit codes

🟣 nuguard policy check

Cross-check policy against SBOM, run a compliance framework assessment, or both.

# Policy vs SBOM gap analysis
nuguard policy check --policy policy.md --sbom app.sbom.json

# Compliance framework assessment
nuguard policy check --sbom app.sbom.json --framework owasp-llm-top10

# Combined with LLM enrichment
nuguard policy check --policy policy.md --sbom app.sbom.json \
  --framework owasp-llm-top10 --llm

# JSON + Markdown in one run
nuguard policy check --policy policy.md --sbom app.sbom.json \
  --format json --format markdown --output reports/policy-check

# Read paths from nuguard.yaml
nuguard policy check

🟣 nuguard policy show

⚠️ nuguard policy show --policy-id <id> always reports "not found" — there is currently no write path that saves a policy for later lookup by ID. Use nuguard policy compile and read the output file directly instead.

Validate AI application happy-path behaviour and cognitive policy compliance against a live target. Runs capability probes, happy-path simulations, boundary assertions, and per-turn policy evaluations, then reports a capability map (which tools were exercised, whether each call stayed policy-compliant) alongside any findings.

Controlled by nuguard.yaml's validate.workflows list — leave it empty to run all five:

boundary_assertion checks are declared explicitly in nuguard.yaml under validate.boundary_assertions, each with a name, an expectation of refused, and a forbid_pattern the response must not match.

This is a faster, more deterministic sibling to nuguard behavior — useful as a quick pass/fail smoke test in CI, where behavior's richer LLM-judged intent alignment isn't needed on every run.

nuguard validate
nuguard validate --target http://localhost:8000 --policy ./policy.md
nuguard validate -c ./nuguard.yaml --output results.json --fail-on critical

Exit codes

Intent-aware behavioral analysis against a live AI application. Runs static SBOM-policy alignment checks (no running app required) and/or dynamic behavior testing with per-turn LLM judging across five dimensions.

See behavior-guide.md for a full description of the engine.

# Static + dynamic (default)
nuguard behavior --config nuguard.yaml

# Static-only alignment checks
nuguard behavior --static

# Dynamic-only with override target
nuguard behavior --dynamic --target http://localhost:8090

# Markdown report to file
nuguard behavior --policy ./policy.md --output ./behavior-report.md --format markdown

# JSON + Markdown in one run
nuguard behavior --config nuguard.yaml --format json --format markdown --output ./behavior-report

# CI gate, comparing against a previous run
nuguard behavior --mode static+dynamic --fail-on critical --compare-to ./last-run.json

Static checks (BA-001 – BA-008) — deterministic SBOM × policy cross-checks; no running application or LLM required. Covers missing system-prompt controls, unenforced topic boundaries, over-permissioned tool edges, missing rate-limit controls, and more.

Dynamic judging — every response is scored 1–5 on five dimensions:

intent_alignment · behavioral_compliance · component_correctness · data_handling · escalation_compliance

Exit codes

Dynamic adversarial testing against a live AI application. Reads the AI-SBOM to derive an attack surface, generates and executes scenarios, and produces structured findings with OWASP/MITRE mappings.

See redteam-guide.md for a complete description of how the engine works.

Subcommands

🟣 nuguard redteam (scan)

# Basic scan (app already running)
nuguard redteam --sbom app.sbom.json --target http://localhost:8000

# Full scan with policy enforcement and canary detection
nuguard redteam --sbom app.sbom.json --target http://localhost:8000 \
  --policy policy.md --canary canary.json --profile full

# Auto-launch the app then scan
nuguard redteam --sbom app.sbom.json --source ./my-app --launch

# Guided adaptive conversations (requires redteam LLM)
NUGUARD_REDTEAM_LLM_MODEL=openrouter/meta-llama/llama-3.3-70b-instruct \
NUGUARD_REDTEAM_LLM_API_KEY=sk-... \
nuguard redteam --sbom app.sbom.json --target http://localhost:8000 \
  --guided --guided-max-turns 15 --guided-concurrency 2

# Skip scenarios that mutate/destroy target state
nuguard redteam --sbom app.sbom.json --target http://localhost:8000 \
  --scenarios non-destructive

# Scan with a custom scenario catalog
nuguard redteam --sbom app.sbom.json --target http://localhost:8000 \
  --catalog ./my-catalog.yaml --profile full

# CI gate — SARIF output, fail on high+
nuguard redteam --sbom app.sbom.json --target $APP_URL \
  --profile ci -f sarif -o results.sarif --fail-on high

# JSON + Markdown in one run
nuguard redteam --sbom app.sbom.json --target $APP_URL \
  --format json --format markdown --output results/redteam

🟣 nuguard redteam catalog-export

Export the full built-in scenario catalog to a YAML file for review or customization. The exported file can be edited and passed back with --catalog to replace the built-in catalog for a scan.

# Write to a file
nuguard redteam catalog-export --output my-catalog.yaml

# Print to stdout (pipe to less or grep)
nuguard redteam catalog-export

Common edits after exporting:

• Set enabled: false on a scenario to skip it entirely.
• Lower base_impact below the profile threshold (e.g. < 5.0 for --profile ci) to exclude it from fast scans without disabling it globally.
• Edit expected_control or success_signal to match your application's specific behavior.

See Customizing the Catalog in the redteam guide for a full walkthrough.

🎯 Target URL resolution order: --target flag → redteam.target in nuguard.yaml → SBOM-discovered URLs (local → staging → production) → error.

LLM configuration (no CLI flags — use env vars or nuguard.yaml):

Advanced YAML-only options (set in nuguard.yaml, no CLI flag):

Bounded, explicitly authorized HTTP/HTTPS application pentesting using the open-source Nuclei engine. Separate from nuguard redteam/nuguard behavior: those exercise the AI-specific chat/agent surface, pentest runs conventional web-application checks (exposed endpoints, misconfig, injection, known-CVE templates) against the app's HTTP surface directly.

See cloud-pentesting.md for the full engine/scope/authentication model.

Requires Nuclei 3.11.1+ on PATH (or --nuclei-binary) — NuGuard does not install it. Refuses to run without --acknowledge-authorization.

# Minimal authorized scan
nuguard pentest --target https://staging.example.com --acknowledge-authorization

# Target + auth from nuguard.yaml
nuguard pentest --config nuguard.yaml --acknowledge-authorization

# Opt in to DAST/fuzzing templates and headless (JS-executing) templates.
# DAST fuzzes real request shapes from an OpenAPI document: an explicit
# --openapi-spec, else the target's own live /openapi.json, else one
# synthesized from --config's SBOM endpoints.
nuguard pentest --config nuguard.yaml --acknowledge-authorization \
  --allow-active-fuzzing --allow-headless-browser

# Fuzz against an explicit OpenAPI document instead
nuguard pentest --config nuguard.yaml --acknowledge-authorization \
  --allow-active-fuzzing --openapi-spec ./openapi.json

# App-specific custom templates, in addition to the always-on bundled ones
nuguard pentest --config nuguard.yaml --acknowledge-authorization \
  --templates-dir ./my-nuclei-templates

# CI gate — SARIF output, fail on high+, 45-minute cap
nuguard pentest --config nuguard.yaml --acknowledge-authorization \
  --format sarif --output pentest.sarif --fail-on high --scan-timeout 2700

Every flag above (except --acknowledge-authorization, which is always CLI-only) can instead be set once in nuguard.yaml under a pentest: block — see nuguard.yaml.example. Precedence is CLI flag > pentest: in nuguard.yaml > built-in default.

pentest:
  profile: standard
  allow_active_fuzzing: true
  use_sbom_endpoints: true
  scan_timeout: 3600

How coverage is assembled, all in one nuguard pentest invocation:

1. The standard Nuclei template corpus (always runs, unless --templates-dir narrows it).
2. NuGuard's bundled generic templates (--bundled, on by default) — auto-signed locally and includes bounded active exploit proofs; use --no-bundled if the approved test plan excludes them.
3. A DAST/fuzzing pass, only with --allow-active-fuzzing (a separate pass: Nuclei's -dast replaces rather than adds to the normal corpus, so NuGuard runs it as its own invocation and merges findings).
4. Your own --templates-dir, if given, as its own pass too.

Findings from every pass are deduplicated and merged into one report; live progress (matched/requests/errors) is logged as each pass runs, not batched at the end.

Verify connectivity and authentication against a live AI application before running a full scan. Prints a status table covering identity, auth type, HTTP status, response time, and any error details.

🟣 nuguard target verify

# Verify using nuguard.yaml
nuguard target verify --config nuguard.yaml

# Quick spot-check with inline options
nuguard target verify --target http://localhost:8000 \
  --endpoint /chat \
  --auth-header "Authorization: Bearer $TOKEN"

# Verify all tenant tokens in a canary file
nuguard target verify --config nuguard.yaml --canary canary.json

# With an SBOM: enables endpoint auto-discovery + a short pre-scan
# conversation that confirms which user/account is being scanned
nuguard target verify --config nuguard.yaml --sbom app.sbom.json

✅ Run nuguard target verify before nuguard redteam, nuguard behavior, or nuguard validate to catch misconfigured endpoints, expired tokens, or firewall blocks early. Exits non-zero if any non-skipped credential fails.

WebSocket chat endpoints are supported transparently — when SBOM or live discovery identifies the chat route as a WebSocket, target verify (and behavior/redteam) automatically switch to a persistent WebSocket connection instead of per-request HTTP POSTs. No extra flags needed; there's currently no nuguard.yaml override for hand-configuring WebSocket auth-message/completion-key framing — it's auto-discovery only.

🟣 nuguard target discover-browser

For target apps that authenticate via an interactive redirect/OAuth flow (Auth0 Universal Login, SSO, etc.) that no static header/Basic Auth/login_flow config can drive. Logs in with a real (headless by default) browser using the credentials in target.auth, captures the resulting session cookie, and — unless --no-sniff-chat — types a message into the chat UI to sniff the app's own outgoing request and discover any extra payload field it requires (e.g. an opaque consumer/account ID). Previews (or, with --write, applies) the corresponding update to nuguard.yaml's target.auth / target.chat_payload_extras, preserving existing comments.

Requires the browser extra: pip install "nuguard[browser]" && playwright install chromium.

# Preview what would change (default: dry-run, nuguard.yaml untouched)
nuguard target discover-browser --config nuguard.yaml

# Apply the discovered auth/config to nuguard.yaml
nuguard target discover-browser --config nuguard.yaml --write --yes

# Debug with a visible browser window, skip payload-field sniffing
nuguard target discover-browser --config nuguard.yaml --headed --no-sniff-chat

Login-flow selectors (which button to click, which fields to fill) use generic heuristics by default. Override them per-app under target.browser_discovery in nuguard.yaml:

target:
  browser_discovery:
    login_button_text: ["Log in"]
    username_selector: "#auth0-username"
    password_selector: "#auth0-password"
    chat_input_selector: "textarea#chat-input"
    send_button_selector: "button#send"

⚠️ The captured session cookie is short-lived (apps commonly expire it within ~24h) — there is no automatic refresh yet. When nuguard target verify receives HTTP 401 or 403 for the saved default cookie session, it prints a refresh hint; re-run nuguard target discover-browser --write --yes.

For now, --canary on redteam/behavior/validate covers the seeding use case (seed the values into your app yourself, then pass the file), and --output/--format on each command covers ad-hoc reporting.