{"id":26276806,"url":"https://github.com/youngsecurity/pentest-agent-system","last_synced_at":"2025-03-14T11:19:34.881Z","repository":{"id":282016777,"uuid":"947204025","full_name":"youngsecurity/pentest-agent-system","owner":"youngsecurity","description":"The Pentest Agent System is an autonomous penetration testing framework built on the MITRE ATT\u0026CK framework.","archived":false,"fork":false,"pushed_at":"2025-03-12T10:45:12.000Z","size":38,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-12T11:24:41.663Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/youngsecurity.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2025-03-12T10:13:45.000Z","updated_at":"2025-03-12T10:45:15.000Z","dependencies_parsed_at":"2025-03-12T11:24:42.932Z","dependency_job_id":"fe5cde79-8cd0-4c75-94b1-7bc970aa9866","html_url":"https://github.com/youngsecurity/pentest-agent-system","commit_stats":null,"previous_names":["youngsecurity/pentest-agent-system"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/youngsecurity%2Fpentest-agent-system","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/youngsecurity%2Fpentest-agent-system/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/youngsecurity%2Fpentest-agent-system/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/youngsecurity%2Fpentest-agent-system/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/youngsecurity","download_url":"https://codeload.github.com/youngsecurity/pentest-agent-system/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243565347,"owners_count":20311705,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":[],"created_at":"2025-03-14T11:19:34.214Z","updated_at":"2025-03-14T11:19:34.870Z","avatar_url":"https://github.com/youngsecurity.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Pentest Agent System\n\nA comprehensive automated penetration testing system for exploiting the \"Blue\" TryHackMe room, built using Deno and TypeScript. This system implements an agent-based approach to cybersecurity operations based on the MITRE ATT\u0026CK framework, enhanced with LLM capabilities for intelligent planning, execution, and analysis.\n\n## System Architecture\n\nThe system consists of four specialized agents working together:\n\n1. **Orchestrator Agent**: Coordinates the overall operation, including planning, execution, and analysis phases. Acts as the central control system.\n\n2. **Planner Agent**: Creates attack plans based on the MITRE ATT\u0026CK framework, with specific focus on the techniques relevant to the Blue Room challenge (EternalBlue exploitation).\n\n3. **Executor Agent**: Executes the attack plan generated by the Planner Agent, interacting with tools like Nmap and Metasploit to perform the actual exploitation.\n\n4. **Analyst Agent**: Analyzes results from scans and exploits, generating insights, vulnerability assessments, and comprehensive reports.\n\n## Features\n\n- **MITRE ATT\u0026CK Framework Integration**: Attack plans are structured around specific MITRE techniques.\n- **Modular Architecture**: Clear separation of concerns between planning, execution, and analysis.\n- **Automated Reconnaissance**: Automatically scans the target and identifies vulnerabilities.\n- **Automated Exploitation**: Executes the EternalBlue exploit to gain access to the target system.\n- **Automated Post-Exploitation**: Performs privilege escalation, credential dumping, and flag collection.\n- **LLM-Enhanced Intelligence**: Uses large language models for improved planning, decision-making, and analysis.\n- **Multi-provider LLM Support**: Compatible with OpenAI, Anthropic, Azure, Ollama, and local LLM deployments.\n- **Detailed Logging**: Comprehensive logging of all operations and results.\n- **Progress Tracking**: Real-time updates on the operation progress.\n- **Error Recovery**: Graceful handling of failures with fallback options.\n- **Comprehensive Analysis**: In-depth analysis of vulnerabilities and exploitation results.\n\n## Blue Room Specific Implementation\n\nThis system is specifically designed to solve the Blue Room challenge on TryHackMe, which involves:\n\n1. Scanning the target to identify the MS17-010 (EternalBlue) vulnerability\n2. Exploiting the vulnerability to gain SYSTEM level access\n3. Finding and capturing three hidden flags on the system\n4. Extracting password hashes\n\n## Prerequisites\n\n- [Deno](https://deno.land/) 1.32.0 or higher\n- Kali Linux or similar penetration testing distribution\n- Metasploit Framework\n- Nmap\n- Active TryHackMe VPN connection\n- API key for LLM services (optional, for enhanced capabilities)\n\n## Installation\n\n1. Clone the repository:\n   ```bash\n   git clone https://github.com/your-username/pentest-agent-system.git\n   cd pentest-agent-system\n   ```\n\n2. Make sure you have Deno installed:\n   ```bash\n   curl -fsSL https://deno.land/x/install/install.sh | sh\n   ```\n\n3. Verify that Metasploit and Nmap are installed:\n   ```bash\n   msfconsole -v\n   nmap --version\n   ```\n\n4. Set your LLM API key as an environment variable (optional, for enhanced capabilities):\n   ```bash\n   export LLM_API_KEY=\"your-api-key\"\n   ```\n\n## Configuration\n\nThe system can be configured through the `config/config.ts` file or by providing command-line arguments. Key configurations include:\n\n- Target IP address\n- Tool paths (Metasploit, Nmap)\n- Flag locations\n- Logging level\n- LLM provider and model settings\n\n## Usage\n\n1. Connect to the TryHackMe VPN:\n   ```bash\n   sudo openvpn your-thm-username.ovpn\n   ```\n\n2. Deploy the Blue Room machine on TryHackMe.\n\n3. Run the system with the target IP address:\n   ```bash\n   deno run --allow-net --allow-read --allow-write --allow-run --allow-env main.ts -t TARGET_IP\n   ```\n\n   Replace `TARGET_IP` with the IP address of the Blue Room machine.\n\n4. To enable LLM capabilities:\n   ```bash\n   deno run --allow-net --allow-read --allow-write --allow-run --allow-env main.ts -t TARGET_IP --enable-llm\n   ```\n\n5. For verbose output:\n   ```bash\n   deno run --allow-net --allow-read --allow-write --allow-run --allow-env main.ts -t TARGET_IP -v --enable-llm\n   ```\n\n## Command-Line Options\n\n- `-t, --target \u003cip\u003e`: Target IP address (required)\n- `-l, --log-level \u003clevel\u003e`: Logging level (DEBUG, INFO, WARNING, ERROR) [default: INFO]\n- `-r, --results-dir \u003cdir\u003e`: Directory to store results [default: ./results]\n- `-v, --verbose`: Enable verbose output\n- `-h, --help`: Show the help message\n\n### LLM Options\n- `-e, --enable-llm`: Enable LLM integration (requires API key)\n- `-p, --llm-provider \u003cprovider\u003e`: LLM provider (openai, anthropic, azure, ollama, local) [default: openai]\n- `-m, --llm-model \u003cmodel\u003e`: LLM model to use [default: gpt-4]\n- `--llm-endpoint \u003curl\u003e`: Custom API endpoint URL\n\n### Environment Variables\n- `LLM_API_KEY`: API key for the LLM provider (required if LLM is enabled)\n\n## System Workflow\n\nWhen executed, the system follows this workflow:\n\n1. **Initialization**: Load configuration and set up the agent system.\n2. **Planning Phase**: The Planner Agent creates an attack plan based on the MITRE ATT\u0026CK framework.\n3. **Reconnaissance**: The Executor Agent scans the target to identify open ports and vulnerabilities.\n4. **Exploitation**: The Executor Agent exploits the MS17-010 vulnerability to gain access.\n5. **Post-exploitation**: The Executor Agent performs various post-exploitation activities:\n   - Privilege escalation\n   - Credential dumping\n   - Flag discovery and collection\n6. **Results Collection**: All findings are collected and stored in the results directory.\n7. **Reporting**: A comprehensive report is generated summarizing the operation.\n\n## Directory Structure\n\n```\nblue-agent-system/\n├── agents/                # Agent implementations\n│   ├── orchestrator.ts    # Orchestrator Agent\n│   ├── planner.ts         # Planner Agent\n│   ├── executor.ts        # Executor Agent\n├── models/                # Type definitions and models\n│   ├── plan.ts            # Attack plan models\n│   ├── mitre.ts           # MITRE ATT\u0026CK models\n│   ├── result.ts          # Result models\n├── config/                # Configuration\n│   ├── config.ts          # System configuration\n│   ├── attack_mapping.ts  # MITRE ATT\u0026CK mappings\n├── utils/                 # Utility functions\n│   ├── logger.ts          # Logging utility\n│   ├── metasploit_client.ts # Metasploit interaction\n│   ├── nmap_client.ts     # Nmap interaction\n├── deps.ts                # Dependencies\n├── main.ts                # Main application\n├── deno.json              # Deno configuration\n├── README.md              # This file\n```\n\n## MITRE ATT\u0026CK Implementation\n\nThis system implements the following MITRE ATT\u0026CK techniques:\n\n- **T1046: Network Service Scanning** - Scanning for open ports and vulnerable services\n- **T1190: Exploit Public-Facing Application** - Exploiting the MS17-010 vulnerability\n- **T1059: Command and Scripting Interpreter** - Executing commands via Meterpreter\n- **T1068: Exploitation for Privilege Escalation** - Gaining SYSTEM privileges\n- **T1070: Indicator Removal on Host** - Clearing event logs\n- **T1003: OS Credential Dumping** - Extracting password hashes\n- **T1083: File and Directory Discovery** - Searching for flag files\n- **T1005: Data from Local System** - Collecting flag content\n- **T1041: Exfiltration Over C2 Channel** - Retrieving flags through Meterpreter\n\n## Results\n\nAfter execution, the system generates results in the specified results directory:\n- Attack plan files (JSON)\n- Execution state files (JSON)\n- Operation result files (JSON)\n- Log files\n\nThe operation results include:\n- Scan results (open ports, detected vulnerabilities)\n- Exploitation results (success/failure, session information)\n- Post-exploitation results (commands executed, artifacts collected)\n- Captured flags\n- Overall operation summary\n\n## Security Considerations\n\nThis tool is designed specifically for educational purposes and ethical penetration testing. Only use it on systems you have permission to test. The tool implements the following security measures:\n\n1. Only targets the specific IP address provided\n2. Does not implement any persistence mechanisms\n3. Logs all activities for accountability\n4. Can be immediately terminated with Ctrl+C\n\n## Troubleshooting\n\nCommon issues and solutions:\n\n1. **Connection errors**: Ensure your VPN connection to TryHackMe is active\n2. **Tool execution failures**: Verify Metasploit and Nmap paths in the configuration\n3. **Permission issues**: Make sure to run the application with appropriate permissions\n4. **Exploit failures**: The Blue Room machine might need to be reset\n\n## Development\n\n### Adding New Techniques\n\nTo add new MITRE ATT\u0026CK techniques:\n\n1. Add the technique definition to `config/attack_mapping.ts`\n2. Implement the technique execution logic in `agents/executor.ts`\n3. Update the planning logic in `agents/planner.ts`\n\n### Testing\n\nRun the application in verbose mode to see detailed execution information:\n\n```bash\ndeno run --allow-net --allow-read --allow-write --allow-run main.ts -t TARGET_IP -v\n```\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Acknowledgments\n\n- TryHackMe for creating the Blue Room challenge\n- MITRE for the ATT\u0026CK framework\n- The Deno and TypeScript communities","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyoungsecurity%2Fpentest-agent-system","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyoungsecurity%2Fpentest-agent-system","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyoungsecurity%2Fpentest-agent-system/lists"}