https://github.com/jpvelasco/nyx
Validate live network behavior against a YAML intent spec — VLAN isolation, VPN routing, host discovery, DNS, and more.
https://github.com/jpvelasco/nyx
cli homelab network-audit npm vlan
Last synced: 21 days ago
JSON representation
Validate live network behavior against a YAML intent spec — VLAN isolation, VPN routing, host discovery, DNS, and more.
- Host: GitHub
- URL: https://github.com/jpvelasco/nyx
- Owner: jpvelasco
- License: mit
- Created: 2026-05-24T00:51:11.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-06-17T07:23:03.000Z (24 days ago)
- Last Synced: 2026-06-17T09:17:15.587Z (24 days ago)
- Topics: cli, homelab, network-audit, npm, vlan
- Language: Go
- Homepage: https://www.npmjs.com/package/nyx-audit-cli
- Size: 859 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: .github/SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# nyx
Your homelab should be doing what you think it's doing. **nyx** proves it.
Validate your network behavior against a declared YAML intent model — VLAN isolation, VPN routing, host counts, route correctness — all verified with live network checks. When something drifts, nyx tells you exactly what changed and how to fix it.
Every command produces structured JSON for automation and AI agent consumption.
**Install from npm:** [`nyx-audit-cli`](https://www.npmjs.com/package/nyx-audit-cli) — `npm install -g nyx-audit-cli`
## Quick Start
```bash
# Install prebuilt binary (recommended)
npm install -g nyx-audit-cli
# If npm blocked the postinstall script (Ubuntu 26+, hardened envs), just run nyx once —
# it detects the missing binary and downloads it automatically. Or manually:
# node $(npm root -g)/nyx-audit-cli/install.js
# Or build from source (requires Go 1.22+)
git clone https://github.com/jpvelasco/nyx.git && cd nyx && make build
# Discover hosts on a subnet
sudo nyx discover --subnet 10.0.10.0/24
# Run a full audit from a spec file
sudo nyx audit --spec examples/homelab.yaml
# Check environment health
nyx doctor
```
### Longer-Term Confidence
Once you've verified your network is behaving correctly, lock in that baseline. Future drift checks will show you exactly what changed — new failures, degradations, or fixes — so you can sleep at night knowing your segmentation and policies are still holding.
```bash
# After a clean audit, save the baseline from the persisted snapshot
sudo nyx audit --spec examples/homelab.yaml
nyx snapshot list
nyx snapshot baseline ~/.nyx/snapshots/snapshot-YYYYMMDD-HHMMSS.json
# Days or weeks later, re-audit and check drift
sudo nyx audit --spec examples/homelab.yaml && nyx drift status
```
For the full story of what this feels like on a real multi-VLAN homelab (including when things go wrong and drift catches it), see [docs/walkthrough.md](docs/walkthrough.md).
## Prerequisites
- **Go 1.22+** — to build from source
- **nmap** — required for `discover` and `subnet_discovery` assertions
nyx does not bundle nmap. Install it for your platform:
| Platform | Command |
|----------|---------|
| Ubuntu/Debian | `sudo apt install nmap` |
| Fedora/RHEL | `sudo dnf install nmap` |
| Arch Linux | `sudo pacman -S nmap` |
| macOS | `brew install nmap` |
| Windows | `winget install nmap` |
If nmap is missing, `nyx doctor` will show the exact install command for your system.
- Root/sudo — required for nmap subnet scans on some platforms
## Commands
| Command | Description | Backends Used |
|---------|-------------|---------------|
| `discover` | Discover hosts in a subnet via nmap ping sweep | nmap |
| `check-routes` | Validate route and gateway to a target IP | system (ip route) |
| `check-vpn` | Verify traffic routes through a VPN tunnel | system (ip route) |
| `verify-isolation` | Check that a target is unreachable (isolation) | system (ping) |
| `audit` | Run all assertions from a YAML spec file | nmap + system |
| `doctor` | Check environment health and optional spec validation | all |
| `provider` | Provider management (`list` subcommand) | all |
| `omada` | Omada SDN vendor commands (`info`, `import`, `check`) | omada backend |
| `opnsense` | OPNsense vendor commands (`info`, `import`, `check`) | opnsense backend |
| `snapshot` | Manage audit history (`baseline`, `list`, `delete`, `clear-baseline`) | — |
| `drift` | Detect drift in audit results (`status`, `compare`) | — |
| `mcp serve` | Start MCP server for AI agent integration | all |
| `version` | Print version | — |
### Global Flags
```
--json Output as JSON (available on all commands)
--output Write output to file instead of stdout
--spec Path to YAML spec file (used by audit)
--verbose Verbose output with additional evidence
--timeout Timeout for operations (default 60s)
```
## YAML Spec Format
nyx validates your network against a declared intent model:
```yaml
version: 1
site: home-lab
networks:
- name: trusted
cidr: 10.0.10.0/24
gateway: 10.0.10.1
zone: trusted
vlan: 10
- name: iot
cidr: 10.0.60.0/24
gateway: 10.0.60.1
zone: iot
vlan: 60
# ... more VLANs
vpn:
- name: home-wg
type: wireguard
interface: wg0
expected_routes:
- 10.0.0.0/8
mode: split-tunnel
policies:
- name: iot-to-trusted-deny
from: iot
to: trusted
action: deny
assertions:
- type: subnet_discovery
network: trusted
expect_hosts_min: 10
expect_hosts_max: 30
- type: isolation
from: iot
to: trusted
expect: deny
- type: vpn_route
vpn: home-wg
target: 10.0.20.50
expect_tunnel: true
- type: route_check
target: 10.0.10.1
```
See `examples/homelab.yaml` for the complete realistic 7-VLAN example used throughout this document.
See the [full structured spec reference](docs/spec.html) (modern HTML).
See `docs/walkthrough.md` for the full narrative — what it actually feels like to land on a complex network, hit real problems, get useful recommendations, and use drift to sleep better at night.
### Assertion Types
| Type | Description | Key Fields |
|------|-------------|------------|
| `subnet_discovery` | Count hosts in a network | `network`, `expect_hosts_min`, `expect_hosts_max` |
| `isolation` | Verify zone-to-zone unreachability | `from`, `to`, `expect: deny` |
| `vpn_route` | Check traffic routes through VPN | `vpn`, `target`, `expect_tunnel` |
| `route_check` | Verify route exists to target | `target` |
| `port_check` | Verify TCP ports are open | `target`, `ports`, `expect: open` |
| `dns_check` | Verify DNS resolution | `query`, `expect_ip`, `server` |
| `network_health` | Verify latency and packet loss | `target`, `expect_latency_ms`, `expect_loss_pct` |
| `acl_check` | Verify controller policy enforcement | `provider`, `policy`, `expect: enforced` |
## Exit Codes
| Code | Meaning |
|------|---------|
| 0 | All checks passed |
| 1 | One or more assertions failed |
| 2 | Execution error or invalid configuration |
| 3 | One or more warnings |
## Snapshot & Drift Detection
After a clean audit, save the result as a baseline:
```bash
nyx snapshot baseline
```
Later, after re-running an audit, check what changed:
```bash
nyx drift status
```
The drift report shows new failures, degradations, fixes, and improvements with a clear net change summary. You can also restore a previous baseline from a saved snapshot:
```bash
nyx snapshot baseline ~/.nyx/snapshots/snapshot-20250601-140000.json
```
### Snapshot Commands
| Command | Description |
|---------|-------------|
| `nyx snapshot baseline` | Set current audit as baseline |
| `nyx snapshot baseline ` | Restore baseline from saved snapshot |
| `nyx snapshot list` | List all saved snapshots |
| `nyx snapshot delete [name]` | Delete a snapshot (or all if no name given) |
| `nyx snapshot clear-baseline` | Remove the current baseline |
| `nyx drift status` | Compare latest audit against baseline |
| `nyx drift compare ` | Compare any two snapshots |
Snapshots are stored in `~/.nyx/snapshots/` with automatic rotation at 50 snapshots.
## MCP Server
nyx includes a Model Context Protocol server for AI agent integration:
```bash
nyx mcp serve --transport stdio
```
### Claude Code Integration
Add to your MCP config:
```json
{
"mcpServers": {
"nyx": {
"command": "/path/to/nyx",
"args": ["mcp", "serve"]
}
}
}
```
### Available MCP Tools
| Tool | Description |
|------|-------------|
| `discover_subnet` | Discover hosts in a subnet (supports `scan_timing`, `scan_min_rate`) |
| `check_routes` | Check route to a target — returns CheckResult |
| `check_vpn` | Check VPN tunnel routing — returns CheckResult |
| `verify_isolation` | Verify network isolation |
| `run_audit` | Run full audit from spec |
| `load_spec` | Load and validate a spec file |
| `get_interfaces` | List network interfaces |
| `ping_target` | Ping a target |
| `run_doctor` | Check environment health + optional spec validation |
| `provider_list` | List registered providers |
## Providers
nyx supports multiple network backends via a provider system. Vendors register at startup and expose vendor-specific commands.
### List Providers
```bash
nyx provider list
```
### Omada SDN
Omada provider supports Omada SDN controller 6.x. Pass your controller address (usually on your management VLAN):
```bash
# Example using a typical management IP
nyx omada info --host 192.168.11.20
# Generate spec from controller
nyx omada import --host 192.168.11.20 --username admin --password password
# Import and audit in one step
nyx omada check --host 192.168.11.20 --username admin --password password --spec examples/homelab.yaml
```
Credentials can be passed via flags or env vars: `OMADA_HOST`, `OMADA_USERNAME`, `OMADA_PASSWORD`.
### OPNsense
OPNsense provider supports info, import, and check. Use your OPNsense address (typically the LAN or a management IP):
```bash
# Example using a typical management IP
nyx opnsense info --host 192.168.11.1 --api-key --api-secret
# Generate spec from OPNsense
nyx opnsense import --host 192.168.11.1 --api-key --api-secret
# Import and audit in one step
nyx opnsense check --host 192.168.11.1 --api-key --api-secret --spec examples/homelab.yaml
```
## Project Structure
```
nyx/
cmd/nyx/ # CLI entry point
internal/
cli/ # Cobra command definitions
models/ # Result envelope, report types
intent/ # YAML spec loader and validation
audit/ # Audit engine
backends/
nmap/ # Nmap subprocess wrapper
system/ # Platform-specific system commands
omada/ # Omada SDN client (low-level)
batfish/ # Stub, planned for v2
providers/ # Provider interface + registry
omada/ # Omada provider (wraps backends/omada)
opnsense/ # OPNsense provider
mcp/ # MCP stdio server
report/ # Output renderers
recommendations/ # Failure analysis and remediation hints
snapshot/ # Audit history and drift detection
logger/ # JSON-lines rotating logger (~/.nyx/nyx.log)
version/ # Single-source version constant
examples/ # Example YAML specs
testdata/ # Test fixtures
.github/workflows/ # CI/CD
```
## Development
```bash
make build # Build binary
make test # Run tests
make vet # Run go vet
make clean # Remove built binaries
make release # Cross-compile for all platforms
```
## Platform Support
| Platform | Status | Commands Used |
|----------|--------|---------------|
| Linux | Full support | `ip route`, `ip route get`, `ip addr show`, `ping -c -W`, `traceroute -n` |
| macOS | Full support | `netstat -rn`, `route -n get`, `ifconfig`, `ping -c -t`, `traceroute -n` |
| Windows | Full support | `route print`, `ping -n -w`, `tracert -d`, Go `net.Interfaces()` |
All three platforms cross-compile from any OS. Platform-specific code uses Go build tags.
## Distribution & Releases
Official binaries are published automatically on every `v*` tag via GitHub Releases.
```bash
# Build from source (recommended for development)
make build
# Or install via npm (once a release exists)
npm install -g nyx-audit-cli
```
The npm package (`nyx-audit-cli`) is a thin platform-aware wrapper that downloads the matching prebuilt binary from the GitHub Release.
See [CONTRIBUTING.md](.github/CONTRIBUTING.md) (or the release workflow) for the exact tagging process.
## License
MIT