nyx-audit-cli 0.2.3 → 0.2.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +168 -0
- package/install.js +1 -1
- package/package.json +43 -13
- package/run.js +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,168 @@
|
|
|
1
|
+
# nyx-audit-cli
|
|
2
|
+
|
|
3
|
+
**Your homelab should be doing what you think it's doing. nyx proves it.**
|
|
4
|
+
|
|
5
|
+
[npm](https://www.npmjs.com/package/nyx-audit-cli) · [GitHub](https://github.com/jpvelasco/nyx) · [Spec reference](https://github.com/jpvelasco/nyx/blob/main/docs/spec.html)
|
|
6
|
+
|
|
7
|
+
Cross-platform CLI that audits **live network behavior** against a declared YAML intent model — VLAN isolation, VPN routing, host counts, DNS, ports, ACLs, and drift over time. Every command emits structured JSON for automation and AI agents.
|
|
8
|
+
|
|
9
|
+
<p align="center">
|
|
10
|
+
<a href="https://github.com/jpvelasco/nyx/actions/workflows/ci.yml"><img src="https://github.com/jpvelasco/nyx/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
|
|
11
|
+
<a href="https://github.com/jpvelasco/nyx/releases/latest"><img src="https://img.shields.io/github/v/release/jpvelasco/nyx" alt="Release"></a>
|
|
12
|
+
<a href="https://www.npmjs.com/package/nyx-audit-cli"><img src="https://img.shields.io/npm/v/nyx-audit-cli" alt="npm"></a>
|
|
13
|
+
<a href="https://www.npmjs.com/package/nyx-audit-cli"><img src="https://img.shields.io/npm/dm/nyx-audit-cli" alt="npm downloads"></a>
|
|
14
|
+
<a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT License"></a>
|
|
15
|
+
</p>
|
|
16
|
+
|
|
17
|
+
## Install
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
npm install -g nyx-audit-cli
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
Try without a global install:
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
npx nyx-audit-cli version
|
|
27
|
+
npx nyx-audit-cli doctor
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Works on **macOS**, **Linux**, **Windows**, and **WSL** — `x64` and `arm64`. Postinstall downloads the matching prebuilt binary from GitHub Releases with embedded SHA-256 verification.
|
|
31
|
+
|
|
32
|
+
## Quickstart
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
# 1. Install (above)
|
|
36
|
+
|
|
37
|
+
# 2. Check prerequisites (nmap, interfaces, spec hints)
|
|
38
|
+
nyx doctor
|
|
39
|
+
|
|
40
|
+
# 3. Generate a starter spec from your machine's RFC1918 networks
|
|
41
|
+
nyx init --output my-network.yaml
|
|
42
|
+
|
|
43
|
+
# 4. Run a full audit against declared intent
|
|
44
|
+
sudo nyx audit --spec my-network.yaml
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
After a clean audit, lock in a baseline from the saved snapshot (each audit writes to `~/.nyx/snapshots/`):
|
|
48
|
+
|
|
49
|
+
```bash
|
|
50
|
+
sudo nyx audit --spec my-network.yaml
|
|
51
|
+
nyx snapshot list
|
|
52
|
+
nyx snapshot baseline ~/.nyx/snapshots/snapshot-YYYYMMDD-HHMMSS.json
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Compare later when something feels off:
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
sudo nyx audit --spec my-network.yaml && nyx drift status
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## What it does
|
|
62
|
+
|
|
63
|
+
```
|
|
64
|
+
sudo nyx audit --spec homelab.yaml
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
One spec file. Eight assertion types. Concurrent live checks:
|
|
68
|
+
|
|
69
|
+
1. **Subnet discovery** — host counts per VLAN (`nmap -sn`)
|
|
70
|
+
2. **Isolation** — prove zones cannot reach each other
|
|
71
|
+
3. **VPN routing** — split-tunnel vs full-tunnel behavior
|
|
72
|
+
4. **Route checks** — gateway and path correctness
|
|
73
|
+
5. **Port checks** — TCP reachability
|
|
74
|
+
6. **DNS checks** — resolution and optional DNSSEC
|
|
75
|
+
7. **Network health** — latency, loss, MTU
|
|
76
|
+
8. **ACL checks** — Omada / OPNsense policy alignment
|
|
77
|
+
|
|
78
|
+
Results preserve spec order, include evidence, and map to exit codes (`0` pass, `1` fail, `2` error, `3` warn).
|
|
79
|
+
|
|
80
|
+
## Why nyx?
|
|
81
|
+
|
|
82
|
+
| Ad-hoc checks | nyx |
|
|
83
|
+
|---------------|-----|
|
|
84
|
+
| Ping one host, hope VLANs are fine | Declared intent across every network |
|
|
85
|
+
| "It worked yesterday" | Snapshot baseline + drift diff |
|
|
86
|
+
| Tribal knowledge in your head | Versioned YAML spec in git |
|
|
87
|
+
| Scattered shell one-liners | One audit, structured JSON output |
|
|
88
|
+
| Manual firewall spot-checks | `acl_check` against Omada / OPNsense |
|
|
89
|
+
|
|
90
|
+
Built for **homelab operators**, **platform engineers**, and **SREs** who run segmented networks and need proof — not vibes.
|
|
91
|
+
|
|
92
|
+
## Assertion types
|
|
93
|
+
|
|
94
|
+
| Type | Validates |
|
|
95
|
+
|------|-----------|
|
|
96
|
+
| `subnet_discovery` | Host count in a CIDR |
|
|
97
|
+
| `isolation` | Zone-to-zone deny/allow |
|
|
98
|
+
| `vpn_route` | Traffic uses the expected tunnel |
|
|
99
|
+
| `route_check` | Route to a target exists |
|
|
100
|
+
| `port_check` | TCP ports open/closed |
|
|
101
|
+
| `dns_check` | Resolution (+ optional DNSSEC) |
|
|
102
|
+
| `network_health` | Latency, loss, MTU |
|
|
103
|
+
| `acl_check` | Controller policy enforcement |
|
|
104
|
+
|
|
105
|
+
Remote probes: set `runner:` on assertions to execute checks over SSH from another VLAN.
|
|
106
|
+
|
|
107
|
+
## Vendor integrations
|
|
108
|
+
|
|
109
|
+
| Provider | Commands | What you get |
|
|
110
|
+
|----------|----------|--------------|
|
|
111
|
+
| **Omada SDN** | `nyx omada info \| import \| check` | Import networks/policies into a spec |
|
|
112
|
+
| **OPNsense** | `nyx opnsense info \| import \| check` | API-driven spec from live firewall |
|
|
113
|
+
|
|
114
|
+
## AI agent integration (MCP)
|
|
115
|
+
|
|
116
|
+
Built-in [Model Context Protocol](https://modelcontextprotocol.io/) server — audit, discover, route-check, and drift tools for Claude Code, Cursor, and other MCP clients.
|
|
117
|
+
|
|
118
|
+
**Claude Code:**
|
|
119
|
+
|
|
120
|
+
```bash
|
|
121
|
+
claude mcp add nyx -- npx -y nyx-audit-cli mcp serve --transport stdio
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
**Claude Desktop / Cursor:**
|
|
125
|
+
|
|
126
|
+
```json
|
|
127
|
+
{
|
|
128
|
+
"mcpServers": {
|
|
129
|
+
"nyx": {
|
|
130
|
+
"command": "npx",
|
|
131
|
+
"args": ["-y", "nyx-audit-cli", "mcp", "serve", "--transport", "stdio"]
|
|
132
|
+
}
|
|
133
|
+
}
|
|
134
|
+
}
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
## Prerequisites
|
|
138
|
+
|
|
139
|
+
- **nmap** — required for discovery (`nyx doctor` prints the install command for your OS)
|
|
140
|
+
- **sudo** — needed for some subnet scans on Linux/macOS
|
|
141
|
+
|
|
142
|
+
## Commands
|
|
143
|
+
|
|
144
|
+
| Command | Purpose |
|
|
145
|
+
|---------|---------|
|
|
146
|
+
| `audit` | Run all assertions from a YAML spec |
|
|
147
|
+
| `init` | Auto-detect networks and generate a starter spec |
|
|
148
|
+
| `doctor` | Environment and spec validation |
|
|
149
|
+
| `discover` | nmap host discovery for a subnet |
|
|
150
|
+
| `check-vpn` | Split-tunnel vs full-tunnel check |
|
|
151
|
+
| `drift status` | Compare latest audit to baseline |
|
|
152
|
+
| `snapshot baseline` | Lock in a known-good audit |
|
|
153
|
+
| `mcp serve` | Start MCP stdio server |
|
|
154
|
+
| `omada` / `opnsense` | Vendor import and check |
|
|
155
|
+
|
|
156
|
+
Global flags: `--json`, `--spec`, `--verbose`, `--timeout`.
|
|
157
|
+
|
|
158
|
+
## Documentation
|
|
159
|
+
|
|
160
|
+
- **Spec reference:** [docs/spec.html](https://github.com/jpvelasco/nyx/blob/main/docs/spec.html)
|
|
161
|
+
- **Walkthrough:** [docs/walkthrough.md](https://github.com/jpvelasco/nyx/blob/main/docs/walkthrough.md)
|
|
162
|
+
- **Repository:** [github.com/jpvelasco/nyx](https://github.com/jpvelasco/nyx)
|
|
163
|
+
|
|
164
|
+
## License
|
|
165
|
+
|
|
166
|
+
MIT — see [LICENSE](https://github.com/jpvelasco/nyx/blob/main/LICENSE).
|
|
167
|
+
|
|
168
|
+
nyx is independent tooling — not affiliated with TP-Link/Omada, OPNsense, or the nmap project.
|
package/install.js
CHANGED
package/package.json
CHANGED
|
@@ -1,12 +1,16 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "nyx-audit-cli",
|
|
3
|
-
"version": "0.2.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "0.2.5",
|
|
4
|
+
"description": "Prove your homelab matches your intent — YAML network specs, live VLAN/VPN audits, drift detection, Omada/OPNsense import. Cross-platform CLI with MCP for AI agents.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
7
7
|
"type": "git",
|
|
8
8
|
"url": "git+https://github.com/jpvelasco/nyx.git"
|
|
9
9
|
},
|
|
10
|
+
"bugs": {
|
|
11
|
+
"url": "https://github.com/jpvelasco/nyx/issues"
|
|
12
|
+
},
|
|
13
|
+
"homepage": "https://github.com/jpvelasco/nyx#readme",
|
|
10
14
|
"bin": {
|
|
11
15
|
"nyx": "run.js"
|
|
12
16
|
},
|
|
@@ -24,25 +28,51 @@
|
|
|
24
28
|
],
|
|
25
29
|
"keywords": [
|
|
26
30
|
"network",
|
|
27
|
-
"audit",
|
|
28
|
-
"
|
|
29
|
-
"
|
|
30
|
-
"
|
|
31
|
+
"network-audit",
|
|
32
|
+
"network-security",
|
|
33
|
+
"network-monitoring",
|
|
34
|
+
"network-validation",
|
|
31
35
|
"homelab",
|
|
36
|
+
"homelab-network",
|
|
37
|
+
"vlan",
|
|
38
|
+
"vpn",
|
|
39
|
+
"wireguard",
|
|
40
|
+
"firewall",
|
|
41
|
+
"segmentation",
|
|
42
|
+
"zero-trust",
|
|
43
|
+
"routing",
|
|
44
|
+
"dns",
|
|
45
|
+
"nmap",
|
|
46
|
+
"infrastructure",
|
|
47
|
+
"intent",
|
|
48
|
+
"yaml",
|
|
49
|
+
"audit",
|
|
50
|
+
"compliance",
|
|
51
|
+
"drift-detection",
|
|
52
|
+
"devops",
|
|
53
|
+
"sre",
|
|
54
|
+
"opnsense",
|
|
55
|
+
"omada",
|
|
56
|
+
"tp-link",
|
|
57
|
+
"sdn",
|
|
32
58
|
"mcp",
|
|
33
|
-
"
|
|
59
|
+
"model-context-protocol",
|
|
60
|
+
"ai-agent",
|
|
61
|
+
"cli",
|
|
62
|
+
"port-scan"
|
|
34
63
|
],
|
|
35
64
|
"files": [
|
|
65
|
+
"README.md",
|
|
36
66
|
"install.js",
|
|
37
67
|
"run.js",
|
|
38
68
|
"bin/"
|
|
39
69
|
],
|
|
40
70
|
"binaryChecksums": {
|
|
41
|
-
"nyx_0.2.
|
|
42
|
-
"nyx_0.2.
|
|
43
|
-
"nyx_0.2.
|
|
44
|
-
"nyx_0.2.
|
|
45
|
-
"nyx_0.2.
|
|
46
|
-
"nyx_0.2.
|
|
71
|
+
"nyx_0.2.5_darwin_amd64.tar.gz": "cb744fbb93bef215b2561d3ac0ce3a88343d2702ff61b57864b916a6a9f2ad5c",
|
|
72
|
+
"nyx_0.2.5_darwin_arm64.tar.gz": "8263e2d26f688c7f1bcebfccbb02f1ec1606c2e3a3c39aa68222cb45f09bce44",
|
|
73
|
+
"nyx_0.2.5_linux_amd64.tar.gz": "517fbec4837ba6dbf316c19e181afcd7377d35c9b67b865a97dc01fa0cfc87bd",
|
|
74
|
+
"nyx_0.2.5_linux_arm64.tar.gz": "e4563604aeba49ba4d0457dbf2c57a51a6a62dd616283cb367e7cb26d3902eee",
|
|
75
|
+
"nyx_0.2.5_windows_amd64.zip": "78192a7765f3e3f138cda933940112c65e6b674f571c497d5292e5242c667ed0",
|
|
76
|
+
"nyx_0.2.5_windows_arm64.zip": "8b8bdcf6b8e02a927ece6314d4ee2b8e94cb4548acba5787e8046caec6bd7632"
|
|
47
77
|
}
|
|
48
78
|
}
|