pyntra

Drive AI agents through the full offensive-security lifecycle — from a single web console or a chat message.

Install · Configure · Setup guides · Usage · Architecture

Pyntra orchestrates 100+ security tools over the Model Context Protocol (MCP), reasons about findings, builds attack chains, retrieves from a security knowledge base, and keeps every step auditable. You describe the objective in plain language; the agent plans, runs tools, correlates results, and reports back.

• Highlights

• How it works

• Installation

• Configuration

• Setup guides

  • LLM backend

  • Recon API keys (Shodan / Censys)

  • Chat bots (Telegram / Slack / Discord)

• Usage

• Tool catalog

• Architecture

• Roadmap

• Contributing

• License

✨ Highlights

Related MCP server: Kali Tools MCP Server

🧭 How it works

flowchart LR
    U([You]) -->|"objective in plain language"| A
    subgraph Pyntra
        A[AI Agent<br/>ReAct · Deep · Plan-Execute · Supervisor]
        A <-->|reason & retrieve| K[(Knowledge Base<br/>RAG)]
        A -->|invoke| M{MCP Layer}
        M --> T1[Recon<br/>shodan · censys · amass]
        M --> T2[Scan<br/>nmap · nuclei · ffuf]
        M --> T3[Exploit / Post<br/>sqlmap · metasploit]
        M --> Tn[100+ tools &<br/>external MCP servers]
    end
    A --> R[/Findings · Attack chain · Report/]
    R --> U
    A -. also reachable via .-> B[Telegram · Slack · Discord]

🚀 Installation

Prerequisites

1 — Clone

git clone https://github.com/prnvv2/pyntra.git
cd pyntra

2 — Start a local model (recommended)

# Install Ollama from https://ollama.com, then pull a model:
ollama pull llama3.1:8b

Set openai.model: llama3.1:8b in config.yaml (the base_url already points at Ollama by default).

3 — Build & run

go build -o pyntra ./cmd/server
./pyntra                     # Windows: .\pyntra.exe

Open the console at http://localhost:8080 and log in with the password from config.yaml.

1. Install Ollama and pull a model (ollama pull llama3.1:8b).

2. Leave openai.base_url: http://localhost:11434/v1 and openai.api_key: ollama in config.yaml.

3. Set openai.model to your pulled model.

4. go build -o pyntra ./cmd/server && ./pyntra

See OLLAMA_QUICKSTART.md for details.

⚙️ Configuration

Everything lives in config.yaml and most of it is editable from the Settings page in the web console.

🔑 Setup guides

LLM backend (Ollama / OpenAI / Claude)

openai:
  provider: openai
  base_url: http://localhost:11434/v1
  api_key: ollama          # any non-empty value
  model: llama3.1:8b

openai:
  provider: openai
  base_url: https://api.openai.com/v1
  api_key: sk-...
  model: gpt-4o

Any OpenAI-protocol endpoint works — just point base_url at it.

openai:
  provider: claude          # bridges to the Anthropic Messages API
  base_url: https://api.anthropic.com
  api_key: sk-ant-...
  model: claude-sonnet-4

Recon API keys (Shodan / Censys)

The shodan_search and censys_search tools read credentials from environment variables at launch (nothing is written to disk):

# Shodan — https://account.shodan.io
export SHODAN_API_KEY="your-key"

# Censys — https://search.censys.io/account/api
export CENSYS_API_ID="your-id"
export CENSYS_API_SECRET="your-secret"

./pyntra

Both tools are enabled and attached to the Information Collection role out of the box.

Chat bots (Telegram / Slack / Discord)

Enable one or more bots in the bots: block of config.yaml. Each bot keeps a per-chat conversation — send /new to reset it, /help for commands.

1. Message @BotFather → /newbot → copy the token.

2. Configure:

   bots:
     telegram:
       enabled: true
       token: "123456:ABC-DEF..."
       role: ""          # optional role name from roles/

3. Restart Pyntra and DM your bot.

1. Create an app at api.slack.com/apps.

2. Enable Socket Mode → generate an app-level token (xapp-…).

3. Add bot scopes (chat:write, app_mentions:read, im:history) → install → copy the bot token (xoxb-…).

4. Subscribe to message.im / app_mention events.

5. Configure:

   bots:
     slack:
       enabled: true
       app_token: "xapp-..."
       bot_token: "xoxb-..."

1. Create an app at the Discord Developer Portal → Bot → copy the token.

2. Enable the Message Content Intent under the bot settings.

3. Invite the bot to your server with the Send Messages permission.

4. Configure:

   bots:
     discord:
       enabled: true
       token: "your-bot-token"

🧑‍💻 Usage

1. Pick a role (e.g. Information Collection, Web Application Scanning, CTF) to scope the agent's prompt and tools — or use the default.

2. Describe the objective in the chat: "Enumerate subdomains and open ports for example.com, then flag anything exploitable."

3. Watch it work — the agent plans, calls tools over MCP, and streams progress.

4. Review findings, the generated attack chain, and recorded vulnerabilities in the console.

5. Iterate — refine in the same conversation; context and history are preserved.

• Multi-agent modes (Deep / Plan-Execute / Supervisor) handle larger objectives by decomposing them across specialized sub-agents.

• Skills and the knowledge base are pulled in automatically to ground the agent in domain techniques and your own notes.

• Batch tasks let you queue many targets and run them on a schedule.

🧰 Tool catalog

Tools are simple YAML definitions in tools/; the agent invokes them over MCP. Highlights:

Add your own by dropping a YAML file in tools/, or plug in any external MCP server from the Settings → MCP page.

🧱 Architecture

flowchart TD
    subgraph Client
        W[Web Console — SPA]
        BOT[Telegram · Slack · Discord]
    end
    W <-->|HTTP + WebSocket| API[Gin API]
    BOT -->|long-poll / socket / gateway| API
    API --> ORCH[Agent Orchestration<br/>single & multi-agent]
    ORCH --> RSK[Roles · Skills · Knowledge RAG · Attack-chain builder]
    ORCH --> MCP[MCP Layer<br/>built-in server + external tool servers]
    MCP --> TOOLS[(100+ security tools)]
    API --> DB[(SQLite<br/>conversations · vulns · webshells · chains)]

Stack: Go · Gin · Gorilla WebSocket · CloudWeGo Eino · Model Context Protocol · modernc SQLite · Zap · discordgo.

🗺️ Roadmap

• Redesigned dashboard and views on the new design system

• Scope / authorization guardrails (target allowlist, engagement scope)

• Multi-user accounts, roles, and audit log

• Exportable pentest report generator (PDF / HTML)

• Local model eval & benchmark panel

🤝 Contributing

Issues and pull requests are welcome. Please keep contributions focused and include a clear description of the change.

📄 License

Licensed under the Apache License 2.0 — see LICENSE.

Pyntra is a derivative work based on an upstream Apache-2.0 project; see NOTICE for attribution and a summary of modifications.