Get started

From install to enforcement in minutes.

Start with the smallest useful workflow, then add CI enforcement and plugins incrementally.

Install

Choose the install method that fits your environment.

Homebrew

brew install felixgeelhaar/tap/nox

Tap-qualified on purpose: a bare brew install nox resolves to an unrelated package in homebrew-core.

go install github.com/nox-hq/nox/cli@latest

Docker

docker run --rm -v $(pwd):/workspace ghcr.io/nox-hq/nox scan /workspace

Build from source

git clone https://github.com/nox-hq/nox.git
cd nox && go build -o nox ./cli

First scan

Run a full scan with zero configuration. Nox auto-discovers files, lockfiles, and AI components.

nox scan .

nox — scanning .
[results] 12 findings, 47 dependencies, 3 AI components
[done] wrote findings.json

If a check could not complete — OSV unreachable, a required plugin missing, a lockfile nox cannot parse — it is reported as a [degraded] line on stderr and recorded in findings.json under meta.degradations, rather than passing as a clean scan. Add --fail-on-degraded to make CI treat that as failure.

CI integration

Add Nox to your GitHub Actions workflow with inline PR annotations and SARIF upload for Code Scanning alerts.

name: Security Scan
on: [push, pull_request]
jobs:
  nox:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: nox-hq/nox@v1
        with:
          path: '.'
          format: sarif
          annotate: 'true'          # inline PR comments
          severity-threshold: high
          fail-on-degraded: 'true'  # a check that could not run fails the job
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

SARIF carries security-severity, so Code Scanning can sort, filter and write alert rules against Nox findings rather than treating every alert alike.

Automated dependency remediation

Open a PR that upgrades vulnerable dependencies on a schedule, with the project's own test suite as the gate.

name: Nox Remediation
on:
  schedule:
    - cron: '0 3 * * 1-5'
  workflow_dispatch:
permissions:
  contents: write
  pull-requests: write
jobs:
  remediate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: nox-hq/nox-remediate-action@v1
        with:
          path: .
          verify-cmd: 'go test ./...'

Dashboard

Generate a standalone HTML report for visual inspection and team review. It is written from an existing findings.json, and honors SOURCE_DATE_EPOCH so the output is reproducible.

nox dashboard .                              # opens in your browser
nox dashboard . --no-browser --output report.html

Configure

Create a .nox.yaml to customize severity thresholds, rule overrides, and output paths.

# .nox.yaml
severity: medium
formats:
  - json
  - sarif
  - cdx
output: reports/
rules:
  SEC-042:
    severity: critical
  IAC-101:
    enabled: false
suppress:
  - id: SEC-007
    reason: "Test credential, rotated weekly"
    expires: "2026-06-01"

Declare plugins (.nox.yaml)

Treat security plugins like dependencies. Pin them in .nox.yaml so anyone cloning your repo gets the same verified set on first scan.

# .nox.yaml — package.json for security
plugins:
  required:
    - nox/reachability        # filter VULN by import reachability
    - nox/taint-analysis      # cross-file + AI taint flow
    - nox/k8s-runtime         # live cluster scanning
    - nox/grc                 # 10 compliance frameworks
  trust_policy: default       # require Cosign keyless or Ed25519

# First scan auto-installs missing required plugins.
# Verified end-to-end via Sigstore — install fails closed
# on unsigned third-party drops.

nox install                  # fetch all required plugins
nox scan .                   # auto-installs if missing

Verify a release out-of-band

Every plugin in the official registry signs its checksums via Sigstore keyless OIDC. The same chain Nox runs at install — reproducible by hand:

cosign verify-blob \
  --certificate-identity-regexp \
    "https://github.com/nox-hq/nox-plugin-reachability/.github/workflows/release.yml@.*" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --bundle checksums.txt.sigstore.json \
  --new-bundle-format \
  checksums.txt

Plugin releases sign with cosign v4, which writes a single checksums.txt.sigstore.json bundle and no detached .sig.

Give your AI agent secure access (MCP)

Let Claude / Cursor / any MCP-aware agent read scan results without giving it write access or shell. Read-only tools, workspace allowlisting, output size limits.

# claude_desktop_config.json (or your MCP host)
{
  "mcpServers": {
    "nox": {
      "command": "nox",
      "args": ["serve", "--allowed-paths", "/path/to/repo"]
    }
  }
}