numasec: An AI Security Agent That Runs Inside Your Terminal
The AI Agent for Cyber Security.
At a glance
- What is it?
- numasec is a TypeScript CLI that wraps an LLM around the security tools already installed on your machine, keeping targets, scope, runbooks, findings and evidence in a single durable operation. It is aimed at authorized AppSec and pentest work, and its AGPL-3.0 licence shapes who can realistically ship it.
- Who is it for?
- Adopt numasec if you already run authorized AppSec or pentest engagements from a shell and want the agent, the local tool inventory and the findings store to live in the same place. Do not adopt it if you need a polished DAST scanner, if your workflow depends on a GUI proxy, or if AGPL-3.0 is incompatible with how you distribute your own product.
- Can I use it commercially?
- Yes, with strict conditions. AGPL-3.0 is a network copyleft licence: if people use a modified version over a network, for example as a hosted service, you must offer them its source code under the same licence.
- Is it still maintained?
- Yes. The repository last received commits 130 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap numasec is trying to fill between chat and scanner
Most AI security tooling arrives in one of two shapes. Either it is a chat window where you paste a request and hope the model remembers the target three turns later, or it is a scanner with an LLM bolted onto the report writer. numasec takes a third position. The README describes it as an agent that uses the tools already installed on your machine, follows security runbooks, and keeps operation context alive across findings and evidence. The stated non-goals are explicit: not a chatbot, not a scanner wrapper, not a Burp or Kali replacement. That framing matters because it tells you where the project expects to be judged. The target user is someone who already moves between shell, browser, HTTP requests, scanners, advisories, notes and reports, and who loses time re-establishing context rather than running commands. The README is candid that the tool is strongest today for authorized AppSec and pentest workflows, and that other cyber surfaces are not marketed as equally mature. Take that at face value: the maturity claim is scoped, and the scope is narrow.
Operations, runbooks and agents: the three objects that carry state
The architecture visible in the README rests on three named concepts. An operation is the durable container: the README says operations can be named, renamed, resumed and exported, and that a security workflow should not disappear because the chat ended. A runbook is the procedural layer, described as security workflows that keep the agent moving through a real task instead of random tool calls. An agent is the posture layer, switched with TAB, covering AppSec, Pentest, OSINT, CTF/lab and research. Findings sit inside the operation rather than in the transcript, and the README states that each finding can carry state, severity, evidence, replay status and next action. Two design decisions stand out. First, weak signals are allowed to stay weak and rejected claims remain visible, which is a deliberate departure from tools that only surface confirmed issues. Second, reportable findings require proof, which means the evidence store is not decorative. The mechanism is a workspace that holds target, scope, tools, runbooks, findings, evidence, replay and report state together while the work happens. What the README does not describe is how the model is invoked, which providers are supported, or how context is truncated as an operation grows. Those are the questions to answer before trusting it on a long engagement.
Getting it running: install, doctor, mode, runbook
Installation is a single global npm package. The README gives `npm install -g numasec` followed by `numasec` to start. The documented first-run sequence is a slash-command flow: `/doctor` to check the environment, `/mode appsec` to set posture, `/runbook run appsec-web-triage http://localhost:3000` to launch a named runbook against a target, and `/share` to export or share the operation. The README advises running numasec from the workspace you are testing and keeping the target scope explicit. The `/doctor` command is the one to run first, because the tool depends on binaries that already exist on your system. The README says numasec shows what is available, missing or degraded, which implies a detection pass over your PATH rather than a bundled toolchain. That is a meaningful constraint: a fresh container with no scanners installed will give the agent very little to work with, and the quality of a runbook run is bounded by what `/doctor` reports. The `appsec-web-triage` runbook name is the only one quoted in the supplied material, so treat the runbook catalogue as something to inspect after install rather than something documented here.
The local-toolchain dependency is the real limitation
Because numasec orchestrates rather than bundles, its output is a function of your environment. The README frames this positively, as using the tools already installed on your machine, but the failure mode is straightforward. If a runbook expects a specific scanner and `/doctor` reports it missing or degraded, the agent cannot silently substitute one. You get a degraded run, and the README's own vocabulary acknowledges that state. There is a second limitation in the same area. A tool that reads your PATH and executes local binaries inherits whatever those binaries do, including their own network behaviour, their own rate limits and their own false positive profiles. numasec does not appear to sandbox them. The README also does not document a hosted execution model, so the operational burden of keeping the toolchain current falls on you. For a solo bug bounty hunter with a tuned Kali install this is fine. For a team that wants reproducible scans across machines, the absence of a pinned toolchain specification is a real gap, and the README does not claim otherwise.
Where numasec is the wrong tool
If you need a scheduled DAST scan that runs unattended in CI and produces a diffable report, numasec is not that. The README describes an interactive terminal agent with a chat-first console, a command palette and a working directory prompt. That is a human-in-the-loop design. It also states plainly that numasec is not a Burp or Kali replacement, so anyone expecting an intercepting proxy or a curated offensive toolset should look elsewhere. The AGPL-3.0 licence is the third boundary. The repository badge reads AGPL-3.0-or-later. If you embed numasec in a product you distribute, or expose a modified version over a network, the copyleft terms reach your code in ways the MIT and Apache-licensed tools around it do not. Internal use by a security team is a different question from shipping it inside a commercial platform, and the README does not discuss licensing at all. That silence is itself worth noting for anyone planning to build on top of it.
How it differs from Semgrep and from a generic coding agent
Semgrep is the closest well-known point of comparison, and the difference is structural. Semgrep is a static analysis engine: you point it at a codebase, it applies rules, it emits findings, and it exits. numasec is a stateful session that decides what to run next based on a runbook and a posture. Semgrep's output is deterministic given the same rules and the same code. numasec's output depends on the model, the runbook, the installed tools and the accumulated operation context, which makes it far harder to reproduce a run exactly. The second comparison is a general-purpose coding agent such as the ones that read code and run tests. Those agents have no concept of scope, no findings store with severity and evidence, and no reportability gate. numasec's contribution is that vocabulary: target, scope, finding, evidence, replay, report. Whether that vocabulary is worth a separate tool depends on how much of your day is spent maintaining it by hand in notes and screenshots. The README's own answer is that the goal is to make security work feel less scattered, which is a workflow claim rather than a detection claim.
Release cadence, maintenance and what to verify
The release history in the supplied material shows v1.1.19 on 2026-05-02, v1.2.0 on 2026-05-06 and v1.2.1 on 2026-05-08, with the last push to main on the same day as v1.2.1. That is a fast patch cadence across a single week, which suggests active work but also means the surface is moving. For an agent that executes local security binaries, frequent releases cut both ways: fixes arrive quickly, and so do behaviour changes in how runbooks drive those binaries. Pin a version in any environment where you need repeatable results. The repository is not archived, the primary language is TypeScript, and the licence badge reads AGPL-3.0-or-later. Before adopting, verify three things that the README leaves open: what `/share` actually transmits and to where, which model providers the agent supports and whether keys stay local, and how operation state is stored on disk and whether it contains target data you would not want in a backup. The README gives the command sequence to start; it does not give the data-handling details, and those are the ones that decide whether numasec can run against a client target.
Editorial conclusion
Adopt numasec if you already run authorized AppSec or pentest engagements from a shell and want the agent, the local tool inventory and the findings store to live in the same place. Do not adopt it if you need a polished DAST scanner, if your workflow depends on a GUI proxy, or if AGPL-3.0 is incompatible with how you distribute your own product. Before committing, run /doctor to see which tools it detects on your machine, run /runbook run appsec-web-triage against a local lab, and confirm whether /share sends data anywhere outside your terminal.
Community notes