pentestagent-tui

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.
domain	cybersecurity
author	oyi77
license	Apache-2.0
subdomain	penetration-testing
tags	["pentest","tui","multi-agent","rag","knowledge-graph","terminal"]
version	1.0.0

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

Trigger phrases:

• "pentestagent tui"

• "Interactive penetration testing with AI guidance"

• "Multi-agent security assessments requiring coordinated specialists"

• "Knowledge-driven pentest where CVE/wordlist injection accelerates findings"

• 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

{
  "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

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

Process

1. Analyze the task requirements
2. Apply domain expertise
3. Verify output quality

Anti-Rationalization Table

Rationalization	Reality
"We are too small to be targeted"	Automated attacks target everyone. Size does not matter.
"Security slows us down"	A breach slows you down 100x more. Build security in from the start.
"We will fix it after launch"	Vulnerabilities in production are exploited within hours. Fix before deploy.