Quickstart · Arsenal · Scope lock · Intel · Docs

AUTHORIZED USE ONLY. Point this at systems you own or have written permission to test. Everything else is a crime scene with extra steps.

MISSION

Security capability layer for the NullByte CLI. An agentic offensive-security toolset that thinks in targets, but is held down by authorization guards, evidence hashes and an audit chain — not by vibes.

sec_* tools cover the full loop: scope, recon, ports, scanners, SAST, the shared threat model, evidence, findings, coverage, retesting, reporting, methodology and audit.

DEMO

_{Illustrative session. No live target is contacted.}

WHY

• Scanning is authorized by default. sec_recon, sec_ports and sec_scan do not require a scope declaration or approval prompt; metadata and link-local addresses are always refused. Shell, webfetch and retest commands still honour an opt-in allow-list.
• Every decision is audited. Allow, deny and ask decisions land in a hash-chained trail.
• Evidence is checked before it is trusted. Artifacts carry SHA-256 digests and are re-hashed on read.
• Findings cannot be closed without proof. The closure gate is code, not a suggestion.
• Reports are deliverables, not chat transcripts: markdown, JSON, HTML, PDF, SARIF and DefectDojo CSV.
• Negative space is recorded. A coverage ledger and shared threat model let the report distinguish "tested and sound" from "never tested".

QUICKSTART

curl -fsSL https://github.com/Eliahhango/nullbyte-security/raw/main/install.sh | bash

One command. The installer clones or updates the repo in ~/.local/share/nullbyte-security (or reuses ~/nullbyte-security), installs dependencies, runs a deterministic install smoke test, and only then repairs the live links. A failed validation leaves an existing installation untouched. Re-run the same command to update or repair.

The full suite is opt-in because it exercises optional PDF converters, local sockets and POSIX permissions that vary by device:

curl -fsSL https://github.com/Eliahhango/nullbyte-security/raw/main/install.sh | bash -s -- --full-test

Use --no-test only when you deliberately want to skip validation.

Inspect without touching anything:

curl -fsSL https://github.com/Eliahhango/nullbyte-security/raw/main/install.sh | bash -s -- --check

Requirements: Linux or macOS, git, Node.js >= 22.6, and the NullByte CLI. Set NULLBYTE_SECURITY_HOME=/path to use a different checkout location.

UNINSTALL

Remove the installed plugin links and the managed checkout, while keeping config and every project's .nullbyte/security/ data:

curl -fsSL https://github.com/Eliahhango/nullbyte-security/raw/main/install.sh | bash -s -- --uninstall

Add --purge to also remove ~/.config/nullbyte. Project data is never touched.

KILL CHAIN

  scope ──▶ recon ──▶ scan ──▶ evidence ──▶ findings ──▶ report
    │                                                       ▲
    └────────────── hash-chained audit trail ───────────────┘

Long scans render a live progress line with elapsed time and counters on a standalone terminal. It is suppressed automatically inside chat/TUI harnesses so stderr animation cannot block the prompt; set NULLBYTE_PROGRESS=1 to force it, or NULLBYTE_NO_PROGRESS=1 / NULLBYTE_PROGRESS=0 to disable it.

ARSENAL

Tool	Function
sec_scope	authorization mode; check a target; write a starter scope
sec_agents	plan, spawn and monitor multiple subagents with parallel work and dependencies; a child can ask you a necessary clarifying question
sec_recon	DNS, HTTP, TLS, headers and fingerprinting; archives raw responses as evidence
sec_ports	bounded TCP connect scan and banner grab
sec_scan	nmap, nuclei, nikto, whatweb, sslscan and sqlmap adapters
sec_sast	local secrets, code smells and dependency checks
sec_evidence	store and verify raw artifacts by SHA-256
sec_finding	findings, CVSS severity, dedupe and closure checks
sec_coverage	record tested surfaces and outcomes; expose the negative space in reports
sec_threat_model	shared per-target threat model with append-only amendments
sec_retest	re-run or record a finding's reproduction
sec_report	export markdown, JSON, HTML, PDF, SARIF or CSV
sec_methodology	search and load shared knowledge fragments, coding skills and security playbooks
sec_audit	review allow/deny decisions and verify the audit chain

bash, read, write, edit, webfetch and todowrite are reused as-is.

SKILL PACKS

sec_methodology ships six NullByte security playbooks — ctf-sprint, agentic-assessment, secure-code-review, vulnerability-remediation, ci-security-gate, application-assessment — plus eight original coding skills: feature-delivery, debugging, test-strategy, refactoring, performance, dependency-upgrade, code-review, api-contract. Search them with sec_methodology action=search query=debugging and load only what the task needs.

The coding skills are also exported as standalone skills/<id>/SKILL.md packages for hosts that discover skills on disk. security-lib/coding-skills.ts is the source of truth; regenerate with node --experimental-strip-types tools/export-skills.ts.

SCOPE LOCK

Scanning needs no scope file: sec_recon, sec_ports and sec_scan are authorized by default, at every intensity, with no approval prompt. Metadata and link-local addresses are still refused. Destructive commands and local credential files stay guarded too.

An opt-in .nullbyte/security/scope.json remains useful for bash, webfetch and sec_retest, which still honour it:

{
  "engagement": "acme-q4",
  "authorized_all": false,
  "intensity": "safe-active",
  "include": [
    { "host": "app.acme.test", "ports": [443, 8443] },
    { "host": "*.acme.test" }
  ],
  "exclude": ["billing.acme.test"]
}

include accepts hosts, wildcards, IPs, CIDRs and URLs. exclude wins. Scope is operator-owned unless allow_model_scope_edit is enabled. Scan targets ignore this allow-list by design; it is not a gate on recon or scanner adapters.

INTEL

• Captures are verbatim by default, including secrets. Use include_secrets=false to redact at capture; this is irreversible.
• Reports are verbatim unless redact=true. Treat every export as credential-grade sensitive.
• Evidence is hash-checked on read; corrupted artifacts are refused.
• Encryption at rest is optional: set NULLBYTE_STORE_KEY or ~/.config/nullbyte/security.key, or require it with plugins.encrypt_store: true.

DOCS

• docs/PENTEST.md — tools, enforcement, pacing, encryption and gotchas
• docs/HACKERAI_GAP_ANALYSIS.md — capability comparison
• docs/IMPLEMENTATION_ROADMAP.md — what is next
• SECURITY.md — vulnerability reporting

LICENSE

MIT — see LICENSE.