{"id":44730255,"url":"https://github.com/nox-hq/nox","last_synced_at":"2026-06-09T07:01:37.073Z","repository":{"id":337459591,"uuid":"1153069198","full_name":"Nox-HQ/nox","owner":"Nox-HQ","description":"Open-source security scanner with first-class AI app security (prompt injection, embedding leakage, agent over-privilege, MCP hardening). Polyglot AIBOM, SARIF, SBOM. Cosign-signed plugin marketplace. Offline-first, agent-native via MCP.","archived":false,"fork":false,"pushed_at":"2026-06-09T05:42:29.000Z","size":10888,"stargazers_count":0,"open_issues_count":9,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-09T06:28:09.471Z","etag":null,"topics":["ai-security","cli","cosign","devsecops","golang","llm-security","mcp","plugin-marketplace","sarif","sbom","scanner","security","sigstore","static-analysis","supply-chain-security"],"latest_commit_sha":null,"homepage":"https://nox-hq.dev","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Nox-HQ.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":"docs/roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-08T21:10:43.000Z","updated_at":"2026-06-09T05:37:01.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Nox-HQ/nox","commit_stats":null,"previous_names":["nox-hq/nox"],"tags_count":27,"template":false,"template_full_name":null,"purl":"pkg:github/Nox-HQ/nox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nox-HQ%2Fnox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nox-HQ%2Fnox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nox-HQ%2Fnox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nox-HQ%2Fnox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Nox-HQ","download_url":"https://codeload.github.com/Nox-HQ/nox/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Nox-HQ%2Fnox/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34095247,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-09T02:00:06.510Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-security","cli","cosign","devsecops","golang","llm-security","mcp","plugin-marketplace","sarif","sbom","scanner","security","sigstore","static-analysis","supply-chain-security"],"created_at":"2026-02-15T18:12:34.405Z","updated_at":"2026-06-09T07:01:37.066Z","avatar_url":"https://github.com/Nox-HQ.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/logo.png\" alt=\"Nox\" width=\"180\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eNox\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/nox-hq/nox/actions/workflows/ci.yml/badge.svg\" alt=\"CI\" /\u003e\n  \u003cimg src=\".github/nox-badge.svg\" alt=\"Security\" /\u003e\n  \u003cimg src=\".github/coverage-badge.svg\" alt=\"Coverage\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Go-1.25+-00ADD8?logo=go\u0026logoColor=white\" alt=\"Go\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/License-Apache_2.0-blue.svg\" alt=\"License\" /\u003e\n\u003c/p\u003e\n\n**The security scanner for AI application developers.** Open source, offline-first, no SaaS.\n\nIf you're shipping LLM features — `chat.completions.create`, RAG ingest into a vector DB, agents with tool calls, MCP servers — nox is the static analyzer that knows how those break. Plus the boring stuff: secrets, dep CVEs, IaC, container scans.\n\n**What nox catches that other scanners don't:**\n\n- **Prompt injection** at the call site (AI-PI-*, OWASP LLM01)\n- **Embedding leakage** when secrets / PII land in vector stores (AI-EMBED-*, LLM06)\n- **Agent over-privilege** when `file_read` + `http_request` live in the same agent context (AI-AGENT-*, LLM07)\n- **Full MCP threat coverage** mapped to the OWASP MCP Top 10 — server hardening (MCP-001..008), tool poisoning (MCP-009..014, MCP03), rug-pull / definition drift (MCP-015, MCP04), authn/authz \u0026 SSRF (MCP-016..021, MCP07), shadow \u0026 cross-server tool shadowing (MCP-022..024, MCP09)\n- **Cross-file AI taint** — `request.json` → service hop → `chat.completions.create` across functions and files (TAINT-AI-*)\n- **Polyglot AIBOM** — Python ingest + Go service + TS frontend produce one inventory naming every model invocation, auth env var, and endpoint\n- **Verified plugin marketplace** — extension scanners (reachability, cross-file taint, k8s-runtime, red-team chains, GRC for 12 frameworks) install with one command, signed end-to-end via Sigstore\n\nBuilt so you can keep your source local, your CI green, and your CISO answered without paying a per-seat SaaS bill or sending code to a vendor.\n\n\u003e **The MCP scanner that never sees your code.** No API. No token. No telemetry. Deterministic. Run `nox scan --offline` and the scan path makes zero outbound connections — enforced by a test, not a promise (`TestOSVDisabled_NoNetworkEgress`). Unlike scanners that proxy your traffic or phone home to a vendor API, nox runs entirely on your machine.\n\n- **Deterministic** -- same inputs produce same outputs, no hidden state\n- **Offline-first** -- zero required external services\n- **Safe by default** -- never uploads source code, never executes untrusted code, never auto-applies fixes\n- **Agent-native** -- safely callable via the Model Context Protocol (MCP)\n- **Cosign-signed plugin marketplace** -- every official plugin verifies via Sigstore keyless OIDC; default trust policy refuses unsigned third-party drops\n\n## Quick Demo\n\nInstall and scan a project in under a minute:\n\n```bash\n# Install\nbrew tap felixgeelhaar/tap \u0026\u0026 brew install nox\n# or: go install github.com/nox-hq/nox/cli@latest\n\n# Scan the current directory\nnox scan .\n\n# Output:\n# nox dev -- scanning .\n# [results] 12 findings, 47 dependencies, 3 AI components\n# [done]\n```\n\nNox writes `findings.json` to the current directory. To generate all output formats at once:\n\n```bash\nnox scan . --format all --output reports/\n```\n\nThis produces:\n\n```\nreports/\n  findings.json        # Nox canonical findings\n  results.sarif        # SARIF 2.1.0 (GitHub Code Scanning)\n  sbom.cdx.json        # CycloneDX SBOM with vulnerability enrichment\n  sbom.spdx.json       # SPDX SBOM with security references\n  report.html          # Standalone HTML report\n  ai.inventory.json    # AI component inventory (if detected)\n```\n\n### Use in CI (GitHub Action)\n\n```yaml\n# .github/workflows/security.yml\n- uses: nox-hq/nox@24c7f00916ad15e99b6c44cdda8e55f05b869e43 # v0.4.2\n  with:\n    path: '.'\n    format: sarif\n    annotate: 'true'    # Post inline PR comments (default: true)\n- uses: github/codeql-action/upload-sarif@33119e582d3ab4ed79c2610af108cb08ff983917 # v3\n  if: always()\n  with:\n    sarif_file: nox-results/results.sarif\n```\n\n### Use with AI Agents (MCP)\n\n```bash\nnox serve --allowed-paths /path/to/project\n```\n\nThis starts an MCP server on stdio with 10 read-only tools and 5 resources. See [MCP Server](#mcp-server) for details.\n\n## Installation\n\n### Homebrew (macOS/Linux)\n\n```bash\nbrew tap felixgeelhaar/tap\nbrew install nox\n```\n\n### Go\n\n```bash\ngo install github.com/nox-hq/nox/cli@latest\n```\n\n### Build from Source\n\n```bash\ngit clone https://github.com/nox-hq/nox.git\ncd nox\nmake build\n./nox scan .\n```\n\n## What Nox Detects\n\nNox ships with **1506 built-in rules** across five analyzer suites:\n\n### Secrets (938 rules)\n\nDetects hardcoded secrets, API keys, tokens, and credentials across **25+ categories** (938 rules total, competitive with TruffleHog):\n\n| Category | Rules | Examples |\n|----------|-------|---------|\n| Cloud Providers | SEC-001 -- SEC-015 | AWS, GCP, Azure, DigitalOcean, Heroku, Alibaba, IBM, Databricks |\n| Source Control | SEC-003, SEC-016 -- SEC-022 | GitHub PAT/fine-grained/app tokens, GitLab, Bitbucket |\n| Communication | SEC-023 -- SEC-029 | Slack, Discord, Telegram, Microsoft Teams |\n| Payment | SEC-030 -- SEC-038 | Stripe, Square, Shopify, PayPal/Braintree |\n| AI/ML Providers | SEC-039 -- SEC-044 | OpenAI, Anthropic, HuggingFace, Replicate, Cohere |\n| DevOps \u0026 CI/CD | SEC-045 -- SEC-056 | NPM, PyPI, Docker Hub, Terraform, Vault, Grafana |\n| SaaS \u0026 APIs | SEC-057 -- SEC-072 | Twilio, SendGrid, Datadog, PagerDuty, Linear, Okta |\n| Database \u0026 Infra | SEC-073 -- SEC-076 | Connection strings (Postgres, MongoDB, Redis), Firebase |\n| Crypto \u0026 Keys | SEC-004, SEC-077 -- SEC-079 | PEM private keys, Age, PGP, PKCS12 |\n| Generic Patterns | SEC-005, SEC-080 -- SEC-086 | Passwords, secrets, Bearer/Basic auth, JWT, URLs with credentials |\n\n**Secret detection features:**\n- **Shannon entropy analysis** for high-entropy strings (API keys, tokens) with configurable thresholds\n- **Context-aware detection** -- lowers entropy threshold when secret-suggestive keywords (`password`, `secret`, `token`, `key`, etc.) appear on the same line\n- **False-positive hardening** -- automatically filters git SHAs, version strings, file paths, camelCase identifiers, hex checksums, and other non-secret patterns\n- **File-pattern scoping** -- entropy rules only scan source-like files (not lockfiles, checksums, or vendored code)\n- **Configurable via `.nox.yaml`** -- override entropy thresholds per rule (see [Entropy Configuration](#entropy-configuration))\n- Git history scanning to find secrets in past commits\n- Custom rules via YAML definition files (`--rules path/to/rules/`)\n\n### AI Security (50 rules)\n\nDetects AI/ML application security risks aligned with the **OWASP LLM Top 10**:\n\n| Category | Rules | OWASP LLM | Examples |\n|----------|-------|-----------|---------|\n| Prompt Injection | AI-001 -- AI-003, AI-010 | LLM01 | Boundary violations, RAG injection, indirect injection |\n| Tool/Agent Safety | AI-004, AI-005, AI-011 | LLM06 | MCP write tools, wildcard allowlists, unrestricted agents |\n| Insecure Logging | AI-006, AI-007 | LLM02 | Prompt/response logging, API key exposure |\n| Output Handling | AI-009, AI-012, AI-015, AI-018 | LLM05 | eval()/exec(), SQL injection, XSS, path traversal |\n| Information Disclosure | AI-013, AI-016 | LLM02, LLM07 | Stack traces in responses, system prompt leakage |\n| Supply Chain | AI-008, AI-014 | LLM03 | Unpinned models, insecure HTTP model downloads |\n| Resource Management | AI-017 | LLM10 | Unlimited token limits |\n\n### Infrastructure as Code (500 rules)\n\nDetects misconfigurations across **7 IaC categories**:\n\n| Category | Rules | Examples |\n|----------|-------|---------|\n| Dockerfile | IAC-001 -- IAC-003, IAC-022 -- IAC-025 | Root user, unpinned images, secrets in ARG, curl-pipe-sh |\n| Terraform/Cloud | IAC-004 -- IAC-006, IAC-036 -- IAC-045 | Public access, disabled encryption, wildcard IAM, public S3 |\n| Kubernetes | IAC-007 -- IAC-010, IAC-026 -- IAC-035 | Privileged pods, host namespaces, dangerous capabilities, cluster-admin |\n| GitHub Actions | IAC-011 -- IAC-018 | pull_request_target, script injection, mutable action tags, write-all |\n| Docker Compose | IAC-019 -- IAC-021, IAC-049 | Privileged mode, host networking, Docker socket mount |\n| Helm | IAC-046 -- IAC-048 | Tiller deployment, hardcoded passwords, RBAC disabled |\n| CI/CD General | IAC-050 | Disabled security checks |\n\n### Dependencies \u0026 SCA (6 rules)\n\nParses lockfiles from **8 ecosystems** (Go, npm, PyPI, RubyGems, Cargo, Maven, Gradle, NuGet) and queries the [OSV.dev](https://osv.dev) database for known vulnerabilities:\n\n| Rule | Description |\n|------|-------------|\n| VULN-001 | Known vulnerability in dependency (severity mapped from CVSS) |\n\n- Batches queries to the OSV.dev API (up to 1000 packages per request)\n- CVSS scores mapped to nox severity levels (Critical/High/Medium/Low/Info)\n- Graceful degradation on network errors (offline-first)\n- Disable with `--no-osv` flag or `scan.osv.disabled: true` in `.nox.yaml`\n- Vulnerability data enriches CycloneDX and SPDX SBOM output\n\n### Data Protection (12 rules)\n\nDetects personally identifiable information (PII) and sensitive data patterns in code and configuration:\n\n| Category | Rules | Examples |\n|----------|-------|---------|\n| Contact Info | DATA-001, DATA-004 | Email addresses, US phone numbers |\n| Financial | DATA-003, DATA-007 | Credit card numbers (Visa/MC/Amex/Discover), IBAN |\n| Government IDs | DATA-002, DATA-008 -- DATA-012 | SSN, UK National Insurance, Tax IDs, driver's license, passport |\n| Health | DATA-010 | Health record identifiers (MRN, patient_id) |\n| Infrastructure | DATA-005 | Hardcoded public IP addresses |\n| Personal | DATA-006 | Date of birth fields |\n\n## Configuration\n\nCreate a `.nox.yaml` in your project root to customize scan behavior:\n\n```yaml\nscan:\n  exclude:\n    - \"vendor/\"\n    - \"testdata/\"\n    - \"*.test.js\"\n  osv:\n    disabled: false          # Set true to skip OSV lookups (offline mode)\n  rules:\n    disable:\n      - \"AI-008\"           # Unpinned model refs OK here\n    severity_override:\n      SEC-005: low          # Downgrade for this project\n\noutput:\n  format: sarif             # Default output format\n  directory: reports        # Default output directory\n\npolicy:\n  fail_on: high             # Only fail on high+ severity (critical, high)\n  warn_on: medium           # Warn on medium findings\n  baseline_mode: warn       # warn | strict | off\n  baseline_path: \"\"         # Default: .nox/baseline.json\n\nexplain:\n  api_key_env: OPENAI_API_KEY   # Env var to read API key from\n  model: gpt-4o                 # LLM model name\n  base_url: \"\"                  # Custom OpenAI-compatible endpoint\n  timeout: 2m                   # Per-request timeout\n  batch_size: 10                # Findings per LLM request\n  output: explanations.json     # Output file path\n```\n\nCLI flags always take precedence over config file values.\n\n### Entropy Configuration\n\nFine-tune entropy-based secret detection thresholds via `.nox.yaml`:\n\n```yaml\nscan:\n  entropy:\n    threshold: 5.0           # General entropy threshold (default: 5.0)\n    hex_threshold: 4.5       # Threshold for hex strings (default: rule-specific)\n    base64_threshold: 5.2    # Threshold for base64 strings (default: rule-specific)\n    require_context: true    # Only flag when secret keyword is present (default: false)\n```\n\n- **`threshold`** -- Minimum Shannon entropy (bits per character) to flag a candidate string. Higher values reduce false positives; lower values catch more secrets.\n- **`require_context`** -- When `true`, only flag high-entropy strings on lines that contain secret-suggestive keywords (`password`, `secret`, `key`, `token`, `credential`, `api_key`, `private`). Useful for reducing noise in codebases with many random-looking constants.\n- **Context boost** -- When a secret keyword is present on the same line, the effective threshold is automatically reduced by 0.5 bits, increasing sensitivity where it matters.\n\n### Baseline Management\n\nManage known findings to track progress and suppress accepted risks:\n\n```bash\n# Create a baseline from all current findings\nnox baseline write .\n\n# Write to a specific file\nnox baseline write . --output my-baseline.json\n\n# Update baseline (add new, prune stale)\nnox baseline update .\nnox baseline update . --baseline my-baseline.json\n\n# Show baseline statistics\nnox baseline show .\n```\n\n### Inline Suppressions\n\nSuppress specific findings directly in source code:\n\n```go\n// nox:ignore SEC-001 -- false positive in test\nvar testKey = \"AKIAEXAMPLEFAKEKEY\"\n\nvar apiKey = \"test\" // nox:ignore SEC-005\n```\n\nSupports all comment styles: `//`, `#`, `--`, `/*`, `\u003c!--`. Multi-rule: `nox:ignore SEC-001,SEC-002`. Expiring: `nox:ignore SEC-001 -- expires:2025-12-31`.\n\n### Diff Mode\n\nShow only findings in changed files:\n\n```bash\nnox diff --base main --head HEAD\nnox diff --base main --json\nnox diff . --rules custom-rules.yaml\n```\n\n### Watch Mode\n\nRe-scan automatically on file changes:\n\n```bash\nnox watch .\nnox watch . --debounce 1s\nnox watch . --json\n```\n\n### Finding Inspector\n\nInspect findings interactively with a TUI or as JSON:\n\n```bash\n# Interactive TUI\nnox show .\n\n# Filter by severity, rule, or file\nnox show . --severity critical,high --rule \"SEC-*\" --file \"src/\"\n\n# JSON output from a previous scan\nnox show --input findings.json --json\n\n# Control source context lines\nnox show . --context 10\n```\n\n### LLM-Powered Explanations\n\nGenerate human-readable explanations of findings using any OpenAI-compatible API:\n\n```bash\nexport OPENAI_API_KEY=sk-...\nnox explain . --model gpt-4o --output explanations.json\n\n# With custom endpoint and timeout\nnox explain . --base-url http://localhost:11434/v1 --model llama3 --timeout 5m\n\n# Control batch size for large scans\nnox explain . --batch-size 20\n\n# Enrich with plugin data\nnox explain . --plugin-dir ./plugins --enrich threat-intel.lookup\n```\n\nThis produces per-finding explanations with remediation guidance and an executive summary. The explain module is optional and never affects scan results.\n\n### Security Badge\n\nGenerate an SVG security grade badge:\n\n```bash\n# Generate from a live scan\nnox badge .\n\n# From existing findings\nnox badge --input findings.json\n\n# Custom output path and label\nnox badge . --output status.svg --label \"security\"\n\n# Generate per-severity breakdown badges\nnox badge . --by-severity\n```\n\n### Security Dashboard\n\nGenerate a standalone HTML dashboard with security grade, severity breakdown, and dependency overview:\n\n```bash\n# Generate and open in browser\nnox dashboard .\n\n# Save to a specific path\nnox dashboard . --output reports/dashboard.html --no-browser\n```\n\nThe dashboard is a single self-contained HTML file with no external dependencies — share it, embed it, or archive it.\n\n### Shell Completions\n\n```bash\n# Bash\neval \"$(nox completion bash)\"\n\n# Zsh\nnox completion zsh \u003e \"${fpath[1]}/_nox\"\n\n# Fish\nnox completion fish | source\n\n# PowerShell\nnox completion powershell | Out-String | Invoke-Expression\n```\n\n### PR Annotations\n\nPost inline review comments on GitHub PRs:\n\n```bash\nnox annotate --input findings.json --pr 123 --repo owner/name\n```\n\nAuto-detects PR number and repo from `GITHUB_REF` and `GITHUB_REPOSITORY` environment variables in CI.\n\n### Pre-commit Hooks\n\nBlock commits that contain secrets or security issues:\n\n```bash\n# Install the nox pre-commit hook\nnox protect install\n\n# With custom severity threshold\nnox protect install --severity-threshold critical\n\n# Force overwrite existing hook\nnox protect install --force\n\n# Custom hook path\nnox protect install --hook-path /path/to/.git/hooks/pre-commit\n\n# Check status\nnox protect status\n\n# Remove\nnox protect uninstall\n```\n\n**For nox contributors**, install the project-level hook that also runs gofmt, go vet, and golangci-lint (including gocritic) -- matching CI:\n\n```bash\nmake hooks\n```\n\n## CLI Reference\n\n```\nnox \u003ccommand\u003e [flags]\n\nCommands:\n  scan \u003cpath\u003e              Scan a directory for security issues\n  show [path]              Inspect findings interactively (TUI or JSON)\n  explain \u003cpath\u003e           Explain findings using an LLM\n  badge [path]             Generate an SVG status badge\n  baseline \u003ccmd\u003e [path]    Manage finding baselines (write, update, show)\n  diff [path]              Show findings in changed files only\n  watch [path]             Watch for changes and re-scan automatically\n  annotate                 Annotate a GitHub PR with inline findings\n  protect \u003ccmd\u003e [path]     Manage git pre-commit hooks (install, uninstall, status)\n  completion \u003cshell\u003e       Generate shell completions (bash, zsh, fish, powershell)\n  dashboard [path]         Generate an interactive HTML security dashboard\n  cache \u003ccmd\u003e              Manage scan cache (clear, status)\n  serve                    Start MCP server on stdio\n  registry \u003ccmd\u003e           Manage plugin registries (add, list, remove)\n  plugin \u003ccmd\u003e             Manage and invoke plugins (search, info, install, update,\n                              list, remove, call, init, test, entry)\n  vex \u003ccmd\u003e                OpenVEX waiver document tools (vex init)\n  install-hook             Install pre-commit/pre-push git hooks\n  fix                      Apply OSV fixed_in remediation upgrades (go/npm/pypi/cargo)\n  doctor                   Report environment, plugin state, config sanity\n  agent-graph              Render agent capability lattice (mermaid/dot)\n  bench                    Scan a corpus directory; report rule fire-rates\n  calibrate                Suggest severity overrides from a bench report\n  version                  Print version and exit\n\nGlobal Flags:\n  --rules string           Path to custom rules YAML file or directory\n  --quiet, -q              Suppress output except errors\n  --verbose, -v            Verbose output\n\nScan Flags:\n  --format string          Output formats: json, sarif, cdx, spdx, html, all (default: json)\n  --output string          Output directory (default: .)\n  --staged                 Scan only git-staged files\n  --severity-threshold     Minimum severity to report (critical, high, medium, low)\n  --no-osv                 Disable OSV.dev vulnerability lookups (offline mode)\n  --no-cache               Disable incremental scan cache\n  --changed-since string   Only scan files changed since git ref\n\nShow Flags:\n  --severity string        Filter by severity (comma-separated: critical,high,medium,low,info)\n  --rule string            Filter by rule pattern (e.g., AI-*, SEC-001)\n  --file string            Filter by file pattern (e.g., src/)\n  --input string           Path to findings.json (default: run scan)\n  --json                   Output JSON instead of interactive TUI\n  --context int            Number of source context lines (default: 5)\n\nExplain Flags:\n  --model string           LLM model name (default: gpt-4o)\n  --base-url string        Custom OpenAI-compatible API base URL\n  --batch-size int         Findings per LLM request (default: 10)\n  --output string          Output file path (default: explanations.json)\n  --plugin-dir string      Directory containing plugin binaries for enrichment\n  --enrich string          Comma-separated list of plugin tools to invoke\n  --timeout duration       Timeout per LLM request (default: 2m)\n\nBadge Flags:\n  --input string           Path to findings.json (default: run scan)\n  --output string          Output SVG file path (default: .github/nox-badge.svg)\n  --label string           Badge label text (default: nox)\n  --by-severity            Generate additional badges per severity level\n\nDiff Flags:\n  --base string            Base git ref for comparison (default: main)\n  --head string            Head git ref for comparison (default: HEAD)\n  --json                   Output as JSON\n\nWatch Flags:\n  --debounce duration      Debounce interval for file changes (default: 500ms)\n  --json                   Output as JSON\n\nProtect Flags:\n  --severity-threshold     Minimum severity to block commit (default: high)\n  --hook-path string       Custom path to pre-commit hook file\n  --force                  Overwrite existing hook without prompting\n\nBaseline Flags:\n  --output string          Baseline file path for write (default: .nox/baseline.json)\n  --baseline string        Baseline file path for update (default: .nox/baseline.json)\n\nAnnotate Flags:\n  --input string           Path to findings.json (default: findings.json)\n  --pr string              PR number (auto-detected from GITHUB_REF)\n  --repo string            Repository owner/name (auto-detected from GITHUB_REPOSITORY)\n\nDashboard Flags:\n  --output string          Output HTML file path (default: temp file)\n  --no-browser             Write HTML file without opening browser\n\nCache Commands:\n  clear                    Clear the scan cache\n  status                   Show cache statistics\n\nServe Flags:\n  --allowed-paths string   Comma-separated list of allowed workspace paths\n\nExit Codes:\n  0   No findings (or policy pass)\n  1   Findings detected (or policy fail)\n  2   Error\n```\n\nSee [`docs/usage.md`](docs/usage.md) for the full CLI reference.\n\n## Architecture\n\nSix top-level packages with strict dependency direction (`core` depends on nothing):\n\n```\ncore/       Scan engine, rule catalog, report generation (no CLI, no network)\ncli/        Argument parsing, TUI, output handling\nserver/     MCP server (stdio, sandboxed, rate-limited)\nplugin/     gRPC-based plugin host with safety profiles\nsdk/        Plugin authoring SDK with conformance tests\nregistry/   Plugin registry client (index + OCI distribution)\nassist/     Optional LLM-powered explanations (no side effects)\n```\n\n### Scan Pipeline\n\n```\n1. Load config (.nox.yaml)\n2. Discover artifacts (respects .gitignore + excludes)\n3. Run analyzers (secrets, IaC, AI security, dependencies)\n4. Apply rule config (disable, severity override)\n5. Deduplicate by fingerprint\n6. Sort deterministically\n7. Apply inline suppressions (nox:ignore)\n8. Apply baseline matching\n9. Evaluate policy (pass/fail thresholds)\n10. Emit reports (JSON, SARIF, CycloneDX, SPDX)\n```\n\n## Plugin Ecosystem\n\nNox supports a gRPC-based plugin system organized into **10 security tracks**, enabling extensibility into domains like DAST, CSPM, secret verification, and more -- without bloating the core scanner:\n\n| Track | Purpose | Example Capabilities |\n|-------|---------|---------------------|\n| core-analysis | Static analysis, secrets, code patterns | Custom SAST rules, language-specific analysis |\n| dynamic-runtime | Runtime behavior and dynamic analysis | DAST scanning, runtime security monitoring |\n| ai-security | AI/ML-specific security concerns | Model supply chain, prompt fuzzing |\n| threat-modeling | Threat identification and modeling | STRIDE analysis, attack surface mapping |\n| supply-chain | Dependency and supply chain security | Malicious package detection, license compliance |\n| intelligence | Threat intelligence integration | Secret verification, IOC enrichment |\n| policy-governance | Policy enforcement and compliance | CSPM, regulatory compliance checks |\n| incident-readiness | Incident response preparation | Runbook validation, playbook testing |\n| developer-experience | Developer tooling and feedback | Fix suggestions, IDE integrations |\n| agent-assistance | AI agent integration and safety | Agent guardrails, tool safety verification |\n\nEach track has built-in safety profiles that control what plugins can and cannot do (e.g., `passive` plugins are read-only, `active` plugins can write files, `runtime` plugins can execute code).\n\n### Scaffold a Plugin\n\n```bash\nnox plugin init --name my-scanner --track core-analysis\ncd nox-plugin-my-scanner\nmake test\n```\n\nAdditional init flags:\n- `--risk-class \u003cpassive|active|runtime\u003e` -- Override the default risk class for the track\n- `--output \u003cdir\u003e` -- Custom output directory\n\nSee [`docs/plugin-authoring.md`](docs/plugin-authoring.md) for the full SDK guide.\n\n### Install and Use Plugins\n\nThe official registry is auto-added on first run; no `nox registry add` needed for the public set. Operators add private registries on top.\n\n**Recommended: declare plugins in `.nox.yaml`** so anyone cloning your project gets the right set automatically:\n\n```yaml\n# .nox.yaml\nplugins:\n  required:\n    - nox/reachability@\u003e=0.5\n    - nox/ai-eval\n    - nox/taint-analysis\n  registries:\n    # Project-level registry overrides; merged with the official source.\n    # Use `name=url` to assign a name.\n    - acme=https://registry.acme.internal/nox/index.json\n```\n\n```bash\nnox install                       # reads plugins.required, fetches each\nnox scan .                        # auto-installs missing required plugins\nnox scan . --no-auto-install      # opt out\n```\n\n**One-shot install (no manifest):**\n\n```bash\n# Search and install (registry auto-configured)\nnox plugin search ai\nnox plugin search --track ai-security\nnox plugin install nox/ai-eval\nnox plugin install nox/reachability@0.5.0\n\n# Inspect, run, update, remove\nnox plugin info nox/ai-eval\nnox plugin list\nnox plugin call ai-eval ai_eval endpoint=http://localhost:8080/chat\nnox plugin update nox/ai-eval\nnox plugin remove nox/ai-eval\n\n# Add a private / enterprise registry on top\nnox registry add https://registry.acme.internal/nox/index.json --name acme\nnox registry list\nnox registry remove acme\n```\n\nAll plugins in the official registry ship Cosign-signed (keyless via\nGitHub OIDC). The default trust policy is `default`: nox downloads\nthe release's `checksums.txt` + Sigstore bundle, verifies the bundle\nagainst the plugin's `release.yml` workflow OIDC subject, and\nconfirms the artifact's SHA-256 is listed in the signed checksums.\nInstall fails closed unless either Cosign keyless **or** an in-tool\nEd25519 signature passes; operators bypass with `--allow-unverified`\nor `plugins.trust_policy: permissive` in `.nox.yaml`. See\n[`docs/marketplace.md`](docs/marketplace.md) for the trust model\ndetails.\n\n```bash\n$ nox plugin install nox/reachability\nTrust: community (signer: cosign-keyless:(?i)https://github.com/nox-hq/nox-plugin-reachability/.github/workflows/release.yml@.*)\nInstalled nox/reachability@0.6.5 (community)\n```\n\n### Currently published plugins\n\n| Plugin | Track | What it adds |\n|---|---|---|\n| `nox/reachability` | core-analysis | Multi-language reachability for VULN findings (Go, PyPI, npm, Cargo, Maven, RubyGems, NuGet). Bundled in the default release archive. |\n| `nox/taint-analysis` | core-analysis | Cross-file taint flow. TAINT-001..005 + interprocedural TAINT-006/007 + AI flows TAINT-AI-001/002. |\n| `nox/k8s-runtime` | dynamic-runtime | Live cluster scanning. KRUNT-001..008. |\n| `nox/red-team` | dynamic-runtime | Attack-chain analysis + active validation. |\n| `nox/grc` | policy-governance | 12 compliance frameworks (SOC2, ISO 27001, GDPR, FedRAMP L/M/H, HIPAA, PCI-DSS, NIST 800-53, NIST CSF, CIS v8, CMMC). |\n| `nox/ai-eval` | dynamic-runtime | Adversarial prompt corpus runner. Fires jailbreak / system-leak / role-confusion / tool-misuse against a chat endpoint. AI-EVAL-001..004. |\n\n### Publish a plugin\n\n```bash\n# Tag the plugin repo. The release workflow builds binaries via\n# GoReleaser, signs the checksums via Cosign keyless, generates a\n# registry entry, and uploads it as a workflow artifact.\ngit tag v0.2.0 \u0026\u0026 git push --tags\n\n# Open a PR against nox-hq/nox to add the entry to\n# registry-scaffold/index.json. Operators see the new version in\n# `nox plugin search` once the PR merges.\n```\n\nSee [`docs/marketplace.md`](docs/marketplace.md) for the full publish flow and the maturity ladder. A public marketplace site rendered from the same index is published at [`nox-hq.github.io/nox`](https://nox-hq.github.io/nox/).\n\n## MCP Server\n\nThe built-in MCP server allows AI agents to invoke scans safely:\n\n```bash\nnox serve --allowed-paths /path/to/project\n```\n\n### Tools\n\n| Tool | Parameters | Description |\n|------|-----------|-------------|\n| `scan` | `path` (required) | Run a security scan on a directory |\n| `get_findings` | `format` (json\\|sarif) | Get findings from last scan |\n| `get_sbom` | `format` (cdx\\|spdx) | Get software bill of materials |\n| `get_finding_detail` | `finding_id`, `context_lines` | Get enriched finding with source context |\n| `list_findings` | `severity`, `rule`, `file`, `limit` | List findings with filtering |\n| `baseline_status` | `path` | Get baseline statistics |\n| `baseline_add` | `path`, `fingerprint`, `reason` | Add finding to baseline |\n| `plugin.list` | -- | List registered plugins |\n| `plugin.call_tool` | `tool`, `input`, `workspace_root` | Invoke a plugin tool |\n| `plugin.read_resource` | `plugin`, `uri` | Read a plugin resource |\n\n### Resources\n\n| URI | Type | Description |\n|-----|------|-------------|\n| `nox://findings` | application/json | Canonical findings |\n| `nox://sarif` | application/json | SARIF 2.1.0 report |\n| `nox://sbom/cdx` | application/json | CycloneDX SBOM |\n| `nox://sbom/spdx` | application/json | SPDX SBOM |\n| `nox://ai-inventory` | application/json | AI component inventory |\n\nAll tools are read-only. Output is truncated at 1 MB. Workspace paths are allowlisted.\n\n## Contributing\n\nContributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, coding standards, and the pull request process.\n\n## Security\n\nFor reporting security vulnerabilities, please see [SECURITY.md](SECURITY.md).\n\n## License\n\nNox is licensed under the [Apache License 2.0](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnox-hq%2Fnox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnox-hq%2Fnox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnox-hq%2Fnox/lists"}