numasec: AI Security Agent for Terminal Workflows

numasec addresses the fragmented nature of security work by providing an AI agent that operates directly within the terminal environment. It targets AppSec engineers, pentesters, bug bounty hunters, and security researchers, aiming to streamline workflows by integrating AI assistance with existing local tools, runbooks, and operational context. The primary benefit is a faster, sharper, and less scattered security workflow, keeping the operator within their familiar shell environment.

How It Works

numasec functions as an AI security agent embedded within the terminal, offering a persistent "security workspace" rather than a detached chatbot. It leverages local tools, integrates with user-defined runbooks for structured task execution, and manages the entire operation's state—including target scope, findings, evidence, and replay artifacts. This approach contrasts with generic AI chats or simple scanner wrappers by maintaining context and state throughout the security lifecycle, enabling agents to operate effectively within the user's existing workflow and toolchain.

Quick Start & Requirements

• Installation: npm install -g numasec (also available via Bun and Docker).
• Prerequisites: Local security tools (e.g., nmap, sqlmap, ffuf) are recommended; use /doctor to check readiness. Model providers (OpenAI, Anthropic, Ollama, etc.) need to be configured.
• Links: GitHub

Highlighted Details

• Agents & Runbooks: Supports specialized agents (AppSec, Pentest, OSINT) and structured runbooks for automated task execution (e.g., appsec-web-triage).
• Operation Memory: Maintains durable state for target, scope, findings, evidence, and replay, allowing operations to be resumed.
• Findings Lifecycle: Tracks security signals through states like candidate, observed, verified, reportable, rejected, and stale.
• Knowledge Broker: Centralizes vulnerability intelligence, advisories, and tool documentation for enriched context.

Maintenance & Community

The project is maintained by Francesco Stabile. Community feedback, bug reports, and feature requests are encouraged via GitHub issues and discussions. The roadmap outlines short-term goals like improved AppSec/Pentest workflows and longer-term plans for OSINT, CTF, and team operations. Contributions require evidence for security claims and replay/exemption for reportable findings.

Licensing & Compatibility

Licensed under the GNU Affero General Public License v3.0 or later (AGPLv3+). Use is restricted to authorized security work, research, education, and defensive operations. The AGPLv3 license may have implications for derivative works and closed-source integration due to its strong copyleft provisions.

Limitations & Caveats

numasec is explicitly focused on AppSec and Pentest workflows, with other cyber surfaces noted as less mature. It does not replace operator judgment, manual review, or specialized tools, and is intended solely for authorized testing scenarios. The AGPLv3 license requires any modifications or derivative works distributed to be made available under the same license.