numasec

What it is

numasec is an AGPL-3.0-or-later terminal agent by Francesco Stabile. It wraps a model of your choice in an "operation kernel" that stores scope, runbooks, observations, findings, evidence, replay artifacts and reports as a durable record, so work survives the end of a chat. The README calls the project early.

How it works

An operation is stored as events, facts, relations, evidence, replay artifacts, workflow state and deliverables. A numasec.md file may exist as a derived context pack, but it is not the source of truth.

Findings move through explicit states. A suspicion starts as a candidate, becomes observed once evidence backs it, and becomes verified when promoted with proof semantics. A finding is reportable only with evidence plus replay or a structured exemption. Candidates can be rejected, and observed or verified items can go stale.

flowchart LR
  C["Candidate"] --> O["Observed"]
  O --> V["Verified"]
  V --> R["Reportable"]
  C --> X["Rejected"]
  O --> S["Stale"]
  V --> S

The agent gets tool surfaces including http_request, browser, scanner, appsec_probe, scope, opsec, autonomy, evidence, finding, report and remediate. The knowledge tool brokers CVE, advisory, methodology and tool-doc lookups. For observed components such as nginx 1.18.0 or npm:react@18.2.0 it separates possibility from applicability, adds KEV/EPSS data where available, and does not turn intelligence into a finding. cve is kept as a compatibility alias.

Preconditions / Affected

• Local tools make it stronger but are optional: nmap, sqlmap, ffuf, gobuster, nikto, nuclei, trivy, checksec.
• Any supported model provider works, including OpenAI, Anthropic, Google, xAI, Bedrock, OpenRouter, Ollama and OpenAI-compatible endpoints.
• Maturity: AppSec and Pentest are the mature focus. The strongest runbooks are appsec-web-triage, web-surface and the pwn starter flow. Repository AppSec, API/auth, network, OSINT, CTF/lab, and cloud/container/IaC/binary triage are labeled less mature.
• Licence: AGPL-3.0 or later.

What to do

Install by one of these routes:

npm install -g numasec
bun add -g numasec
docker run -it --rm -v "$PWD:/work" -w /work francescostabile/numasec:latestgit clone https://github.com/FrancescoStabile/numasec.git

(The Docker and git lines run together in the page text; they are separate commands.) Install the helper tools:

apt install nmap sqlmap ffuf gobuster nikto nuclei trivy checksec
brew install nmap sqlmap ffuf gobuster nikto nuclei trivy checksec

A first session against a local lab or owned app:

/doctor
/mode appsec
/runbook run appsec-web-triage http://localhost:3000
/share

/doctor reports which tools are available, degraded or missing. /opsec strict tightens operation boundaries. /pwn <target> creates a scoped pentest operation. /remediate <observation_id> produces remediation guidance. /share exports the operation bundle.

To build and test from source, work inside the package, not the repo root:

bun install
bun typecheck
cd packages/numasec
bun test --timeout 30000
bun run build
bun run bench:cyber --domain appsec
bun run bench:cyber --domain pentest

Caveats

• The README says it is for authorized work only: systems you own, labs, CTFs, or targets with permission.
• It does not claim to replace authorization, operator judgment, manual review or specialized tools.
• The page gives no benchmark results, so the bench:cyber outputs are unknown. The benchmarks are described as local and manual release-confidence tools.
• Roadmap items such as team operations, OSINT with provenance, and community runbooks are not yet built.