DarkMatter-Security/OmniPentestX

# â—ˆ OmniPentestX â—ˆ **AI-Powered Universal Penetration Testing Platform** [](https://python.org) [](https://www.gnu.org/licenses/gpl-3.0) [](https://github.com/DarkMatter-Security/OmniPentestX) [](https://github.com/astral-sh/ruff) [](https://github.com/DarkMatter-Security/OmniPentestX) [](https://github.com/DarkMatter-Security/OmniPentestX/releases) **Built by [AntiSyntax.protocol CREW](https://github.com/DarkMatter-Security/OmniPentestX)** — for the underground, by the underground. **Part of the [Dark Matter Security](https://github.com/DarkMatter-Security/DarkMatter_Security) universe.** — Invisible Influence. Indirect Intelligence. **FREE. OPEN. FOR EVERYONE.** Whether you're a seasoned red teamer or an up-and-coming pentester with zero tool-bank — this is YOUR platform. No licenses, no paywalls, no gatekeeping. Download it, run it, learn with it, break things with it. Just don't be stupid — get authorization first. ## Table of Contents - [âš¡ Overview](#-overview) - [🚀 Quick Start](#-quick-start) - [🏗️ Architecture Overview](#️-architecture-overview) - [📦 Module Reference](#-module-reference) - [Package Root](#1-package-root-__init__py--__main__py--versionpy--configpy) - [Core Engine](#2-core-engine-core) - [Interfaces](#3-interfaces-interfaces) - [Tools](#4-tools-tools) - [Reporting](#5-reporting-reporting) - [Utilities](#6-utilities-utils) - [💻 Interface Guide](#-interface-guide) - [CLI — Terminal Interface](#1-cli--terminal-interface) - [Web Dashboard — FastAPI](#2-web-dashboard--fastapi) - [Desktop GUI — PySide6](#3-desktop-gui--pyside6) - [Python API — Programmatic](#4-python-api--programmatic) - [🧠 AI Provider Setup](#-ai-provider-setup) - [🔧 Configuration](#-configuration) - [✅ 7-Gate Validation System](#-7-gate-validation-system) - [📊 Reporting & Portfolio](#-reporting--portfolio) - [🔒 Ethical & Legal](#-ethical--legal) - [📦 Publishing & Distribution](#-publishing--distribution) - [🤝 Contributing](#-contributing) - [📄 License](#-license) ## âš¡ Overview **OmniPentestX** is an AI-powered penetration testing platform that unifies **42 built-in security tools**, **4 AI providers** (OpenAI, Anthropic, Ollama, LM Studio), and **4 interfaces** (CLI, Web, GUI, Python API) into a single cohesive framework — built by **AntiSyntax.protocol CREW** for the pentesting community. ### What makes it different? | Feature | Benefit | |---------|---------| | **AI-driven orchestration** | The AI plans, executes, and analyzes scans autonomously | | **All three interfaces** | Use the terminal, web browser, or desktop app — same engine underneath | | **42 pre-configured tools** | Nmap, Nuclei, SQLMap, Metasploit, Hydra, John, GoBuster, and more — all set up and ready | | **Simulated mode** | Works as a complete training/demo platform even without security tools installed | | **Persistent memory** | ChromaDB vector search + knowledge graph — the platform learns from every scan | | **7-gate validation** | Professional quality gates: target verification → authorization check → evidence integrity → report quality | | **Zero-config SQLite** | Everything persists automatically to `~/.omnipentestx/` — no database server needed | ## 🚀 Quick Start ### Installation # 1) Clone git clone https://github.com/DarkMatter-Security/OmniPentestX.git cd OmniPentestX- # 2) Virtual environment (recommended) python -m venv venv # Windows: venv\Scripts\activate # macOS/Linux: source venv/bin/activate # 3) Install pip install -e . # Optional extras: pip install -e ".[gui]" # Desktop GUI (PySide6) pip install -e ".[pdf]" # PDF report generation pip install -e ".[full]" # Everything ### Verify It Works # Check version python -m omnipentestx -v # Output: OmniPentestX v1.0.0.dev1 # Run the test suite python -m pytest tests/ -v # Output: 32 passed ### First Scan # Interactive CLI python -m omnipentestx cli # One-shot scan python -m omnipentestx cli scan example.com # List all 42 tools python -m omnipentestx cli tools # Web dashboard python -m omnipentestx web # then open http://127.0.0.1:8666/dashboard # Desktop GUI (requires PySide6) python -m omnipentestx gui ## 🏗️ Architecture Overview ┌──────────────────────────────────────────────────────────────────────────┐ │ USER INTERFACES │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌───────────────────┐ │ │ │ CLI │ │ GUI │ │ Web │ │ Python API │ │ │ │ (Rich) │ │ (PySide6)│ │ (FastAPI)│ │ (OmniPentestXAPI) │ │ │ └────┬─────┘ └────┬─────┘ └────┬─────┘ └─────────┬─────────┘ │ └────────┼──────────────┼──────────────┼────────────────────┼─────────────┘ │ │ │ │ ┌────────┴──────────────┴──────────────┴─────────────────────┴─────────────┐ │ ORCHESTRATION ENGINE │ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ │ OmniEngine │ │ │ │ ┌──────────┐ ┌───────────┐ ┌───────────┐ ┌────────────────┐ │ │ │ │ │ AIAgent │ │TaskPlanner│ │CommandExec │ │ MemorySystem │ │ │ │ │ │ (LLM) │ │ (Planning)│ │ (Executor) │ │ (Vector+Graph) │ │ │ │ │ └──────────┘ └───────────┘ └───────────┘ └────────────────┘ │ │ │ │ ┌──────────┐ ┌───────────┐ ┌───────────┐ ┌────────────────┐ │ │ │ │ │Database │ │ Validator │ │ Reporter │ │ MCP Client │ │ │ │ │ │ (SQLite) │ │ (7 Gates) │ │ (Engine) │ │ (Protocol) │ │ │ │ │ └──────────┘ └───────────┘ └───────────┘ └────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────────┘ │ └───────────────────────────────────────────────────────────────────────────┘ │ ┌─────────────────────────────────┴───────────────────────────────────────────┐ │ TOOL INTEGRATION LAYER │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────┐ ┌──────────┐ │ │ │ Recon │ │ Web │ │ Exploit │ │ Cloud │ │ OSINT │ │ │ │─────────────│ │─────────────│ │─────────────│ │─────────│ │──────────│ │ │ │ nmap │ │ nuclei │ │ sqlmap │ │ awscli │ │ shodan │ │ │ │ whois │ │ nikto │ │ hydra │ │ azurecli│ │ censys │ │ │ │ dig │ │ gobuster │ │ metasploit │ │ │ │ │ │ │ │ dnsrecon │ │ ffuf │ │ burpsuite │ │ │ │ │ │ │ │ theharvester│ │ wpscan │ │ john │ │ │ │ │ │ │ │ sherlock │ │ dirb │ │ hashcat │ │ │ │ │ │ │ │ whatweb │ │ │ │ netcat │ │ │ │ │ │ │ │ curl │ │ │ │ │ │ │ │ │ │ │ │ openssl │ │ │ │ │ │ │ │ │ │ │ │ enum4linux │ │ │ │ │ │ │ │ │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ └─────────┘ └──────────┘ │ └────────────────────────────────────────────────────────────────────────────┘ ### Data Flow: A Scan's Journey User Input OmniEngine Output ────────── ────────── ────── │ │ │ scan("example.com") │ ├─────────────────────────────►│ │ │ │ ┌────────┴────────┐ │ │ 1. Validate │ ← 7 Gates │ │ 2. Plan │ ← TaskPlanner │ │ 3. Execute │ ← CommandExecutor │ │ 4. Analyze │ ← AIAgent │ │ 5. Learn │ ← MemorySystem │ │ 6. Report │ ← ReportEngine │ └────────┬────────┘ │ │ │ ◄── ScanSession (findings, │ │ evidence, logs, │ │ report path) │ │ │ ## 📦 Module Reference ### 1. Package Root (`__init__.py` / `__main__.py` / `version.py` / `config.py`) #### `__init__.py` The package front door. Always check what you're running: import omnipentestx print(omnipentestx.__version__) # "1.0.0.dev1" print(omnipentestx.VERSION_CODENAME) # "Quantum Genesis" #### `__main__.py` — Mode Dispatcher This is the entry point for `python -m omnipentestx`. It reads the first argument and routes to the right interface: | Command | What it does | |---------|-------------| | `python -m omnipentestx` | Default: CLI interactive mode | | `python -m omnipentestx cli` | Same as above | | `python -m omnipentestx cli scan example.com` | One-shot scan | | `python -m omnipentestx web` | Start web dashboard (port 8666) | | `python -m omnipentestx web --port 8080` | Web on custom port | | `python -m omnipentestx gui` | Desktop GUI | | `python -m omnipentestx api` | Headless REST API server | | `python -m omnipentestx -v` | Print version | | `python -m omnipentestx help` | Show usage | #### `version.py` Semantic version with codename progression: (1, 0, 0, "dev", 1) → "Quantum Genesis" ← CURRENT (1, 0, 0, "alpha", 1) → "First Light" (1, 0, 0, "beta", 1) → "Rising Storm" (1, 0, 0, "rc", 1) → "Thunderbird" (1, 0, 0, "final", 0) → "OmniForce" #### `config.py` — Central Settings Six configuration groups, all accessible via `get_config()`: OmniPentestXConfig │ ├── .ai AI provider settings │ ├── .provider "openai", "anthropic", "ollama", "lmstudio", "custom" │ ├── .model Model name (e.g., "gpt-4o", "claude-3-opus", "llama3") │ ├── .api_key Falls back to OPENAI_API_KEY / ANTHROPIC_API_KEY │ ├── .api_base Custom API endpoint URL │ ├── .temperature 0.2 (default) │ ├── .max_tokens 4096 │ ├── .timeout 120s │ ├── .max_retries 3 │ └── .context_window 128,000 tokens │ ├── .security Safety & isolation │ ├── .sandbox_enabled Docker sandbox for dangerous commands │ ├── .dangerous_commands_require_approval Prompt before exploits │ ├── .max_concurrent_tools 5 │ ├── .tool_timeout 600s (10 minutes) │ └── .audit_log Log all operations │ ├── .database Persistence layer │ ├── .engine "sqlite" (default) or "postgresql" │ └── .path SQLite database file path │ ├── .memory AI learning subsystem │ ├── .enabled On/off │ ├── .backend "chromadb" (vector search database) │ ├── .embedding_model "text-embedding-3-small" │ ├── .similarity_top_k 10 (results per query) │ └── .auto_learn Learn from every scan automatically │ ├── .interface Per-interface settings │ ├── .web_host 127.0.0.1 │ ├── .web_port 8666 │ ├── .gui_width 1400 │ └── .gui_height 900 │ └── .reporting Report generation ├── .default_format "pdf", "html", "json", "markdown" ├── .include_evidence Include raw evidence in reports ├── .include_remediation Include fix recommendations ├── .company_name Your company/team name └── .compliance_templates OWASP Top 10, PCI-DSS, ISO-27001, NIST 800-53 **Configuration priority** (last wins): 1. Hardcoded dataclass defaults 2. `~/.omnipentestx/config.json` — persistent user config 3. Environment variables (highest priority) **Key environment variables:** | Variable | What it does | |----------|-------------| | `OPENAI_API_KEY` | API key for OpenAI | | `ANTHROPIC_API_KEY` | API key for Anthropic | | `OMNIPENTESTX_AI_PROVIDER` | `openai`, `anthropic`, `ollama`, `lmstudio` | | `OMNIPENTESTX_AI_MODEL` | Override the model name | | `OMNIPENTESTX_DEBUG` | `true` to enable debug logging | | `OMNIPENTESTX_LOG_LEVEL` | `DEBUG`, `INFO`, `WARNING`, `ERROR` | | `OMNIPENTESTX_WEB_HOST` | Web server bind address | | `OMNIPENTESTX_WEB_PORT` | Web server port | | `OMNIPENTESTX_DB_ENGINE` | `sqlite` or `postgresql` | | `OMNIPENTESTX_SANDBOX` | `true`/`false` for Docker sandbox | ### 2. Core Engine (`core/`) core/ ├── __init__.py Re-exports all core classes ├── engine.py OmniEngine — the central orchestrator ├── agent.py AIAgent — LLM integration layer ├── planner.py TaskPlanner — scan plan generation ├── executor.py CommandExecutor — runs security tools ├── database.py DatabaseManager — persistence └── memory.py MemorySystem — vector search + knowledge graph #### `engine.py` — OmniEngine (The Brain) The master controller. Manages the full scan lifecycle: **Scan lifecycle (10 states):** PENDING → PLANNING → RECON → ENUMERATION → EXPLOITATION → PRIVESC → POST_EXPLOIT → REPORTING → COMPLETED → FAILED → CANCELLED **Key methods:** engine = OmniEngine(config=config) session = await engine.create_session(target="example.com", name="My Scan") await engine.run_scan(session.id) # Execute full pipeline session = await engine.get_session(session.id) sessions = await engine.list_sessions(status="completed") gate_result = await engine.validate_gate(session.id, gate) **7 Validation Gates:** | Gate | Purpose | |------|---------| | `TARGET_VERIFICATION` | Target is a valid IP/domain/URL/CIDR | | `SCOPE_CONFIRMATION` | Target is within defined scope | | `AUTHORIZATION_CHECK` | You have legal authorization | | `RISK_ASSESSMENT` | Operational risk is acceptable | | `METHODOLOGY_APPROVAL` | Scan plan follows security methodology | | `EVIDENCE_INTEGRITY` | All evidence is intact and verifiable | | `REPORT_QUALITY` | Report meets professional standards | #### `agent.py` — AIAgent Unified interface over 5 LLM providers: | Provider | How to use | |----------|-----------| | **OpenAI** | Set `OPENAI_API_KEY` env var (default) | | **Anthropic** | Set `ANTHROPIC_API_KEY` env var + `ANTHROPIC` provider | | **Ollama** | `OMNIPENTESTX_AI_PROVIDER=ollama` (local, free) | | **LM Studio** | `OMNIPENTESTX_AI_PROVIDER=lmstudio` (local OpenAI-compatible) | | **Custom** | `OMNIPENTESTX_AI_PROVIDER=custom` + set `api_base` | Agent role system — different AI personas: - `STRATEGIST` — High-level planning and methodology - `OPERATOR` — Running tools and parsing command output - `ANALYST` — Interpreting findings and correlating data - `REVIEWER` — Quality checking results and evidence The agent operates in an autonomous loop (up to 50 iterations) — decides what to scan next, runs the tool, interprets results, and adapts the plan. #### `planner.py` — TaskPlanner Generates a structured `ScanPlan` — a sequence of phases, each with the right tools: Phase Tools Used ────────────────────────────────────────────────── RECON nmap, whois, dig, dnsrecon, theharvester, sherlock, whatweb ENUMERATION whatweb, gobuster, nikto, ffuf, dirb, wpscan EXPLOITATION sqlmap, hydra, metasploit, burpsuite, john, hashcat PRIVESC john, hashcat, netcat POST_EXPLOIT enum4linux, curl, openssl #### `executor.py` — CommandExecutor The tool runner. For every command it: 1. **Checks availability** — `which()` to find the tool on your PATH 2. **Simulates if missing** — generates realistic mock output (perfect for training/demos) 3. **Builds the command** — uses the ToolRegistry's command template 4. **Checks safety** — dangerous tools (hydra, metasploit, sqlmap) trigger approval prompts 5. **Runs with timeout** — configurable per-tool timeout (default 10 min) 6. **Parses output** — tool-specific parsers extract structured findings: | Parser | Extracts | |--------|----------| | `NmapParser` | Open ports, services, versions, OS detection | | `NucleiParser` | CVEs, vulnerability template matches, severity | | `SQLMapParser` | Injection points, DB types, compromised tables | | `GenericParser` | IPs, ports, keywords from any tool output | Returns `ExecutorResult` — structured dataclass with findings, evidence, timing. #### `database.py` — DatabaseManager Auto-creates and manages `~/.omnipentestx/omnipentestx.db`. Tables: - **sessions** — Scan metadata (target, status, timing, tags) - **findings** — Each finding with severity, description, evidence refs - **evidence** — Raw output, screenshots, logs - **tags** — Session classification tags db = DatabaseManager() await db.initialize() await db.create_session(session) session = await db.get_session(session_id) all_sessions = await db.list_sessions() stats = await db.get_stats() # Aggregate counts for dashboard #### `memory.py` — MemorySystem Three-tier memory that makes the platform learn over time: 1. **MemoryEntry** — Plain-text lessons from past scans ("port 8080 on 10.0.0.5 had Apache Tomcat") 2. **Vector search** — ChromaDB embeddings for semantic retrieval ("find scans with SQL injection") 3. **KnowledgeEdge** — Graph relationships between targets, tools, findings, and techniques memory = MemorySystem() await memory.remember("nmap", target="10.0.0.1", result=result) # Auto-learns results = await memory.search("Apache Struts vulnerability") # Semantic search related = await memory.get_related("10.0.0.1") # Knowledge graph ### 3. Interfaces (`interfaces/`) interfaces/ ├── api.py OmniPentestXAPI — programmable Python API ├── cli.py Rich terminal interface ├── gui.py Desktop GUI launcher ├── gui_window.py PySide6 desktop app main window └── web/ └── app.py FastAPI server + embedded dashboard #### `api.py` — OmniPentestXAPI The unified public API that all three interfaces use under the hood. Perfect for scripting and CI/CD: from omnipentestx.interfaces.api import OmniPentestXAPI import asyncio async def main(): api = OmniPentestXAPI() # Tool management all_tools = api.list_tools() recon_tools = api.list_tools(category="recon") found = api.search_tools("sql") # Configuration config = api.get_config() # Scanning session = await api.scan("example.com", name="CI Pipeline Scan") session = await api.get_session(session.id) # Reports html_path = await api.generate_report(session.id, fmt="html") json_path = await api.generate_report(session.id, fmt="json") # Validation gates = await api.validate_session(session.id) # All 7 gates gate = await api.validate_session(session.id, gate="target_verification") # One gate # Utilities await api.run_tool("nmap", "example.com") await api.cleanup() asyncio.run(main()) #### `cli.py` — Terminal Interface Two operating modes: **Interactive shell mode:** $ python -m omnipentestx cli +====================================================+ | ██████╗ ███╗ ███╗███╗ ██╗██╗██████╗ ███████╗... | ██╔═══██╗████╗ ████║████╗ ██║██║██╔══██╗██╔════╝... | ██║ ██║██╔████╔██║██╔██╗ ██║██║██████╔╝█████╗ ... | ██║ ██║██║╚██╔╝██║██║╚██╗██║██║██╔═══╝ ██╔══╝ ... | ╚██████╔╝██║ ╚═╝ ██║██║ ╚████║██║██║ ███████╗... | ╚═════╝ ╚═╝ ╚═╝╚═╝ ╚═══╝╚═╝╚═╝ ╚══════╝... | One Framework. Zero Limits. Infinite Power. +====================================================+ Version 1.0.0.dev1 [Quantum Genesis] ============================================================ Interactive Mode — Type 'help' for commands, 'quit' to exit ============================================================ omnipentestx> **Available interactive commands:** | Command | Description | |---------|-------------| | `scan ` | Run a full pentest scan | | `scan --name "..." --tags t1,t2` | Scan with metadata | | `list` | List all sessions | | `list --status completed` | Filter by status | | `info ` | Show session details | | `report ` | Generate default report | | `report --format html` | Specific format | | `tools` | List all 42 tools | | `tools --category recon` | Filter by category | | `tools --search sql` | Search tools by keyword | | `validate ` | Run all validation gates | | `validate --gate target_verification` | Single gate | | `dashboard` | Live updating real-time dashboard | | `config` | Show current configuration | | `help` | Show this help | | `quit` / `exit` | Exit | **Direct command mode** (non-interactive, for scripts): python -m omnipentestx cli scan example.com --name "Quick Scan" python -m omnipentestx cli tools --category exploit python -m omnipentestx cli report abc123 --format html python -m omnipentestx cli config #### 2. Web Dashboard — FastAPI python -m omnipentestx web Starts a FastAPI server on `http://127.0.0.1:8666` with: | Endpoint | Method | Purpose | |----------|--------|---------| | `/` | GET | API root | | `/dashboard` | GET | **Full HTML dashboard** (open this!) | | `/api/health` | GET | Health check | | `/api/scan` | POST | Start a scan `{"target": "example.com"}` | | `/api/sessions` | GET | List all sessions | | `/api/sessions/{id}` | GET | Session details | | `/api/sessions/{id}` | DELETE | Delete a session | | `/api/tools` | GET | List all tools | | `/api/tools/run` | POST | Run a single tool | | `/api/report/{id}` | GET | Download report (query: `?format=html`) | | `/api/portfolio` | GET | Multi-session portfolio report | | `/api/validate/{id}` | GET | Run validation gates | | `/api/stats` | GET | Aggregate statistics | | `/ws` | WebSocket | Real-time scan updates | | `/docs` | GET | Swagger UI interactive docs | | `/redoc` | GET | ReDoc alternative docs | **Flags:** python -m omnipentestx web --host 0.0.0.0 --port 8080 #### 3. Desktop GUI — PySide6 pip install omnipentestx[gui] python -m omnipentestx gui Features: - Dark cyber-aesthetic theme - Session management panel (create, view, delete) - Tool browser with category filtering - Live scan status and console output - Menu bar with full controls - Status bar with real-time stats #### 4. Python API — Programmatic The API is the **foundation** — CLI, Web, and GUI all call the same `OmniPentestXAPI` class: from omnipentestx.interfaces.api import OmniPentestXAPI api = OmniPentestXAPI() # ── Tool discovery ── all_tools = api.list_tools() # 27 tools web_tools = api.list_tools(category="web") # Filtered matches = api.search_tools("dns") # Search by name/description # ── Scanning ── session = await api.scan("10.0.0.1", name="Internal", tags=["prod"]) print(session.status, len(session.findings)) # ── Reports ── path = await api.generate_report(session.id, fmt="html") path = await api.generate_report(session.id, fmt="json") # ── Validation ── all_passed = await api.validate_session(session.id) # ── Tool execution ── result = await api.run_tool("nmap", "scanme.nmap.org", args=["-p", "80,443"]) print(result.stdout[:500]) ### 4. Tools (`tools/`) tools/ ├── registry.py ToolRegistry — all 42 tool definitions ├── mcp_client.py MCP protocol for AI-driven tool discovery ├── recon/ Reconnaissance tool category stubs ├── web/ Web app security tool category stubs ├── exploit/ Exploitation tool category stubs ├── cloud/ Cloud security tool category stubs └── osint/ OSINT tool category stubs #### `registry.py` — ToolRegistry All **27 tools** loaded on startup: | # | Tool | Category | Description | |---|------|----------|-------------| | 1 | nmap | recon | Network port scanner & service discovery | | 2 | whois | recon | Domain registration information lookup | | 3 | dig | recon | DNS lookup utility | | 4 | dnsrecon | recon | Advanced DNS enumeration | | 5 | theharvester | recon | Email & subdomain harvesting | | 6 | sherlock | recon | Username search across social networks | | 7 | whatweb | recon | Web technology fingerprinting | | 8 | curl | recon | HTTP/S data transfer tool | | 9 | openssl | recon | SSL/TLS certificate analysis | | 10 | enum4linux | recon | Windows/Samba enumeration | | 11 | nuclei | web | Template-based vulnerability scanner | | 12 | nikto | web | Web server vulnerability scanner | | 13 | gobuster | web | Directory/file brute-forcing | | 14 | ffuf | web | Fast web fuzzer | | 15 | wpscan | web | WordPress security scanner | | 16 | dirb | web | Web content scanner | | 17 | sqlmap | exploit | SQL injection automation tool | | 18 | hydra | exploit | Password brute-forcing | | 19 | metasploit | exploit | Exploit framework | | 20 | burpsuite | exploit | Web application security proxy | | 21 | john | exploit | John the Ripper password cracker | | 22 | hashcat | exploit | GPU-accelerated password cracking | | 23 | netcat | exploit | Network connection & data transfer | | 24 | shodan | osint | Shodan.io search engine integration | | 25 | censys | osint | Censys.io certificate & network search | | 26 | awscli | cloud | AWS CLI for cloud security assessment | | 27 | azurecli | cloud | Azure CLI for cloud security assessment | **Extending the registry at runtime:** from omnipentestx.tools.registry import ToolRegistry registry = ToolRegistry() registry.register_tool( "my-custom-tool", category="recon", description="My custom scanner", command_template="{tool} {target} {args}", default_args=["-v"], safe=True, ) #### `mcp_client.py` — MCP Protocol Client Implements the Model Context Protocol for AI agent tool discovery. Lets the AI agent dynamically discover what tools are available and how to use them — no hardcoded tool lists needed. ### 5. Reporting (`reporting/`) reporting/ ├── report_engine.py Multi-format report generator ├── portfolio.py Multi-session portfolio builder └── templates/ HTML/Markdown report templates #### `report_engine.py` — ReportEngine Generates security reports in 4 formats: | Format | Always works? | Use case | |--------|:---:|----------| | **HTML** | ✅ Yes | Full formatted report, view in browser | | **JSON** | ✅ Yes | Machine-readable, API integration | | **Markdown** | ✅ Yes | Readable plaintext, version control | | **PDF** | ❌ Requires weasyprint/pdfkit | Professional delivery | from omnipentestx.reporting.report_engine import ReportEngine reporter = ReportEngine() html_path = await reporter.generate(session, fmt="html") json_path = await reporter.generate(session, fmt="json") md_path = await reporter.generate(session, fmt="markdown") #### `portfolio.py` — PortfolioBuilder Aggregates findings across **multiple sessions** into one unified report: from omnipentestx.reporting.portfolio import PortfolioBuilder portfolio = PortfolioBuilder() path = await portfolio.build(["session_1", "session_2", "session_3"], fmt="html") ### 6. Utilities (`utils/`) utils/ ├── logger.py Color-formatted logging (console + file) ├── helpers.py Command execution, timers, progress bars, string utils └── validators.py IP, domain, URL, port, CVSS, CIDR validation #### `logger.py` from omnipentestx.utils.logger import get_logger log = get_logger("my_module") log.success("Operation completed") # Green log.error("Something broke") # Red log.warning("Check this") # Yellow log.info("Processing...") # Cyan log.debug("x = 42") # Dim/gray Logs are written to both console (colored) and `~/.omnipentestx/logs/`. #### `helpers.py` from omnipentestx.utils.helpers import ( run_command, # Execute shell command with timeout ProgressBar, # Terminal progress visualization Timer, # Context manager for timing Colorize, # ANSI color helpers slugify, # "Hello World" → "hello_world" human_size, # 1048576 → "1.0 MB" truncate_text, # Truncate with ellipsis mask_secret, # "sk-abc123" → "sk-****23" timestamp, # Current ISO timestamp ensure_dir, # Create dir if it doesn't exist ) #### `validators.py` from omnipentestx.utils.validators import ( validate_ip, # "192.168.1.1" → (True, "") validate_domain, # "example.com" → (True, "") validate_url, # "https://example.com" → (True, "") validate_port, # "80" → (True, ""), "99999" → (False, ...) validate_cvss, # "7.5" → (True, "HIGH") validate_cidr, # "192.168.0.0/16" → (True, "") validate_target, # Auto-detects type: IP, domain, URL, CIDR ) ## 💻 Interface Guide ### 1. CLI — Terminal Interface **Start interactive mode:** python -m omnipentestx cli **Lifecycle of a CLI session:** 1. Launch → Banner displays, engine initializes 2. `tools` → See all 27 available tools 3. `scan example.com --name "Demo"` → Run a scan 4. `info ` → See results 5. `report --format html` → Generate report 6. `validate ` → Check quality gates 7. `quit` **Direct commands (one-shot):** python -m omnipentestx cli scan example.com python -m omnipentestx cli tools --category exploit python -m omnipentestx cli config python -m omnipentestx cli report abc123 --format json ### 2. Web Dashboard — FastAPI python -m omnipentestx web Then navigate to `http://127.0.0.1:8666/dashboard` for the HTML UI. **Typical workflow:** 1. Open `/dashboard` — see live statistics, create scans 2. POST to `/api/scan` with `{"target": "example.com"}` — start a scan 3. GET `/api/sessions` — watch progress 4. GET `/api/sessions/{id}` — inspect findings 5. GET `/api/report/{id}?format=html` — download report 6. GET `/api/validate/{id}` — check quality gates ### 3. Desktop GUI — PySide6 Requires: `pip install omnipentestx[gui]` python -m omnipentestx gui Features a dark cyber-themed desktop application with: - Left panel: session list with real-time status icons - Center: detail views for sessions, findings, and evidence - Right panel: tool browser with category/search filtering - Bottom: console output log - Menu bar: File, Edit, View, Tools, Help ### 4. Python API — Programmatic The API is designed for **CI/CD integration**: # In your CI pipeline script from omnipentestx.interfaces.api import OmniPentestXAPI import asyncio async def security_scan(target): api = OmniPentestXAPI() session = await api.scan(target, name="CI Pipeline Scan") summary = { "target": session.target, "findings": len(session.findings), "critical": sum(1 for f in session.findings if f.get("severity") == "critical"), "high": sum(1 for f in session.findings if f.get("severity") == "high"), } await api.generate_report(session.id, fmt="json") return summary result = asyncio.run(security_scan("staging.example.com")) print(f"Found {result['critical']} critical vulnerabilities") ## 🧠 AI Provider Setup ### Option 1: OpenAI (Default) set OPENAI_API_KEY=sk-your-key-here python -m omnipentestx cli Uses `gpt-4o` by default. Change with `OMNIPENTESTX_AI_MODEL=gpt-4-turbo`. ### Option 2: Anthropic set ANTHROPIC_API_KEY=sk-ant-your-key-here set OMNIPENTESTX_AI_PROVIDER=anthropic set OMNIPENTESTX_AI_MODEL=claude-3-opus-20240229 python -m omnipentestx cli ### Option 3: Ollama (Local — Free) # Install Ollama from https://ollama.com ollama pull qwen2.5-coder:7b # Or llama3, mistral, etc. set OMNIPENTESTX_AI_PROVIDER=ollama set OMNIPENTESTX_AI_MODEL=qwen2.5-coder:7b python -m omnipentestx cli Ollama runs a local OpenAI-compatible server at `http://localhost:11434/v1` — the agent talks to it just like OpenAI, but everything stays on your machine. ### Option 4: LM Studio # Open LM Studio, load a model, start the local server set OMNIPENTESTX_AI_PROVIDER=lmstudio set OMNIPENTESTX_AI_MODEL=local-model python -m omnipentestx cli ### Option 5: Custom Endpoint set OMNIPENTESTX_AI_PROVIDER=custom # Set api_base in config to your endpoint python -m omnipentestx cli ### Config File Method Create `~/.omnipentestx/config.json`: { "ai": { "provider": "ollama", "model": "qwen2.5-coder:7b", "api_base": "http://localhost:11434/v1", "temperature": 0.2, "max_tokens": 4096 }, "interface": { "web_host": "0.0.0.0", "web_port": 8666 }, "debug": true } ## 🔧 Configuration ### All Environment Variables | Variable | Default | Description | |----------|---------|-------------| | `OPENAI_API_KEY` | — | OpenAI API key | | `ANTHROPIC_API_KEY` | — | Anthropic API key | | `OMNIPENTESTX_AI_PROVIDER` | `openai` | AI backend | | `OMNIPENTESTX_AI_MODEL` | `gpt-4o` | Model override | | `OMNIPENTESTX_DEBUG` | `false` | Enable debug mode | | `OMNIPENTESTX_LOG_LEVEL` | `INFO` | Log verbosity | | `OMNIPENTESTX_WEB_HOST` | `127.0.0.1` | Web bind address | | `OMNIPENTESTX_WEB_PORT` | `8666` | Web port | | `OMNIPENTESTX_DB_ENGINE` | `sqlite` | Database engine | | `OMNIPENTESTX_SANDBOX` | `true` | Docker sandbox toggle | ### Persistent Config File Location: `~/.omnipentestx/config.json` { "ai": { "provider": "ollama", "model": "llama3" }, "security": { "tool_timeout": 300, "dangerous_commands_require_approval": true }, "database": { "engine": "sqlite" }, "interface": { "web_port": 8666 }, "reporting": { "default_format": "html", "company_name": "My Team" } } ## 📊 Reporting & Portfolio ### Generate a Report CLI: python -m omnipentestx cli report abc123 --format html API: path = await api.generate_report(session.id, fmt="html") ### Generate a Portfolio (Multi-Session) from omnipentestx.reporting.portfolio import PortfolioBuilder import asyncio async def main(): portfolio = PortfolioBuilder() path = await portfolio.build( ["session_1_id", "session_2_id", "session_3_id"], fmt="html", title="Q1 2026 Security Assessment Portfolio", ) print(f"Portfolio report: {path}") asyncio.run(main()) ### Report Formats | Format | Command flag | Dependencies | |--------|:-----------:|:------------| | HTML | `--format html` | None (built-in) | | JSON | `--format json` | None (built-in) | | Markdown | `--format markdown` | None (built-in) | | PDF | `--format pdf` | weasyprint or pdfkit | ## 🔒 Ethical & Legal **OmniPentestX is designed for authorized security testing only.** ### Rules of Engagement 1. **Obtain explicit written permission** before testing any system 2. **Comply with all applicable laws** (CFAA, Computer Misuse Act, GDPR, etc.) 3. **Stay within authorized scope** — never deviate from the agreed target 4. **Handle findings responsibly** — disclose to system owners, not publicly 5. **Never exfiltrate data** beyond what's necessary for proof of concept ### Built-in Safeguards - **Dangerous commands require approval** — hydra, metasploit, sqlmap, etc. prompt before running - **Audit logging** — every command is logged with timestamp, target, and user - **Sandbox mode** — Docker isolation for destructive tools ## 📦 Publishing & Distribution ### Distribution Channels #### 1. PyPI (pip install) # Build the package pip install build python -m build # Upload to PyPI pip install twine twine upload dist/* # Users install with: pip install omnipentestx **Before publishing:** - [ ] Set a real version (e.g., `1.0.0a1` for alpha) - [ ] Create a PyPI account at https://pypi.org - [ ] Generate an API token - [ ] Create `~/.pypirc` with your credentials - [ ] Consider publishing to **TestPyPI** first: `twine upload --repository testpypi dist/*` #### 2. GitHub Releases git tag v1.0.0a1 git push origin v1.0.0a1 # Then create a Release on GitHub with the built .whl and .tar.gz files attached #### 3. Docker Image FROM python:3.11-slim RUN pip install omnipentestx EXPOSE 8666 CMD ["python", "-m", "omnipentestx", "web"] ### Testing Phase — Getting Pentesters On Board #### Phase 1: Internal Alpha (You + Trusted Peers) **What to share:** Git clone URL Quick start commands The full README (this document) **What to ask testers:** - ✅ Does `pip install -e .` work on your OS? - ✅ Does `python -m pytest tests/` pass (32/32)? - ✅ Can you run `python -m omnipentestx cli tools` and see all 27 tools? - ✅ Does `python -m omnipentestx web` start and serve the dashboard? - ✅ What error messages do you hit first? - ✅ Is the simulated scan mode useful for training? **Feedback to collect:** - OS + Python version they're using - Any import errors or dependency issues - Which features feel intuitive vs confusing - What tools they'd add to the registry - Any crashes or unexpected behavior #### Phase 2: Community Beta (GitHub + Discord/Matrix) **Set up:** 1. Enable **GitHub Issues** for bug tracking 2. Create issue templates: - `bug_report.md` — structured bug reports - `feature_request.md` — tool/feature requests - `integration_report.md` — "works on my machine" reports 3. Set up a **Discord** or **Matrix** server for real-time discussion 4. Create a `CONTRIBUTING.md` with: - Code style guide (Ruff) - PR process - How to add a new tool to the registry - How to write output parsers **Announcement channels:** - Reddit: r/netsec, r/cybersecurity, r/hacking - Twitter/X: #infosec #pentest #opensource - Hacker News: "Show HN" post - Discord: InfoSec Community, Hack The Box, TryHackMe #### Phase 3: Pre-Release Checklist - [ ] Working CI/CD (GitHub Actions — lint + test on PR) - [ ] All 32+ tests passing on Windows, macOS, Linux - [ ] At least 3 external testers have verified it works - [ ] No unhandled crashes on basic operations - [ ] README covers all the common failure modes - [ ] Ethical/legal disclaimers are prominent - [ ] Version bumped to `1.0.0a1` (alpha) or `1.0.0b1` (beta) - [ ] CHANGELOG.md exists ## 🤝 Contributing We welcome contributions from the security community! ### How to Add a New Tool 1. Open `tools/registry.py` 2. Add a `ToolDefinition`: self._tools.append(ToolDefinition( name="my-tool", category="recon", description="Does X, Y, Z", command_template="{tool} {target} {args}", safe=True, )) 3. If it needs output parsing, add a parser class in `core/executor.py` 4. Add a test in `tests/test_core.py` 5. Submit a PR! ### Development Setup git clone https://github.com/alphax-research/omnipentestx.git cd omnipentestx python -m venv venv source venv/bin/activate pip install -e ".[full]" pip install pytest pytest-asyncio ### Code Standards - Python 3.11+ with type hints everywhere - Ruff for linting (see `pyproject.toml`) - All functions need docstrings - Tests required for new features - Keep it cross-platform (Windows, macOS, Linux) ## 📄 License **GNU General Public License v3.0** OmniPentestX is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but **WITHOUT ANY WARRANTY**; without even the implied warranty of **MERCHANTABILITY** or **FITNESS FOR A PARTICULAR PURPOSE**. See the GNU General Public License for more details. **OmniPentestX** — Built by **AntiSyntax.protocol CREW** **Join the crew. Learn the craft. Give back to the community.** — [AntiSyntax.protocol CREW](https://github.com/DarkMatter-Security/OmniPentestX)

_{For the underground, by the underground.
One Framework. Zero Limits. Infinite Power.}

标签：Python, 人工智能, 实时处理, 密码管理, 无后门, 用户模式Hook绕过, 网络调试, 自动化, 逆向工具