Contract
Binding invocation, exit codes, meta schema, and identity rules.
Binding contract for all official and custom NXS. Source: nxs/CONTRACT.md (v0.1). Breaking changes increment major version; additive fields stay compatible within the same major.
Mandatory
Every NXS must be executable, support global options below, honour the exit-code table, ignore unknown meta fields, and expose a stable id.
Invocation
nxs-<name> [GLOBAL OPTIONS] [SCRIPT-SPECIFIC OPTIONS]
| Option | Required | Description |
|---|---|---|
--crash <path> | Yes* | Input that caused the event |
--target <host:port> | Yes* | e.g. 10.0.0.5:21 |
--event <type> | No | crash | hang | interesting | new_coverage | new_state |
--model <name> | No | Protocol model |
--minimized <path> | No | Minimised crash input |
--meta <path> | No | JSON metadata from Nexsiz |
--out <dir> | No | Artefact directory |
--timeout <secs> | No | Internal timeout |
-v / --verbose | No | Human log on stderr |
--help / -h | Yes | Usage |
--version | Yes | Version + stable id |
* At least one of --crash or --meta must be present. Meta may supply crash.path and target.
Exit codes
| Code | Meaning |
|---|---|
0 | Completed; no further vulnerability indication |
1 | Operational error |
2 | Escalate — further vulnerability / exploit-assist |
3 | Internal timeout |
4 | Interrupted / cancelled |
≥10 | Script-specific success variants (document in nxs.toml) |
See also Exit Codes.
Metadata JSON
Nexsiz writes meta on spawn. Minimal fields include nexsiz_version, event, timestamp, target, model, crash, result, worker_id, output_dir. Unknown fields must be ignored.
Artefacts (recommended)
<out>/
├── report.json
├── repro/
├── logs/
└── artifacts/
report.json should carry nxs_id, exit_hint, summary, findings, artifacts.
Stdio
- stdout — concise; optional final JSON line
- stderr — human progress/errors (
-v) - stdin — not required;
--meta -may read meta from stdin
Identity (nxs.toml)
| Field | Example |
|---|---|
id | crash/auto-repro |
name | auto-repro |
version | 1.0.0 |
categories | crash,safe,default |
events | crash,hang |
description | one paragraph |