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 nox

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

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@v0.9.5
        with:
          path: '.'
          format: sarif
          annotate: 'true'   # inline PR comments
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

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.

nox scan . --format html --output report.html
nox dashboard .

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                 # 12 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.sig.bundle \
  --new-bundle-format \
  checksums.txt

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"]
    }
  }
}