Skip to main content

Calchas

Black-box injection vulnerability detection for MCP (Model Context Protocol) servers.

Calchas connects to an MCP server over Streamable HTTP, reads its tools/list, and tests every tool parameter for server-side injection flaws — without source code, instrumentation, or knowledge of the server's implementation language. A finding is only confirmed when the server's response (or an out-of-band callback) shows that the injected payload was actually executed.

Supported vulnerability classes:

Class Example sink
Command injection subprocess(..., shell=True)
Argument injection user value reaching an argv option (git --upload-pack=...)
Path traversal file read/write outside the intended root
SSRF server-side fetch of an attacker-chosen URL
Code injection eval / template / expression evaluation

Authorized use only. calchas scan sends real attack payloads (command, path, SSRF and code payloads, file writes, out-of-band callbacks). Run it only against servers you own or are explicitly permitted to test.

How it works

  1. Semantic parameter classification — each parameter's name, description and JSON Schema are classified (rules + LLM) into the injection classes it may reach.
  2. Execution-guided sequence construction — tools that cannot be called standalone are brought into a callable state by an agent that builds the prerequisite call sequence from benign values.
  3. Execution-confirmation oracle — payloads are paired with benign controls and judged through in-band reflection, timing, cross-tool read-back and (optionally) out-of-band callbacks; only the difference between attack and control counts as evidence.

Install

Requires Python ≥ 3.11. curl must be on PATH when LLM features are used.

pipx install mcp-calchas      # recommended for a CLI tool (isolated environment)
# or
pip install mcp-calchas

The distribution is called mcp-calchas; the command and the Python package are calchas.

Quick start

# 1. Preview the attack surface only (no payloads sent)
calchas recon http://localhost:8080/mcp --no-llm-sink --no-agent --no-llm-plan

# 2. Full scan with an OpenAI-compatible LLM
export CALCHAS_LLM_API_KEY=sk-...
calchas scan http://localhost:8080/mcp \
    --llm-base-url https://api.openai.com/v1 --llm-model gpt-4o

Results are written to ./runs/<timestamp>__<server>/ in the current directory (runs/latest points to the most recent run). Change the location with -o DIR.

File Content
report.md human-readable report
findings.json machine-readable findings
catalog.json tools and parameters returned by tools/list
sinks.json per-parameter injection-class classification
events.jsonl full event log of the run

Re-render a report later with calchas report runs/latest/findings.json runs/latest/catalog.json.

Configuring the LLM

No model is bundled. LLM features (parameter classification, sequence agent, planning) need an OpenAI-compatible chat-completions endpoint, configured in one of three ways:

# command line (the key may also come from $CALCHAS_LLM_API_KEY)
calchas scan <url> --llm-base-url https://api.example.com/v1 --llm-api-key sk-... --llm-model my-model

# provider file, with automatic failover in listed order
calchas scan <url> --llm-config providers.json

# no LLM at all (rule-based classification, single-call plans)
calchas scan <url> --no-llm-sink --no-agent --no-llm-plan

--llm-base-url accepts either .../v1 or the full .../v1/chat/completions URL.

providers.json:

{
  "providers": [
    {"name": "primary", "base_url": "https://api.example.com/v1", "api_key": "env:MY_KEY", "model": "model-a"},
    {"name": "backup",  "base_url": "https://api.other.com/v1",   "api_key": "sk-...",     "model": "model-b"}
  ],
  "agent_provider": "primary"
}

"api_key": "env:VAR" reads the key from environment variable VAR. An optional "extra_body" object is merged into every request to that provider, for provider-specific switches — for example "extra_body": {"enable_thinking": false} turns off the default reasoning mode of Qwen3-series models.

Out-of-band (OOB) channel

Blind SSRF and blind command execution are confirmed by an out-of-band callback. The OOB channel is off by default; enable it by pointing Calchas at a collector the target can reach:

calchas scan <url> --oob-callback http://<collector-ip>:9100

The collector must record any request to /<token> and report hits as JSON at /__hits (override with --oob-query). A standard-library reference implementation is in the repository at deploy/infra/oob/collector.py. Without OOB, Calchas still detects and confirms through in-band reflection, timing and read-back channels.

Common options

Option Purpose
--header 'Authorization: Bearer ...' add HTTP headers (repeatable)
--tool NAME / --exclude-tool NAME limit which tools are tested
--sink command_injection limit which vulnerability classes are tested
--batch FILE --batch-name NAME scan many targets; writes batch_summary.md
--yes skip the interactive confirmation (needed for batch/CI)
--format json machine-readable console output

Run calchas scan --help for the full list.

Repository layout

Path Content
calchas/ the tool (the only code shipped in the PyPI package)
dev/ developer debugging scripts
deploy/ experiment infrastructure: batch-scan docker-compose cells, OOB collector, frozen batch records
dataset/ vulnerability-dataset pipeline (CVE/GHSA/OSV collection and labeling)
docs/, research_notes/ design notes and related-work surveys

Development

python3 -m venv .venv && .venv/bin/pip install -e .
.venv/bin/calchas selftest

License

Apache-2.0

Metadata

Release files for mcp-calchas 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mcp-calchas 0.1.0
File Size Uploaded Provenance Actions
mcp_calchas-0.1.0.tar.gz 105.2 kB Without provenance Details for mcp_calchas-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mcp-calchas 0.1.0
File Interpreter ABI Platform Actions
mcp_calchas-0.1.0-py3-none-any.whl Python 3 none any Details for mcp_calchas-0.1.0-py3-none-any.whl

Total release size: 224.8 kB

Release files / mcp_calchas-0.1.0.tar.gz

Download URL mcp_calchas-0.1.0.tar.gz
Size 105.2 kB
Tags Source
SHA-256 checksum
How to use checksums
641c7db027f0c73dcb7036fcc7c70cddc3c9314b52e19b0eb67ed649c2e8c846
BLAKE2b-256 checksum
How to use checksums
8e12d3c8b457227d63b78f6248f1ac4a2d237d2482b6100846e73eae6b78758c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.7

Release files / mcp_calchas-0.1.0-py3-none-any.whl

Download URL mcp_calchas-0.1.0-py3-none-any.whl
Size 119.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7c3f78cb30ecba6d608bb10c9dadea8818977dbe921edd28041271c2fdb02002
BLAKE2b-256 checksum
How to use checksums
00e9bce2e7ee77435322ef71e6f368b58c00001cfaaf0c8d15b937d5b61f2046
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.7

Security for mcp-calchas 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page