{"id":46576833,"url":"https://github.com/rfunix/tengu","last_synced_at":"2026-03-07T10:07:04.113Z","repository":{"id":341313052,"uuid":"1169061250","full_name":"rfunix/tengu","owner":"rfunix","description":"AI-powered penetration testing MCP server","archived":false,"fork":false,"pushed_at":"2026-03-01T05:43:11.000Z","size":7617,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-01T06:42:15.480Z","etag":null,"topics":["ai-security","claude","cybersecurity","ethical-hacking","infosec","kali-linux","mcp","mcp-server","metasploit","nmap","offensive-security","owasp","penetration-testing","pentesting","red-team","security","vulnerability-scanner"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rfunix.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security-model.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-28T05:49:57.000Z","updated_at":"2026-03-01T05:43:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/rfunix/tengu","commit_stats":null,"previous_names":["rfunix/tengu"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/rfunix/tengu","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rfunix%2Ftengu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rfunix%2Ftengu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rfunix%2Ftengu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rfunix%2Ftengu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rfunix","download_url":"https://codeload.github.com/rfunix/tengu/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rfunix%2Ftengu/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30212021,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-07T09:02:10.694Z","status":"ssl_error","status_checked_at":"2026-03-07T09:02:08.429Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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-security","claude","cybersecurity","ethical-hacking","infosec","kali-linux","mcp","mcp-server","metasploit","nmap","offensive-security","owasp","penetration-testing","pentesting","red-team","security","vulnerability-scanner"],"created_at":"2026-03-07T10:07:03.549Z","updated_at":"2026-03-07T10:07:04.107Z","avatar_url":"https://github.com/rfunix.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Tengu — Pentesting MCP Server\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/Tengu.png\" alt=\"Tengu\" width=\"480\"/\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003e\"In Japanese mythology, the Tengu is a fierce mountain spirit — master strategist, warrior, and trainer of samurai. In cybersecurity, it guides you through every phase of the hunt.\"\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eFrom recon to report — AI-assisted pentesting in one command.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/rfunix/tengu/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/rfunix/tengu/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT-blue.svg\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://python.org\"\u003e\u003cimg src=\"https://img.shields.io/badge/python-3.12+-blue.svg\" alt=\"Python\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://modelcontextprotocol.io\"\u003e\u003cimg src=\"https://img.shields.io/badge/MCP-compatible-green.svg\" alt=\"MCP\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/tools-80-orange.svg\" alt=\"Tools\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/version-0.3.0-brightgreen.svg\" alt=\"Version\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/agent-LangGraph-purple.svg\" alt=\"Agent\"\u003e\n\u003c/p\u003e\n\n---\n\n**Tengu** is an MCP server that turns Claude into a penetration testing copilot. It orchestrates 80 security tools — from Nmap to Metasploit — with built-in safety controls, audit logging, and professional reporting.\n\n- **What is it?** An MCP server that connects Claude to industry-standard pentest tools\n- **Why use it?** Automates recon and scanning while keeping the human in control of exploits\n- **Who is it for?** Pentesters, red teamers, security students, and consulting firms\n\n### Key Features\n\n- **80 Tools** — Nmap, Metasploit, SQLMap, Nuclei, Hydra, Burp-compatible ZAP, and more\n- **AI-Orchestrated** — Claude decides the next tool based on previous findings\n- **Safety First** — Allowlist, rate limiting, audit logs, and human-in-the-loop for destructive actions\n- **Auto Reports** — Correlate findings and generate professional pentest reports (MD/HTML/PDF)\n- **35 Workflows** — Pre-built prompts for full pentest, web app, AD, cloud, and more\n- **20 Resources** — Built-in OWASP Top 10, MITRE ATT\u0026CK, PTES, and pentest checklists\n- **Stealth Layer** — Optional Tor/SOCKS5 proxy routing, UA rotation, and timing jitter\n\n---\n\n## MCP Server Mode (Copilot)\n\nUse Claude as an interactive pentest copilot — you direct the engagement, Claude picks the right tools and chains them together automatically.\n\n[![Tengu copilot demo](https://img.youtube.com/vi/KklDFk4pxZ0/maxresdefault.jpg)](https://www.youtube.com/watch?v=KklDFk4pxZ0)\n\n### Quick Start\n\n```bash\ngit clone https://github.com/rfunix/tengu.git \u0026\u0026 cd tengu\nmake docker-build\nmake docker-up\n```\n\nConnect Claude Code to the running server:\n\n```bash\nclaude mcp add --transport sse tengu http://localhost:8000/sse\n```\n\nThen ask Claude: `Do a full pentest on http://192.168.1.100`\n\nClaude chains tools automatically: `validate_target` → `whatweb` → `nmap` → `nikto` →\n`nuclei` → `sqlmap` → `correlate_findings` → `generate_report`\n\n### Docker Profiles\n\n| Command | What it starts |\n|---------|----------------|\n| `make docker-up` | Tengu MCP server (`:8000`) |\n| `make docker-lab` | + Juice Shop, DVWA (safe practice targets) |\n| `make docker-pentest` | + Metasploit, OWASP ZAP (real-world targets) |\n| `make docker-full` | + Metasploit, ZAP, and lab targets |\n\n**Scan custom targets without editing files:**\n\n```bash\nTENGU_ALLOWED_HOSTS=\"192.168.1.0/24,10.0.0.0/8\" make docker-up\n```\n\n### Image Tiers\n\nChoose the right size for your use case:\n\n| Tier | Size | MCP Tools | Use case |\n|------|------|-----------|----------|\n| `minimal` | ~480MB | 17 | Lightweight analysis, CVE research, reporting |\n| `core` | ~7GB | 47 | Full pentest toolkit (default) |\n| `full` | ~8GB | 80 | Everything + AD, wireless, stealth/OPSEC |\n\n```bash\nTENGU_TIER=minimal make docker-build   # lightweight\nTENGU_TIER=core    make docker-build   # default\nTENGU_TIER=full    make docker-build   # everything\n```\n\n\u003e **All tiers include all 35 prompts and 20 resources** — only the binary tools differ.\n\n\u003cdetails\u003e\n\u003csummary\u003eManual Install (without Docker)\u003c/summary\u003e\n\n**Prerequisites:** Python 3.12+, [`uv`](https://github.com/astral-sh/uv), Kali Linux (recommended)\n\n```bash\ngit clone https://github.com/rfunix/tengu.git \u0026\u0026 cd tengu\n\n# Install Python dependencies\nuv sync\n\n# Install external pentesting tools (Kali/Debian)\nmake install-tools\n\n# Run the MCP server (stdio transport)\nuv run tengu\n```\n\nConnect Claude Code:\n\n```bash\nclaude mcp add --scope user tengu -- uv run --directory /path/to/tengu tengu\n```\n\nConfigure allowed targets in `tengu.toml`:\n\n```toml\n[targets]\nallowed_hosts = [\"192.168.1.0/24\", \"example.com\"]\n```\n\nFor Claude Desktop, VM/SSE remote setup, and advanced configurations, see [docs/deployment-guide.md](docs/deployment-guide.md).\n\n\u003c/details\u003e\n\n### Configuration Reference\n\n```toml\n[targets]\n# REQUIRED: Only these hosts will be scanned\nallowed_hosts = [\"192.168.1.0/24\", \"example.com\"]\nblocked_hosts = []  # Always blocked, even if in allowed_hosts\n\n[stealth]\nenabled = false  # Route traffic through Tor/proxy\n\n[stealth.proxy]\nenabled = false\ntype = \"socks5h\"\nhost = \"127.0.0.1\"\nport = 9050\n\n[osint]\nshodan_api_key = \"\"  # Required for shodan_lookup\n\n[tools.defaults]\nscan_timeout = 300   # seconds\n```\n\nSee [docs/configuration-reference.md](docs/configuration-reference.md) for the full reference.\n\n---\n\n## Autonomous Agent Mode\n\nRun a fully autonomous pentest without manual tool invocation. The agent uses Claude as its strategic brain and Tengu as its execution toolset, following the PTES methodology from recon through reporting.\n\n[![Tengu autonomous agent demo](https://img.youtube.com/vi/BESaKamKPO8/maxresdefault.jpg)](https://www.youtube.com/watch?v=BESaKamKPO8)\n\n### Quick Start\n\n```bash\ncp .env.example .env\n# Edit .env: set ANTHROPIC_API_KEY and TENGU_AGENT_TARGET\n```\n\n**Lab targets (Juice Shop, DVWA):**\n\n```bash\nmake docker-lab\nmake docker-agent          # default model (sonnet)\nmake docker-agent-haiku    # cheaper — claude-haiku-4-5, max_tokens=1024\nmake docker-agent-sonnet   # balanced — claude-sonnet-4-6, max_tokens=4096\n```\n\n**Real-world pentests (Tengu + MSF + ZAP, no lab containers):**\n\n```bash\nmake docker-pentest\nmake docker-agent\n```\n\n**View reports in browser:**\n\n```bash\nmake docker-report-view          # http://localhost:8888 — styled HTML, all reports\nmake docker-report-browse        # same, auto-opens browser\nREPORT_PORT=9999 make docker-report-view   # custom port\n```\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/report.png\" alt=\"Tengu report viewer\" width=\"800\"/\u003e\n\u003c/p\u003e\n\n**Without Docker:**\n\n```bash\nuv sync --extra agent\npython autonomous_tengu.py 192.168.1.100 --scope 192.168.1.0/24 --type blackbox\n\n# Cost-optimised run\npython autonomous_tengu.py 192.168.1.100 --model claude-haiku-4-5 --max-tokens 1024 --timeout 30\n```\n\n**Cost control** — three env vars / CLI flags:\n\n| Flag | Env var | Default |\n|---|---|---|\n| `--model` | `TENGU_AGENT_MODEL` | `claude-sonnet-4-6` |\n| `--max-tokens` | `TENGU_AGENT_MAX_TOKENS` | `2048` |\n| `--timeout` | `TENGU_AGENT_TIMEOUT` | `60` (minutes, `0`=unlimited) |\n\n### How It Works\n\n```\nSTART → initializer → strategist ─┬─→ executor → analyst ─┬─→ strategist (loop)\n                                   │                        └─→ reporter → END\n                                   ├─→ human_gate → executor\n                                   └─→ reporter → END\n```\n\n**Key behaviors:**\n\n- **Strategist** (Claude) reads the current PTES phase and accumulated state to decide each action\n- **Executor** calls exactly one Tengu MCP tool per iteration\n- **Analyst** (Claude) extracts structured data from tool output and advances phases\n- **Human gate** interrupts execution before destructive tools (`msf_run_module`, `hydra_attack`, `impacket_kerberoast`, `sqlmap_scan` with level≥3)\n- Runs until all 7 PTES phases are covered or `--max-iterations` is reached\n- Final **Reporter** calls `correlate_findings` + `score_risk` + `generate_report`\n\n### PTES Methodology — 7 Phases\n\n| Phase | Name | What Tengu Does | Key Tools |\n|:---:|---|---|---|\n| 1 | Pre-Engagement | `validate_target` confirms scope, `check_tools` verifies readiness | `validate_target`, `check_tools` |\n| 2 | Intelligence Gathering | OSINT, DNS recon, subdomain enumeration, technology fingerprinting | `nmap`, `subfinder`, `amass`, `shodan`, `whatweb` |\n| 3 | Threat Modeling | Claude analyzes gathered intel, prioritizes attack surface, builds threat scenarios | *(AI-driven — no external tool)* |\n| 4 | Vulnerability Analysis | Template scanning, web app testing, SSL/TLS analysis, parameter fuzzing | `nuclei`, `nikto`, `ffuf`, `sqlmap`, `testssl` |\n| 5 | Exploitation | Controlled exploitation of confirmed vulnerabilities with human-in-the-loop | `msf_run_module`, `sqlmap`, `hydra`, `searchsploit` |\n| 6 | Post-Exploitation | Credential harvesting, lateral movement assessment, privilege escalation | `impacket_kerberoast`, `nxc_enum`, `enum4linux` |\n| 7 | Reporting | Correlate all findings, calculate risk scores, generate professional report | `correlate_findings`, `score_risk`, `generate_report` |\n\n---\n\n## Tool Catalog\n\n\u003e `minimal` (17 tools, ~480MB) · `core` (47 tools, ~7GB, default) · `full` (80 tools, ~8GB)\n\u003e Build with: `TENGU_TIER=\u003ctier\u003e make docker-build`. All tiers include all 35 prompts and 20 resources.\n\n| Category | Tools | Count |\n|----------|-------|-------|\n| Reconnaissance | Nmap, Masscan, Amass, Subfinder, Gowitness, HTTrack, Katana, httpx, SNMPwalk, RustScan | 10 |\n| Web Scanning | Nikto, Nuclei, FFUF, Gobuster, WPScan, Feroxbuster, OWASP ZAP, wafw00f | 8 |\n| SSL / TLS | sslyze, testssl.sh, HTTP headers analysis, CORS tester | 4 |\n| DNS | DNS Enumerate, DNSRecon, Subjack, WHOIS | 4 |\n| OSINT | theHarvester, Shodan, WhatWeb, DNStwist | 4 |\n| Injection Testing | SQLMap, Dalfox (XSS), Commix, CRLFuzz, GraphQL Security Check, Arjun | 6 |\n| Brute Force | Hydra, John the Ripper, Hashcat, CeWL | 4 |\n| Exploitation | Metasploit (search, info, run, sessions, cmd), SearchSploit | 6 |\n| Social Engineering | SET credential harvester, QR code attack, payload generator | 3 |\n| Secrets \u0026 Code | TruffleHog, Gitleaks | 2 |\n| Container \u0026 Cloud | Trivy, Checkov, ScoutSuite, Prowler | 4 |\n| Active Directory | NetExec, Enum4linux, Impacket (Kerberoast, secretsdump, psexec, wmiexec, smbclient), BloodHound, Responder, SMBMap | 10 |\n| Wireless | aircrack-ng / airodump-ng | 1 |\n| Anonymity \u0026 Stealth | Tor check/rotate, proxy check, identity rotation | 5 |\n| Analysis \u0026 Reporting | Finding correlation, CVSS risk scoring, report generation | 3 |\n| CVE Intelligence | CVE lookup (NVD), CVE search by keyword/product/severity | 2 |\n| Utility | Tool checker, target validator | 2 |\n\n\u003cdetails\u003e\n\u003csummary\u003eFull tool list (80 tools)\u003c/summary\u003e\n\n### Reconnaissance\n| Tool | Description |\n|------|-------------|\n| `nmap_scan` | Port scanning and service/OS detection |\n| `masscan_scan` | High-speed port scanner for large networks |\n| `subfinder_enum` | Passive subdomain enumeration |\n| `amass_enum` | Attack surface mapping and DNS brute-force |\n| `dnsrecon_scan` | DNS recon (zone transfer, brute-force, PTR) |\n| `dns_enumerate` | DNS record enumeration (A, MX, NS, TXT, SOA…) |\n| `whois_lookup` | WHOIS domain and IP lookup |\n| `subjack_check` | Subdomain takeover detection |\n| `gowitness_screenshot` | Web screenshot capture for documentation |\n| `httrack_mirror` | Full website mirror for offline analysis and forensics |\n| `katana_crawl` | Fast web crawler for link discovery and endpoint mapping |\n| `httpx_probe` | HTTP probe — status codes, tech stack, redirects |\n| `snmpwalk_scan` | SNMP enumeration and MIB walking |\n| `rustscan_scan` | Ultra-fast port scanning (finds open ports for Nmap follow-up) |\n\n### Web Scanning\n| Tool | Description |\n|------|-------------|\n| `nuclei_scan` | Template-based vulnerability scanner (CVEs, misconfigs) |\n| `nikto_scan` | Web server misconfiguration and outdated software scanner |\n| `ffuf_fuzz` | Directory, parameter, and vhost fuzzing |\n| `gobuster_scan` | Directory, DNS, and vhost brute-force |\n| `wpscan_scan` | WordPress vulnerability scanner |\n| `testssl_check` | Comprehensive SSL/TLS configuration analysis |\n| `analyze_headers` | HTTP security headers analysis and grading |\n| `test_cors` | CORS misconfiguration detection |\n| `ssl_tls_check` | SSL/TLS certificate and cipher check (sslyze) |\n| `wafw00f_scan` | Web Application Firewall detection and fingerprinting |\n| `feroxbuster_scan` | Fast, recursive content discovery via brute-force |\n\n### OSINT\n| Tool | Description |\n|------|-------------|\n| `theharvester_scan` | Email, subdomain, and host enumeration from public sources |\n| `shodan_lookup` | Shodan host and asset search |\n| `whatweb_scan` | Web technology fingerprinting (CMS, WAF, frameworks) |\n| `dnstwist_scan` | Domain permutation and typosquatting detection |\n\n### Injection Testing\n| Tool | Description |\n|------|-------------|\n| `sqlmap_scan` | Automated SQL injection detection and exploitation |\n| `xss_scan` | XSS detection via Dalfox |\n| `commix_scan` | Automated command injection detection and exploitation |\n| `crlfuzz_scan` | CRLF injection fuzzing for header injection vulnerabilities |\n| `graphql_security_check` | GraphQL introspection, batching, depth limit, field suggestions |\n| `arjun_discover` | Hidden HTTP parameter discovery |\n\n### Exploitation\n| Tool | Description |\n|------|-------------|\n| `msf_search` | Search Metasploit modules |\n| `msf_module_info` | Get detailed Metasploit module information |\n| `msf_run_module` | Execute a Metasploit module (requires explicit confirmation) |\n| `msf_sessions_list` | List active Metasploit sessions |\n| `msf_session_cmd` | Execute a command on an active session (shell/Meterpreter) |\n| `searchsploit_query` | Search Exploit-DB offline database |\n\n### Social Engineering\n| Tool | Description |\n|------|-------------|\n| `set_credential_harvester` | Clone a website and capture submitted credentials (authorized phishing simulations) |\n| `set_qrcode_attack` | Generate QR code pointing to a URL for physical social engineering assessments |\n| `set_payload_generator` | Generate social engineering payloads (PowerShell, HTA) for authorized campaigns |\n\n### Brute Force\n| Tool | Description |\n|------|-------------|\n| `hydra_attack` | Network login brute-force (SSH, FTP, HTTP, SMB…) |\n| `hash_crack` | Dictionary hash cracking (Hashcat / John the Ripper) |\n| `hash_identify` | Hash type identification |\n| `cewl_generate` | Custom wordlist generation from a target website |\n\n### Proxy / DAST\n| Tool | Description |\n|------|-------------|\n| `zap_spider` | OWASP ZAP web spider |\n| `zap_active_scan` | OWASP ZAP active vulnerability scan |\n| `zap_get_alerts` | Retrieve ZAP scan findings |\n\n### Secrets \u0026 Code Analysis\n| Tool | Description |\n|------|-------------|\n| `trufflehog_scan` | Leaked secrets detection in git repositories |\n| `gitleaks_scan` | Credential scanning in git history |\n\n### Container Security\n| Tool | Description |\n|------|-------------|\n| `trivy_scan` | Vulnerability scanning for Docker images, IaC, and SBOM |\n\n### Cloud Security\n| Tool | Description |\n|------|-------------|\n| `scoutsuite_scan` | Cloud security audit (AWS, Azure, GCP) |\n| `prowler_scan` | AWS/GCP/Azure security best practices and compliance audit |\n\n### Active Directory\n| Tool | Description |\n|------|-------------|\n| `enum4linux_scan` | SMB/NetBIOS enumeration |\n| `nxc_enum` | Active Directory enumeration via NetExec |\n| `impacket_kerberoast` | Kerberoasting with Impacket GetUserSPNs |\n| `impacket_secretsdump` | Remote SAM/LSA/NTDS secrets dump via Impacket |\n| `impacket_psexec` | Remote command execution via SMB (PsExec-style) |\n| `impacket_wmiexec` | Remote command execution via WMI |\n| `impacket_smbclient` | SMB share enumeration and file access |\n| `bloodhound_collect` | BloodHound AD data collection (SharpHound/bloodhound-python) |\n| `responder_capture` | LLMNR/NBT-NS/MDNS poisoning for credential capture |\n| `smbmap_scan` | SMB share enumeration and access testing |\n\n### Wireless\n| Tool | Description |\n|------|-------------|\n| `aircrack_scan` | Passive wireless network scan (airodump-ng) |\n\n### IaC Security\n| Tool | Description |\n|------|-------------|\n| `checkov_scan` | IaC misconfiguration scan (Terraform, K8s, Dockerfile) |\n\n### Stealth / OPSEC\n| Tool | Description |\n|------|-------------|\n| `tor_check` | Verify Tor connectivity and exit node IP |\n| `tor_new_identity` | Request new Tor circuit (NEWNYM) |\n| `check_anonymity` | Check exposed IP, DNS leaks, and anonymity level |\n| `proxy_check` | Validate proxy latency, exit IP, and anonymity type |\n| `rotate_identity` | Rotate Tor circuit and User-Agent simultaneously |\n\n### Analysis \u0026 Utility\n| Tool | Description |\n|------|-------------|\n| `check_tools` | Verify which external tools are installed |\n| `validate_target` | Validate target against allowlist |\n| `correlate_findings` | Correlate findings across multiple scans |\n| `score_risk` | CVSS-based risk scoring |\n| `cve_lookup` | CVE details from NVD (CVSS, CWE, affected products) |\n| `cve_search` | Search CVEs by keyword, product, or severity |\n| `generate_report` | Generate Markdown/HTML/PDF pentest report |\n\n\u003c/details\u003e\n\n---\n\n## Workflows \u0026 Prompts (35)\n\nPre-built workflow templates that guide Claude through complete engagements.\n\n| Category | Prompts |\n|----------|---------|\n| **Pentest workflows** | `full_pentest`, `quick_recon`, `web_app_assessment` |\n| **Vulnerability assessment** | `assess_injection`, `assess_access_control`, `assess_crypto`, `assess_misconfig` |\n| **OSINT** | `osint_investigation` |\n| **Reports** | `executive_report`, `technical_report`, `full_pentest_report`, `finding_detail`, `risk_matrix`, `remediation_plan`, `retest_report`, `save_report` |\n| **Stealth/OPSEC** | `stealth_assessment`, `opsec_checklist` |\n| **Specialized** | `ad_assessment`, `api_security_assessment`, `container_assessment`, `cloud_assessment`, `wireless_assessment`, `bug_bounty_workflow`, `compliance_assessment` |\n| **Quick actions** | `explore_url`, `map_network`, `hunt_subdomains`, `find_vulns`, `find_secrets`, `go_stealth`, `crack_wifi`, `pwn_target`, `msf_exploit_workflow` |\n| **Social Engineering** | `social_engineering_assessment` |\n\n---\n\n## Built-in Resources (20)\n\nStatic reference data loaded by Claude during engagements.\n\n| URI | Content |\n|-----|---------|\n| `owasp://top10/2025` | OWASP Top 10:2025 full list |\n| `owasp://top10/2025/{A01..A10}` | Per-category details + testing checklist |\n| `owasp://api-security/top10` | OWASP API Security Top 10 (2023) |\n| `owasp://api-security/top10/{API1..API10}` | Per-category details |\n| `ptes://phases` | PTES 7-phase methodology overview |\n| `ptes://phase/{1..7}` | Phase details (objectives, tools, deliverables) |\n| `checklist://web-application` | Web app pentest checklist (OWASP Testing Guide) |\n| `checklist://api` | API pentest checklist |\n| `checklist://network` | Network infrastructure checklist |\n| `mitre://attack/tactics` | MITRE ATT\u0026CK Enterprise tactics + techniques |\n| `mitre://attack/technique/{T1xxx}` | Technique detail by ID |\n| `creds://defaults/{product}` | Default credentials database |\n| `payloads://{type}` | Curated payload lists by type (xss, sqli, lfi, ssti, etc.) |\n| `stealth://techniques` | Reference guide for operational security techniques |\n| `stealth://proxy-guide` | Step-by-step proxy and Tor configuration guide |\n| `tools://catalog` | Live tool availability status |\n| `tools://{tool}/usage` | Usage guide for nmap, nuclei, sqlmap, metasploit, trivy, amass |\n| `prompts://list` | List of all available prompts with descriptions |\n| `prompts://category/{category}` | Prompts filtered by category |\n\n---\n\n## Architecture\n\n```\n┌─────────────┐     MCP      ┌─────────────────┐    subprocess    ┌─────────────────┐\n│   Claude    │◄────────────►│     Tengu        │─────────────────►│  Nmap, SQLMap,  │\n│  (Desktop / │  stdio/SSE   │   MCP Server     │  (never shell=T) │  Metasploit...  │\n│   Code)     │              │                  │                  └─────────────────┘\n└─────────────┘              └────────┬─────────┘\n                                      │\n                               Every tool call passes through:\n                                      │\n                             ┌────────▼─────────┐\n                             │  Safety Pipeline  │\n                             │                  │\n                             │  1. sanitizer    │  ← strip metacharacters, validate format\n                             │  2. allowlist    │  ← check target against tengu.toml\n                             │  3. rate_limiter │  ← sliding window + concurrent slots\n                             │  4. audit logger │  ← JSON log to ./logs/tengu-audit.log\n                             └──────────────────┘\n```\n\n---\n\n## Configuration Files\n\nTengu uses three configuration files. Editing the wrong one is the most common source\nof confusion when switching between local and Docker workflows.\n\n| File | When to use | What it controls |\n|------|-------------|------------------|\n| `tengu.toml` (root) | Running locally: `uv run tengu`, `uv run python autonomous_tengu.py` | MCP server config: `allowed_hosts`, tool paths, rate limits, stealth |\n| `docker/tengu.toml` | Running via Docker: `make docker-up`, `make docker-agent` | Same settings as root, but pre-configured for Docker networking (`172.16.0.0/12`, service DNS aliases). Baked into the image at build time — **rebuild required** after changes (`make docker-rebuild-tengu`) |\n| `.env` | Both local and Docker | Secrets and runtime vars: `ANTHROPIC_API_KEY`, `TENGU_AGENT_TARGET`, `TENGU_AGENT_MODEL`, `TENGU_AGENT_MAX_TOKENS`, etc. Read by `docker compose` and `load_dotenv()` |\n| `.env.example` | Reference only | Template listing all available environment variables |\n\n**Quick config for copilot mode (local):** edit `tengu.toml` at the project root —\nadd your target to `[targets] allowed_hosts`.\n\n**Quick config for agent mode (Docker):** edit `docker/tengu.toml`, then run\n`make docker-rebuild-tengu` before `make docker-agent`.\n\n\u003e **Common pitfall:** if scans fail with `TargetNotAllowedError` inside Docker, you\n\u003e probably edited `tengu.toml` (root) instead of `docker/tengu.toml`. Docker uses its\n\u003e own copy baked into the image. After editing, run `make docker-rebuild-tengu`.\n\n---\n\n## Safety by Design\n\nTengu is built as a **force multiplier for human pentesters**, not an autonomous attack tool.\n\n| Control | Description |\n|---------|-------------|\n| **Target Allowlist** | Only pre-approved targets in `tengu.toml` are ever scanned |\n| **Input Sanitization** | All inputs are validated against strict patterns before reaching any tool |\n| **Rate Limiting** | Sliding window + concurrent slot limits prevent accidental DoS |\n| **Audit Logging** | Every tool invocation logged to `./logs/tengu-audit.log` in JSON format |\n| **Human-in-the-Loop** | `msf_run_module`, `hydra_attack`, and `impacket_kerberoast` require explicit confirmation |\n| **No shell=True — ever** | All subprocess calls use `asyncio.create_subprocess_exec` |\n\n---\n\n## Development\n\n```bash\nmake install-dev    # Install Python deps + dev extras\nmake test           # Run unit + security tests\nmake lint           # ruff check\nmake typecheck      # mypy strict\nmake check          # lint + typecheck\nmake coverage       # pytest --cov\nmake inspect        # Open MCP Inspector\nmake doctor         # Check which pentest tools are installed\n```\n\nTengu has 1931+ tests covering unit logic, security (command injection, input validation), and integration scenarios. See [CLAUDE.md](CLAUDE.md) for the full contributor guide.\n\n---\n\n## Legal Notice\n\nTengu is designed for **authorized security testing only**. Only scan systems you own or have explicit written permission to test. Unauthorized scanning is illegal in most jurisdictions. The authors accept no liability for misuse.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frfunix%2Ftengu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frfunix%2Ftengu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frfunix%2Ftengu/lists"}