{"id":50053537,"url":"https://github.com/FrancescoStabile/numasec","last_synced_at":"2026-05-28T00:01:09.646Z","repository":{"id":337795113,"uuid":"1147932880","full_name":"FrancescoStabile/numasec","owner":"FrancescoStabile","description":"The AI Agent for Cyber Security.","archived":false,"fork":false,"pushed_at":"2026-05-08T22:41:59.000Z","size":266185,"stargazers_count":375,"open_issues_count":2,"forks_count":46,"subscribers_count":9,"default_branch":"main","last_synced_at":"2026-05-26T23:47:21.627Z","etag":null,"topics":["ai-agent","ai-security","appsec","bug-bounty","cli","cybersecurity","dast","devsecops","ethical-hacking","llm","mcp","mcp-tools","owasp","penetration-testing","red-team","security-automation","security-testing","typescript","vulnerability-scanner","web-security"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FrancescoStabile.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":"FrancescoStabile"}},"created_at":"2026-02-02T11:31:26.000Z","updated_at":"2026-05-26T21:06:50.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/FrancescoStabile/numasec","commit_stats":null,"previous_names":["francescostabile/numasec"],"tags_count":26,"template":false,"template_full_name":null,"purl":"pkg:github/FrancescoStabile/numasec","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FrancescoStabile%2Fnumasec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FrancescoStabile%2Fnumasec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FrancescoStabile%2Fnumasec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FrancescoStabile%2Fnumasec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FrancescoStabile","download_url":"https://codeload.github.com/FrancescoStabile/numasec/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FrancescoStabile%2Fnumasec/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33588345,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-27T02:00:06.184Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","ai-security","appsec","bug-bounty","cli","cybersecurity","dast","devsecops","ethical-hacking","llm","mcp","mcp-tools","owasp","penetration-testing","red-team","security-automation","security-testing","typescript","vulnerability-scanner","web-security"],"created_at":"2026-05-21T11:00:55.295Z","updated_at":"2026-05-28T00:01:09.632Z","avatar_url":"https://github.com/FrancescoStabile.png","language":"TypeScript","funding_links":["https://github.com/sponsors/FrancescoStabile"],"categories":["Tools"],"sub_categories":["Penetration Testing"],"readme":"\u003ch1 align=\"center\"\u003enumasec\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cb\u003eThe open source AI security agent.\u003c/b\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  Give your terminal a security brain.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  Run security workflows with your local tools, agents, runbooks, findings, evidence, replay and reports.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ccode\u003enpm install -g numasec\u003c/code\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/FrancescoStabile/numasec/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/FrancescoStabile/numasec/ci.yml?branch=main\u0026style=for-the-badge\u0026label=CI\u0026logo=github\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/FrancescoStabile/numasec/releases\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/FrancescoStabile/numasec?include_prereleases\u0026style=for-the-badge\u0026label=release\u0026labelColor=0b0f0a\u0026color=2f81f7\" alt=\"release\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/numasec\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/numasec?style=for-the-badge\u0026label=npm\u0026logo=npm\u0026logoColor=white\u0026labelColor=0b0f0a\u0026color=cb3837\" alt=\"npm\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/numasec\"\u003e\u003cimg src=\"https://img.shields.io/npm/dm/numasec?style=for-the-badge\u0026color=00c2ff\u0026label=downloads\" alt=\"npm downloads\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/FrancescoStabile/numasec/stargazers\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/FrancescoStabile/numasec.svg?style=for-the-badge\u0026label=stars\u0026logo=github\u0026logoColor=white\u0026labelColor=0b0f0a\u0026color=f5a524\u0026cacheSeconds=1800\" alt=\"GitHub stars\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-AGPL--3.0--or--later-00c2ff?style=for-the-badge\" alt=\"AGPL-3.0-or-later license\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/topreadme.png\" alt=\"numasec AI security agent running in the terminal\" width=\"920\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#demo\"\u003eDemo\u003c/a\u003e |\n  \u003ca href=\"#why-numasec\"\u003eWhy\u003c/a\u003e |\n  \u003ca href=\"#what-it-feels-like\"\u003eWhat it feels like\u003c/a\u003e |\n  \u003ca href=\"#try-it\"\u003eTry it\u003c/a\u003e |\n  \u003ca href=\"#what-it-does\"\u003eWhat it does\u003c/a\u003e |\n  \u003ca href=\"#commands\"\u003eCommands\u003c/a\u003e |\n  \u003ca href=\"#architecture\"\u003eArchitecture\u003c/a\u003e |\n  \u003ca href=\"#roadmap\"\u003eRoadmap\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## What is numasec?\n\nnumasec is an AI security agent that runs in your terminal.\n\nIt uses the tools already installed on your machine, follows security runbooks, switches between cyber agents, keeps the operation context alive, tracks findings, stores evidence and helps turn the work into reports.\n\nIt is built for people who already live between shell, browser, HTTP requests, scanners, advisories, notes and reports.\n\n- Not a chatbot.\n- Not a scanner wrapper.\n- Not a Burp or Kali replacement.\n\nA security agent for the workflow you already have.\n\n## Demo\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"assets/demo.mp4\"\u003e\n    \u003cimg src=\"assets/demo-preview.gif\" alt=\"numasec running a scoped security operation from the terminal\" width=\"940\" /\u003e\n  \u003c/a\u003e\n  \u003cbr /\u003e\n  \u003csub\u003eClick the preview for the full terminal recording.\u003c/sub\u003e\n\u003c/p\u003e\n\n## Why numasec\n\nSecurity work does not happen in one clean place.\n\nYou move between terminal commands, browser work, HTTP requests, local tools, scanners, advisories, notes, screenshots, findings and reports.\n\nAI can help, but only if it lives inside that workflow.\n\nnumasec gives the model a security workspace instead of just a chat box. It keeps the target, scope, tools, runbooks, findings, evidence, replay and report state together while the work is happening.\n\nThe goal is simple:\n\n**make security work feel faster, sharper and less scattered.**\n\nnumasec is strongest today for authorized AppSec and Pentest workflows. Other cyber surfaces exist or are possible, but they are not marketed as equally mature yet.\n\n## Why now\n\nCoding agents changed how developers work.\n\nThey read code, run commands, edit files, execute tests and stay inside the development loop.\n\nSecurity needs the same shift, but security work has different constraints.\n\nA security agent needs to know the target, stay inside scope, use the local toolchain, remember what happened, separate noise from findings and keep enough context to produce useful output later.\n\nThat is what numasec is trying to become:\n\n**the open source AI security agent for the terminal.**\n\n## What it feels like\n\nOpen numasec inside the workspace you are testing, pick the right security agent, check which local tools are available, then start a runbook and let the agent help you move through the workflow.\n\nWhen the work changes, switch posture. When something matters, keep the finding, evidence, replay and report context close to the operation instead of scattering it across shell history, screenshots and notes.\n\nThen come back later and resume without starting from zero.\n\n## Product tour\n\nnumasec starts like a terminal agent, then the security work begins, and it becomes a workspace.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/dashboard.png\" alt=\"numasec chat-first security console home screen\" width=\"840\" /\u003e\n\u003c/p\u003e\n\nYou get the model, the active agent, the command palette, the working directory and the prompt. The point is not to leave your terminal; the point is to make the terminal smarter.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/findings.png\" alt=\"numasec findings lens with evidence, replay, reportability and operation sidebar\" width=\"940\" /\u003e\n\u003c/p\u003e\n\nFindings are not dumped into chat: they live in the operation, where each one can carry state, severity, evidence, replay status and next action, so the agent can keep working without losing the thread.\n\nWeak signals can stay weak. Rejected claims remain visible. Reportable findings need proof.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/switchagents.gif\" alt=\"switching between numasec cyber specialist agents\" width=\"760\" /\u003e\n\u003c/p\u003e\n\nSecurity work changes shape. AppSec, Pentest, OSINT, CTF/lab and research do not need the same posture, so you can switch the agent when the work changes instead of forcing one generic assistant to behave the same way everywhere.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/operations.png\" alt=\"numasec operation selector with rename support\" width=\"760\" /\u003e\n\u003c/p\u003e\n\nOperations are durable. Name them, rename them, resume them and export them. A security workflow should not disappear because the chat ended.\n\n## Try it\n\n```bash\nnpm install -g numasec\nnumasec\n```\n\nThen start with a local lab, CTF, owned app or authorized target:\n\n```text\n/doctor\n/mode appsec\n/runbook run appsec-web-triage http://localhost:3000\n/share\n```\n\nRun numasec from the workspace you are testing and keep the target scope explicit.\n\n## What it does\n\n| Capability | What it gives you |\n| --- | --- |\n| **AI security agent** | A model that works inside your terminal instead of sitting in a separate chat window. |\n| **Local tools** | numasec uses the tools installed on your machine and shows what is available, missing or degraded. |\n| **Runbooks** | Security workflows that keep the agent moving through a real task instead of random tool calls. |\n| **Agents** | Switch posture with TAB for AppSec, Pentest, OSINT, CTF/lab and research-style work. |\n| **Operation memory** | Keep target, scope, activity, findings, evidence, replay and report state together. |\n| **Findings workflow** | Track security signals as they move from weak ideas to useful findings. |\n| **Evidence and replay** | Keep the material needed to understand, verify and reproduce important work. |\n| **Cyber knowledge** | Bring vulnerability intelligence, advisories, methodology and tool docs into the workflow. |\n| **Reports** | Generate deliverables from the operation instead of reconstructing everything at the end. |\n| **Share bundles** | Export the work so it can be reviewed, resumed or handed off. |\n\n## Built for\n\nnumasec is for people who want an AI agent inside their security workflow, not beside it.\n\n- **AppSec engineers** triaging web apps, APIs, dependencies, auth flows and reports.\n- **Pentesters** moving through scoped work with terminal tools, notes, evidence and deliverables.\n- **Bug bounty hunters** who want to move faster without losing target context.\n- **Security researchers** jumping between shell, browser, HTTP, advisories, tradecraft and notes.\n- **CTF and lab users** who want structure while still keeping direct control of the tools.\n\nnumasec is for authorized security work. Use it only on systems you own, labs, CTFs, or targets where you have permission to test.\n\n## How the workflow fits together\n\nnumasec is not just a prompt with tools.\n\nIt keeps the security workflow connected: target, operation, posture, runbook, local tools, observations, findings, evidence, replay and report.\n\n```mermaid\nflowchart LR\n  target[\"Target\"] --\u003e operation[\"Operation\"]\n  operation --\u003e posture[\"Scope + opsec + autonomy\"]\n  posture --\u003e runbook[\"Runbook\"]\n  runbook --\u003e tools[\"Local cyber tools\"]\n\n  tools --\u003e evidence[\"Evidence\"]\n  evidence --\u003e observations[\"Observations\"]\n  observations --\u003e findings[\"Findings\"]\n  findings --\u003e proof[\"Replay / proof\"]\n  proof --\u003e report[\"Report\"]\n\n  operation -. source of truth .-\u003e kernel[\"Cyber kernel\"]\n  kernel --\u003e evidence\n  kernel --\u003e findings\n  kernel --\u003e report\n\n  classDef primary fill:#04130d,stroke:#00ff88,color:#eafff4,stroke-width:2px;\n  classDef secondary fill:#061014,stroke:#00c2ff,color:#eaf9ff,stroke-width:1.5px;\n  classDef proofNode fill:#151104,stroke:#ffcc66,color:#fff7df,stroke-width:1.5px;\n  classDef findingNode fill:#190808,stroke:#ff5f6d,color:#fff0f0,stroke-width:1.5px;\n\n  class target,operation,posture,runbook,tools primary;\n  class evidence,observations,kernel secondary;\n  class proof,report proofNode;\n  class findings findingNode;\n```\n\nThe important part: the operation does not live only in chat. numasec keeps a durable record of the work so the agent can continue, the operator can review, and the report can come from what actually happened.\n\n## How numasec is different\n\nMost AI security tools fall into one of two traps: they only talk, or they only wrap tools. numasec tries to do something different: keep the workflow alive while the agent works.\n\n| Compared with | What usually happens | What numasec does |\n| --- | --- | --- |\n| **Generic AI chats** | Good advice, but detached from the actual work. | Runs inside the terminal workflow with tools, memory and operation state. |\n| **Generic coding agents** | Great for repos and tests, but not shaped around security work. | Adds security agents, runbooks, scope, findings, evidence, replay and reports. |\n| **Scanner wrappers** | Fast output, weak context. | Turns tool output into part of a larger operation. |\n| **Manual notes** | Flexible, but everything drifts apart. | Keeps findings, evidence, replay and reports connected. |\n| **Tool servers** | Expose capabilities, but leave workflow and memory to the user. | Adds the security workflow around the tools. |\n\n## Commands\n\nnumasec is designed to stay fast from the keyboard: start an operation, switch agents, run workflows, inspect tools, tighten opsec, export the work and come back later.\n\n```text\n/doctor                        inspect local tool readiness\n/mode appsec                   switch to the AppSec agent\n/mode pentest                  switch to the Pentest agent\n/agents                        open the agent switcher\n/runbook list                  show available security workflows\n/runbook run appsec-web-triage \u003ctarget\u003e\n/runbook run web-surface \u003ctarget\u003e\n/operations                    inspect, rename, resume or switch operations\n/opsec strict                  tighten operation boundaries\n/models                        switch provider or model\n/share                         export the active operation bundle\n/remediate \u003cobservation_id\u003e    turn an observation into remediation guidance\n/pwn \u003ctarget\u003e                  create a scoped pentest operation for a target\n```\n\n## Install\n\n### npm\n\n```bash\nnpm install -g numasec\nnumasec\n```\n\n### Bun\n\n```bash\nbun add -g numasec\nnumasec\n```\n\n### Docker\n\n```bash\ndocker run -it --rm -v \"$PWD:/work\" -w /work francescostabile/numasec:latest\n```\n\n### From source\n\n```bash\ngit clone https://github.com/FrancescoStabile/numasec.git\ncd numasec\nbun install\ncd packages/numasec\nbun run build\n```\n\n## Tool surface\n\nnumasec does not try to replace your tools.\n\nIt gives the agent a controlled way to use and reason around the environment you already have: shell, files, browser, HTTP, scanners, evidence, reports, knowledge and workspace state.\n\nThe agent sees a small set of useful security surfaces:\n\n- **terminal and files:** `bash`, `read`, `write`, `edit`, `apply_patch`, `grep`, `glob`\n- **web and application testing:** `http_request`, `browser`, `scanner`, `appsec_probe`\n- **operation control:** `runbook`, `pwn_bootstrap`, `scope`, `opsec`, `autonomy`, `identity`\n- **proof workflow:** `evidence`, `observation`, `finding`, `report`, `share`, `remediate`\n- **security intelligence:** `knowledge`, `methodology`, `cve`\n- **environment:** `doctor`, `workspace`, `vault`, `net`, `crypto`, `analyze`\n\n`knowledge` is the preferred cyber research surface. It routes vulnerability intelligence, package advisories, methodology, tradecraft, exploit signals and installed tool docs through one provenance-aware broker.\n\nFor observed components like `nginx 1.18.0`, `OpenSSH_8.2p1` or `npm:react@18.2.0`, it separates **possibility** from **applicability**, enriches with KEV/EPSS where available, and suggests safe next actions without turning intelligence into a finding.\n\n`cve` remains as a compatibility alias for CVE-style lookup. New cyber research should use `knowledge`.\n\nLocal tools make numasec stronger. If these are installed, the agent can use or reason around them:\n\n```bash\n# Debian / Kali / Ubuntu\napt install nmap sqlmap ffuf gobuster nikto nuclei trivy checksec\n\n# macOS\nbrew install nmap sqlmap ffuf gobuster nikto nuclei trivy checksec\n```\n\nUse `/doctor` to see what is available, degraded, or missing on the current machine.\n\n## Models and providers\n\nBring the model you trust. numasec is model-agnostic and wraps the model you choose with a security workflow: terminal, tools, agents, runbooks, operation memory, findings, evidence and reports.\n\nSupported provider families include OpenAI, Anthropic, Google, xAI, Bedrock, OpenRouter, Ollama, Vercel AI Gateway, OpenAI-compatible endpoints, and other providers supported through the local model stack.\n\nThe bet is not that one model magically solves security. The bet is that good models become much more useful when they work inside the right security environment.\n\n## Architecture\n\nnumasec wraps the model with a security workflow. The model can reason and act; numasec keeps the operation around it: tools, runbooks, events, facts, evidence, replay, findings and deliverables.\n\n```mermaid\nflowchart TB\n  operator[\"Operator\"] --\u003e console[\"Terminal console\"]\n  console --\u003e control[\"Permissioned / auto execution\"]\n  control --\u003e agents[\"Cyber agents\"]\n  agents --\u003e runbooks[\"Runbooks\"]\n\n  subgraph tool_layer[\"Tool layer\"]\n    browser[\"Browser\"]\n    http[\"HTTP\"]\n    scanner[\"Scanner\"]\n    shell[\"Shell\"]\n    knowledge[\"Knowledge broker\"]\n    vault[\"Vault\"]\n  end\n\n  runbooks --\u003e browser\n  runbooks --\u003e http\n  runbooks --\u003e scanner\n  runbooks --\u003e shell\n  runbooks --\u003e knowledge\n  runbooks --\u003e vault\n\n  subgraph kernel[\"Cyber operation kernel\"]\n    ledger[\"Ledger\"]\n    facts[\"Facts\"]\n    relations[\"Relations\"]\n    evidence[\"Evidence\"]\n    replay[\"Replay\"]\n    workflow[\"Workflow\"]\n  end\n\n  browser --\u003e evidence\n  http --\u003e evidence\n  scanner --\u003e evidence\n  shell --\u003e evidence\n  knowledge --\u003e facts\n  vault --\u003e facts\n\n  ledger --\u003e facts\n  facts --\u003e relations\n  evidence --\u003e replay\n  facts --\u003e workflow\n\n  facts --\u003e lifecycle[\"Finding lifecycle\"]\n  relations --\u003e lifecycle\n  replay --\u003e lifecycle\n  workflow --\u003e deliverables[\"Reports / share bundles / remediation\"]\n  lifecycle --\u003e deliverables\n\n  classDef top fill:#04130d,stroke:#00ff88,color:#eafff4,stroke-width:2px;\n  classDef tool fill:#061014,stroke:#00c2ff,color:#eaf9ff,stroke-width:1.5px;\n  classDef state fill:#0b0f0a,stroke:#7affb2,color:#eafff4,stroke-width:1.5px;\n  classDef proofNode fill:#151104,stroke:#ffcc66,color:#fff7df,stroke-width:1.5px;\n  classDef findingNode fill:#190808,stroke:#ff5f6d,color:#fff0f0,stroke-width:1.5px;\n\n  class operator,console,control,agents,runbooks top;\n  class browser,http,scanner,shell,knowledge,vault tool;\n  class ledger,facts,relations,workflow state;\n  class evidence,replay,deliverables proofNode;\n  class lifecycle findingNode;\n```\n\n### Operation memory\n\nAn operation is stored as events, facts, relations, evidence, replay artifacts, workflow state and deliverables.\n\n`numasec.md` can exist as a derived context pack. It helps orient the model, but it is not the source of truth.\n\n### Finding lifecycle\n\nSecurity work has messy intermediate states. Something can look interesting without being true. Something can be observed without being ready for a report. Something can be verified and later become stale.\n\nnumasec keeps those states visible instead of flattening everything into chat output.\n\n```mermaid\nflowchart LR\n  candidate[\"Candidate\u003cbr/\u003esuspicion\"] --\u003e observed[\"Observed\u003cbr/\u003eevidence-backed signal\"]\n  observed --\u003e verified[\"Verified\u003cbr/\u003epromoted with proof semantics\"]\n  verified --\u003e reportable[\"Reportable\u003cbr/\u003eevidence + replay/exemption\"]\n\n  candidate --\u003e rejected[\"Rejected\u003cbr/\u003eruled out\"]\n  observed --\u003e stale[\"Stale\u003cbr/\u003eno longer trusted\"]\n  verified --\u003e stale\n\n  classDef weak fill:#12170c,stroke:#d6ff66,color:#f8ffd8,stroke-width:1.5px;\n  classDef proof fill:#061014,stroke:#00c2ff,color:#eaf9ff,stroke-width:1.5px;\n  classDef report fill:#04130d,stroke:#00ff88,color:#eafff4,stroke-width:2px;\n  classDef stop fill:#190808,stroke:#ff5f6d,color:#fff0f0,stroke-width:1.5px;\n\n  class candidate weak;\n  class observed,verified proof;\n  class reportable report;\n  class rejected,stale stop;\n```\n\nThe model is allowed to explore. The workflow is not allowed to pretend every idea is a finding.\n\n### Runbooks instead of random tool spam\n\nSecurity agents get noisy when they can call tools without a workflow. numasec uses runbooks to keep the agent moving through a recognizable task shape: surface mapping, AppSec triage, scoped pentest work and future domain-specific workflows.\n\nStrongest today:\n\n- `appsec-web-triage`\n- `web-surface`\n- `pwn` / Pentest starter flow\n\nMaturity-labeled surfaces:\n\n- repository AppSec triage\n- API and auth surface work\n- network surface work\n- OSINT target work\n- CTF and lab workflows\n- cloud, container, IaC and binary triage\n\n## Built to avoid AI security slop\n\nnumasec is built around a simple rule: **the agent can help you move faster, but the workflow should not let it overclaim.**\n\nThat is why numasec tracks scope, operation state, findings, evidence, replay and report output.\n\nMature focus:\n\n- AppSec\n- Pentest\n\nOther cyber surfaces exist or are planned, but they are not marketed as equally mature yet.\n\nnumasec does not claim to replace authorization, operator judgment, manual review or specialized tools.\n\nThat honesty is not marketing modesty. It is part of the product. Security tools lose trust when they confuse confidence with proof.\n\n## Roadmap\n\nThe long-term vision is simple:\n\n**an open source AI security agent that can grow with the community.**\n\nShort term, numasec is staying focused:\n\n- better AppSec workflows\n- better Pentest workflows\n- stronger local tool adapters\n- better evidence and replay capture\n- cleaner report generation\n- more useful agents\n- better operation sharing\n- clearer maturity labels\n\nLonger term:\n\n- OSINT workflows with provenance\n- CTF and lab workflows\n- cloud, container and IaC triage\n- team operations\n- review and handoff\n- richer knowledge packs\n- community runbooks\n\nThe rule stays the same: every mature domain needs real workflow support, not just a prompt.\n\n## Documentation\n\n- [Operations](docs/OPERATIONS.md)\n- [Tool reference](docs/TOOLS.md)\n- [Operation file format](docs/NUMASEC_FILE_FORMAT.md)\n- [Changelog](CHANGELOG.md)\n- [Contributing](CONTRIBUTING.md)\n- [Security](SECURITY.md)\n\n## Development\n\n```bash\nbun install\nbun typecheck\n\ncd packages/numasec\nbun test --timeout 30000\nbun run build\n```\n\nAppSec and Pentest benchmarks are local/manual release-confidence tools:\n\n```bash\ncd packages/numasec\nbun run bench:cyber --domain appsec\nbun run bench:cyber --domain pentest\n```\n\nDo not run package tests from the repo root. numasec uses Bun-first package-local workflows.\n\n## Contributing\n\nThe most valuable contributions make numasec a better operator:\n\n- runbooks with clear scope and proof semantics;\n- parsers that turn tool output into provenance-backed facts;\n- adapters for real security tools;\n- benchmark scenarios that are hard to fake;\n- report templates that reduce overclaiming;\n- TUI polish that makes operations easier to read under pressure.\n\nIf a change creates a confirmed security claim, it needs evidence. If a finding is reportable, it needs replay or a structured exemption.\n\n## Community\n\nThe best feedback is not \"cool project\".\n\nThe best feedback is:\n\n- I tried it on this kind of authorized workflow\n- this part made me faster\n- this part got in my way\n- this tool should be better supported\n- this runbook should exist\n- this finding flow felt wrong\n- this report output was useful or useless\n\nUse GitHub issues and discussions for bugs, workflow feedback, runbook ideas, adapters and release questions.\n\nPlease keep examples authorized, lab-based or safely anonymized.\n\n## Help shape numasec\n\nnumasec is early, but the direction is clear:\n\n**make security work feel faster, sharper and less scattered with an AI agent that lives in the terminal.**\n\nIf that feels useful, star the repo, try it on an authorized workflow and tell me where it breaks.\n\n## License\n\n[GNU Affero General Public License v3.0 or later](./LICENSE). Use numasec for authorized security work, research, education, and defensive operations.\n\n\u003cp align=\"center\"\u003e\n  Built by \u003ca href=\"https://www.linkedin.com/in/francesco-stabile-dev\"\u003eFrancesco Stabile\u003c/a\u003e\n  | \u003ca href=\"https://x.com/Francesco_Sta\"\u003e@Francesco_Sta\u003c/a\u003e\n  \u003cbr/\u003e\u003csub\u003eIf numasec helps you, \u003ca href=\"https://github.com/FrancescoStabile/numasec/stargazers\"\u003edrop a star\u003c/a\u003e and share the workflow.\u003c/sub\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FFrancescoStabile%2Fnumasec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FFrancescoStabile%2Fnumasec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FFrancescoStabile%2Fnumasec/lists"}