NuGuard OSS

NuGuard is an open source AI application security CLI. It can generate an AI-focused SBOM from source code, run static security analysis, validate cognitive policy documents, and red-team a live AI app with scenario-driven adversarial testing.

What It Does

• Generate an AI-SBOM from a local codebase or Git repo
• Analyze the SBOM for structural AI security risks and dependency issues
• Cross-check a cognitive policy against the SBOM
• Red-team a running AI application with prompt injection, tool abuse, data exfiltration, and related attack scenarios
• Export findings in text, JSON, Markdown, and SARIF-oriented workflows

Current CLI Surface

Implemented and usable today:

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

Present but still stubbed / not yet implemented:

• nuguard seed
• nuguard report
• nuguard findings
• nuguard replay

Requirements

• Python 3.12+
• uv for the recommended local workflow

Optional external tools used by some analysis paths:

• grype
• checkov
• trivy
• semgrep

If these tools are not installed, the corresponding checks can be skipped or may report as unavailable depending on the command path.

Installation

The steps below describe how to set up a local development environment. For production use, install the package from PyPI with: pip install nuguard

uv sync --dev

Run the CLI with:

uv run nuguard --help

Or, from the virtual environment:

. .venv/bin/activate
nuguard --help

Quick Start

1. Generate an AI-SBOM

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

You can also scan a remote repository:

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

2. Run Static Analysis

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

Typical outputs:

• markdown for human review
• json for automation
• sarif for code scanning pipelines

3. Validate or Check a Cognitive Policy

Validate policy structure:

nuguard policy validate --file cognitive-policy.md

Cross-check policy against the SBOM:

nuguard policy check \
  --policy cognitive-policy.md \
  --sbom app.sbom.json

4. Red-Team a Live App

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

For richer red-team coverage, you can also provide:

• a cognitive policy with --policy
• canary values with --canary
• a config file with --config

5. Run the Unified Pipeline

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

This is the easiest way to run SBOM generation plus static analysis in one pass.

Configuration

NuGuard supports project configuration through nuguard.yaml. A ready-to-edit example lives at nuguard.yaml.example.

Key areas in the example config:

• sbom: existing SBOM path
• source: source directory for generation
• policy: cognitive policy path
• llm: model settings for LLM-assisted features
• redteam: target URL, endpoint, canary file, profiles, scenario filters, and guided conversation settings
• analyze: minimum severity threshold
• database: SQLite or Postgres-backed storage settings
• output: output format and failure threshold

CLI flags take precedence over nuguard.yaml, which takes precedence over environment variables and built-in defaults.

Red-Team Canaries

NuGuard can watch for seeded canary values during dynamic testing to produce high-confidence exfiltration findings. Start from canary.example.json, create your local canary.json, seed those values into the target system, then point nuguard redteam at that file with --canary.

More detail is available in docs/redteam-engine.md.

Common Commands

nuguard --help
nuguard sbom --help
nuguard analyze --help
nuguard policy --help
nuguard redteam --help
nuguard scan --help

Development

Install dev dependencies:

make dev

Run tests:

make test

Run linting and type checks:

make lint

Format the codebase:

make fmt

Publishing

This repo includes GitHub Actions workflows for Trusted Publishing to TestPyPI and PyPI:

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

Before the workflows can publish, configure Trusted Publishers in TestPyPI and PyPI for the nuguard project with:

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

Recommended release flow:

1. Run the TestPyPI workflow manually from GitHub Actions.
2. Verify the package install and CLI behavior from TestPyPI.
3. Create a GitHub release to trigger the PyPI publish workflow.

Repo Notes

• The repository currently contains example outputs and benchmark fixtures under tests/output/
• Some red-team and benchmark tests are opt-in and gated by environment variables
• LLM-assisted features depend on provider credentials being available via environment variables

License

No license file is currently present in this repository. Add one before treating the project as redistributable open source.