Nexus

An autonomous security assessor for systems you own or are authorized to test.

Nexus reasons like an attacker (recon → enumerate → probe for real weaknesses) and reports like a defender (severity, evidence, concrete remediation) — and it acts only inside an authorized scope you declare up front. It is a tool for assessing your own infrastructure and engagements you have written permission for. It is not a service for attacking third parties.

The brain is a capable model driving a tool-use loop over real security tooling. The built-in probes are pure stdlib, so the core runs in a minimal or air-gapped box.

---

What makes it different: the evidence gate

Every LLM confabulates under pressure. Point any model — a small local one or a frontier one — at a target and ask it to "write the security report", and it will pad the report with plausible findings it never actually confirmed: an imagined TLS weakness, a fabricated exposed-secret, a "likely" SQL injection. For a security tool, a fabricated finding is the worst possible output.

Nexus splits the two jobs the model is good and bad at:

• the model probes — it decides what to test and fires the payloads (it's good at this);
• a deterministic evidence gate (findings.py) writes the report — and it credits a finding only when the live target's own response proves it: the XSS marker reflected back unescaped, /etc/passwd contents returned on a traversal, a SQL error on a quote, a server issuing a token for ' OR 1=1--.

Nothing in the authoritative report comes from the model's prose. The result is a report where every finding is backed by a real response the target actually gave — fabrication is structurally impossible, not merely discouraged.

Proof (live, evidence-gated)

• Real external target — against IBM's public, sanctioned-for-scanning AltoroMutual demo bank (demo.testfire.net), Nexus autonomously enumerated the app and confirmed a Reflected XSS (High) on /search.jsp?query= (marker reflected unescaped), alongside server-version disclosure and missing CSP/HSTS — all live-confirmed, zero fabricated findings.
• OWASP Juice Shop — full pass across the exercised vulnerability classes (SQLi auth-bypass → broken access control), reproduced deterministically.

Ethics & authorization — the core, not a footnote

Nexus is built to be used only against systems you are authorized to test.

• Scope is an explicit allowlist you provide at launch (scope.py). Every tool re-checks the scope before touching a target, and re-checks every redirect hop (an in-scope target that 302s to cloud metadata or loopback is refused — SSRF guard). Out of scope = hard refuse, enforced in code, not left to the model's goodwill.
• --authorized is required to start — it attests you have explicit permission.
• External targets require a second gate. If the target resolves to a public-internet address, Nexus refuses until you pass --rules-accepted — attesting that active, automated testing is permitted by that target's program rules — and it applies a politeness throttle so a live service is never hammered.
• No destructive or denial-of-service actions. The agent assesses through safe, read-leaning means; the system prompt and tool allowlist forbid damage/DoS.

Using this against systems you don't own or have written permission to test is illegal. Don't.

Install

pip install nexus-sec           # core is stdlib — zero runtime deps
pip install "nexus-sec[tui]"    # optional: the full-screen interactive console

Then just run:

nexus

The interactive console

Run nexus with no arguments and you get a full-screen console — a pinned input box, a scrolling conversation above it, a live status line — the shape of a modern agent CLI:

• Type a target (example.com, 127.0.0.1:8080) → it runs an authorized assessment, streaming each tool call and the agent's live reasoning, then a colour-coded findings panel.
• Ask a question (what is broken access control?) → it answers like an AI assistant, with a live "thinking" view as the reply forms.
• Slash commands with live hints (type / to see them, Tab to complete): /model (switch brain/model, with a picker), /key (set your Anthropic API key, hidden), /format (report as md · sarif · json), /scope, /report (render the last report), /defend · /guard · /estate (defend a host/estate you own — read-only posture, proposals only), /clear, /help, /quit. Recall past inputs with ↑/↓; press Esc to stop a run.
• On first run it starts the local Ollama server for you and pulls a free default model — zero setup. Pick a frontier brain any time with /model → Claude, then paste your key inline.

Prefer scripting? The one-shot flag form works too:

Use

# assess a system you own (loopback/lab — no external gate needed):
nexus --target 127.0.0.1:8080 --scope 127.0.0.1 --authorized

# an authorized external engagement (bug-bounty / VDP / written scope):
nexus --target app.example.com --authorized --rules-accepted \
        --rate-limit 2 --objective "Assess the login flow and TLS posture."

# emit SARIF for GitHub code-scanning / CI (or --format json for a raw feed):
nexus --target 127.0.0.1:8080 --scope 127.0.0.1 --authorized --format sarif

# a client-ready deliverable (executive summary, CVSS, attack paths) — print to PDF from a browser:
nexus --target 127.0.0.1:8080 --scope 127.0.0.1 --authorized \
        --format html --client "BluePeak Ltd" --vendor "Acme Offensive Security"

Without --authorized it refuses to run. Against a public-internet target it also refuses without --rules-accepted. The report is evidence-gated by default; add --trust-model-report to see the model's raw (unverified) prose instead.

--format sarif writes a standard SARIF 2.1.0 file (same evidence, machine-readable) that GitHub Security, VS Code, and CI pipelines ingest directly; --format json gives a plain structured feed. The output file extension follows the format.

The client deliverable (--format html)

--format html turns the same evidence-gated findings into a document you can hand a client — a branded, self-contained HTML report (no external assets; open it and Print → Save as PDF). It adds what a raw finding list doesn't:

• an executive summary in plain language for a non-technical reader;
• a computed CVSS 3.1 base score + vector on every finding (the real formula, not a guess);
• attack paths — the narrative of how separate weaknesses combine into a breach (e.g. arbitrary file read → harvest the leaked secret → authenticate), the story a scanner's flat list never tells;
• a compliance mapping — every finding tied to its CWE, OWASP Top 10 (2021) category, and the closest PCI DSS v4.0 requirement, so the report doubles as an audit artefact for a SOC 2 / ISO 27001 / PCI client.

Every line still comes from the evidence gate — CVSS is computed from a fixed vector per class and an attack chain is only asserted when both of its findings were actually confirmed, so the prettier document is no less honest than the raw report. Because it renders offline, the whole report — including the AI-written prose — can be produced on client data you are contractually forbidden to send to a cloud AI. Brand it with --client / --vendor.

Retest / delta (nexus retest)

An engagement doesn't end at the first report — the client remediates and you retest to prove the fixes landed. Save each run's findings (--format json) and diff them:

nexus --target app.example.com --authorized --rules-accepted --format json --report run1.json
# … client remediates …
nexus --target app.example.com --authorized --rules-accepted --format json --report run2.json

nexus retest run1.json run2.json                       # fixed / still-open / new, in the terminal
nexus retest run1.json run2.json --format html \
        --client "BluePeak Ltd" --vendor "Acme Security"   # a branded retest deliverable

It matches findings by class + location and reports each as fixed, still open, or new, with a remediation rate (e.g. 2 of 3 prior findings remediated (67%)) — the proof-of-remediation artefact a retest is paid to produce. Fully offline; nothing is inferred.

Remediation plan (nexus fixes)

A finding list tells a client what is wrong; a senior report tells them what to do Monday morning. From a saved report, nexus fixes emits a prioritised roadmap — findings grouped into Immediate / Short-term / Hygiene by real CVSS risk — plus a copy-paste fix per finding class (a parameterised query, a strict CSP, a path-canonicalisation guard, an nginx deny rule):

nexus --target app.example.com --authorized --rules-accepted --format json --report run.json
nexus fixes run.json                          # the phased plan + code, in the terminal
nexus fixes run.json --report plan.md         # …or written to a Markdown fix-pack

The same plan and fixes ride inside the --format html deliverable. Every fix is a deterministic, curated projection over the evidence-gated findings — no model-authored prose, so the remediation is exactly as trustworthy as the findings it answers. A live leaked credential is always flagged Immediate, regardless of score.

Ask the co-pilot (nexus ask)

Once you have a saved report, interrogate it in plain language — the report becomes an interactive consultation:

nexus --target app.example.com --authorized --rules-accepted --format json --report run.json

nexus ask run.json "what do I fix first?"
nexus ask run.json "how do these chain together?"
nexus ask run.json "explain the exposed secrets"
nexus ask run.json "draft a client summary email"

Answers are deterministic and grounded only in the confirmed findings (reusing the same CVSS / attack-path / compliance / fix projections). That is deliberate: the moat is never fabricate, so the co-pilot cannot invent a finding the target didn't confirm. Ask it to "explain the SQLi" when no SQL injection was found and it tells you there's no evidence for one — rather than making one up. Offline; no model call. nexus ask run.json with no question lists what it can answer.

Choose your brain

Nexus is model-agnostic — the same tool-use loop runs on any of three brains:

--brain	what it is	when
claude (default)	Claude Messages API	strongest reasoning; needs an API key
ollama	a local Ollama server (e.g. qwen2.5:7b)	fully local, no API key
local	an offline HF student model	air-gapped boxes; pip install nexus-sec[local]

Because the evidence gate — not the model's eloquence — is what makes the report trustworthy, even a small local brain produces a report free of fabricated findings.

Coverage

• Custom parametric fuzzing (fuzz_params) — crawls the app (forms, JS-built URLs, and, with the optional [spa] extra, JavaScript-rendered single-page apps), enumerates every parameter, and live-confirms reflected-XSS / path-traversal / SQL-injection with zero false positives.
• Mature-scanner orchestration (nuclei) — thousands of templates for known CVEs / exposures / misconfigurations, with each match passed through the same evidence gate. The two complement each other: nuclei knows the known, fuzz_params finds the custom app logic no template covers.
• Blue-team posture — security-header grading, version-disclosure, TLS checks.

Defend from within

Nexus doesn't only attack — it can attach to a system you own and defend it from the inside. The same evidence gate that makes the pentest report fabrication-proof grades the defensive posture, and a deterministic diff turns a one-shot check into continuous defence: what's new, what's still open, and what's been fixed since the last patrol.

# one-shot: read-only posture of THIS host + an AI triage brief + fix PROPOSALS
nexus --defend --authorized

# continuous guardian: cheap deterministic sweeps on a timer; the AI brain engages ONLY when a
# NEW hole appears — the quiet tiers stay free, the model is spent only where it earns its keep
nexus --guard --authorized --interval 300

# defend a whole estate (hosts + web services) declared in a config, rolled into one posture
nexus --estate assets.json --authorized --interval 300

Inside the interactive console the same capability is /defend, /guard, and /estate.

It inspects, read-only: network-exposed sensitive services (RDP/SMB/WinRM/…), whether endpoint protection and the host firewall are actually on, and hijackable (unquoted) service paths — each reported only on a concrete, evidence-backed bad condition (zero false positives; a healthy setting produces nothing). For every open finding it proposes an exact, reversible fix with its verify + rollback and a risk grade.

Proposals only — nothing is ever applied automatically. Detection and triage never change the system; applying a fix is a separate, explicit, confirm-first step (python -m redblue.blue --apply <finding> --yes), so the defender can never surprise a live box.

Architecture

module	role
scope.py	authorization core — hostname-suffix + IP/CIDR matching + redirect-hop SSRF guard; the ethical line
findings.py	the evidence gate — derives the report from real tool results, never from model prose
llm.py / local.py / hf_local.py	model-agnostic brain seam (Claude / Ollama / offline student)
tools.py	scope-gated hands: DNS / HTTP / port-scan / TLS + parametric fuzzer + allowlisted binaries (nmap, nuclei, ffuf, ...)
agent.py	the autonomous tool-use loop + red+blue system prompt
sentinel.py	defender diff engine — deterministic sweeps graded by the evidence gate, diffed new / still-open / fixed; asset-agnostic
host.py	attach from the inside — read-only host posture (exposed services, Defender/firewall, hijackable paths)
estate.py	defend a whole estate — many hosts + web services rolled into one posture with what changed
blue.py	the defender's brain — triage / risk / attack-chains + the two-tier autonomous guardian (read-only)
remediate.py	a finding → an exact, reversible fix proposal (verify + rollback + risk); applying stays confirm-first
cli.py	launch + the --authorized / external --rules-accepted gates + interactive REPL
tui.py / tui_app.py	the optional rich / full-screen (Textual) interactive console — presentation only

Status

Real and working: the loop, scope gate, evidence gate, parametric fuzzer, SPA rendering, nuclei orchestration, external-target preflight, the interactive full-screen console, the AI-assistant chat mode, and the defender (host/estate posture, the two-tier guardian, and confirm-first remediation) all work and are covered by 285 tests. Proven end-to-end on a live external target, on OWASP Juice Shop, and — locally, driving the console with a free Ollama model — finding real path-traversal and reflected-XSS with zero fabricated findings.