If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/vxcontrol/pentagi shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 1d ago
• 5 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 59% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live vxcontrol/pentagi repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/vxcontrol/pentagi.

What it runs against: a local clone of vxcontrol/pentagi — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in vxcontrol/pentagi | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of vxcontrol/pentagi. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/vxcontrol/pentagi.git
#   cd pentagi
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of vxcontrol/pentagi and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "vxcontrol/pentagi(\\.git)?\\b" \\
  && ok "origin remote is vxcontrol/pentagi" \\
  || miss "origin remote is not vxcontrol/pentagi (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "backend/cmd/installer/main.go" \\
  && ok "backend/cmd/installer/main.go" \\
  || miss "missing critical file: backend/cmd/installer/main.go"
test -f "backend/cmd/ftester/worker/executor.go" \\
  && ok "backend/cmd/ftester/worker/executor.go" \\
  || miss "missing critical file: backend/cmd/ftester/worker/executor.go"
test -f "backend/cmd/installer/processor/processor.go" \\
  && ok "backend/cmd/installer/processor/processor.go" \\
  || miss "missing critical file: backend/cmd/installer/processor/processor.go"
test -f "backend/cmd/installer/loader/loader.go" \\
  && ok "backend/cmd/installer/loader/loader.go" \\
  || miss "missing critical file: backend/cmd/installer/loader/loader.go"
test -f "backend/cmd/installer/hardening/hardening.go" \\
  && ok "backend/cmd/installer/hardening/hardening.go" \\
  || miss "missing critical file: backend/cmd/installer/hardening/hardening.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/vxcontrol/pentagi"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

PentAGI is a fully autonomous AI agent system for penetration testing that leverages LLM providers (OpenAI, Anthropic, Ollama, AWS Bedrock, etc.) to automatically orchestrate and execute complex security testing tasks. It combines a Go backend with Docker sandboxing for isolated test execution, TypeScript frontend for UI, and integrates knowledge graphs (Graphiti), observability (Langfuse), and multiple embedding models to enable sophisticated autonomous security workflows. Monorepo structure: backend/ contains Go CLI tools (ctester, etester, ftester, installer) and core agent logic; separate frontend (TypeScript/React) consumed via .github workflows and Docker orchestration. backend/cmd/ftester/worker/ handles actual test execution with isolated subprocess management; backend/cmd/etester/ manages embeddings and search; installer/ bootstraps environments. Database layer uses GORM + pgvector for vector similarity on PostgreSQL.

Security researchers, penetration testers, and InfoSec professionals who need automated vulnerability discovery and testing at scale without manually scripting each attack vector. Also appeals to AI/LLM researchers studying autonomous agent behavior in adversarial domains and red-teamers building enterprise security testing pipelines.

Actively developed with substantial codebase (4.5MB Go, 1.3MB TypeScript) and GitHub workflows for CI/CD present. The presence of Docker orchestration, database migrations (Goose v3), and multiple LLM provider integrations suggests production intent. However, no explicit version tags or release notes visible in file list; assess via commit history before production deployment.

Moderate complexity risk: the system manages Docker containers, LLM API calls across 8+ providers, and direct penetration testing execution — misconfigurations could cause unintended lateral movement or compliance violations. Dependencies on external services (OpenAI, AWS, Anthropic) create operational brittleness; the heavy TypeScript/Go split increases maintenance surface. Verify current security audit status and LLM prompt injection mitigations before handling sensitive networks.

Active development on autonomous agent supervision, LLM provider abstraction (supporting DeepSeek, GLM, Kimi, Qwen alongside major providers), and knowledge graph integration via Graphiti. CI workflows in .github/workflows/ci.yml active; CONTRIBUTING.md and CONTRIBUTORS.md indicate ongoing community engagement. Observability features (Langfuse integration) and OAuth (GitHub/Google) are recent additions.

git clone https://github.com/vxcontrol/pentagi.git && cd pentagi && cp .env.example .env && docker-compose up (inferred from Dockerfile, docker-compose presence, and .env.example). For local backend dev: cd backend && go mod download && go run ./cmd/installer or similar for bootstrapping.

Daily commands: Backend: cd backend && go run ./cmd/installer/main.go (or specific command tool). Frontend: typical Node.js build (inferred from TypeScript). Docker: docker build -f Dockerfile . && docker run (see .dockerignore and Dockerfile for layers). .github/workflows/ci.yml reveals automated test/build pipeline — check that for authoritative build steps.

• backend/cmd/installer/main.go — Entry point for the installation wizard that sets up the entire PentAGI system, handling Docker, database, and AI provider configuration.
• backend/cmd/ftester/worker/executor.go — Core execution engine for autonomous pentesting tasks, orchestrating agent workflows and tool invocations.
• backend/cmd/installer/processor/processor.go — Main state machine that processes installation steps, coordinates all subsystems (Docker, PostgreSQL, configuration loading).
• backend/cmd/installer/loader/loader.go — Configuration loader that parses provider configs, environment variables, and compose files—foundational for system initialization.
• backend/cmd/installer/hardening/hardening.go — Security hardening and database migration orchestration, critical for production deployment safety.
• backend/cmd/ftester/worker/tester.go — Test execution framework that validates agent behavior, tool responses, and pentesting workflow integrity.
• backend/cmd/installer/wizard/app.go — Interactive UI controller for the installation wizard using Bubble Tea, the primary user-facing entry point for setup.

Add a New Installation Wizard Screen

1. Create a new form model struct in backend/cmd/installer/wizard/models/ implementing the base_screen.go interface (Init, Update, View, etc.) (backend/cmd/installer/wizard/models/base_screen.go)
2. Register the screen in the navigator's routing logic and screen list (backend/cmd/installer/navigator/navigator.go)
3. Add localization strings for the new screen in the locale package (backend/cmd/installer/wizard/locale/locale.go)
4. Integrate screen validation and state persistence into the processor state machine (backend/cmd/installer/processor/processor.go)

Add a New Penetration Testing Task for Autonomous Agents

1. Define the task input/output schema and implement execution logic, extending the executor's task handler (backend/cmd/ftester/worker/executor.go)
2. Add validation and testing cases for the new task in the functional tester (backend/cmd/ftester/worker/tester.go)
3. Register any required tools or external integrations in the mock tools setup (backend/cmd/ftester/mocks/tools.go)
4. Add integration tests to verify the task execution pipeline (backend/cmd/ftester/main.go)

Add Support for a New LLM Provider

1. Create a provider YAML configuration file in backend/cmd/installer/files/links/providers-configs/ (backend/cmd/installer/files/links/providers-configs)
2. Extend the loader to parse and validate the new provider configuration schema (backend/cmd/installer/loader/loader.go)
3. Add a provider configuration form in the installer wizard models (backend/cmd/installer/wizard/models/ai_agents_settings_form.go)
4. Update Docker Compose template generation to include the new provider's environment variables (backend/cmd/installer/processor/compose.go)

Add a Pre-Flight System Check

1. Implement a new check function in the checker package following existing patterns (e.g., Docker availability, disk space) (backend/cmd/installer/checker/checker.go)
2. Register the check in the checker's list and define failure messages (backend/cmd/installer/checker/helpers.go)
3. Add test cases for the new check in the test file (backend/cmd/installer/checker/helpers_test.go)
4. Integrate the check result into the installation processor's validation flow (backend/cmd/installer/processor/processor.go)

• Go 1.24.1 — Compiled, statically-typed language enables high-performance autonomous agent execution with minimal runtime overhead; strong concurrency primitives suit parallel task execution.
• Bubble Tea + Charmbracelet — Terminal UI framework provides elegant, responsive TUI for guided installation wizard without external dependencies; terminal-native fits headless deployment scenarios.
• Docker & Docker Compose — Containerization ensures consistent deployment across environments; Compose enables multi-service orchestration (agents, LLM providers, observability stack) with simple YAML configuration.
• PostgreSQL — Persistent relational database for storing agent execution history, pentesting results, and configuration state; required for distributed agent coordination.
• AWS SDK (Bedrock) — Provides unified interface to multiple LLM providers (Claude, Llama) via Bedrock; enables provider abstraction without tight coupling.
• GraphQL (gqlgen) — Enables flexible agent/API queries; supports dynamic field selection for large result sets typical in pentesting workflows.

• Interactive TUI wizard vs. headless API-only setup

  • Why: User-friendly guided installation reduces operational friction for first-time setup; enables validation and feedback loops at each step.
  • Consequence: Adds terminal UI dependencies; may complicate non-interactive CI/CD deployment (mitigated by flag-based configuration fallback).

• Embedded configuration templates vs. external config repository

  • Why: Self-contained binary reduces deployment complexity; templates generated at compile-time ensure consistency.
  • Consequence: Configuration updates require recompilation; harder to patch configs post-deployment (mitigated by dynamic config reload during runtime).

• Provider abstraction via YAML config vs. hardcoded provider support

  • Why: Enables rapid addition of new LLM providers without code changes; supports custom provider endpoints (e.g.,
  • Consequence: undefined

1. Multiple LLM providers require individual API key configuration in .env — missing keys will silently degrade to fallback or fail at runtime; 2) Docker daemon must be accessible and running (Unix socket /var/run/docker.sock or TCP endpoint configured); 3) PostgreSQL + pgvector extension required for embedding storage; database migrations via Goose must run before API starts; 4) Agent prompt injection risks are non-obvious — audit LLM context windows and function tool definitions before pointing at untrusted targets; 5) Langfuse integration is optional but enabled by default in some configs — disable if not desired; 6) Go version pinned to 1.24.1 — older Go installations may fail.

• Autonomous Agent Loops — PentAGI's core value is self-directed task execution without human intervention — understanding agent planning, reasoning loops, and action selection is essential to debug or extend agent behavior
• Vector Embeddings & Semantic Search — PentAGI uses pgvector + etester to index and retrieve domain knowledge for agents — embeddings enable semantic matching of attack patterns, tools, and target context
• LLM Function Calling / Tool Use — Agents invoke penetration testing tools (nmap, sqlmap, etc.) via LLM-controlled function calls defined in mocks/tools.go — improper tool definitions leak arbitrary command execution
• Docker Sandbox Isolation — All test execution runs in isolated Docker containers to prevent cross-test interference and lateral movement — understanding container networking, seccomp, and resource limits is critical for security
• Prompt Injection & Jailbreaking — Untrusted data (target descriptions, previous outputs) fed into LLM prompts can manipulate agent behavior — PentAGI's risk surface scales with number of autonomous agents and external inputs
• Knowledge Graph Integration (Graphiti) — PentAGI integrates graphiti-go-client for structured memory of discovered vulnerabilities and attack chains — enables agents to learn and coordinate across multiple pentests
• JWT Token-Based Auth with OAuth — Multi-user isolation and enterprise SSO require understanding JWT claims, session lifecycle, and OAuth (GitHub/Google) provider integration in gin-contrib/sessions

• gpt4all-local/gpt4all — Alternative local LLM provider for pentesting agents without external API dependencies — complementary to PentAGI's Ollama/AWS Bedrock integrations
• langchain-ai/langchain — Upstream LLM orchestration framework (PentAGI uses langchaingo fork vxcontrol/langchaingo v0.1.14) — understanding Langchain agent patterns directly informs PentAGI agent design
• opensemanticsearch/open-semantic-search — Semantic search engine using embeddings — PentAGI's pgvector + etester implements similar patterns for knowledge graph search
• grafana/grafana — Monitoring and observability stack — PentAGI integrates Langfuse for LLM observability; Grafana dashboards can visualize pentesting campaign metrics
• docker/cli — Docker SDK integration is central to PentAGI's sandboxing model — understanding Docker API internals (docker/docker Go SDK) clarifies container lifecycle management

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for backend/cmd/installer/checker/checker.go

The checker package validates system requirements during installation. Currently only helpers_test.go exists with partial coverage. The main checker.go logic lacks tests, which is critical for a security tool where installation validation directly impacts system safety. This would prevent regressions in dependency checking and validation logic.

• [ ] Review backend/cmd/installer/checker/checker.go to identify all exported functions and validation paths
• [ ] Create backend/cmd/installer/checker/checker_test.go with unit tests covering: OS detection, dependency validation, version checking, and error handling
• [ ] Test edge cases like missing dependencies, version mismatches, and platform-specific behaviors
• [ ] Ensure test coverage reaches >80% for the checker package
• [ ] Run go test ./backend/cmd/installer/checker/... locally to verify

Add integration tests for backend/cmd/ftester/worker/executor.go (worker execution)

The executor.go handles tool execution and worker lifecycle—core to the penetration testing agent system. No test files exist in backend/cmd/ftester/worker/. Given this is a critical execution path for autonomous agents, integration tests validating command execution, error handling, and result processing would significantly improve reliability and catch regressions.

• [ ] Analyze backend/cmd/ftester/worker/executor.go to map execution flow and dependencies (args.go, interactive.go)
• [ ] Create backend/cmd/ftester/worker/executor_test.go with integration tests using mocks from backend/cmd/ftester/mocks/
• [ ] Test scenarios: successful execution, timeout handling, argument validation, and interactive mode edge cases
• [ ] Ensure mocks in backend/cmd/ftester/mocks/tools.go and logs.go are leveraged appropriately
• [ ] Add tests to backend/cmd/ftester/worker/interactive_test.go for interactive mode if missing

Add GitHub Actions workflow for Go linting and security scanning

The .github/workflows/ci.yml exists but the repo uses go 1.24.1 with complex dependencies (GraphQL, AWS SDK, Docker, gqlgen) without visible lint/security checks. Adding a workflow for golangci-lint and gosec would catch code quality issues and known vulnerabilities early, especially important for a penetration testing framework where code security is paramount.

• [ ] Examine .github/workflows/ci.yml to understand current CI setup and avoid duplication
• [ ] Create .github/workflows/lint-security.yml with jobs for: golangci-lint (configured in .golangci.yml or inline), gosec (Go security scanner), and Go vet
• [ ] Configure golangci-lint to check key packages: backend/cmd/installer/, backend/cmd/ftester/, and core agent logic
• [ ] Set up gosec to scan for security issues with exclusions for test files (backend/cmd/*/mocks)
• [ ] Add badges to README.md linking to workflow status (security/lint passing)

• Add unit tests for backend/cmd/installer/checker/helpers.go — currently 1 test file exists (helpers_test.go) but coverage is sparse; add cases for each OS-specific check function (Windows, Linux, macOS).
• Document LLM provider setup for AWS Bedrock and Ollama in README.md with working .env examples and troubleshooting steps — currently mentioned but lack step-by-step walkthrough matching OpenAI's detail level.
• Implement GraphQL schema validation tests for gqlgen-generated types (99designs/gqlgen v0.17.57) to catch breaking changes in agent query/mutation contracts before deployment.

• High · Deprecated GORM Package Usage — go.mod - github.com/jinzhu/gorm v1.9.16. The codebase uses github.com/jinzhu/gorm v1.9.16, which is an old and deprecated ORM library. GORM v1 has known security vulnerabilities and is no longer maintained. The project should migrate to GORM v2 or another actively maintained ORM. Fix: Upgrade to GORM v2 (github.com/gorm.io/gorm) which has better security practices, regular updates, and improved SQL injection prevention mechanisms.
• High · Outdated Docker Base Image — Dockerfile - Line 5 (FROM node:23-slim AS frontend-compiler). The Dockerfile uses 'node:23-slim' as the base image without pinning to a specific digest or version patch. This can lead to unpredictable security updates and potential supply chain attacks. Fix: Pin the base image to a specific digest (e.g., node:23.3.0-slim@sha256:...) to ensure reproducible and predictable builds. Use tools like Dependabot or Renovate to manage version updates.
• High · Potential Secrets in Environment Variables — .env.example - Multiple API key and credential fields. The .env.example file contains placeholders for multiple sensitive credentials including API keys (OPEN_AI_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY), AWS credentials (BEDROCK_ACCESS_KEY_ID, BEDROCK_SECRET_ACCESS_KEY), and authentication tokens. Risk of secrets being accidentally committed to version control. Fix: Ensure .env files are in .gitignore (verify in .gitignore file). Use a secrets management solution like HashiCorp Vault, AWS Secrets Manager, or similar. Never commit actual credentials. Implement pre-commit hooks to prevent secrets leakage.
• High · Insecure Gin Framework Default Configuration — go.mod - github.com/gin-gonic/gin and github.com/gin-contrib/cors. The codebase uses github.com/gin-gonic/gin v1.10.0 with CORS enabled (github.com/gin-contrib/cors v1.7.2), but without visible configuration in the provided files. Missing proper CORS configuration can expose the API to cross-origin attacks. Fix: Implement strict CORS configuration with specific allowed origins, methods, and headers. Avoid using wildcard '*' for allowed origins. Review backend configuration files for CORS setup.
• Medium · Unverified Docker Runtime Privileges — Dockerfile - missing USER directive. The Dockerfile indicates this is a penetration testing tool that may execute arbitrary code or system commands. No visible security context restrictions or non-root user configuration in the provided Dockerfile snippet. Fix: Add a non-root USER directive in the Dockerfile. Ensure the application runs with minimal privileges. Consider using security contexts in Kubernetes deployments (runAsNonRoot, readOnlyRootFilesystem, etc.).
• Medium · Missing Security Headers Configuration — backend application configuration (not fully visible). The web server (Gin framework) configuration is not visible in the provided files. Standard security headers (CSP, X-Frame-Options, X-Content-Type-Options, HSTS) may not be configured. Fix: Implement middleware to set security headers: Content-Security-Policy, X-Frame-Options: DENY, X-Content-Type-Options: nosniff, X-XSS-Protection, Strict-Transport-Security.
• Medium · Potential SQL Injection via GORM v1 — go.mod - github.com/jinzhu/gorm v1.9.16 and database query files. GORM v1 has known SQL injection vulnerabilities when using raw SQL queries. The codebase appears to use raw database queries in several places based on file structure (backend/cmd/*/...). Fix: Migrate to GORM v2 which has improved query safety. Use parameterized queries exclusively. Avoid string concatenation for SQL queries. Implement input validation.
• Medium · Outdated Dependencies with Known Vulnerabilities — undefined. Several dependencies appear outdated: github.com/v Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.