Ramibot

RamiBot — AI Security Operations Platform

Local-first • Red/Blue Team • MCP-Powered • Docker-Integrated

---

Execute. Analyze. Harden.

Key Features

RamiBot connects AI reasoning with real cybersecurity tools through a structured operations pipeline.

AI & Reasoning

• 🧠 Multi-provider LLM support

OpenAI, Anthropic, OpenRouter, LM Studio, and Ollama

• 🧠 Skill Pipeline

Structured methodology: Recon → Exploit → Defense → Reporting

• 🔐 Evidence-Locked Reporting

Prevents hallucinated CVEs, versions, or findings

Security Tool Integration

• 🧰 Real security tool execution via MCP

Integrates pentesting tools inside controlled environments

• 🕵️ Rami-Kali MCP server

45+ pentesting tools available to the LLM

Infrastructure

• 🐳 Docker-integrated terminal

Run commands directly inside containerized environments

• 🛑 Tool Approval Gate

Human approval before executing security tools

• 📄 One-click PDF report export

Generate structured security reports instantly

RamiBot v3.8.0

A local-first AI chat interface for security operations. Supports multiple LLM providers, real-time streaming, MCP tool integration, a dynamic security skill system, Docker terminal access, Tor transparent proxy management, a persistent findings database, one-click PDF report export, a human-in-the-loop Tool Approval Gate that pauses execution before every MCP tool call, a global Evidence-Locked Reporting system that prevents the model from fabricating versions, CVEs, severity ratings, or security properties not explicitly present in tool output, a dedicated Burp Suite web assessment skill, a response language selector, Hermes tool chaining that detects and executes ` XML emitted by Llama/Hermes fine-tuned models, **zsh shell with syntax highlighting and autosuggestions** in the Docker terminal, **proxychains4 proxy routing** with ready-made Burp and Tor profiles, **Service-Bound CVE Correlation** that locks every CVE to its exact detected service via CPE data, a **CVE Query Lock** rule that prevents semantic drift when generating NVD lookup queries after service discovery, **OAuth token support** for OpenAI (ChatGPT Plus/Pro subscription via Codex CLI) and Anthropic (reserved, pending re-enablement), and **one-command install and start scripts** (install.sh / install.bat, start.sh / start.bat`) that automate the full setup from a fresh system.

Demo

AI-Assisted Pentesting Pipeline (Claude 4.5 + Rami-Kali)

Port Scan → CVE Intelligence → Security Report (Local AI) Qwen 3.5 4B (Q8_0)

---

Installation

Requirements

• Python 3.9+
• Node.js 18+
• npm
• Docker Desktop (required — for the rami-kali MCP server, Docker terminal, and Tor features)

Windows Installer (easiest)

Download RamiBot-Setup-v3.8.0.exe from the Releases page, run it, and follow the wizard.

Before running the installer, make sure Docker Desktop is installed and running. The installer checks for it and will abort if Docker is not found.

The wizard checks for Python 3.9+ and Node.js 18+. If either is missing it downloads and installs them via their official wizards, then installs all Python and npm dependencies automatically. After the wizard completes, launch RamiBot from the desktop shortcut and add your API key(s) in Settings.

> First launch: on the very first start, RamiBot automatically builds the rami-kali Docker image in the background. This can take a few minutes depending on your connection. Subsequent launches are instant — the image is already built and the container starts in seconds.

🎥 Full Installation Demo (Windows)

One-command install (recommended)

git clone 
cd ramibot

# Linux / macOS
bash install.sh

# Windows
install.bat

The script checks all prerequisites (Python, Node, Docker), installs missing ones automatically where possible, sets up the Python venv, installs npm dependencies, copies settings.example.json → settings.json, builds the rami-kali Docker image, and starts the container — all in one step. Running it again is safe; existing config is never overwritten.

After install, edit backend/settings.json and add your API key(s), then:

# Linux / macOS
bash start.sh

# Windows
start.bat

start.sh / start.bat launches backend + frontend in the background and opens http://localhost:5173 after 4 seconds. The rami-kali container is left running on shutdown (restart: unless-stopped).

Manual install (alternative)

git clone 
cd ramibot

Backend:

cd backend
python -m venv .venv

# Windows
.venv\Scripts\activate

# macOS / Linux
source .venv/bin/activate

pip install -r requirements.txt

Frontend:

cd frontend
npm install

Run

One command (after install):

bash start.sh      # Linux / macOS
start.bat          # Windows

Two terminals (manual):

# Terminal 1
cd backend
python -m uvicorn main:app --reload --port 8000

# Terminal 2
cd frontend
npm run dev

Makefile (macOS/Linux):

make install
make dev

Open http://localhost:5173.

---

Overview

RamiBot is a self-hosted chat application built for security engineers who need a controllable, extensible interface between LLMs and operational tooling.

It does not depend on any cloud chat product. Conversations are stored locally in SQLite. Provider API keys are configured at runtime. All tool execution happens inside Docker containers.

The core differentiator is the skill pipeline: a prompt engineering system that detects the operational context from user input (reconnaissance, exploitation, defense, analysis, reporting), selects the appropriate skill, and injects structured methodology instructions into the system prompt before each LLM call. Team mode (red or blue) controls which skills are available and how the LLM frames its responses.

Who it is for:

• Security engineers running structured red team or blue team workflows
• Analysts who need LLM-assisted reasoning alongside real tool execution via MCP
• Researchers integrating local models (Ollama, LM Studio) into security workflows
• Teams that need full local data control with no cloud dependency for conversation history

---

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         FRONTEND (React 19)                     │
│  Sidebar  │  ChatPanel  │  SettingsModal  │  DockerTerminal     │
│                    Zustand State Store                          │
│           SSE consumer / fetch client (port 5173)               │
└───────────────────────────┬─────────────────────────────────────┘
                            │ HTTP / SSE
┌───────────────────────────▼─────────────────────────────────────┐
│                      BACKEND (FastAPI)                          │
│                                                                 │
│  /api/chat/stream ──► SkillPipeline ──► LLM Adapter             │
│                             │                    │              │
│                      PromptComposer       httpx (SSE)           │
│                             │                    │              │
│                      System Prompt        Provider API          │
│                                                                 │
│  Tool call detected ──► MCPClient ──► rami-kali MCP server      │
│                     (auto-configured)   (docker exec stdio)     │
│                                    ──► MCP Server (stdio/HTTP)  │
│  Tool result ──────────────────────► LLM follow-up              │
│                                                                 │
│  /api/terminal/* ──► TerminalSession ──► docker exec            │
│  /api/docker/tor ──► tor_start/stop  ──► iptables (container)   │
│                                                                 │
│  aiosqlite ──► ramibot.db                                       │
│  settings.json ──► provider credentials + docker config         │
└─────────────────────────────────────────────────────────────────┘

Data flow for a streaming chat request:

1. Frontend sends POST /api/chat/stream with conversation ID, provider, model, team mode, MCP flag, and optional require_tool_approval
2. Backend loads conversation history from SQLite
3. If MCP is enabled: skill pipeline classifies the input, selects a skill, builds a system prompt, and injects it as the first message in history
4. Adapter streams the LLM response as Server-Sent Events (token events)
5. If the LLM emits a tool call and Approval Mode is on: backend yields a tool_approval_required SSE event and waits (up to 120 s) for the operator's decision via POST /api/chat/approve; auto-denies on timeout
6. If approved (or Approval Mode is off): the MCP client executes the tool, the result is appended to history, and a follow-up generation is triggered
7. Backend saves the final message to SQLite with token usage and latency
8. Frontend renders tokens incrementally and tool traces in real time

---

Skill System

The skill system is invoked on every MCP-enabled chat request. It classifies input, selects a skill, and builds a structured system prompt tailored to the operation phase and team mode.

Components

| Component | File | Responsibility | |-----------|------|----------------| | SkillPipeline | skills/pipeline.py | Orchestrates the full build-prompt flow | | InputClassifier | skills/classifier.py | Regex and substring trigger matching | | PromptComposer | skills/composer.py | Assembles system prompt from selected skill | | SkillRegistry | skills/registry.py | Loads skill definitions from JSON |

Skill Definitions

| Skill | Teams | Priority | Risk | Trigger examples | |-------|-------|----------|------|------------------| | recon | red, blue | 10 | low | scan, nmap, enumerate, port, subdomain, dns | | exploit | red only | 20 | high | exploit, payload, shell, rce, xss, sqli, privesc, metasploit | | defense | blue only | 20 | low | harden, firewall, patch, mitigate, incident, siem, ids | | analysis | red, blue | 30 | low | analyze, log, traffic, pcap, forensic, anomaly, wireshark | | reporting | red, blue | 50 | low | report, document, executive, findings, export | | burp_expert | red, blue | 15 | high | burp, web app, proxy history, repeater, intruder, fuzz, owasp |

Pipeline Logic

1. Trigger classification: Word-boundary regex matches user input against skill trigger lists
2. Phase inference: If no triggers match, the last 3 messages are scanned for phase markers ([RECON], payload, patch, etc.)
3. Dominant skill selection: Highest-priority match wins. reporting is suppressed if exploit or defense is also matched.
4. Fallback: No match defaults to the team default (recon for red, analysis for blue)
5. Context extraction: IPv4, URL, and host:port patterns are extracted from input and recent history and injected as CONTEXT TARGET in the prompt
6. Execution intent: Imperative verbs ("run", "execute", "scan", "exploit") are detected and signaled to the composer
7. Prompt assembly: Team preamble + skill methodology section + EVIDENCE_RULES + COMMON_FOOTER
8. Audit log: Every decision is appended as JSON to skill_decisions.log

Team Modes

Red (team_mode: "red")

• Preamble: authorized engagement, attacker perspective, tool-first
• Active skills: recon, exploit, analysis, reporting
• Priority order: exploit > recon > analysis > reporting

Blue (team_mode: "blue")

• Preamble: incident responder, remediation-driven
• Active skills: defense, analysis, reporting, recon
• Priority order: defense > analysis > reporting > recon

Team mode is selected per conversation from the sidebar toggle and persisted in localStorage.

---

Evidence-Locked Reporting

RamiBot enforces a strict evidence discipline across all team modes and all skills to prevent LLM hallucinations in security reports and operational output.

How it works

Tool result wrapping (backend/main.py):

Every successful MCP tool result is wrapped in immutable evidence tags before being injected into the LLM's follow-up context:

[EVIDENCE BLOCK — DO NOT MODIFY]

[END OF EVIDENCE]

Global enforcement (backend/skills/composer.py):

EVIDENCE_RULES is injected into every system prompt regardless of team mode or skill. Ten mandatory rules apply to all responses:

| Rule | Enforcement | |------|-------------| | Only Evidence Block content is fact | No information from model training cited as operational finding | | No fabricated versions / CVEs / CVSS | "Version not detected." / "Requires manual validation." / score omitted | | No external gap-filling | If nmap shows a service with no version, no version is assumed | | No inferred properties | Encryption status, authentication state, EOL status, exploitability, internet exposure, and credential weakness may only be stated if the Evidence Block explicitly contains them | | Conditional risk language | Forbidden: "is vulnerable", "is exploitable", "is exposed". Required: "may be", "appears to", "consistent with" — unless the tool itself uses assertive language | | Severity from confirmed findings only | No Critical/High/Medium/Low from port number, service name, or version string alone. Default: "Informational" if no vulnerability is explicitly reported | | Three-layer output discipline | [RAW OUTPUT] / [PARSED DATA] / [INTERPRETATION] clearly separated | | No Evidence Block → no fabrication | State "No tool output available" and stop | | Service-Bound CVE Correlation | Each CVE result carries a SERVICE BINDING line (derived from CPE data). A CVE may only be attached to the detected service whose name matches that binding — never reassigned across unrelated services on the same host | | CVE Query Lock | cve_lookup queries must be derived from the exact product name and version string in the Evidence Block. Forbidden: host IP as query input; semantic pivots to adjacent software (Apache detected → do not query Log4j); famous CVEs introduced from background knowledge without confirmed product presence |

Skill-level reinforcement:

Each skill definition carries its own EVIDENCE DISCIPLINE: note scoped to its operational context:

• recon: report only scan output; no added versions or CVEs
• exploit: CVE candidates are hypotheses ("may be vulnerable — requires validation"), not confirmed matches
• analysis: TTP attribution uses conditional language only ("consistent with", "suggests")
• defense: remediation only for confirmed findings; no hypothetical patching
• reporting: verbatim Evidence Block excerpts in the Evidence field; severity and CVSS only from tool output

Reasoning block stripping

When reasoning-capable models (LM Studio / DeepSeek / QwQ) emit ... content, it is stripped at two independent points:

1. Storage layer (store.js — stripReasoning()): applied to fullContent before it is committed to the messages array. Stored messages and SQLite records never contain reasoning blocks.
2. Export layer (reportPdf.js): three-pass cleaning before HTML rendering — strip reasoning tags, discard content before `` marker, strip internal markers. Defense-in-depth for messages stored before the stripping was deployed.

---

LLM Integration

All providers implement a common BaseAdapter interface:

async def capabilities() -> dict
async def list_models() -> list[dict]
async def generate(messages, model, **kwargs) -> dict
async def stream(message

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [RamiBotAI](https://github.com/RamiBotAI)
- **Source:** [RamiBotAI/ramibot](https://github.com/RamiBotAI/ramibot)
- **License:** MIT
- **Homepage:** https://RamiBot.com

Install and usage instructions live in the source repository linked above.