Configuration

Nyx uses TOML configuration files. A default config is auto-generated on first run. If you’d rather edit settings and rules from the browser, the Config page in nyx serve is a live editor that writes back to nyx.local:

File Locations

Run nyx config path to see the exact directory on your system.

File Precedence

1. nyx.conf – Default config (auto-created from built-in template on first run)
2. nyx.local – User overrides (loaded on top of defaults)

Both files are optional. CLI flags take precedence over both.

Merge Strategy

Example:

# nyx.conf (default):
excluded_extensions = ["jpg", "png", "exe"]

# nyx.local (user):
excluded_extensions = ["foo", "jpg"]

# Effective result:
# ["exe", "foo", "jpg", "png"]  -- sorted, deduped union

Full Schema

[scanner]

[database]

[output]

[performance]

[server]

Configuration for the local web UI (nyx serve).

[runs]

Configuration for scan run persistence and history.

[profiles.<name>]

Named scan presets that override scan-related config. Activate with --profile <name>.

All fields are optional; omitted fields inherit from the base config.

Built-in profiles:

User-defined profiles with the same name as a built-in will override it.

[analysis.engine]

Release-grade switches for the optional analysis passes. Each toggle has a matching CLI flag (pair of --foo / --no-foo) that overrides the config value for a single run. These used to be NYX_* environment variables (NYX_CONSTRAINT, NYX_ABSTRACT_INTERP, NYX_SYMEX, NYX_CROSS_FILE_SYMEX, NYX_SYMEX_INTERPROC, NYX_CONTEXT_SENSITIVE, NYX_PARSE_TIMEOUT_MS, NYX_SMT); those env vars are still honored as a last-resort override when nyx is used as a library (no CLI entry point), but the config/CLI surface is the stable path.

[analysis.engine.symex] sub-section:

CLI flag map (each pair is --enable / --no-enable):

Engine-depth profile shortcut: instead of flipping individual toggles, pass --engine-profile {fast,balanced,deep} to set the whole stack at once. Individual flags override the profile, so --engine-profile fast --backwards-analysis runs the fast stack with backwards analysis on. See docs/cli.md for the exact toggle matrix.

Explain effective engine: pass --explain-engine to print the resolved engine configuration (profile + config + CLI overrides) and exit without scanning.

[analysis.languages.<slug>]

Per-language custom rules. <slug> is one of: rust, javascript, typescript, python, go, java, c, cpp, php, ruby.

Rule object:

[[analysis.languages.javascript.rules]]
matchers = ["escapeHtml"]
kind = "sanitizer"        # "source" | "sanitizer" | "sink"
cap = "html_escape"       # "env_var" | "html_escape" | "shell_escape" |
                          # "url_encode" | "json_parse" | "file_io" |
                          # "fmt_string" | "sql_query" | "deserialize" |
                          # "ssrf" | "code_exec" | "crypto" | "all"

Example Configurations

Minimal override (nyx.local)

[scanner]
min_severity = "Medium"

[output]
default_format = "json"
max_results = 100

CI-optimized

[scanner]
mode = "full"
min_severity = "Medium"
excluded_directories = ["node_modules", ".git", "target", "vendor", "dist"]

[output]
quiet = true
default_format = "sarif"

[performance]
worker_threads = 4

Using a scan profile

# Use a built-in profile
nyx scan --profile ci

# CLI flags still override profile values
nyx scan --profile ci --format json

Custom profile

[profiles.security_audit]
mode = "full"
min_severity = "Low"
enable_state_analysis = true
show_all = true

Custom rules for a Node.js project

[analysis.languages.javascript]
terminators = ["process.exit", "abort"]
event_handlers = ["addEventListener"]

[[analysis.languages.javascript.rules]]
matchers = ["escapeHtml", "sanitizeInput"]
kind = "sanitizer"
cap = "html_escape"

[[analysis.languages.javascript.rules]]
matchers = ["dangerouslySetInnerHTML"]
kind = "sink"
cap = "html_escape"

[[analysis.languages.javascript.rules]]
matchers = ["getRequestBody", "readUserInput"]
kind = "source"
cap = "all"

Adding rules via CLI

# Add a sanitizer
nyx config add-rule --lang javascript --matcher escapeHtml --kind sanitizer --cap html_escape

# Add a terminator
nyx config add-terminator --lang javascript --name process.exit

# Verify
nyx config show

Config Validation

Config is validated after loading and merging. Validation checks include:

• Server port must be 1–65535
• Server host must not be empty
• max_saved_runs must be > 0 when persist_runs is true
• max_runs must be > 0 when persist is true
• batch_size and channel_multiplier must be > 0
• rollup_examples must be > 0
• Profile names must be alphanumeric with underscores only

Invalid config produces structured error messages identifying the section, field, and issue.

State Analysis

State analysis detects resource lifecycle violations (use-after-close, double-close, resource leaks) and unauthenticated access patterns. It is enabled by default.

To disable:

[scanner]
enable_state_analysis = false

State analysis requires mode = "full" or mode = "taint". It has no effect in mode = "ast".

Tradeoffs:

• Additional per-function state-machine pass adds some scan time
• May produce findings that require domain knowledge to evaluate (e.g., whether a resource handle is intentionally left open)
• Most useful for C, C++, Rust, Go, and Java where acquire/release patterns are common

Upgrading

Engine-version mismatch is handled automatically

Nyx stores the scanner’s CARGO_PKG_VERSION in the project index database. When the version recorded in the DB differs from the running binary; or the row is missing entirely; every cached summary, SSA body, and file-hash row is wiped on the next open so the next scan rebuilds the index against the new engine. No flag is needed; CI pipelines keep working across upgrades.

The rebuild is logged at info level:

engine version changed (0.4.0 → 0.5.0), rebuilding index

If you see this once per upgrade it is working as intended. If you see it on every scan, the metadata row is not being persisted; file an issue.

Forcing a reindex

Use --index rebuild to throw away the current project’s cached summaries and re-run pass 1 against the current rules. Useful after editing nyx.local rules, after an upgrade that changed label definitions without changing the engine version, or when you want a known-clean baseline:

nyx scan --index rebuild .

This clears the current project’s rows in files, function_summaries, ssa_function_summaries, and ssa_function_bodies; other projects sharing the same DB directory are untouched.

Recovering from a corrupt database

If the .sqlite file itself is damaged (e.g. from a killed scan or full disk) and nyx scan fails to open it, delete the file and let the next scan recreate it:

rm "$(nyx config path)"/<project>.sqlite*

On the next scan Nyx builds a fresh index from scratch.

Reserved Fields

Some config fields are defined but not yet implemented. They are marked (RESERVED) in the default config and accept values without effect. This allows forward-compatible config files; settings will activate when the feature is implemented without requiring config changes.