Nyx

Nyx is a lightweight, Rust‑native command‑line tool that detects potentially dangerous code patterns across several programming languages. It combines the accuracy of tree‑sitter parsing with a curated rule set and an optional SQLite‑backed index to deliver fast, repeatable scans on projects of any size.

Project status – Alpha
Nyx is under active development. The public interface, rule set, and output formats may change without notice while we stabilize the core. Please pin exact versions in production environments.

---

Key Capabilities

Capability	Description
Multi‑language support	Rust, C, C++, Java, Go, PHP, Python, Ruby, TypeScript, JavaScript
AST‑level pattern matching	Language‑specific queries written against precise parse trees
Incremental indexing	SQLite database stores file hashes and previous findings to skip unchanged files
Parallel execution	File walking and rule execution run concurrently; defaults scale with available CPU cores
Configurable scan parameters	Exclude directories, set maximum file size, tune worker threads, limit output, and more
Multiple output formats	Human‑readable console view (default) and machine‑readable JSON / CSV / SARIF (roadmap)

---

Installation

Build from source

$ git clone https://github.com/<your‑org>/nyx.git
$ cd nyx
$ cargo build --release
# optional – copy the binary into PATH
$ cargo install --path .

Nyx targets stable Rust 1.78 or later.

---

Quick Start

# Scan the current directory (creates/uses an index automatically)
$ nyx scan

# Scan a specific path and emit JSON
$ nyx scan ./server --format json

# Perform an ad‑hoc scan without touching the index
$ nyx scan --no-index

# Restrict results to high‑severity findings
$ nyx scan --high-only

Index Management

# Create or rebuild an index
$ nyx index build [PATH] [--force]

# Display index metadata (size, modified date, etc.)
$ nyx index status [PATH]

# List all indexed projects (add -v for detailed view)
$ nyx list [-v]

# Remove a single project or purge all indexes
$ nyx clean <PROJECT_NAME>
$ nyx clean --all

---

Configuration Overview

Nyx merges a default configuration file (nyx.conf) with user overrides (nyx.local). Both live in the platform‑specific configuration directory shown below.

Platform	Directory
Linux / macOS	~/.config/nyx/
Windows	%APPDATA%\ecpeter23\nyx\config\

Minimal example (nyx.local):

[scanner]
min_severity        = "Medium"
follow_symlinks     = true
excluded_extensions = ["mp3", "mp4"]

[output]
default_format = "json"
max_results    = 200

[performance]
worker_threads     = 8  # 0 = auto‑detect
batch_size         = 200
channel_multiplier = 2

A fully documented nyx.conf is generated automatically on first run.

---

Architecture in Brief

1. File enumeration – A highly parallel walker applies ignore rules, size limits, and user exclusions.
2. Parsing – Supported files are parsed into ASTs via the appropriate tree‑sitter grammar.
3. Rule execution – Each language ships with a dedicated rule set expressed as tree‑sitter queries. Matches are classified into three severity levels (High, Medium, Low).
4. Indexing (optional) – File digests and findings are stored in SQLite. Later scans skip files whose content and modification time are unchanged.
5. Reporting – Results are grouped by file and emitted to the console or serialized in the requested format.

---

Roadmap

Area	Planned Improvements
Control‑flow analysis	Generation of CFGs for deeper reasoning about execution paths
Taint tracking	Intra‑ / inter‑procedural tracing of untrusted data from sources to sinks
Output formats	Full SARIF 2.1.0, JUnit XML, HTML report generator
Rule updates	Remote rule feed with signature verification

Community feedback will help shape priorities; please open an issue to discuss proposed changes.

---

Contributing

Pull requests are welcome. To contribute:

1. Fork the repository and create a feature branch.
2. Adhere to rustfmt and ensure cargo clippy --all -- -D warnings passes.
3. Add unit and/or integration tests where applicable (cargo test should remain green).
4. Submit a concise, well‑documented pull request.

See CONTRIBUTING.md for full guidelines.

---

License

Nyx is dual‑licensed under Apache‑2.0 and MIT. You may choose either license.