https://github.com/youngsecurity/pentest-agent-system

The Pentest Agent System is an autonomous penetration testing framework built on the MITRE ATT&CK framework.
https://github.com/youngsecurity/pentest-agent-system

Last synced: about 1 year ago
JSON representation

The Pentest Agent System is an autonomous penetration testing framework built on the MITRE ATT&CK framework.

• Host: GitHub
• URL: https://github.com/youngsecurity/pentest-agent-system
• Owner: youngsecurity
• License: mit
• Created: 2025-03-12T10:13:45.000Z (about 1 year ago)
• Default Branch: main
• Last Pushed: 2025-03-12T10:45:12.000Z (about 1 year ago)
• Last Synced: 2025-03-12T11:24:41.663Z (about 1 year ago)
• Language: TypeScript
• Size: 37.1 KB
• Stars: 0
• Watchers: 1
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          
# Pentest Agent System

A 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&CK framework, enhanced with LLM capabilities for intelligent planning, execution, and analysis.

## System Architecture

The system consists of four specialized agents working together:

1. **Orchestrator Agent**: Coordinates the overall operation, including planning, execution, and analysis phases. Acts as the central control system.

2. **Planner Agent**: Creates attack plans based on the MITRE ATT&CK framework, with specific focus on the techniques relevant to the Blue Room challenge (EternalBlue exploitation).

3. **Executor Agent**: Executes the attack plan generated by the Planner Agent, interacting with tools like Nmap and Metasploit to perform the actual exploitation.

4. **Analyst Agent**: Analyzes results from scans and exploits, generating insights, vulnerability assessments, and comprehensive reports.

## Features

- **MITRE ATT&CK Framework Integration**: Attack plans are structured around specific MITRE techniques.

- **Modular Architecture**: Clear separation of concerns between planning, execution, and analysis.

- **Automated Reconnaissance**: Automatically scans the target and identifies vulnerabilities.

- **Automated Exploitation**: Executes the EternalBlue exploit to gain access to the target system.

- **Automated Post-Exploitation**: Performs privilege escalation, credential dumping, and flag collection.

- **LLM-Enhanced Intelligence**: Uses large language models for improved planning, decision-making, and analysis.

- **Multi-provider LLM Support**: Compatible with OpenAI, Anthropic, Azure, Ollama, and local LLM deployments.

- **Detailed Logging**: Comprehensive logging of all operations and results.

- **Progress Tracking**: Real-time updates on the operation progress.

- **Error Recovery**: Graceful handling of failures with fallback options.

- **Comprehensive Analysis**: In-depth analysis of vulnerabilities and exploitation results.

## Blue Room Specific Implementation

This system is specifically designed to solve the Blue Room challenge on TryHackMe, which involves:

1. Scanning the target to identify the MS17-010 (EternalBlue) vulnerability

2. Exploiting the vulnerability to gain SYSTEM level access

3. Finding and capturing three hidden flags on the system

4. Extracting password hashes

## Prerequisites

- [Deno](https://deno.land/) 1.32.0 or higher

- Kali Linux or similar penetration testing distribution

- Metasploit Framework

- Nmap

- Active TryHackMe VPN connection

- API key for LLM services (optional, for enhanced capabilities)

## Installation

1. Clone the repository:

   ```bash

   git clone https://github.com/your-username/pentest-agent-system.git

   cd pentest-agent-system

   ```

2. Make sure you have Deno installed:

   ```bash

   curl -fsSL https://deno.land/x/install/install.sh | sh

   ```

3. Verify that Metasploit and Nmap are installed:

   ```bash

   msfconsole -v

   nmap --version

   ```

4. Set your LLM API key as an environment variable (optional, for enhanced capabilities):

   ```bash

   export LLM_API_KEY="your-api-key"

   ```

## Configuration

The system can be configured through the `config/config.ts` file or by providing command-line arguments. Key configurations include:

- Target IP address

- Tool paths (Metasploit, Nmap)

- Flag locations

- Logging level

- LLM provider and model settings

## Usage

1. Connect to the TryHackMe VPN:

   ```bash

   sudo openvpn your-thm-username.ovpn

   ```

2. Deploy the Blue Room machine on TryHackMe.

3. Run the system with the target IP address:

   ```bash

   deno run --allow-net --allow-read --allow-write --allow-run --allow-env main.ts -t TARGET_IP

   ```

   Replace `TARGET_IP` with the IP address of the Blue Room machine.

4. To enable LLM capabilities:

   ```bash

   deno run --allow-net --allow-read --allow-write --allow-run --allow-env main.ts -t TARGET_IP --enable-llm

   ```

5. For verbose output:

   ```bash

   deno run --allow-net --allow-read --allow-write --allow-run --allow-env main.ts -t TARGET_IP -v --enable-llm

   ```

## Command-Line Options

- `-t, --target `: Target IP address (required)

- `-l, --log-level `: Logging level (DEBUG, INFO, WARNING, ERROR) [default: INFO]

- `-r, --results-dir `: Directory to store results [default: ./results]

- `-v, --verbose`: Enable verbose output

- `-h, --help`: Show the help message

### LLM Options

- `-e, --enable-llm`: Enable LLM integration (requires API key)

- `-p, --llm-provider `: LLM provider (openai, anthropic, azure, ollama, local) [default: openai]

- `-m, --llm-model `: LLM model to use [default: gpt-4]

- `--llm-endpoint `: Custom API endpoint URL

### Environment Variables

- `LLM_API_KEY`: API key for the LLM provider (required if LLM is enabled)

## System Workflow

When executed, the system follows this workflow:

1. **Initialization**: Load configuration and set up the agent system.

2. **Planning Phase**: The Planner Agent creates an attack plan based on the MITRE ATT&CK framework.

3. **Reconnaissance**: The Executor Agent scans the target to identify open ports and vulnerabilities.

4. **Exploitation**: The Executor Agent exploits the MS17-010 vulnerability to gain access.

5. **Post-exploitation**: The Executor Agent performs various post-exploitation activities:

   - Privilege escalation

   - Credential dumping

   - Flag discovery and collection

6. **Results Collection**: All findings are collected and stored in the results directory.

7. **Reporting**: A comprehensive report is generated summarizing the operation.

## Directory Structure

```

blue-agent-system/

├── agents/                # Agent implementations

│   ├── orchestrator.ts    # Orchestrator Agent

│   ├── planner.ts         # Planner Agent

│   ├── executor.ts        # Executor Agent

├── models/                # Type definitions and models

│   ├── plan.ts            # Attack plan models

│   ├── mitre.ts           # MITRE ATT&CK models

│   ├── result.ts          # Result models

├── config/                # Configuration

│   ├── config.ts          # System configuration

│   ├── attack_mapping.ts  # MITRE ATT&CK mappings

├── utils/                 # Utility functions

│   ├── logger.ts          # Logging utility

│   ├── metasploit_client.ts # Metasploit interaction

│   ├── nmap_client.ts     # Nmap interaction

├── deps.ts                # Dependencies

├── main.ts                # Main application

├── deno.json              # Deno configuration

├── README.md              # This file

```

## MITRE ATT&CK Implementation

This system implements the following MITRE ATT&CK techniques:

- **T1046: Network Service Scanning** - Scanning for open ports and vulnerable services

- **T1190: Exploit Public-Facing Application** - Exploiting the MS17-010 vulnerability

- **T1059: Command and Scripting Interpreter** - Executing commands via Meterpreter

- **T1068: Exploitation for Privilege Escalation** - Gaining SYSTEM privileges

- **T1070: Indicator Removal on Host** - Clearing event logs

- **T1003: OS Credential Dumping** - Extracting password hashes

- **T1083: File and Directory Discovery** - Searching for flag files

- **T1005: Data from Local System** - Collecting flag content

- **T1041: Exfiltration Over C2 Channel** - Retrieving flags through Meterpreter

## Results

After execution, the system generates results in the specified results directory:

- Attack plan files (JSON)

- Execution state files (JSON)

- Operation result files (JSON)

- Log files

The operation results include:

- Scan results (open ports, detected vulnerabilities)

- Exploitation results (success/failure, session information)

- Post-exploitation results (commands executed, artifacts collected)

- Captured flags

- Overall operation summary

## Security Considerations

This 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:

1. Only targets the specific IP address provided

2. Does not implement any persistence mechanisms

3. Logs all activities for accountability

4. Can be immediately terminated with Ctrl+C

## Troubleshooting

Common issues and solutions:

1. **Connection errors**: Ensure your VPN connection to TryHackMe is active

2. **Tool execution failures**: Verify Metasploit and Nmap paths in the configuration

3. **Permission issues**: Make sure to run the application with appropriate permissions

4. **Exploit failures**: The Blue Room machine might need to be reset

## Development

### Adding New Techniques

To add new MITRE ATT&CK techniques:

1. Add the technique definition to `config/attack_mapping.ts`

2. Implement the technique execution logic in `agents/executor.ts`

3. Update the planning logic in `agents/planner.ts`

### Testing

Run the application in verbose mode to see detailed execution information:

```bash

deno run --allow-net --allow-read --allow-write --allow-run main.ts -t TARGET_IP -v

```

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Acknowledgments

- TryHackMe for creating the Blue Room challenge

- MITRE for the ATT&CK framework

- The Deno and TypeScript communities