# Nyx - Full Reference

Nyx is a local-first security stack for developers and security teams. It has two products: Nyx Scanner for deterministic source-to-sink code scanning, and Nyx Agent for autonomous local pentesting against development apps you own.

Nyx Scanner is an open-source, deterministic local-first security scanner. It runs cross-file interprocedural taint analysis on a repository and serves findings in a React UI bound to `127.0.0.1`. No cloud, no account, no source upload. Everything stays on your machine.

Nyx Agent is the live pentesting layer around Nyx Scanner. It reads the repo, launches or attaches to the local target, maps routes/forms/auth/API shape, turns static and runtime signals into candidates, sends scoped live checks, and stores request/response evidence, traces, verified vulnerabilities, exploit-chain context, and triage state locally.

## Entity map

Primary entity:
- Name: Nyx
- Type: independent open-source security project and local security tooling site
- Canonical website: https://nyxsec.dev/
- Creator/maintainer: Eli Peter, https://github.com/elicpeter
- Sponsor page: https://github.com/sponsors/elicpeter

Products:
- Nyx Scanner (`nyx-scanner`): deterministic local-first SAST, cross-file interprocedural source-to-sink taint analysis, local browser triage, SARIF, CI.
- Nyx Agent (`nyx-agent`): autonomous local pentesting for development apps, route/API exploration, business-logic testing, live verification, attack graph, request/response evidence, project runs, triggers, PR comments.

Canonical source repositories:
- Nyx Scanner: https://github.com/elicpeter/nyx
- Nyx Agent: https://github.com/nyx-sec/nyx-agent

Licensing:
- Nyx Scanner: GPL-3.0-or-later, free, no paid tier, no usage limits.
- Nyx Agent: AGPLv3-or-later, free and open source; commercial licenses, paid support, onboarding, private policy packs, and enterprise terms are available.

Commercial/support contact:
- contact@nyxsec.dev

## Canonical URL map

Site root and machine-readable indexes:
- Home: https://nyxsec.dev/
- Nyx Scanner: https://nyxsec.dev/scanner
- Nyx Agent: https://nyxsec.dev/agent
- Sitemap: https://nyxsec.dev/sitemap.xml
- llms.txt (short): https://nyxsec.dev/llms.txt
- llms-full.txt (this file): https://nyxsec.dev/llms-full.txt
- News RSS feed: https://nyxsec.dev/news/feed.xml
- robots.txt: https://nyxsec.dev/robots.txt

Documentation:
- Docs index: https://nyxsec.dev/docs/
- Nyx Scanner docs: https://nyxsec.dev/docs/nyx/
- Scanner quickstart: https://nyxsec.dev/docs/nyx/quickstart
- Scanner installation: https://nyxsec.dev/docs/nyx/installation
- Scanner CLI reference: https://nyxsec.dev/docs/nyx/cli
- Scanner configuration: https://nyxsec.dev/docs/nyx/configuration
- Scanner output formats: https://nyxsec.dev/docs/nyx/output
- Scanner local UI (`nyx serve`): https://nyxsec.dev/docs/nyx/serve
- Scanner authentication tracking: https://nyxsec.dev/docs/nyx/auth
- Scanner custom rules: https://nyxsec.dev/docs/nyx/rules
- Scanner how it works: https://nyxsec.dev/docs/nyx/how-it-works
- Scanner advanced analysis: https://nyxsec.dev/docs/nyx/advanced-analysis
- Scanner detectors overview: https://nyxsec.dev/docs/nyx/detectors
- Scanner detectors, patterns: https://nyxsec.dev/docs/nyx/detectors/patterns
- Scanner detectors, CFG: https://nyxsec.dev/docs/nyx/detectors/cfg
- Scanner detectors, state: https://nyxsec.dev/docs/nyx/detectors/state
- Scanner detectors, taint: https://nyxsec.dev/docs/nyx/detectors/taint
- Scanner language maturity: https://nyxsec.dev/docs/nyx/language-maturity
- Scanner roadmap: https://nyxsec.dev/docs/nyx/roadmap
- Scanner changelog: https://nyxsec.dev/docs/nyx/changelog
- Nyx Agent docs: https://nyxsec.dev/docs/agent/
- Agent quickstart: https://nyxsec.dev/docs/agent/quickstart
- Agent install: https://nyxsec.dev/docs/agent/install
- Agent CLI reference: https://nyxsec.dev/docs/agent/cli
- Agent configuration: https://nyxsec.dev/docs/agent/config
- Agent API: https://nyxsec.dev/docs/agent/api
- Agent architecture: https://nyxsec.dev/docs/agent/architecture
- Agent AI runtime: https://nyxsec.dev/docs/agent/ai-runtime
- Agent attack graph: https://nyxsec.dev/docs/agent/attack-graph
- Agent business-logic templates: https://nyxsec.dev/docs/agent/business-logic-templates
- Agent triggers: https://nyxsec.dev/docs/agent/triggers/
- Agent GitHub Actions: https://nyxsec.dev/docs/agent/ci/github-actions

Release notes:
- News index: https://nyxsec.dev/news/
- Nyx Agent launch: https://nyxsec.dev/news/nyx-agent
- Nyx 0.7.0: https://nyxsec.dev/news/nyx-0-7-0
- Nyx 0.6.0: https://nyxsec.dev/news/nyx-0-6-0
- Nyx 0.5.0: https://nyxsec.dev/news/nyx-0-5-0
- Nyx 0.4.0: https://nyxsec.dev/news/nyx-0-4-0
- Nyx 0.3.0: https://nyxsec.dev/news/nyx-0-3-0
- Nyx 0.2.0: https://nyxsec.dev/news/nyx-0-2-0
- Alpha releases: https://nyxsec.dev/news/nyx-alpha

External:
- Source code: https://github.com/elicpeter/nyx
- Nyx Agent source code: https://github.com/nyx-sec/nyx-agent
- Crate: https://crates.io/crates/nyx-scanner
- Rustdocs: https://docs.rs/nyx-scanner/latest/nyx_scanner/
- Releases: https://github.com/elicpeter/nyx/releases
- Security policy: https://github.com/elicpeter/nyx/blob/master/SECURITY.md
- Roadmap (repo): https://github.com/elicpeter/nyx/blob/master/ROADMAP.md
- Agent README: https://github.com/nyx-sec/nyx-agent
- Sponsor: https://github.com/sponsors/elicpeter

## Project metadata

- Current package: `nyx-scanner` v0.7.0
- Rust requirement: stable Rust 1.88+ for Cargo installs
- Primary site: https://nyxsec.dev
- Scanner page: https://nyxsec.dev/scanner
- Source code: https://github.com/elicpeter/nyx
- Crate: https://crates.io/crates/nyx-scanner
- Docs: https://nyxsec.dev/docs/nyx/
- Rustdocs: https://docs.rs/nyx-scanner/latest/nyx_scanner/
- Releases: https://github.com/elicpeter/nyx/releases
- Security policy: https://github.com/elicpeter/nyx/blob/master/SECURITY.md
- Roadmap: https://github.com/elicpeter/nyx/blob/master/ROADMAP.md

Agent metadata:
- Current binary: `nyx-agent`
- Status: pre-MVP; the core loop works, packaging is still moving.
- Default daemon bind: `127.0.0.1:8765`
- Source install/build path today: `cargo build --workspace`, `cargo run --bin nyx-agent -- doctor`, `cargo run --bin nyx-agent -- serve`
- Agent docs: https://nyxsec.dev/docs/agent/
- Agent source code: https://github.com/nyx-sec/nyx-agent
- Agent license: AGPLv3-or-later; commercial terms available.

## Nyx Agent

Nyx Agent runs enterprise-style pentests against development apps without requiring a hosted AI pentesting vendor. Point it at one or more repos and a local/dev URL. It can start or watch the app, run setup/seed/login/reset hooks, map routes and APIs, run Nyx static scans, synthesize concrete candidates, verify findings against the live target, and keep proof with the run.

The pitch: bring much of the workflow people pay external AI pentesting companies for into a free, local, open-source control plane. Teams can run with AI disabled, with a local OpenAI-compatible model, with local CLI adapters, or with their own BYOK provider credentials. Nyx Agent does not include, proxy, sublicense, or resell model access.

Typical commands:
```bash
cargo run --bin nyx-agent -- scan --project acme-app --app-url http://127.0.0.1:3000
cargo run --bin nyx-agent -- serve
nyx-agent doctor
nyx-agent scan --project acme-app --unsafe-attack-agent
nyx-agent pr-comment --report report.json
```

Run stages:
- Scope: load project repos, target URLs, launch profile, previous findings, and runtime settings.
- Launch/orchestration: optionally build/start the local app, wait for health checks, run seed/login hooks, and capture lifecycle logs.
- Static scan: run `nyx` over the source tree and normalize scanner output.
- Explore: build route, form, auth, and API context from the app and codebase.
- Candidate pass: turn scanner findings and runtime signals into concrete issues worth checking.
- Verification: send targeted live checks and collect request, response, and trace proof.
- Evidence review: deterministic oracles remain the hard gate; AI review can downgrade or block weak confirmations before rows are promoted to verified vulnerabilities.
- Attack pass: optionally run focused destructive specialists and cross-domain chain hunting.
- Chain reasoning: inspect graph evidence and, when an agent-loop runtime is configured, read/search repo code before returning chain JSON.
- Triage: store verified vulnerabilities with confidence, status, evidence, and run attribution.

What Nyx Agent stores:
- Project and repo inventory, including local paths or git sources.
- Run history, traces, request and response evidence, payload attempts, route models, candidates, verified vulnerabilities, chains, budgets, feedback, repro bundles, and the attack graph.
- Local SQLite state under the Nyx Agent state directory; no hosted Nyx service is required.

Enterprise workflow features:
- Project-level setup for multi-repo products.
- Launch profiles for build/start/health/seed/login/reset/stop commands.
- Local dashboard, CLI, JSON reports, PR comments, GitHub Actions use, cron schedules, and HMAC git webhooks.
- Budget controls for AI-assisted work, local keychain storage for API keys, and local-first evidence retention.
- Sandbox backends: process, birdcage, libkrun, firecracker, and docker where available.
- Optional scanner integrations from local PATH when installed: OWASP ZAP baseline, Nuclei, Trivy, OSV-Scanner, Gitleaks/detect-secrets, Katana, ProjectDiscovery httpx.

Autonomous pentesting modes:
- Default non-destructive run: static scan, route/API exploration, candidate synthesis, and scoped live verification.
- Exploit mode: enables invasive verification only when the exploit-mode gate is on.
- State-changing live probes: require exploit mode plus `allow_state_changing_live_probes`.
- Business-logic templates: generate candidates for bugs normal scanners often miss, such as tenant/object isolation, role comparison, invites, webhook replay/freshness, checkout or entitlement drift, and workflow abuse.
- Vuln Research Mode: adds hypotheses for lifecycle bugs, stale access, replay, downgrade or entitlement mismatch, team/org transitions, webhook/event consistency, AI-agent indirect actions, and background-job side effects without relaxing live execution gates.
- Unsafe attack-agent mode: final unrestricted local phase for disposable user-owned dev apps. It runs seven specialist agents, a critical chain hunter, and a final triage pass.

Unsafe attack-agent specialist passes:
- Business logic: workflow, state-machine, role-transition, invite, quota, entitlement, lifecycle, replay, and order-of-operation bugs.
- Payments and billing: checkout, subscriptions, invoices, coupons, trials, refunds, webhooks, payment status, and plan enforcement.
- User data and privacy: IDORs, cross-tenant reads/writes, exports/imports, files, logs, analytics payloads, admin views, and deleted-user data.
- Auth and session: authentication, authorization, sessions, cookies, password reset, magic links, OAuth, MFA, CSRF, account linking, and privilege escalation.
- API and input handling: mass assignment, validation gaps, schema mismatch, hidden fields, file uploads, SSRF-like fetches, parser confusion, injection, and deserialization.
- Infra and dev/prod drift: secrets, env config, debug routes, local services, dev mailers, seed credentials, logs, queues, storage, admin tooling, CORS, and deployment assumptions.
- Abuse and automation: rate limits, brute force, enumeration, scraping, invite/email/SMS abuse, cost abuse, queue flooding, resource exhaustion, and free-tier bypass.
- Critical chain hunter: cross-domain paths that combine smaller primitives into account takeover, cross-tenant compromise, payment bypass, persistent admin access, or secret exposure.
- Attack triage: deduplication, dev-only classification, focused confirmation, and material severity/impact upgrades.

AI runtime posture:
- `none`: AI features off; the static lane and deterministic pieces still run locally.
- `local-llm`: local OpenAI-compatible `/v1` endpoint such as LM Studio, Ollama, or vLLM. This is the fully local model-assisted path.
- `codex`: optional local adapter that drives an already-installed Codex CLI.
- `claude-code`: optional local adapter that drives an already-installed Claude Code CLI.
- `anthropic`: direct BYOK API path using the operator's API key.
- API keys are stored in the OS keychain, not in TOML.
- Local runs record local model token counts when reported but cost is zero because Nyx Agent cannot know local hardware accounting.

Attack graph:
- Run-scoped graph over routes, endpoints, forms, parameters, roles, objects, static signals, candidates, business-logic templates, verification attempts, verified vulnerabilities, chains, and exploration memory.
- Answers provenance questions like "what evidence led to this vulnerability?" and blast-radius questions like "what vulnerabilities touch this route/object/role?"
- Chain planning uses graph-backed edges and validates that every adjacent chain member is supported by evidence before storing a chain.

Safety posture:
- The first-launch wizard requires `i_own_this = true`.
- Default daemon bind is loopback (`127.0.0.1:8765`).
- Destructive checks are opt-in and meant for disposable development data.
- Unsafe attack-agent mode can mutate data, create accounts, submit payloads, corrupt fixtures, or knock the dev app over; use it only on targets you own and can reset.

Nyx Agent is open source under AGPLv3-or-later. Commercial licenses, paid support, onboarding help, private policy packs, and enterprise terms are available for teams that need proprietary embedding, hosted resale, custom support obligations, or license comfort.

Links:
- Product page: https://nyxsec.dev/agent
- Docs: https://nyxsec.dev/docs/agent/
- Source code: https://github.com/nyx-sec/nyx-agent
- Launch notes: https://nyxsec.dev/news/nyx-agent

---

## Install

**Cargo (recommended):**
```bash
cargo install nyx-scanner
```

Requires stable Rust 1.88+. The frontend is compiled and embedded in the binary at build time; no separate install step for `nyx serve`.

**Pre-built binaries:** Linux and macOS (x86_64, ARM64). Download from the [Releases page](https://github.com/elicpeter/nyx/releases), verify against `SHA256SUMS`, unzip, and drop `nyx` on your PATH.

**From source:**
```bash
git clone https://github.com/elicpeter/nyx.git
cd nyx && cargo build --release
```

**Nyx Agent from source while packaging is moving:**
```bash
git clone https://github.com/nyx-sec/nyx-agent.git
cd nyx-agent
cargo build --workspace
cargo run --bin nyx-agent -- doctor
cargo run --bin nyx-agent -- serve
```

---

## Basic usage

```bash
nyx scan           # taint analysis, caches findings in .nyx/
nyx serve          # opens http://localhost:9700 in the browser
nyx scan --help    # full option reference

nyx-agent scan --project acme-app --app-url http://127.0.0.1:3000
nyx-agent scan --project acme-app --exploit-mode --allow-state-changing-live-probes
nyx-agent scan --project acme-app --research-mode
nyx-agent scan --project acme-app --unsafe-attack-agent
nyx-agent serve    # opens the local Agent dashboard at 127.0.0.1:8765
```

First run builds a SQLite index under `.nyx/`; later runs skip files whose content hash has not changed.

---

## CI / GitHub Actions

```bash
# Fail on medium or higher, emit SARIF
nyx scan --format sarif --fail-on MEDIUM > results.sarif

# Ad-hoc JSON, no index
nyx scan ./server --format json --index off

# AST patterns only (fastest; skips CFG and taint)
nyx scan --mode ast

# Engine depth shortcut
nyx scan --engine-profile deep
```

GitHub Actions workflow:

```yaml
- uses: elicpeter/nyx@v0.7.0
  with:
    format: sarif
    fail-on: MEDIUM
- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: nyx-results.sarif
```

Action inputs: `path`, `version`, `format` (`sarif`|`json`|`console`), `fail-on`, `args`, `token`.
Action outputs: `finding-count`, `sarif-file`, `exit-code`, `nyx-version`.
Supported runners: Linux and macOS (x86_64, ARM64).

---

## Analysis modes and engine depth

Two separate controls:

**`--mode`** selects which detector families run:

| Mode | Active detectors |
|------|-----------------|
| `full` (default) | Taint + CFG structural + State model + AST patterns |
| `ast` | AST patterns only |
| `cfg` | Taint + CFG + State (no AST patterns) |
| `taint` | Taint + State |

**`--engine-profile`** selects analysis depth within the taint engine:

| Profile | What it does |
|---------|-------------|
| `fast` | AST patterns only, no CFG or taint |
| `balanced` (default) | Cross-file taint, k=1 context-sensitive inlining |
| `deep` | Adds symbolic execution + demand-driven backwards taint (~2-3x cost, higher precision) |

Symex and backwards analysis can also be enabled individually: `--symex`, `--backwards-analysis`.

---

## Detector families

Nyx ships four independent detector families:

| Family | Rule prefix | What it finds |
|--------|-------------|---------------|
| Taint analysis | `taint-*` | Unsanitized data flowing source to sink across files |
| CFG structural | `cfg-*` | Auth gaps, unguarded sinks, error fallthrough, resource release on all paths |
| State model | `state-*` | Use-after-close, double-close, resource leaks, unauthenticated access |
| AST patterns | `<lang>.<cat>.<name>` | Banned APIs, weak crypto, dangerous constructs |

In `--mode full`, all four run together. Taint and AST can both fire on the same line with distinct rule IDs. State supersedes CFG on resource leaks at the same location.

### Taint rule classes

| Rule ID | Surface |
|---------|---------|
| `taint-unsanitised-flow` | Default taint flow (SQL injection, CMDI, path traversal, XSS, SSRF, deserialization, code execution, open redirect) |
| `taint-data-exfiltration` | Sensitive data flowing into the payload of an outbound network request |
| `rs.auth.missing_ownership_check.taint` | Rust auth subsystem: taint-aware ownership-check gap |

---

## Output formats

| Format | Flag | Use case |
|--------|------|----------|
| Console | `--format console` | Human-readable terminal output, default |
| SARIF 2.1 | `--format sarif` | GitHub Code Scanning, any SARIF viewer |
| JSON | `--format json` | Scripting, custom pipelines |

---

## Supported languages

All 10 languages parse via tree-sitter and run through the same cross-file taint pipeline. Rule-level F1 = 100% across all 10 languages on a 507-case benchmark corpus (P=1.000, R=1.000).

| Tier | Languages | F1 | Use as CI gate? |
|------|-----------|-----|-----------------|
| Stable | Python, JavaScript, TypeScript | 100% | Yes |
| Beta | Go, Java, PHP, Ruby, Rust | 100% | Yes, with light FP triage |
| Preview | C, C++ | 100% on synthetic corpus | No - deep pointer aliasing and function pointers are not tracked |

Stable tier has gated-sink modeling (argument-role-aware, e.g. `setAttribute("href", …)` only flags href-like attributes), the deepest rule sets, and full advanced-analysis coverage. Beta tier has solid rule depth but no gated sinks. Preview tier passes the synthetic corpus but has structural blind spots (deep pointer aliasing, function pointers) that matter on real codebases.

---

## What Nyx detects

Cross-file, interprocedural taint analysis with sanitizer tracking. Finds:

- **SQL injection** - user input reaching raw SQL without parameterization
- **Command injection** - unsanitized input to shell execution (subprocess, exec, eval, system, Popen)
- **Path traversal** - user-controlled path segments reaching filesystem operations
- **SSRF** - user-controlled URLs reaching outbound HTTP clients
- **XSS** - unsanitized input reaching HTML rendering or response sinks
- **Unsafe deserialization** - untrusted data reaching pickle, YAML.load, Java ObjectInputStream, PHP unserialize, etc.
- **Code execution** - eval, exec, SSTI (template injection)
- **Open redirect** - user-controlled URLs in redirect responses
- **Data exfiltration** - sensitive data (cookies, env vars, session tokens) in outbound request bodies

CFG structural and state detectors additionally find: auth bypass gaps, unguarded sinks, use-after-close, double-close, resource leaks, and unauthenticated-access paths.

---

## Status and caveats

Nyx is under active development. APIs, detector behavior, and configuration options may change between releases. Rule-level F1 on the 507-case corpus is the CI regression floor, but results may still contain false positives or false negatives on real code. Manual review is expected.

C and C++ are Preview tier. Nyx tracks STL container flow, builder chains, and inline class member functions, but deep pointer aliasing and function pointers are not tracked. Pair C/C++ scans with clang-tidy, Clang Static Analyzer, Infer, or a comparable clang-based tool before using results as a hard CI gate.

---

## Validated against published CVEs

The benchmark corpus includes vulnerable/patched fixtures from published CVE/GHSA advisories listed in the source README. Nyx fires on the vulnerable file and emits zero findings on the patched file for each listed real-advisory pair.

| CVE | Project | Language | Class |
|-----|---------|----------|-------|
| CVE-2023-48022 | Ray | Python | Command injection |
| CVE-2017-18342 | PyYAML | Python | Deserialization |
| CVE-2025-69662 | geopandas | Python | SQL injection |
| CVE-2026-33626 | LMDeploy | Python | SSRF |
| CVE-2024-23334 | aiohttp | Python | Path traversal |
| CVE-2023-6568 | MLflow | Python | XSS |
| CVE-2024-21513 | LangChain Experimental | Python | Code execution |
| CVE-2019-14939 | mongo-express | JavaScript | Code execution (eval) |
| CVE-2025-64430 | Parse Server | JavaScript | SSRF |
| CVE-2023-22621 | Strapi | JavaScript | Code execution (SSTI) |
| CVE-2023-26159 | follow-redirects | TypeScript | SSRF |
| GHSA-4x48-cgf9-q33f | Novu | TypeScript | SSRF |
| CVE-2026-25544 | Payload CMS | TypeScript | SQL injection |
| CVE-2022-30323 | hashicorp/go-getter | Go | Command injection |
| CVE-2023-3188 | owncast | Go | SSRF |
| CVE-2024-31450 | owncast | Go | Path traversal |
| CVE-2026-41422 | daptin | Go | SQL injection |
| CVE-2015-7501 | Apache Commons Collections | Java | Deserialization |
| CVE-2017-12629 | Apache Solr | Java | Command injection |
| CVE-2022-1471 | SnakeYAML | Java | Deserialization |
| CVE-2022-42889 | Apache Commons Text | Java | Code execution |
| GHSA-h8cj-hpmg-636v | Appsmith | Java | SQL injection |
| CVE-2013-0156 | Ruby on Rails | Ruby | Deserialization |
| CVE-2020-8130 | Rake | Ruby | Command injection |
| CVE-2021-21288 | CarrierWave | Ruby | SSRF |
| CVE-2023-38337 | rswag | Ruby | Path traversal |
| CVE-2017-9841 | PHPUnit | PHP | Code execution (eval) |
| CVE-2018-15133 | Laravel | PHP | Deserialization |
| CVE-2018-20997 | tar-rs | Rust | Path traversal |
| CVE-2022-36113 | cargo | Rust | Path traversal |
| CVE-2023-42456 | sudo-rs | Rust | Path traversal |
| CVE-2024-24576 | Rust stdlib | Rust | Command injection |
| CVE-2024-32884 | gitoxide | Rust | Command injection |
| CVE-2025-53549 | matrix-rust-sdk | Rust | SQL injection |
| CVE-2016-3714 | ImageMagick (ImageTragick) | C | Command injection |
| CVE-2019-18634 | sudo (pwfeedback) | C | Memory safety |
| CVE-2019-13132 | ZeroMQ libzmq | C++ | Memory safety |
| CVE-2022-1941 | Protocol Buffers | C++ | Memory safety |

---

## Browser UI (`nyx serve`)

`nyx serve` starts a local React UI at `127.0.0.1:9700` (default port). Flags: `--port <N>`, `--host <addr>` (loopback only), `--no-browser`.

| Page | What it shows |
|------|---------------|
| Overview | Dashboard: finding counts by severity, health score, top offenders, engine profile |
| Findings | Browsable list with severity badges, triage status, rule and language filters |
| Finding detail | Flow-path visualizer with numbered steps (source to sanitizer to sink), code snippets, evidence, triage dropdown |
| Triage | Bulk update states, audit trail, import/export JSON |
| Explorer | File tree with per-file symbol list and finding overlay |
| Scans | Run history, metrics, diff two scans to see what changed |
| Rules | Built-in and custom rules per language; add rules from the UI |
| Config | Live config editor; reload without restart |

Triage states: `open`, `investigating`, `fixed`, `false_positive`, `accepted_risk`, `suppressed`.

Triage decisions save to `.nyx/triage.json`. Commit that file and the team shares one triage state. No account or external service needed.

---

## Security model

- Loopback-only bind (`127.0.0.1`). Host-header enforcement blocks DNS rebinding.
- CSRF protection on every mutation.
- No telemetry or analytics of any kind.
- No outbound connections from the scanner or UI.
- Source code never leaves the machine.

---

## Configuration

Config lives in platform config directories:

| Platform | Directory |
|----------|-----------|
| Linux | `~/.config/nyx/` |
| macOS | `~/Library/Application Support/nyx/` |
| Windows | `%APPDATA%\elicpeter\nyx\config\` |

Run `nyx config path` to see the exact path. Two files: `nyx.conf` (defaults, auto-created on first run), `nyx.local` (user overrides loaded on top). CLI flags take precedence over both.

```toml
[scanner]
mode         = "full"        # full | ast | cfg | taint
min_severity = "Medium"
include_nonprod = false      # true = keep original severity for test/vendor paths

[server]
host = "127.0.0.1"
port = 9700
open_browser = true

# Project-specific sanitizer rule
[[analysis.languages.javascript.rules]]
matchers = ["escapeHtml"]
kind     = "sanitizer"
cap      = "html_escape"
```

Or add rules from the CLI: `nyx config add-rule --lang javascript --matcher escapeHtml --kind sanitizer --cap html_escape`.

Available cap values: `env_var`, `html_escape`, `shell_escape`, `url_encode`, `json_parse`, `file_io`, `fmt_string`, `sql_query`, `deserialize`, `ssrf`, `data_exfil`, `code_exec`, `crypto`, `unauthorized_id`, `all`.

Full schema: [Configuration docs](https://nyxsec.dev/docs/nyx/configuration).

---

## Custom rules

Custom rules are YAML files. Add them via the Rules page in `nyx serve`, via `nyx config add-rule`, or by editing `nyx.local` directly. Each rule defines sources, sinks, and optional sanitizers with cap labels. Rule files are per-language under the `[[analysis.languages.<lang>.rules]]` array.

---

## How it works

Two passes over the filesystem, with an optional SQLite index:

1. **Pass 1**: parse each file via tree-sitter, build an intra-procedural CFG (petgraph), lower to pruned SSA (Cytron phi insertion over dominance frontiers), export per-function summaries (source/sanitizer/sink caps, taint transforms, points-to, callees).
2. **Summary merge**: union all per-file summaries into a `GlobalSummaries` map.
3. **Pass 2**: re-analyze each file with cross-file context under bounded context sensitivity (k=1 inlining for intra-file callees, SCC fixpoint capped at 64 iterations). A forward dataflow worklist propagates taint through the SSA lattice. Call-graph SCCs iterate to fixed-point so mutually recursive functions get accurate summaries.
4. **Rank, dedupe, emit**: findings are scored by severity × evidence strength × source-kind exploitability, then emitted.

The default `balanced` profile also runs abstract interpretation (interval and string prefix/suffix domains) to suppress false positives on bounded integers and locked URL prefixes. The `deep` profile adds symbolic execution and a demand-driven backwards walk for path-sensitive precision.

---

## Comparison with alternatives

### Nyx vs Semgrep

Semgrep matches patterns. It does not follow data across function call boundaries or file boundaries without Semgrep Pro. Cross-file taint analysis is a paid feature in Semgrep. Nyx does it in the free, open-source version.

### Nyx vs CodeQL

CodeQL needs a build step and either GitHub Actions or the CodeQL CLI installed locally. Nyx reads source files directly. No build, no extra toolchain, installs with `cargo install nyx-scanner`.

### Nyx vs Snyk

Snyk sends code to Snyk's cloud for analysis and requires an account. Nyx runs entirely on-device. No code upload, no login.

### Nyx vs Bandit / ESLint security plugins

Bandit and ESLint security plugins flag suspicious call patterns but do not track actual data flow across function boundaries. This produces false positives (sanitization elsewhere) and false negatives (unsanitized flow that doesn't match the pattern). Nyx traces the full source-to-sink path.

### Nyx Agent vs hosted AI pentesting tools

Hosted AI pentesting products usually put the control plane, model runtime, findings store, and evidence handling in a vendor service. Nyx Agent keeps the pentest control plane local and open source. With `local-llm`, Codex/Claude Code CLI adapters, or AI disabled, teams can avoid paying another company to run AI pentests and can keep app context, traces, and evidence on their own machine or infrastructure. If a team chooses a hosted model provider, it is BYOK/direct API rather than model access resold by Nyx Agent.

### Feature comparison

| | Nyx | Semgrep | CodeQL | Snyk | Bandit / ESLint |
|---|---|---|---|---|---|
| Cross-file taint | Yes | Pro only | Yes | Yes | No |
| Fully offline | Yes | Yes | Local, needs CodeQL CLI + build | No | Yes |
| No code upload | Yes | Yes | Needs GitHub or local build | No | Yes |
| No account | Yes | Free tier needs signup | Needs GitHub | No | Yes |
| Local browser UI | Yes | No | No | Cloud only | No |
| SARIF + CI | Yes | Yes | Yes | Yes | Partial |
| Open source | GPL-3.0 | Core open, taint is closed | Yes | No | Yes |
| Free for all use | Yes, no paid tier | Core free; Pro is paid | Free for open source | Free tier, usage limits | Yes |
| No build step | Yes | Yes | No | Yes | Yes |

---

## Engine limitations

- Interprocedural precision is bounded (context-sensitive inlining is k=1 with a callee body-size cap; SCC fixpoint has an iteration cap). When the engine hits a bound it falls back to summaries and records an `engine_note` on the finding.
- Cross-language calls (FFI, subprocess, WASM) are not traversed. Each language is analyzed independently.
- Several language features are not modeled: macros, most dynamic dispatch, aliased imports, reflection.
- C/C++ are Preview tier. STL container flow, builder chains, and inline class member functions are tracked. Deep pointer aliasing and function pointers are not.
- Results may contain false positives or false negatives. Manual review is expected.

---

## Roadmap

Scanner focus: recall and precision on real open-source codebases. Running Nyx against real repos and real CVEs, then closing the gap between what it finds and what it should find.

Agent focus: local autonomous pentesting, verified vulnerability evidence, business-logic testing, attack graph and chain reasoning, local/BYOK AI runtime adapters, and enterprise workflow surfaces such as projects, triggers, reports, PR comments, and repeatable local app orchestration.

Scanner roadmap: https://github.com/elicpeter/nyx/blob/master/ROADMAP.md

---

## License and cost

Nyx Scanner: GPL-3.0-or-later. Free, no paid tier, no usage limits.

Nyx Agent: AGPLv3-or-later. Free and open source; commercial licensing and support are available when teams need proprietary embedding, hosted resale, custom support obligations, private policy packs, or license comfort.

Support the project: https://github.com/sponsors/elicpeter

---

## Key topics

- local-first security scanner
- open-source SAST
- static application security testing
- source-to-sink taint analysis
- cross-file interprocedural taint
- no cloud security scanner
- offline security scanner
- developer security workflow
- Rust security tooling
- SARIF output
- GitHub Actions security
- browser triage UI
- no code upload scanner
- privacy-preserving SAST
- security scanner without account
- alternative to Semgrep
- alternative to CodeQL
- alternative to Snyk
- Bandit alternative with taint analysis
- cargo install security scanner
- four detector families: taint, CFG, state model, AST patterns
- Nyx Agent
- autonomous pentesting
- local AI pentesting
- free AI pentesting
- open-source pentesting agent
- enterprise pentesting
- AI pentesting without SaaS
- live appsec verification
- verified vulnerabilities
- stored evidence
- request response proof
- attack graph
- exploit chain reasoning
- business logic testing
- IDOR testing
- authorization testing
- tenant isolation testing
- local LLM security testing
- BYOK AI runtime
- Codex CLI security agent
- Claude Code security agent
- local pentest dashboard
- PR security comments
- HMAC webhook security scans
- cron security scans
- disposable dev app testing