pentagi

# Clone the repository
git clone https://github.com/vxcontrol/pentagi.git
cd pentagi

# Copy and configure environment
cp .env.example .env

# .env — Essential configuration
# LLM Provider (choose one)
OPENAI_API_KEY=sk-...                    # OpenAI
# ANTHROPIC_API_KEY=sk-ant-...           # Anthropic
# OLLAMA_SERVER_URL=http://host:11434    # Local Ollama

# Primary model for the main agent
LLM_MODEL=gpt-4o                         # or claude-3-5-sonnet, llama3.1
LLM_PROVIDER=openai                       # openai, anthropic, ollama, bedrock, gemini, deepseek

# Search provider for web intelligence
TAVILY_API_KEY=tvly-...                   # Tavily (recommended)
# GOOGLE_SEARCH_API_KEY=...              # or Google Custom Search
# SEARXNG_URL=http://localhost:8080      # or self-hosted SearXNG

# Security — change these in production
POSTGRES_PASSWORD=your-secure-password
SECRET_KEY=your-secret-key-min-32-chars

# Deploy the full stack
docker compose up -d

# Access the web UI
open http://localhost:3000

# Agent architecture (configured via UI or API)
#
# Primary Agent (Orchestrator)
#   ├── Researches target, plans attack phases
#   ├── Delegates to specialists:
#   │   ├── Research Agent — OSINT, web scraping, CVE lookup
#   │   ├── Development Agent — exploit modification, payload crafting
#   │   └── Infrastructure Agent — container management, tool setup
#   ├── Executes security tools in sandboxed containers
#   └── Generates vulnerability reports
#
# Each agent has access to:
#   - 20+ security tools (nmap, metasploit, sqlmap, nikto, etc.)
#   - Web browser for research
#   - Knowledge graph for persistent memory
#   - Previous engagement learnings

1. Open http://localhost:3000
2. Create a new engagement:
   - Target: IP address, domain, or CIDR range
   - Scope: Which services/ports to test
   - Rules of engagement: What's allowed (e.g., no DoS, no data exfiltration)
   - Objective: "Full security assessment" or specific focus
3. The AI agent:
   - Performs reconnaissance (nmap, whois, DNS enumeration)
   - Identifies services and versions
   - Searches for known vulnerabilities (CVE databases)
   - Attempts exploitation with appropriate tools
   - Documents findings with evidence
   - Generates a vulnerability report

// Integrate PentAGI into your security pipeline via GraphQL
const PENTAGI_URL = 'http://localhost:3000/graphql'

// Create a new engagement
const createEngagement = await fetch(PENTAGI_URL, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${API_TOKEN}`,
  },
  body: JSON.stringify({
    query: `
      mutation CreateTask($input: CreateTaskInput!) {
        createTask(input: $input) {
          id
          status
          createdAt
        }
      }
    `,
    variables: {
      input: {
        target: '192.168.1.0/24',
        objective: 'Perform a comprehensive security assessment of the internal network segment. Focus on identifying exposed services, default credentials, unpatched vulnerabilities, and potential lateral movement paths.',
        scope: ['port-scan', 'service-enum', 'vuln-scan', 'web-app-test'],
        constraints: ['no-dos', 'no-data-exfil', 'business-hours-only'],
      },
    },
  }),
})

// Monitor progress
const checkStatus = await fetch(PENTAGI_URL, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${API_TOKEN}` },
  body: JSON.stringify({
    query: `
      query TaskStatus($id: ID!) {
        task(id: $id) {
          id
          status
          progress
          currentPhase
          findings {
            severity
            title
            description
            evidence
            remediation
          }
          logs {
            timestamp
            agent
            action
            output
          }
        }
      }
    `,
    variables: { id: engagement.id },
  }),
})

# PentAGI remembers findings across engagements via Neo4j + Graphiti
#
# After each engagement, the knowledge graph stores:
# - Vulnerability patterns found per technology stack
# - Successful exploitation techniques
# - Network topology relationships
# - Service fingerprints and their known weaknesses
#
# In future engagements, the agent queries this knowledge to:
# - Prioritize attack vectors that worked before on similar targets
# - Skip techniques known to fail on specific configurations
# - Correlate findings across multiple assessments
# - Identify systemic issues across the organization

# Grafana dashboards — real-time monitoring
open http://localhost:3001
# Dashboards include:
# - Active agent operations and tool execution
# - Token usage and LLM cost tracking
# - Container resource utilization
# - Engagement timeline and progress

# Langfuse — LLM observability
open http://localhost:3002
# Track:
# - Agent reasoning chains
# - Prompt effectiveness
# - Token usage per engagement phase
# - Model performance comparison

# Export vulnerability report
curl -H "Authorization: Bearer $API_TOKEN" \
  "http://localhost:3000/api/v1/tasks/$TASK_ID/report" \
  -o vulnerability-report.pdf

# Report includes:
# - Executive summary
# - Detailed findings with CVSS scores
# - Evidence (screenshots, command output)
# - Remediation recommendations
# - Risk matrix