---
name: pentestagent-tui
description: AI-powered pentesting terminal UI with 4 modes (Assist, Agent, Crew, Interact) and RAG knowledge system. Use when running interactive pentests, multi-agent security assessments, or knowledge-driven penetration testing.
domain: cybersecurity
subdomain: penetration-testing
tags:
- pentest
- tui
- multi-agent
- rag
- knowledge-graph
- terminal
---

# PentestAgent TUI

## Overview

PentestAgent is an AI-powered penetration testing terminal UI (v0.2.0, MIT-licensed) that provides interactive and autonomous security assessment capabilities. It features four operating modes, five built-in tools, a RAG-based knowledge system, and an MCP server exposing 18+ tools for external integration.

**Source:** https://github.com/GH05TCREW/pentestagent
**Version:** v0.2.0 | **License:** MIT | **Platform:** Terminal (cross-platform)
**Architecture:** Python TUI with MCP server, RAG pipeline, and knowledge graph

## When to Use

- Interactive penetration testing with AI guidance
- Multi-agent security assessments requiring coordinated specialists
- Knowledge-driven pentest where CVE/wordlist injection accelerates findings
- Building a reusable knowledge base across engagements
- Need a terminal-native pentest interface with persistent context

## Operating Modes

This section covers operating modes for pentestagent tui.

- Ensure all prerequisites are met before proceeding
- Follow the documented workflow steps in sequence
- Record results and any anomalies encountered during this phase
### 1. Assist Mode
Single-shot question-answer interaction.
- Ask a security question, get an expert answer
- One tool execution per query
- Fastest mode for quick lookups and targeted analysis
- Best for: "What's the attack surface of this service?", "Generate a payload for X"

### 2. Agent Mode
Autonomous single-agent execution.
- Agent plans and executes multi-step tasks independently
- Iterates through tool calls until objective is met
- Self-corrects on failure, retries with adjusted approach
- Best for: "Enumerate all services on 10.0.0.1 and find vulnerabilities"

### 3. Crew Mode
Multi-agent orchestration with specialized roles.
- Orchestrator delegates tasks to specialist agents
- Shadow Graph (knowledge graph) tracks relationships across agents
- Parallel execution of independent sub-tasks
- Result aggregation and conflict resolution
- Best for: Full pentest engagements, complex multi-vector assessments

### 4. Interact Mode
Guided chat with human-in-the-loop.
- Conversational interface with suggestion prompts
- Agent proposes actions, human approves or redirects
- Step-by-step execution with checkpoints
- Best for: Learning, exploratory testing, supervised assessments

## Built-in Tools (5 Tools)

| Tool | Purpose |
|------|---------|
| Burp Suite | Web application security testing proxy |
| Metasploit | Exploitation framework for penetration testing |
| Nmap | Network discovery and security auditing |
| Impacket | Python library for network protocol interaction |
### terminal
Execute shell commands and security tools directly from the TUI. Captures stdout/stderr for context-aware follow-up actions.

### browser
Web browser automation for testing web applications. Navigate, fill forms, intercept requests, capture screenshots.

### notes
Persistent note-taking system organized by type:
- **Credentials** — discovered usernames, passwords, hashes, tokens
- **Vulnerabilities** — confirmed findings with evidence and severity
- **Findings** — observations, interesting configurations, potential leads
- **Artifacts** — screenshots, logs, extracted data, tool output

### web_search
Search the web for CVE details, exploit code, tool documentation, and vulnerability information. Results feed into the RAG knowledge base.

### spawn_mcp_agent
Spawn additional MCP-based agents for parallel task execution. Used in Crew mode to create specialist sub-agents on demand.

## Knowledge System

This section covers knowledge system for pentestagent tui.

- Ensure all prerequisites are met before proceeding
- Follow the documented workflow steps in sequence
- Record results and any anomalies encountered during this phase
### RAG (Retrieval-Augmented Generation)
Inject domain knowledge into the AI context:
- **CVE injection** — load CVE details for targeted vulnerability testing
- **Wordlist injection** — context-aware wordlist selection based on target technology
- **Technique injection** — load attack playbooks for specific vulnerability classes
- Knowledge persists across sessions for cumulative learning

### Notes System
Structured finding management:
```
Type: vulnerability
Title: SQL Injection in login form
Severity: Critical
Evidence: ' OR 1=1-- bypasses authentication
Target: https://target.example.com/login
Remediation: Use parameterized queries
```

### Shadow Graph (Crew Mode)
Knowledge graph that maps relationships discovered during assessment:
- Host-to-service relationships
- Service-to-vulnerability mappings
- Credential-to-access-path chains
- User-to-privilege escalation paths
- Shared across all agents in Crew mode for consistent context

## MCP Server (18+ Tools)

PentestAgent exposes its capabilities as an MCP server for integration with external clients.

### Tool Categories

| Category | Tools | Purpose |
|----------|-------|---------|
| Reconnaissance | `nmap_scan`, `subdomain_enum`, `port_scan` | Target discovery and enumeration |
| Web Testing | `web_scan`, `dir_brute`, `param_fuzz` | Web application vulnerability testing |
| Exploitation | `exploit_run`, `payload_gen`, `shell_handler` | Exploit execution and payload delivery |
| Post-Exploitation | `privesc_check`, `cred_harvest`, `persist` | Post-access operations |
| Knowledge | `cve_lookup`, `note_add`, `graph_query` | Knowledge management and lookup |
| Utility | `file_read`, `cmd_exec`, `screenshot` | General-purpose tools |

### MCP Configuration
```json
{
  "mcpServers": {
    "pentestagent": {
      "command": "python",
      "args": ["-m", "pentestagent.mcp_server"],
      "env": {}
    }
  }
}
```

## Engagement Workflow

```
1. Start in Interact mode — define scope and objectives
2. Switch to Agent mode — automated reconnaissance
3. Review notes and Shadow Graph for attack paths
4. Switch to Crew mode — parallel exploitation with specialists
5. RAG system enriches agents with relevant CVEs and techniques
6. Notes system tracks all findings throughout
7. Export findings from notes for report generation
```

## Installation

```bash
git clone https://github.com/GH05TCREW/pentestagent.git
cd pentestagent
pip install -r requirements.txt

# Launch TUI
python -m pentestagent

# Or start MCP server only
python -m pentestagent.mcp_server
```

## When NOT to Use

- Task is outside your authorization scope
- You need to implement controls (use implementing-* skills)
- Task is about analysis, not action (use analyzing-* skills)
- You don't have access to target systems
- Task requires compliance expertise (consult professionals)
- Task is about defense, not offense (use defensive skills)


## Red Flags

- Only test targets with explicit written authorization
- Credential notes contain sensitive data — protect the notes database
- Crew mode agents can execute commands autonomously — use approval gates
- RAG knowledge injection should not include real target credentials in shared environments
- Shadow Graph persists between sessions — clear it between engagements to prevent data leakage
## Verification

- All steps executed successfully against a test environment before production use
- Output documented with screenshots or logs demonstrating expected behavior
- All exploited vulnerabilities documented with reproduction steps
- Scope boundaries confirmed — only authorized targets were tested
- Remediation recommendations included for every finding