# Quick start
After `cargo install nyx-scanner` (or dropping a release binary on your PATH), point Nyx at a directory:
```bash
nyx scan ./my-project
```
First run builds a SQLite index under `.nyx/`; later runs skip files whose content hash hasn't changed.
## What a finding looks like
The same scan in console form:
```
/tmp/demo/cmdi_direct.py
6:5 ✖ [HIGH] taint-unsanitised-flow (source 5:11) (Score: 81, Confidence: High)
Unsanitised user input flows from request.args.get → os.system
Source: request.args.get (5:11)
Sink: os.system
6:5 ✖ [HIGH] py.cmdi.os_system (Score: 64, Confidence: High)
Os.system() — shell command execution
/tmp/demo/xss_document_write.js
5:5 ✖ [HIGH] taint-unsanitised-flow (source 3:18) (Score: 81, Confidence: High)
Unsanitised user input flows from req.query.content → document.write
Source: req.query.content (3:18)
Sink: document.write
5:5 ⚠ [MEDIUM] js.xss.document_write (Score: 34, Confidence: High)
Document.write() — XSS sink
warning 'demo' generated 10 issues.
Finished in 0.054s.
```
Each finding is one line of header plus evidence. Fields that matter:
| Field | Meaning |
|---|---|
| `[HIGH]` / `[MEDIUM]` / `[LOW]` | Severity after the non-prod downgrade |
| Rule ID | Either a taint rule (`taint-unsanitised-flow`), a structural rule (`cfg-*`, `state-*`), or an AST pattern (`..`) |
| Score | Attack-surface ranking (severity + analysis kind + source kind + evidence). Higher is more exploitable |
| Confidence | `High`, `Medium`, `Low`. Drops for AST-only matches, capped widened flows, and lowered-to-Low backwards-infeasible findings |
| Source / Sink | Where tainted data entered and where the dangerous call happened |
Two rules firing on the same line (the taint finding plus the AST pattern) is normal. The pattern matches the structural presence of `document.write`; the taint rule adds the evidence that `req.query.content` actually reached it. Both carry distinct rule IDs so suppressions can target one without the other.
## Fail a CI job on High findings
```bash
nyx scan . --fail-on HIGH --quiet
```
Exit 1 if any HIGH finding remains. `--quiet` drops the "Using default configuration" banner so CI logs stay tidy.
## Emit SARIF for GitHub Code Scanning
```bash
nyx scan . --format sarif > results.sarif
```
Full SARIF schema and GitHub Actions wiring: [cli.md](cli.md) and [output.md](output.md).
## Tighten the gate
```bash
# Only HIGH findings
nyx scan . --severity HIGH
# HIGH + MEDIUM
nyx scan . --severity ">=MEDIUM"
# Drop anything below Medium confidence (useful for CI)
nyx scan . --min-confidence medium
# Also drop findings the engine could not fully resolve (widened / bailed)
nyx scan . --require-converged
```
`--require-converged` keeps `under-report` findings (the emitted flow is still real) but drops over-reports and widenings. Intended for strict gates where a noisy finding is worse than nothing.
## Skip dataflow for a fast first pass
```bash
nyx scan . --mode ast
```
AST-only mode runs tree-sitter patterns without building a CFG or running taint. It's fast and still catches banned-API uses, weak crypto, and obvious XSS sinks, but it can't tell `eval("1+1")` apart from `eval(userInput)`. Use it as a pre-commit filter, not as a CI gate replacement.
## Next
- [CLI reference](cli.md) for every flag and subcommand.
- [Configuration](configuration.md) for the `nyx.conf` / `nyx.local` schema, profiles, and custom rules.
- [`nyx serve`](serve.md) for the browser UI, triage workflow, and scan history.
- [Language maturity](language-maturity.md) for per-language tier and known FP/FN patterns.