NOX is a modular, Go based attack surface management and vulnerability scanning framework. It ships with 300 built in modules covering OSINT, subdomain enumeration, DNS, port scanning, web fingerprinting, and deep active vulnerability testing across injection, authentication, authorization, client side, cloud, API, and business logic vulnerability classes.
Authorization notice. NOX performs real network requests against the systems you point it at. Only run active or deep scans against systems you own or have explicit written authorization to test. Unauthorized testing is illegal.
1. What NOX does
NOX gives you three ways to run a scan, depending on how much control you want:
nox full <domain>runs all 300 modules in a fixed, sensible order, with live progress in the terminal. One command, no setup.nox scan --workflow <file>runs a YAML workflow: your own stage graph, with parallel stages, dependencies, retries, and checkpoints, so it can resume after an interruption.nox proberuns just the HTTP prober, directly, for a fast liveness and technology check on a list of hosts.
Every module implements the same Go interface, so it works the same way no matter which command runs it. See docs/architecture for the full design.
2. Architecture at a glance
flowchart TD
CLI["CLI<br/>full, scan, resume, probe, health-check,<br/>modules, report, version, wordlists"]
APP["App<br/>config, logger, registry, storage, engine"]
FULL["nox full<br/>24 phase hard coded chain"]
WF["Workflow engine<br/>parses YAML, sorts stages by dependency"]
ENGINE["Scan engine<br/>retries, rate limiting, persistence"]
REG["Module registry<br/>300 modules"]
STORE["Storage<br/>sqlite, bolt, or memory"]
CLI --> APP
CLI -->|nox full| FULL --> REG
CLI -->|nox scan --workflow| WF --> ENGINE
APP --> ENGINE
APP --> REG
ENGINE --> REG
ENGINE --> STORE
nox full and nox scan --workflow workflows/full.yaml run the same 300 modules, in the same 24 phase order. See docs/modules for the complete phase by phase module list and diagram.
3. Install
NOX is written in Go and requires Go 1.25 or newer, plus CGO enabled for the default SQLite storage backend.
git clone https://github.com/kernelstub/nox.git
cd nox
./scripts/build.sh
This produces a nox binary in dist/. To install it into $GOPATH/bin instead:
./scripts/build.sh --output "$(go env GOPATH)/bin/nox"
Other useful scripts:
./scripts/install-deps.sh # install external tools NOX modules shell out to (nuclei, nmap, chromium, ...)
./scripts/release.sh # cross compile + archive for Linux, macOS (amd64 and arm64), and Windows, into dist/release/
go test ./..., go vet ./..., and gofmt cover testing/linting; there's no wrapper script for those. A Dockerfile and docker-compose.yml are also provided if you prefer to run NOX in a container (docker build -t nox .).
4. Quick start
nox --help
# A safe, read only pass: OSINT, subdomains, and web fingerprinting only.
nox scan --workflow workflows/passive.yaml --target example.com
# A fast three stage check: subdomains, HTTP probe, TLS.
nox scan --workflow workflows/quick.yaml --target example.com
# Everything NOX has, in real world order. Requires authorization.
nox full example.com --mode active --output ./results
# Just check which hosts are alive.
nox probe -l targets.txt --threads 50 --json
Every module can also run on its own:
nox modules list
nox modules run whois --target example.com
See docs/scans/recipes.md for a longer list of ready to use commands, including deep scans, full coverage scans, subdomain focused runs, JSON output, and distributed scanning.
5. Commands
| Command | Purpose |
|---|---|
nox full <domain> |
Run all 300 modules in a fixed, real world order. |
nox scan |
Run a scan directly, or through a workflow YAML file with --workflow. Supports --baseline <scan-id> to diff against a previous run. |
nox resume |
Resume a previously paused or failed scan by scan ID. |
nox probe |
Fast, standalone HTTP prober, similar to httpx. |
nox schedule |
Manage recurring scans via the system crontab — no background daemon required. |
nox modules list / nox modules run |
List or run individual modules. |
nox health-check |
Verify that all NOX subsystems are operational. |
nox report |
Generate a JSON, HTML, or Markdown report from a completed scan. |
nox file-issues |
File confirmed findings from a completed scan as GitHub Issues via your own gh CLI auth. |
nox audit verify |
Verify the hash chain of a --audit-log file hasn't been tampered with. |
nox wordlists |
Download and manage wordlists used by bruteforce and fuzzing modules. |
nox version |
Show version, build commit, and runtime information. --check looks up the latest GitHub release and reports whether you're up to date. |
Run nox <command> --help for the full flag reference for any command. See docs/scans for the complete command and workflow reference.
6. The 300 modules
Modules are organized into 24 phases, matching the order nox full runs them in: OSINT and passive intelligence first, then subdomain and DNS discovery, then port scanning and web fingerprinting, then 18 phases of progressively deeper active vulnerability testing, finishing with reporting and enrichment.
| Phase group | Example phases |
|---|---|
| Recon | OSINT and passive intelligence, subdomain enumeration, DNS resolution, port scan, HTTP probe and web fingerprinting |
| Core vulnerability scanning | Nuclei, XSS, SQLi, SSRF, TLS, security headers |
| Deep vulnerability testing | Session and auth security, authorization, client side security, cloud vulnerabilities, injection variants, cross site scripting, API security, cache and CORS, browser security policies |
| Specialized testing | Content discovery, file download vulnerabilities, deserialization, secrets and source exposure, email vulnerabilities, mobile API security, business logic abuse, AI and LLM security |
| Output | Reporting and enrichment: CWE, OWASP, CAPEC, and EPSS mapping |
See docs/modules for the full list of all 300 modules with descriptions, grouped by phase.
7. Configuration
NOX uses layered configuration: built in defaults, then an optional YAML file passed with --config, then NOX_ prefixed environment variables, then command line flags.
cp configs/nox.yaml ~/.nox/config.yaml
# edit ~/.nox/config.yaml
nox scan --config ~/.nox/config.yaml --target example.com
See docs/configuration for the full field reference, including scan limits, scope rules, storage backends, notification channels, and the NOX data directory layout under ~/.nox/.
8. Documentation
The full documentation set lives under docs/, organized into one folder per topic:
| Guide | Covers |
|---|---|
| docs/architecture/ | How the CLI, app layer, engines, module interface, and storage fit together, and how to add a new module. |
| docs/scans/ | Every scan command, scan modes, the workflow file format, checkpoints, and reports. |
| docs/modules/ | All 300 modules, grouped into the 24 phases nox full runs, with a diagram of the execution order. |
| docs/configuration/ | Every configuration field, its default, and its environment variable. |
9. Development
make test # run tests with the race detector
make test-coverage # generate and open an HTML coverage report
make lint # run golangci-lint
make fmt # format all Go source with gofmt
make vet # run go vet
Continuous integration runs the test suite and linter on every push, defined in .github/workflows/ci.yml. Releases are cut with GoReleaser, defined in .github/workflows/release.yml.
To cut a release: bump the version, sanity-build, commit, tag, and push in one step with ./scripts/commit.sh:
./scripts/commit.sh v1.0.2 "commit message" # asks for confirmation before pushing
./scripts/commit.sh v1.0.2 "commit message" --yes # skip the confirmation
This runs ./scripts/build.sh as a sanity check, bumps the hardcoded version strings (internal/config/config.go, configs/nox.yaml, docs/configuration/sections/app.md), re-verifies with go vet/go build, then commits, tags, and pushes. Pushing the tag triggers .github/workflows/release.yml (GoReleaser).
To add a new module, see docs/architecture/adding-a-module.md.
Comments