{"id":51061917,"url":"https://github.com/hackerbone/serpenter","last_synced_at":"2026-06-23T03:01:29.898Z","repository":{"id":356124853,"uuid":"1140802124","full_name":"Hackerbone/serpenter","owner":"Hackerbone","description":"An Open Source Autonomous Pentesting Assistant for Active Directory Engagements","archived":false,"fork":false,"pushed_at":"2026-05-06T19:19:29.000Z","size":417,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-06T19:30:58.627Z","etag":null,"topics":["active-directory","cybersecurity","pentesting"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Hackerbone.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"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-01-23T19:28:23.000Z","updated_at":"2026-05-06T19:19:34.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Hackerbone/serpenter","commit_stats":null,"previous_names":["hackerbone/serpenter"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/Hackerbone/serpenter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hackerbone%2Fserpenter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hackerbone%2Fserpenter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hackerbone%2Fserpenter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hackerbone%2Fserpenter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Hackerbone","download_url":"https://codeload.github.com/Hackerbone/serpenter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Hackerbone%2Fserpenter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34673437,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-23T02:00:07.161Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["active-directory","cybersecurity","pentesting"],"created_at":"2026-06-23T03:01:28.463Z","updated_at":"2026-06-23T03:01:29.892Z","avatar_url":"https://github.com/Hackerbone.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🐍 SERPENTER\n\n**S**emi-Autonomous **E**numeration and **R**econnaissance **P**entesting **E**ngine with **N**atural **T**ask **E**xecution via **R**easoning\n\nAn AI-powered pentesting agent specialized in Active Directory environments. SERPENTER intelligently executes reconnaissance and enumeration tasks using natural language commands.\n\n## ✨ Features\n\n- 🤖 **Natural Language Interface** - Describe your pentesting objectives in plain English\n- 🔧 **Multi-Provider LLM Support** - Choose from Anthropic Claude, OpenAI GPT, Groq, or local Ollama models\n- 🛠️ **Intelligent Tool Orchestration** - Automatically chains tools (nmap, netexec, etc.) to accomplish tasks\n- 📺 **Real-Time Progress Monitoring** - See tool execution in real-time with streaming output\n- 🎛️ **Interactive Visibility Controls** - Toggle debug/verbose/quiet modes on the fly\n- 🎯 **AD Pentesting Focus** - Specialized in Active Directory enumeration and reconnaissance\n- ⚙️ **Flexible Configuration** - YAML-based config for easy customization\n- 📊 **Rich Terminal Output** - Beautiful, informative command-line interface\n\n## 🚀 Quick Start\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone \u003crepo-url\u003e\ncd serpenter\n\n# Install dependencies with uv\nuv sync\n\n# Set up configuration\ncp config.yaml my-config.yaml\n# Edit my-config.yaml with your settings\n```\n\n### Configure Your LLM Provider\n\nSERPENTER supports multiple LLM providers. Choose one:\n\n**Option 1: Groq (Recommended - Fast \u0026 Free Tier)**\n```bash\nexport GROQ_API_KEY='your-groq-api-key'\n```\nGet your key at: https://console.groq.com/keys\n\n**Option 2: Anthropic Claude**\n```bash\nexport ANTHROPIC_API_KEY='your-anthropic-key'\n```\n\n**Option 3: OpenAI**\n```bash\nexport OPENAI_API_KEY='your-openai-key'\n```\n\n**Option 4: Ollama (Local, No API Key)**\n```bash\nollama pull llama3:70b\n# No API key needed!\n```\n\nEdit `config.yaml` to select your provider:\n```yaml\nllm:\n  provider: \"groq\"  # or \"anthropic\", \"openai\", \"ollama\"\n  model: \"llama-3.3-70b-versatile\"\n  temperature: 0.1\n  max_tokens: 4096\n```\n\n### Run SERPENTER\n\n```bash\n# One-shot command\nuv run serpenter_cli.py run \"list all SMB services in 192.168.1.0/24\"\n\n# Interactive mode (recommended)\nuv run serpenter_cli.py interactive\n\n# With custom config\nuv run serpenter_cli.py --config my-config.yaml run \"enumerate domain controllers\"\n\n# Debug mode (shows detailed tool execution)\nuv run serpenter_cli.py --debug run \"find accessible shares on 10.0.0.5\"\n```\n\n### Full Internal Assessment\n\nSerpenter also has a full-scale internal assessment mode that produces a\nBugbase-style report with entities, findings, attack paths, evidence, and an\nAI analyst summary while keeping Serpenter's AI-native tool execution model.\n\n```bash\n# Unauthenticated/anonymous-safe internal assessment with AI evidence analysis\nuv run serpenter_cli.py internal-assessment 192.168.1.0/24 -o results/internal.json\n\n# Authenticated AD assessment with LDAP, Kerberos, SMB, and AD CS coverage\nuv run serpenter_cli.py internal-assessment 10.0.0.0/24 \\\n  --domain corp.local \\\n  --dc-ip 10.0.0.10 \\\n  -u auditor \\\n  -p 'Password123!' \\\n  -o results/corp-internal.json\n\n# Enable active exploit validation steps explicitly\nuv run serpenter_cli.py internal-assessment 10.0.0.0/24 \\\n  --domain corp.local --dc-ip 10.0.0.10 -u auditor -p 'Password123!' \\\n  --allow-exploits\n\n# Subnet-only assessment. RCE validation runs only if credentials are supplied\n# or discovered from collected evidence by future credential-acquisition phases.\nuv run serpenter_cli.py internal-assessment 192.168.56.0/24 \\\n  --allow-exploits \\\n  --rce-command whoami \\\n  -o results/goad-internal.json\n```\n\nDefault output mirrors the internal assessment mental model:\n\n- `entities`: hosts, services, and discovered AD/service objects\n- `findings`: vulnerability-style records with severity, target, evidence, and remediation\n- `attack_paths`: source-to-evidence-to-vulnerability chains\n- `evidence`: every phase/tool run with reproducible command arguments and raw output\n- `ai_summary`: LLM synthesis when enabled, deterministic fallback otherwise\n\nAI is required by default in internal assessment mode. Use `--no-ai` only for\noffline smoke tests or deterministic CI runs.\n\nSerpenter does not ship lab-specific secrets or default credentials. Any\ncredentialed validation must come from explicit run input or evidence collected\nduring the assessment.\n\n### Interactive Mode Commands\n\n```bash\nserpenter\u003e /help     # Show all commands\nserpenter\u003e /verbose  # Toggle real-time progress (default: ON)\nserpenter\u003e /debug    # Toggle detailed debug output\nserpenter\u003e /quiet    # Minimal output, fastest execution\nserpenter\u003e /status   # Show current settings\nserpenter\u003e exit      # Exit SERPENTER\n```\n\nSee [INTERACTIVE_GUIDE.md](INTERACTIVE_GUIDE.md) for detailed usage.\n\n## 📖 Usage Examples\n\n### Network Discovery\n```bash\nserpenter run \"discover live hosts in 192.168.1.0/24\"\nserpenter run \"find all domain controllers in the subnet\"\nserpenter run \"scan for open SMB ports on 10.0.0.0/24\"\n```\n\n### SMB Enumeration\n```bash\nserpenter run \"list all SMB shares in 192.168.1.0/24\"\nserpenter run \"enumerate users on 10.0.0.5 via SMB\"\nserpenter run \"find accessible shares with guest access\"\n```\n\n### Multi-Protocol Enumeration\n```bash\nserpenter run \"test WinRM access on 192.168.1.100\"\nserpenter run \"enumerate LDAP users on domain controller 10.0.0.10\"\nserpenter run \"check RDP access across 192.168.1.0/24\"\n```\n\n### Complex Tasks\n```bash\nserpenter run \"map the AD environment in 10.0.0.0/24\"\nserpenter run \"find potential privilege escalation paths\"\nserpenter run \"identify misconfigured shares containing credentials\"\n```\n\n### Certificate Attacks (AD CS)\n```bash\nserpenter run \"enumerate vulnerable certificate templates on 10.0.0.10\"\nserpenter run \"perform ESC1 attack using vulnerable template\"\nserpenter run \"add shadow credentials to target account\"\nserpenter run \"find all AD CS misconfigurations in the domain\"\n```\n\n## 🔧 Configuration\n\nSERPENTER uses a YAML configuration file for flexibility. See [config.examples.md](config.examples.md) for detailed examples.\n\n### Configuration Structure\n\n```yaml\n# LLM Provider\nllm:\n  provider: \"groq\"\n  model: \"llama-3.3-70b-versatile\"\n  temperature: 0.1\n  max_tokens: 4096\n\n# Agent Behavior\nagent:\n  debug: false\n  max_iterations: 10\n  auto_mode: false\n  verbose: true\n\n# Tools\ntools:\n  enabled:\n    - nmap\n    - netexec\n    - bash\n  \n  nmap:\n    default_timeout: 300\n  \n  netexec:\n    default_timeout: 180\n\n# Output\noutput:\n  log_file: null\n  save_results: false\n  results_dir: \"./results\"\n```\n\n### Available LLM Providers\n\n| Provider | Models | Speed | Cost | Best For |\n|----------|--------|-------|------|----------|\n| **Groq** | llama-3.3-70b, mixtral-8x7b | ⚡⚡⚡ | 💰 Free tier | General use |\n| **Anthropic** | claude-sonnet-4 | ⚡⚡ | 💰💰 | Complex reasoning |\n| **OpenAI** | gpt-4, gpt-3.5 | ⚡⚡ | 💰💰💰 | Reliable performance |\n| **Ollama** | llama3:70b, mixtral | ⚡ | 💰 Free | Privacy, offline |\n\n## 🛠️ Tools\n\nSERPENTER includes the following pentesting tools:\n\n### nmap_scan\nNetwork discovery and port scanning\n- Quick host discovery\n- Service version detection\n- Vulnerability scanning\n\n### netexec (Generic)\nMulti-protocol enumeration supporting:\n- **SMB**: shares, users, groups, sessions\n- **WinRM**: user enumeration, command execution\n- **LDAP**: users, groups, computers\n- **RDP**: access testing\n- **SSH**: authentication testing\n- And more...\n\n### impacket\nPython-based AD exploitation toolkit:\n- **secretsdump**: Extract credentials from SAM/NTDS\n- **GetUserSPNs**: Kerberoasting attacks\n- **GetNPUsers**: AS-REP roasting\n- **psexec/wmiexec**: Remote code execution\n- And many more Impacket scripts\n\n### ldapsearch\nLDAP enumeration for Active Directory:\n- Enumerate users, computers, groups\n- Find privileged accounts\n- Discover Kerberoastable accounts\n- Identify AS-REP roastable users\n- Query GPOs and domain trusts\n\n### hashcat\nPassword cracking:\n- NTLM hashes\n- NetNTLMv2\n- Kerberoast tickets\n- AS-REP hashes\n\n### certipy\nActive Directory Certificate Services (AD CS) attacks:\n- **find**: Enumerate certificate templates and identify vulnerabilities (ESC1-8)\n- **req**: Request certificates from templates\n- **auth**: Authenticate using certificates to obtain NTLM hashes/TGT\n- **shadow**: Shadow credentials attacks\n- **ca**: Dump CA certificates and keys\n- **forge**: Create golden certificates\n- Support for all major AD CS attack scenarios\n\n### bash_execute\nExecute custom bash commands (with safety checks)\n\n## 🏗️ Architecture\n\n```\nUser Input (Natural Language)\n    ↓\nSERPENTER CLI\n    ↓\nConfig (YAML) → Agent (LangGraph)\n    ↓\nLLM Provider (Groq/Claude/GPT/Ollama)\n    ↓\nTool Selection \u0026 Execution\n    ↓\n    ├→ nmap_scan\n    ├→ netexec (smb/winrm/ldap/rdp/ssh)\n    └→ bash_execute\n    ↓\nResults \u0026 Analysis\n    ↓\nUser Output (Rich Terminal)\n```\n\n## 🔐 Security Considerations\n\n- **Dangerous commands are blocked** by default in bash_execute\n- **API keys should never be committed** to version control\n- **Use responsibly** - Only scan networks you have permission to test\n- **Debug mode may expose sensitive data** - Use cautiously in production\n\n## 📚 Documentation\n\n- [Interactive Mode Guide](INTERACTIVE_GUIDE.md) - Real-time monitoring and visibility controls\n- [Configuration Guide](CONFIGURATION_GUIDE.md) - Complete configuration reference\n- [Configuration Examples](config.examples.md) - Provider-specific examples\n- [Tool Documentation](tools.py) - Tool implementation details\n\n## 🧪 Development\n\n```bash\n# Install development dependencies\nuv sync\n\n# Run tests\nuv run pytest\n\n# Format code\nuv run black .\n\n# Lint\nuv run ruff check .\n```\n\n## 🤝 Contributing\n\nContributions are welcome! Please:\n1. Fork the repository\n2. Create a feature branch\n3. Add tests for new functionality\n4. Submit a pull request\n\n## 📝 License\n\nMIT License - See LICENSE file for details\n\n## ⚠️ Disclaimer\n\nThis tool is for authorized security testing only. Users are responsible for complying with all applicable laws and regulations. Unauthorized access to computer systems is illegal.\n\n## 🙏 Acknowledgments\n\nBuilt with:\n- [LangChain](https://github.com/langchain-ai/langchain) \u0026 [LangGraph](https://github.com/langchain-ai/langgraph)\n- [Anthropic Claude](https://www.anthropic.com/) / [Groq](https://groq.com/) / [OpenAI](https://openai.com/)\n- [Rich](https://github.com/Textualize/rich) for beautiful terminal output\n- [Click](https://click.palletsprojects.com/) for CLI\n- Security tools: nmap, netexec, impacket, certipy, hashcat, ldapsearch\n\n---\n\n**Made with 🐍 for the pentesting community**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhackerbone%2Fserpenter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhackerbone%2Fserpenter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhackerbone%2Fserpenter/lists"}