Schrody/CariddiCTF
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Changed readme

Browse Source
This commit is contained in:
Schrody
2026-02-12 17:51:42 +01:00
parent a7d9c15d27
commit 28169f48bc
1 changed files with 52 additions and 269 deletions
Download Patch File Download Diff File Expand all files Collapse all files

321
README.md
View File

@@ -1,353 +1,136 @@
# Cariddi - MCP Client and Server
# Cariddi – MCP Client and Server
A complete MCP (Model Context Protocol) solution consisting of:
- **Cariddi Server**: A FastMCP server with filesystem tools for file operations and command execution
- **Cariddi Client**: A Python client that uses Ollama models for inference and connects to MCP servers, specialized as a Crypto Solver Agent for CTF challenges
## Project Structure
```
Cariddi/
├── mcpServer/ # MCP Server implementation
│ ├── main.py # FastMCP server entry point
│ ├── modules/
│ │ └── filesystem.py # Filesystem operation implementations
│ ├── requirements.txt
│ ├── Dockerfile
│ ├── docker-compose.yml
│ └── mcp.json # MCP server configuration
├── mcpClient/ # MCP Client with Ollama
│ ├── mcpClient.py # Main client implementation
│ └── requirements.txt
└── challs/ # CTF challenges
└── cryptoEasy/
├── challenge.py
└── cryptoeasy.txt
```
Complete MCP (Model Context Protocol) stack for CTF and reverse engineering workflows:
---
## Cariddi Server
A FastMCP server that provides filesystem tools for file operations, command execution, and Python file writing with proper handling of escape characters.
FastMCP server exposing filesystem and execution tools, with correct handling of escape characters when writing Python files.
### Server Setup
### Setup
1. Navigate to the server directory:
```bash
cd Cariddi
```
2. Create and activate virtual environment:
```bash
python3 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
```
3. Install dependencies:
```bash
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r requirements.txt
```
### Running the Server
### Run
```bash
source venv/bin/activate # On Windows: venv\Scripts\activate
source venv/bin/activate
python main.py
```
The server will start on `http://0.0.0.0:8000/mcp` with streamable-http transport.
Server listens on `http://0.0.0.0:8000/mcp` (streamable HTTP).
### Environment Variables
### Environment
- `FASTMCP_HOST` or `MCP_HOST`: Server host (default: `0.0.0.0`)
- `FASTMCP_PORT` or `MCP_PORT`: Server port (default: `8000`)
- `FASTMCP_HOST` / `MCP_HOST`: host (default `0.0.0.0`)
- `FASTMCP_PORT` / `MCP_PORT`: port (default `8000`)
### Using MCP Inspector
### MCP Inspector
The MCP Inspector is a visual tool for testing and debugging MCP servers.
With the server running:
#### Install and Run Inspector
1. Make sure your server is running (see above)
2. Run the inspector to connect to your server:
```bash
npx @modelcontextprotocol/inspector --url http://localhost:8000/mcp
```
The inspector will open in your browser (typically at `http://localhost:5173`).
Use transport **Streamable HTTP** and URL `http://localhost:8000/mcp`.
#### Alternative: Run Inspector with Server
Or run inspector and server together:
You can also run the inspector and server together:
```bash
npx @modelcontextprotocol/inspector python main.py
```
#### Setup MCP Inspector
Use "Streamable HTTP"
With Compose:
URL: `http://localhost:8000/mcp`
and press connect.
### Docker Deployment
#### Build and Run with Docker
1. Navigate to the server directory:
```bash
cd Cariddi
```
2. Build the Docker image:
```bash
docker build -t cariddi-mcp-server .
```
3. Run the container:
```bash
docker run -d -p 8000:8000 --name cariddi-mcp cariddi-mcp-server
```
#### Using Docker Compose
1. Navigate to the server directory:
```bash
cd Cariddi
```
2. Start the server:
```bash
docker-compose up -d
```
3. View logs:
```bash
docker-compose logs -f
```
4. Stop the server:
```bash
docker-compose down
```
The server will be accessible at `http://localhost:8000/mcp` from your host machine.
### Server Tools
The server provides the following tools:
- **`listFiles(path: str)`** - List all files in the given path
- **`readFile(path: str)`** - Read the contents of a file
- **`writeFile(path: str, content: str)`** - Write contents to a file
- **`executeCommand(command: str)`** - Execute a shell command and return stdout, stderr, and return code
- **`writePythonFile(path: str, content: str)`** - Write a Python file handling streaming and escape characters correctly (handles code blocks and unicode escapes)
---
## Cariddi Client
A Python MCP client that uses Ollama models for inference. The client is specialized as a **Crypto Solver Agent** for CTF (Capture The Flag) challenges, capable of identifying, analyzing, and solving cryptographic challenges.
Python MCP client that talks to Ollama and connects to MCP servers. Configured as a **Crypto Solver Agent** for CTF crypto challenges.
### Client Requirements
### Requirements
- Python 3.7+
- Ollama installed and running (see https://ollama.ai/)
- [Ollama](https://ollama.ai/) installed and running
### Client Installation
### Install
1. Navigate to the client directory:
```bash
cd CariddiClient
```
2. Install Python dependencies:
```bash
pip install -r requirements.txt
```
3. Make sure Ollama is running:
```bash
ollama serve
ollama pull ministral-3 # or llama3.2
```
4. Pull a model (if you haven't already):
```bash
ollama pull ministral-3
# or
ollama pull llama3.2
```
### Usage
### Client Usage
#### List available models
```bash
# List models
python mcpClient.py --list-models
```
#### Send a single prompt
```bash
# Single prompt
python mcpClient.py --prompt "What is the capital of France?"
```
#### Interactive mode
```bash
# Interactive
python mcpClient.py --interactive
```
#### Custom Ollama URL and model
```bash
# Custom Ollama and model
python mcpClient.py --base-url http://localhost:11434 --model ministral-3 --prompt "Hello!"
```
#### Connect to MCP server (streamable HTTP)
```bash
# Connect to MCP server via streamable HTTP
# Connect to MCP server (streamable HTTP)
python mcpClient.py --mcp-server "http://localhost:8000/mcp" --prompt "Use tools to help me"
python mcpClient.py --mcp-server "http://localhost:8000/mcp" --interactive
# With authentication headers
# With auth headers
python mcpClient.py --mcp-server "http://localhost:8000/mcp" --mcp-headers '{"Authorization": "Bearer token"}' --interactive
```
### Client Examples
### Defaults
```bash
# Simple question
python mcpClient.py --prompt "Explain quantum computing in simple terms"
# Interactive chat
python mcpClient.py -i
# Use a different model
python mcpClient.py --model mistral --prompt "Write a haiku about coding"
```
### Client Features
- Connects to local or remote Ollama instances
- Supports chat and generation modes
- **Connect to MCP servers** and use their tools automatically
- Tool registration for extensibility
- Interactive and non-interactive modes
- Health checking for Ollama server
- Automatic tool calling from MCP server tools
- **Specialized Crypto Solver Agent** with built-in knowledge for CTF challenges
- Ollama: `http://localhost:11434`
- Model: `ministral-3`
- MCP Server: `http://localhost:8000/mcp`
### Crypto Solver Agent
The client is configured as a specialized Crypto Solver Agent that:
The client is tuned to:
1. **Exploration**: Lists files in `/tmp` directory to identify relevant challenge files
2. **Analysis**: Identifies cryptographic schemes (RSA, AES, DES, XOR, etc.) and vulnerabilities
3. **Execution**: Writes and executes Python scripts to solve challenges
4. **Validation**: Searches for flags in the format `flag{...}`
1. **Explore**: List files (e.g. in `/tmp`) to find challenge files.
2. **Analyze**: Recognize crypto (RSA, AES, DES, XOR, encodings) and typical weaknesses.
3. **Execute**: Write and run Python scripts to recover keys or plaintext.
4. **Validate**: Look for flags in the form `flag{...}`.
The agent can handle:
- **RSA**: Small modulus factorization, low public exponent attacks, Wiener attack, Hastad attack, common modulus attacks
- **Symmetric Encryption**: AES/DES with various modes (ECB, CBC), IV vulnerabilities, key reuse
- **Classical Ciphers**: Frequency analysis, fixed-key attacks
- **Encoding**: Base64, Hex, Big-Endian/Little-Endian conversions
Covered areas: RSA (small modulus, low exponent, Wiener, Hastad, common modulus), symmetric (AES/DES, ECB/CBC, IV/key reuse), classical ciphers, Base64/Hex/endianness.
### Connecting to an MCP Server
The client uses **FastMCP** to connect to an existing MCP server via **streamable HTTP**. Once connected, the client:
1. Automatically loads available tools from the MCP server
2. Passes them to Ollama as usable tools
3. Executes tools when requested by the model
4. Returns results to the model to continue the conversation
#### Example with MCP Server
```bash
# Connect to an MCP server via streamable HTTP
python mcpClient.py --mcp-server "http://localhost:8000/mcp" --interactive
# With authentication headers
python mcpClient.py --mcp-server "http://localhost:8000/mcp" --mcp-headers '{"Authorization": "Bearer your-token"}' --prompt "Use your tools"
```
### Default Configuration
- **Default Ollama URL**: `http://localhost:11434`
- **Default Model**: `ministral-3`
- **Default MCP Server**: `http://localhost:8000/mcp`
---
## Complete Workflow Example
### 1. Start the MCP Server
```bash
cd Cariddi
python main.py
```
The server will start on `http://localhost:8000/mcp`.
### 2. Run the Client and Connect to the Server
In another terminal:
```bash
cd CariddiClient
python mcpClient.py --mcp-server "http://localhost:8000/mcp" --interactive
```
### 3. Use the Crypto Solver Agent
The client will automatically discover and use the server's tools (like `listFiles`, `readFile`, `writeFile`, `executeCommand`, `writePythonFile`) through Ollama. You can ask it to solve CTF challenges:
```
You: Analyze the files in /tmp and solve the crypto challenge
```
The agent will:
- List files in `/tmp`
- Read relevant files
- Analyze the cryptographic scheme
- Write and execute Python scripts to solve the challenge
- Return the flag
---
## CTF Challenges
The `challs/` directory contains CTF challenges for testing the Crypto Solver Agent:
- **cryptoEasy**: A Diffie-Hellman based challenge with AES encryption
- **cryptoEasy**: Diffie–Hellman + AES encryption challenge (in `challs/cryptoEasy/`).
---
## Development
## Candidate MCP Servers
### Server Development
Other MCP servers you can combine with Cariddi or use in similar workflows (reverse engineering, binary analysis, malware analysis, shell execution):
The server is built using FastMCP and provides filesystem operations. To add new tools:
| Project | Description |
|--------|-------------|
| [radare2-mcp](https://github.com/radareorg/radare2-mcp) | MCP stdio server for radare2 – binary analysis with r2, r2pipe, optional raw r2 commands. |
| [headless-ida-mcp-server](https://github.com/cnitlrt/headless-ida-mcp-server) | Headless IDA Pro MCP server – analyze binaries via IDA’s headless mode (idat). |
| [MalwareAnalyzerMCP](https://github.com/abdessamad-elamrani/malwareanalyzermcp) | MCP server for malware analysis – `file`, `strings`, `hexdump`, `objdump`, `xxd`, shell commands with timeouts. |
| [GhidrAssistMCP](https://github.com/jtang613/ghidrassistmcp) | Ghidra MCP extension – 34 tools, resources, prompts for reverse engineering (decompile, xrefs, structs, etc.). |
| [shell-exec-mcp](https://github.com/domdomegg/shell-exec-mcp) | MCP server for shell command execution – run bash commands with optional timeout and background jobs. |
| [ida-pro-mcp](https://github.com/mrexodia/ida-pro-mcp) | IDA Pro MCP bridge – AI-assisted reversing in IDA (decompile, disasm, xrefs, types, debugger extension). |
1. Implement the tool function in `modules/filesystem.py`
2. Register it as an MCP tool in `main.py` using `@mcpServer.tool()`
### Client Development
The client uses FastMCP for server communication and Ollama for inference. To modify the agent's behavior:
1. Edit the system prompt in `mcpClient.py` (line 248)
2. Add custom tools using `registerTool()` method
3. Modify the tool execution logic in `_executeTool()` method
---
## License
[Add your license information here]
---
## Contributing
[Add contributing guidelines here]
---