Fallback Runner MCP

MCP server để ChatGPT có thể dùng máy của bạn kiểm tra kết nối tới các target/server CTF hoặc lab.

Repo có 2 chế độ:

Basic: nhẹ, dùng để test/local, có tool kiểm tra kết nối và chạy solver Python pwn/web cơ bản.
Full / Advanced: cài thêm Docker runner images, phù hợp chạy trên VPS hoặc máy chủ cloud.

Tool Modes

Basic Mode

Basic là chế độ mặc định (ENABLE_ADVANCED_TOOLS=false). Không cần Docker image.

Tool basic:

health_check
get_capabilities
check_target_allowed
probe_target_from_runner
run_basic_python_solver

Dùng basic khi:

bạn chỉ muốn ChatGPT connect tới MCP server,
cần kiểm tra host/port từ mạng máy bạn,
cần chạy solver Python nhẹ cho pwn/web qua máy bạn,
đang test connector,
chạy trên laptop/local machine.

Basic Python packages:

requests
beautifulsoup4
lxml
pwntools
pycryptodome
z3-solver
sympy
gmpy2
websocket-client
websockets

run_basic_python_solver requires a target object (host and port). That target must be allowed by ALLOWED_TCP_TARGETS. The solver receives TARGET_HOST and TARGET_PORT in its environment.

Full / Advanced Mode

Full mode bật bằng ./scripts/install_advanced_tools.sh.

Tool advanced thêm:

get_runner_environments
run_solver_fallback
validate_run_request
upload_artifact
rerun_run
get_run_log
list_recent_runs
delete_run
get_run_stdout
get_run_stderr
tail_run_output
create_workspace
upload_file_to_workspace
list_workspace_files
read_workspace_file
delete_workspace
run_command

Full mode sẽ build các Docker image nặng:

ctf-python-runner:latest
ctf-pwn-runner:latest
ctf-sage-runner:latest
ctf-forensics-runner:latest

Important Note

For normal testing, ChatGPT connector setup, and lightweight pwn/web solving, install basic only:

./scripts/install_basic.sh

Install full/advanced only on a VPS or cloud server if you need containerized solver execution, Sage, forensics, or heavier isolated tooling. The full install downloads and builds large Docker images and can take a long time on a laptop.

Quick Start: Basic

cd /home/light/Workspace/agy/botquanganh_mcp
chmod +x scripts/*.sh
./scripts/install_basic.sh

Edit .env:

ENABLE_ADVANCED_TOOLS=false
ALLOWED_TCP_TARGETS=target.host:port
BLOCK_PRIVATE_IPS=true

Start MCP server with Cloudflare Tunnel:

./scripts/start_tunnel_server.sh

The script prints a public endpoint like:

https://xxxx.trycloudflare.com/mcp

Use that URL in ChatGPT MCP Connector settings.

ChatGPT Connector Setup

Run:
```
./scripts/start_tunnel_server.sh
```
Copy the printed URL ending in /mcp.
In ChatGPT, create/add an MCP connector.
Paste the URL, for example:
```
https://xxxx.trycloudflare.com/mcp
```
Test with:
```
health_check
```

In basic mode, ChatGPT should see exactly:

health_check
get_capabilities
check_target_allowed
probe_target_from_runner
run_basic_python_solver

Configure Allowed Targets

ALLOWED_TCP_TARGETS controls which host:port ChatGPT may probe through your machine.

Specific allowlist:

ALLOWED_TCP_TARGETS=socket.cryptohack.org:13418,example.com:443

Wildcard:

ALLOWED_TCP_TARGETS=*

Avoid * unless you understand the risk. This server uses your machine/network.

Recommended:

BLOCK_PRIVATE_IPS=true

This helps block localhost/private-network targets unless explicitly allowed for testing.

Full Install For VPS / Cloud Server

Use this only when you want ChatGPT to run solver scripts or shell commands inside isolated Docker containers.

cd /home/light/Workspace/agy/botquanganh_mcp
chmod +x scripts/*.sh
./scripts/install_advanced_tools.sh

After installation, restart the server:

./scripts/start_tunnel_server.sh

install_advanced_tools.sh will:

run basic install,
build all runner Docker images,
set ENABLE_ADVANCED_TOOLS=true in .env.

Manual Server Start

Without tunnel:

source .venv/bin/activate
PYTHONPATH=. python3 -m app.main

HTTP mode:

source .venv/bin/activate
PYTHONPATH=. fastmcp run app/main.py --transport http --port 8000 --host 127.0.0.1

Dev UI:

./scripts/dev.sh

Test

For local testing and lightweight pwn/web solving, basic install is enough:

./scripts/install_basic.sh
./scripts/test.sh

The test suite uses mocks for Docker paths, so it does not require full install just to validate code.

Project Layout

app/
  main.py              MCP entrypoint
  config.py            environment config
  security.py          allowlist and safety checks
  tools/
    health.py          basic health/capability tools
    probe.py           basic target connectivity probe
    basic_runner.py    basic Python pwn/web solver runner
    fallback.py        advanced solver runner tools
    workspace.py       advanced workspace tools
    runs.py            advanced run log tools
    shell.py           advanced container command tool
runner_images/         Dockerfiles for full install
scripts/
  install_basic.sh
  install_advanced_tools.sh
  start_tunnel_server.sh
  build_runner_images.sh
  test.sh
logs/                  runtime logs, ignored by git

Security Notes

Keep basic mode for laptop/local testing and lightweight pwn/web challenges.
Use full mode mainly on VPS/cloud servers with Docker.
Keep ALLOWED_TCP_TARGETS narrow when possible.
Keep BLOCK_PRIVATE_IPS=true unless you are intentionally testing local targets.
Full mode exposes more powerful tools, including container execution and file workspace operations.

MCP Servers