numasec 3.0.0__tar.gz

numasec-3.0.0/.gitignore

@@ -0,0 +1,104 @@
+# ── Virtual environments ──
+.venv/
+venv/
+ENV/
+env/
+
+# ── Node ──
+node_modules/
+package-lock.json
+
+# ── Python bytecode & packaging ──
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+.eggs/
+dist/
+build/
+*.so
+.Python
+
+# ── Testing & coverage ──
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+
+# ── Linters & type checkers ──
+.ruff_cache/
+.mypy_cache/
+
+# ── Data files (local databases, sessions) ──
+/data/
+*.db
+*.sqlite
+*.sqlite3
+
+# ── CTF artifacts (output files) ──
+*_context.txt
+*_extracted/
+*_carved/
+*_foremost/
+*_http_objects/
+
+# ── Generated reports ──
+numasec_report_*
+
+# ── IDE ──
+.vscode/
+.idea/
+*.swp
+*.swo
+.github/copilot-instructions.md
+
+# ── OS ──
+.DS_Store
+Thumbs.db
+
+# ── Temp & log files ──
+test.*
+*.tmp
+*.bak
+*.log
+*_results.txt
+*_debug.txt
+debug_*.txt
+reproduction_*.txt
+
+# ── Knowledge base cache ──
+.numasec_kb_cache/
+.numasec_vector_db/
+
+# ── Workspace sessions (generated) ──
+workspace/sessions/
+
+# ── Binaries downloaded during CTF ──
+*.elf
+*.exe
+*.dll
+
+# ── Large files ──
+*.raw
+*.dd
+*.img
+*.vmem
+
+# ── Secrets & runtime data ──
+.env
+.env.*
+!.env.example
+config.yaml
+evidence/
+
+# ── Private docs (not for public repo) ──
+docs/STRATEGY.md
+docs/LAUNCH_CONTENT.md
+docs/notes/
+
+# ── Misc ──
+.trash/
+.agent/

numasec-3.0.0/CHANGELOG.md

@@ -0,0 +1,116 @@
+# Changelog
+
+All notable changes to NumaSec will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [3.0.0] - 2026-02-05 🚀
+
+### The Great Refactor
+
+**Complete rewrite from 41k lines to ~8k lines.** Simpler, faster, cheaper, smarter.
+
+### Architecture — v3 ReAct Agent
+
+- **ReAct agent loop** — Structured reasoning with loop detection, adaptive timeouts, smart failure handling
+- **Attack Planner** — 5-phase hierarchical plan (recon → enumeration → exploitation → post-exploit → reporting) with auto-advance
+- **Target Profile** — Structured memory: ports, endpoints, technologies, credentials, vulnerability hypotheses
+- **14 Auto-Extractors** — Parse tool output (nmap, httpx, nuclei, sqlmap, ffuf, etc.) into structured data automatically
+- **Reflection Engine** — Strategic analysis after each tool call with tool-specific reflectors
+- **14 Escalation Chains** — Pre-built attack chains (SQLi→RCE, LFI→RCE, SSTI→RCE, upload→RCE, etc.)
+- **Knowledge Base** — 39 curated entries: cheatsheets, payloads, attack patterns, loaded on-demand with LRU cache
+- **Task-Type LLM Routing** — 5 task types (PLANNING, TOOL_USE, ANALYSIS, REFLECTION, REPORT) routed to optimal model
+- **Report Generator** — Professional MD/HTML/JSON with dark-theme HTML, remediation engine, CVSS mapping
+- **Plugin System** — Extend with custom tools, chains, extractors via `~/.numasec/plugins/`
+- **19 security tools** — Focused, not bloated
+- **Multi-LLM support** — DeepSeek, Claude, OpenAI, Ollama with automatic fallback
+
+### New Modules
+
+| Module | Purpose |
+|--------|---------|
+| `target_profile.py` | Structured memory (Port, Endpoint, Technology, Credential, VulnHypothesis) |
+| `extractors.py` | 14 tool-output extractors → TargetProfile |
+| `planner.py` | 5-phase hierarchical attack plan with PhaseStatus tracking |
+| `reflection.py` | Strategic reflection with tool-specific analysis |
+| `chains.py` | 14 escalation chains for confirmed vulnerabilities |
+| `knowledge_loader.py` | On-demand knowledge loading with LRU cache (39 entries) |
+| `report.py` | MD/HTML/JSON report generation with remediation guidance |
+| `plugins.py` | Plugin discovery, loading, scaffolding |
+
+### SOTA Prompt Engineering
+
+| Technique | Impact | Source |
+|-----------|--------|--------|
+| Few-Shot Examples | +55% tool accuracy | Brown et al. 2020 |
+| Chain-of-Thought | -30% mistakes | Wei et al. 2022 |
+| Self-Correction | +40% recovery | Shinn et al. 2023 |
+| Error Recovery | +44% retry success | 23 patterns |
+| Context Management | 0 API errors | Group-based trimming |
+
+### Tools (19 total)
+
+**Recon:**
+- `nmap` - Port scanning, service detection
+- `httpx` - HTTP probing, tech fingerprinting  
+- `subfinder` - Subdomain enumeration
+- `ffuf` - Directory/file fuzzing
+
+**Web:**
+- `http` - HTTP requests (SQLi, IDOR, auth bypass)
+- `browser_navigate` - JavaScript pages (SPAs)
+- `browser_fill` - Form testing, XSS payloads
+- `browser_click` - Click elements (CSRF)
+- `browser_screenshot` - Visual evidence
+- `browser_login` - Authenticated testing
+- `browser_get_cookies` - Session analysis
+- `browser_set_cookies` - Session hijacking
+- `browser_clear_session` - Fresh sessions
+
+**Exploit:**
+- `nuclei` - CVE scanning
+- `sqlmap` - SQL injection
+- `run_exploit` - Custom exploit execution (Python/curl/scripts)
+
+**Core:**
+- `read_file` - Read files
+- `write_file` - Write evidence
+- `run_command` - Shell commands
+
+### Features
+
+- **Browser automation** - Playwright for XSS testing with screenshots
+- **Session persistence** - Resume pentests with `/resume`
+- **Cost tracking** - Real-time cost display, budget limits
+- **Cyberpunk CLI** - Beautiful Rich TUI
+- **Context trimming** - Group-based, never breaks tool sequences
+
+### Removed
+
+- ❌ MCP protocol (unnecessary complexity)
+- ❌ LanceDB/vector storage (not needed)
+- ❌ Multi-agent architecture (too expensive)
+- ❌ 28 tools → 17 (focused set)
+- ❌ 41k lines → 6k lines
+
+### Cost
+
+| Provider | Avg Cost/Pentest |
+|----------|------------------|
+| DeepSeek | $0.12 |
+| Claude | $0.50 |
+| OpenAI | $0.80 |
+
+---
+
+## [2.x] - Legacy
+
+Previous versions used MCP architecture with 28+ tools and ~41k lines of code.
+Deprecated in favor of simpler single-agent design.
+
+---
+
+[3.0.0]: https://github.com/FrancescoStabile/numasec/releases/tag/v3.0.0

numasec-3.0.0/LICENSE

@@ -0,0 +1,46 @@
+MIT License
+
+Copyright (c) 2026 Francesco Stabile
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+SECURITY TOOL DISCLAIMER
+
+This software is a penetration testing tool designed for authorized security
+assessments only. By using this software, you acknowledge and agree that:
+
+1. You will only use this software on systems you own or have explicit written
+   authorization to test.
+2. You are solely responsible for ensuring your use complies with all applicable
+   laws, including but not limited to the Computer Fraud and Abuse Act (CFAA),
+   Computer Misuse Act, and similar legislation in your jurisdiction.
+3. The authors and contributors are not responsible for any misuse of this
+   software or any damages, legal consequences, or liabilities arising from
+   its use.
+4. Unauthorized access to computer systems is a criminal offense. The authors
+   do not condone, encourage, or support any illegal activities.
+
+---
+
+Trademark Notice: The "NumaSec" name and logo are trademarks of Francesco Stabile
+and are not covered by the MIT license above. You may not use the NumaSec name
+or logo to endorse or promote products derived from this software without prior
+written permission.

numasec-3.0.0/PKG-INFO

@@ -0,0 +1,306 @@
+Metadata-Version: 2.4
+Name: numasec
+Version: 3.0.0
+Summary: AI security testing for apps. Paste a URL, get a full security report. Like having a pentester on your team for $0.12.
+Project-URL: Homepage, https://github.com/FrancescoStabile/numasec
+Project-URL: Documentation, https://github.com/FrancescoStabile/numasec/blob/main/docs/ARCHITECTURE.md
+Project-URL: Repository, https://github.com/FrancescoStabile/numasec
+Project-URL: Issues, https://github.com/FrancescoStabile/numasec/issues
+Project-URL: Changelog, https://github.com/FrancescoStabile/numasec/blob/main/CHANGELOG.md
+Author-email: Francesco Stabile <francesco.stabile.dev@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai,ai-security,app-security,claude,cybersecurity,deepseek,llm,pentesting,playwright,security,security-check,security-testing,vibe-security,vulnerability-scanner,web-security
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: playwright>=1.40.0
+Requires-Dist: prompt-toolkit>=3.0.43
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: rich>=13.7.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.9.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.3.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5.0; extra == 'docs'
+Requires-Dist: mkdocs>=1.5.0; extra == 'docs'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# Numasec
+
+### Vibe coding changed how we build. Numasec changes how we secure it.
+
+One command. Real vulnerabilities. Full report. **$0.12.**
+
+<img src="docs/assets/demo.gif" alt="Numasec Demo" width="700">
+
+*Numasec autonomously finding 8 vulnerabilities in [OWASP Juice Shop](https://owasp.org/www-project-juice-shop/) — a deliberately insecure web app used as a security training benchmark.*
+
+[![$0.12/scan](https://img.shields.io/badge/cost-$0.12%2Fscan-58a6ff?style=flat-square&labelColor=0d1117)](#quick-start)
+[![Autonomous Agent](https://img.shields.io/badge/agent-fully_autonomous-8b5cf6?style=flat-square&labelColor=0d1117)](#how-it-works)
+[![Bring Your Own LLM](https://img.shields.io/badge/LLM-bring_your_own-f97316?style=flat-square&labelColor=0d1117)](#quick-start)
+[![MIT License](https://img.shields.io/badge/license-MIT-6b7280?style=flat-square&labelColor=0d1117)](LICENSE)
+
+</div>
+
+---
+
+You describe the target. Numasec figures out how to break in — planning the attack, picking techniques, adapting on the fly, and writing the report. No security expertise. No config files. No $10K consultant.
+
+```bash
+pip install numasec && numasec --demo
+```
+
+```
+λ check http://localhost:3000 for security issues
+
+  ◉ SCANNING
+  http://localhost:3000
+
+  ── [1] http → GET http://localhost:3000/
+  │ 200
+  │ server: Express
+  │ x-powered-by: Express
+  └─ 0.1s
+
+  ── [2] http → GET http://localhost:3000/.env
+  │ 200
+  │ DATABASE_URL=postgresql://admin:supersecret@db:5432/myapp
+  │ JWT_SECRET=mysecretkey123
+  └─ 0.2s
+
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  ▲▲ CRITICAL — Environment File Exposed
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  │ The .env file is publicly accessible. It contains the
+  │ database password, JWT secret, and API keys. Anyone can
+  │ read them.
+  │
+  │ Evidence:   GET /.env → 200 OK with credentials
+  │ Fix:        Block .env in Express static config
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  ▲▲ CRITICAL — SQL Injection in Login
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  │ The login endpoint doesn't sanitize input. A single
+  │ payload bypasses authentication and grants admin access
+  │ to any account.
+  │
+  │ Payload:    ' OR '1'='1
+  │ Evidence:   POST /api/auth/login → 200 OK with admin token
+  │ Fix:        Use parameterized queries (Prisma/Sequelize)
+  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  ┌──────────────────────────────────────────────────────┐
+  │              ASSESSMENT COMPLETE                     │
+  │                                                      │
+  │  Target:    http://localhost:3000                    │
+  │  Duration:  4m 23s                                   │
+  │  Cost:      $0.12                                    │
+  │                                                      │
+  │  ▲▲ 2 CRITICAL   ▲ 1 HIGH                            │
+  │  ■  1 MEDIUM     ● 1 LOW                             │
+  │                                                      │
+  │  Risk Level: CRITICAL                                │
+  │                                                      │
+  │  Critical security issues detected — immediate       │
+  │  action required. Fix critical findings first.       │
+  └──────────────────────────────────────────────────────┘
+```
+
+---
+
+## What It Finds
+
+Numasec doesn't just scan — it thinks. It plans an attack strategy, picks the right tools, adapts based on what it discovers, and escalates when it finds something real.
+
+| What it tests | How |
+|--------------|-----|
+| **Exposed secrets** — .env files, API keys, credentials in source | HTTP probing, directory fuzzing |
+| **SQL injection** — auth bypass, data extraction, blind injection | Manual payloads → sqlmap escalation |
+| **XSS** — reflected, stored, DOM-based in forms and search fields | Playwright browser automation with screenshots |
+| **Misconfigurations** — missing headers, debug mode, stack traces | Response analysis, technology fingerprinting |
+| **Known CVEs** — outdated frameworks, vulnerable dependencies | Nuclei templates, version detection |
+| **Auth flaws** — default creds, IDOR, broken access controls | Login testing, session analysis |
+
+Every finding comes with evidence and a fix — not just "vulnerability found", but *what's wrong*, *why it matters*, and *exactly how to fix it*.
+
+---
+
+## Quick Start
+
+```bash
+pip install numasec
+```
+
+**See it work instantly** — no API key, no target, no setup:
+
+```bash
+numasec --demo
+```
+
+**Run it for real** — set one API key and go:
+
+```bash
+export DEEPSEEK_API_KEY="sk-..."    # ~$0.12/scan, 1M free tokens for new accounts
+numasec
+```
+
+That's it. Paste a URL, describe what to test, and Numasec handles the rest.
+
+<details>
+<summary><b>More options</b> — Claude, OpenAI, Ollama, browser mode, security tools</summary>
+
+```bash
+# AI providers (set any combination — automatic fallback)
+export DEEPSEEK_API_KEY="sk-..."          # Cheapest (~$0.12/scan)
+export ANTHROPIC_API_KEY="sk-ant-..."     # Best reasoning
+export OPENAI_API_KEY="sk-..."            # General purpose
+# Ollama detected automatically if running locally (free)
+
+# Browser automation — XSS testing, form filling, visual evidence
+playwright install chromium
+
+# Security scanners — advanced vulnerability detection
+sudo apt install nmap sqlmap
+# nuclei: https://github.com/projectdiscovery/nuclei
+
+# Usage
+numasec                              # Interactive mode
+numasec check http://localhost:3000  # One-shot check
+numasec --show-browser               # Watch the browser in real-time
+numasec --budget 5.0                 # Set cost limit
+numasec --resume <session-id>        # Resume a previous session
+```
+
+</details>
+
+---
+
+## The Report
+
+Every assessment produces a professional HTML report — dark theme, severity donut chart, evidence blocks, remediation steps. Share it with your team, attach it to a ticket, or hand it to an AI to fix the code.
+
+<div align="center">
+<img src="docs/assets/report.gif" alt="Numasec Security Report" width="700">
+</div>
+
+---
+
+## How It Works
+
+```
+You describe the target
+  → AI plans the attack (discovery → mapping → testing → exploitation → results)
+  → Picks the right tool for each step (19 tools: nmap, sqlmap, Playwright, nuclei...)
+  → Analyzes results, generates hypotheses, adapts the plan
+  → Confirmed findings documented with evidence and fixes
+  → Professional report generated automatically
+```
+
+It's not a scanner. It's not a ChatGPT wrapper. It's an autonomous agent with structured memory, attack planning, 14 result extractors, 14 escalation chains, and a 46-file knowledge base — all orchestrated by a ReAct loop that thinks before it acts.
+
+<details>
+<summary><b>Architecture deep dive</b></summary>
+
+```
+cli.py          → Interactive REPL with real-time streaming
+agent.py        → ReAct loop (50 iterations, loop detection, circuit breaker)
+router.py       → Multi-provider LLM routing (DeepSeek → Claude → OpenAI → Ollama)
+planner.py      → 5-phase attack plan (discovery → mapping → testing → analysis → results)
+state.py        → Structured memory (TargetProfile with ports, endpoints, technologies)
+extractors.py   → 14 extractors parse tool output into structured data automatically
+reflection.py   → 7 tool-specific analyzers guide what to check next
+chains.py       → 14 escalation chains (SQLi→RCE, LFI→RCE, SSTI→RCE, XSS→session theft...)
+knowledge/      → 46 attack patterns, cheatsheets, and payload references
+report.py       → Reports in Markdown, HTML, and JSON
+plugins.py      → Extend with custom tools, chains, and extractors
+renderer.py     → Terminal UI with character-by-character streaming
+```
+
+12,000+ lines of Python. 170+ tests. 5 core dependencies.
+
+See [ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full technical breakdown.
+
+</details>
+
+<details>
+<summary><b>Python API</b></summary>
+
+```python
+from numasec.agent import Agent
+from numasec.router import LLMRouter, Provider
+from numasec.tools import create_tool_registry
+from numasec.state import State
+
+router = LLMRouter(primary=Provider.DEEPSEEK)
+tools = create_tool_registry()
+state = State()
+agent = Agent(router=router, tools=tools, state=state)
+
+async for event in agent.run("find SQLi in localhost:3000"):
+    if event.type == "text":
+        print(event.content, end="")
+    elif event.type == "finding":
+        print(f"Found: {event.finding.title}")
+```
+
+</details>
+
+---
+
+## Legal
+
+**Only test apps you own or have explicit permission to test.** Numasec is a security tool — use it responsibly.
+
+✅ Your own apps, staging/production environments, bug bounty targets, practice labs (DVWA, Juice Shop, HackTheBox)
+
+❌ Other people's apps without written authorization
+
+---
+
+## Roadmap
+
+- Parallel tool execution (asyncio.gather for independent scans)
+- LLM-powered planning (adaptive strategies based on target type)
+- Benchmark suite (automated scoring against DVWA, Juice Shop, WebGoat)
+- CI/CD integration (security gates in deployment pipelines)
+- MCP integration (Model Context Protocol for tool interoperability)
+
+See [VISION.md](docs/notes/VISION.md) for the full technical blueprint.
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Issues, PRs, and feedback welcome.
+
+---
+
+**Built by [Francesco Stabile](https://www.linkedin.com/in/francesco-stabile-dev)** — making security accessible to every developer.
+
+[![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)