Metadata-Version: 2.4
Name: numasec
Version: 4.0.0
Summary: AI-powered penetration testing via MCP — 21 security tools, PTES methodology, multi-provider
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Requires-Python: >=3.11
Requires-Dist: aiosqlite<1,>=0.20
Requires-Dist: beautifulsoup4<5,>=4.12
Requires-Dist: cryptography<44,>=43
Requires-Dist: dnspython<3,>=2.6
Requires-Dist: httpx<1,>=0.27
Requires-Dist: litellm<2,>=1.50
Requires-Dist: playwright>=1.48
Requires-Dist: pydantic<3,>=2.5
Requires-Dist: pyyaml<7,>=6.0
Requires-Dist: rank-bm25<1,>=0.2
Requires-Dist: zstandard<1,>=0.23
Provides-Extra: all
Requires-Dist: asyncssh>=2.14; extra == 'all'
Requires-Dist: hvac>=2.4; extra == 'all'
Requires-Dist: mcp[cli]>=1.26.0; extra == 'all'
Requires-Dist: mypy>=1.10; extra == 'all'
Requires-Dist: pytest-asyncio>=0.24; extra == 'all'
Requires-Dist: pytest-cov>=5.0; extra == 'all'
Requires-Dist: pytest>=8.0; extra == 'all'
Requires-Dist: ruff>=0.5; extra == 'all'
Requires-Dist: smbprotocol>=1.12; extra == 'all'
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp[cli]>=1.26.0; extra == 'mcp'
Provides-Extra: protocols
Requires-Dist: asyncssh>=2.14; extra == 'protocols'
Requires-Dist: smbprotocol>=1.12; extra == 'protocols'
Provides-Extra: vault
Requires-Dist: hvac>=2.4; extra == 'vault'
Description-Content-Type: text/markdown

<h1 align="center">numasec</h1>
<h3 align="center">Your AI Cyber Security companion. Open source. Runs in the terminal.</h3>

<p align="center">
  <img src="docs/numasecpreview.png" alt="numasec running a pentest against OWASP Juice Shop" width="900" />
</p>

<p align="center">
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="MIT License" /></a>
  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.11+-blue?style=flat-square&logo=python&logoColor=white" alt="Python 3.11+" /></a>
  <a href="https://github.com/FrancescoStabile/numasec/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/FrancescoStabile/numasec/ci.yml?branch=main&style=flat-square&label=build" alt="Build" /></a>
  <a href="https://github.com/FrancescoStabile/numasec/releases/latest"><img src="https://img.shields.io/github/v/release/FrancescoStabile/numasec?style=flat-square&label=release" alt="Release" /></a>
</p>

---

```
curl -fsSL https://numasec.dev/install | bash
numasec
```

Type a URL, endpoint, everything. The AI scans it, finds vulnerabilities, and writes the report. You watch, approve, and steer — like pair-programming, but for security.

It follows real pentest methodology (PTES): reconnaissance, attack surface mapping, vulnerability testing, exploitation, reporting. Not a toy scanner that dumps a CSV. An actual AI agent that thinks, adapts, and chains attacks together.

Works with Claude, GPT-4, Gemini, DeepSeek, or any OpenAI-compatible model.

---

### What you see

A live terminal session. Findings pop up in a sidebar as they're discovered — color-coded by severity, grouped into attack chains, with OWASP Top 10 coverage tracking in the header. Everything is scoped: the agent won't touch anything outside your target.

Type `/target https://yourapp.com` to start. Type `/findings` to see what it found. Type `/report` to get the deliverable.

### What it finds

SQL injection (blind, time-based, union, error-based), XSS (reflected, stored, DOM), SSRF with cloud metadata detection, authentication flaws (JWT attacks, OAuth misconfig, credential spraying, default passwords), IDOR, CSRF, CORS misconfig, path traversal, LFI, command injection, SSTI, XXE, GraphQL introspection — and it chains them. A leaked API key in JS → SSRF → cloud metadata → account takeover.

### What it produces

- **SARIF** — drop it into GitHub Code Scanning
- **HTML** — share with the team
- **Markdown / JSON** — integrate anywhere

Every finding comes with CWE ID, CVSS 3.1 score, OWASP category, MITRE ATT&CK technique, and remediation guidance. Not just "you have a vuln" — actionable output.

---

### How it works

The terminal is a TypeScript TUI (forked from [OpenCode](https://github.com/opencode-ai/opencode), MIT) driving 21 Python security scanners through a JSON-RPC bridge. A knowledge base of 34 templates covers detection patterns, exploitation techniques per DBMS/engine/OS, post-exploitation, payloads, and remediation — so the AI doesn't hallucinate attack methodology, it looks it up.

96% recall on OWASP Juice Shop v17 — 25 of 26 ground-truth vulnerabilities found across all 10 OWASP categories.

---

### Development

```bash
pip install -e ".[all]"
pytest tests/ -v
ruff check numasec/
```

924 tests. Benchmarks against Juice Shop, DVWA, and WebGoat in `tests/benchmarks/`.

---

**Built by [Francesco Stabile](https://www.linkedin.com/in/francesco-stabile-dev)**.

[![LinkedIn](https://img.shields.io/badge/LinkedIn-0077B5?style=flat-square&logo=linkedin&logoColor=white)](https://www.linkedin.com/in/francesco-stabile-dev)
[![X](https://img.shields.io/badge/X-000000?style=flat-square&logo=x&logoColor=white)](https://x.com/Francesco_Sta)

[MIT License](LICENSE)
