secure-mcp
joemunene-by/secure-mcp
MCP server exposing security tools to AI agents with policy gates, subprocess sandboxing, and audit trails.
Instalação
npx convez-ai joemunene-by/secure-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
secure-mcp
An MCP server that exposes security tools to AI agents — with policy gates, sandboxing, and audit trails.
Drop it into Claude Desktop, Cursor, or any MCP-compatible client and give your agent a constrained security toolbox. Every call is checked against a YAML policy, run in a sandboxed subprocess when relevant, and written to an append-only audit log.
Authorized use only. These tools can probe, scan, and fingerprint systems. Only point them at targets you own or have explicit written permission to test. The default policy is intentionally strict (private networks + localhost only). Change it deliberately.
Why
LLM agents with raw tool access are a liability. They can scan arbitrary hosts, exfiltrate files, or chain tools in unintended ways. secure-mcp puts a thin but real control plane between the model and the tools:
| Concern | How secure-mcp addresses it |
|---|---|
| Agent scans arbitrary IPs | target_allowlist per tool (CIDR + wildcard matching) |
| Agent spams tools | Per-tool rate limits (sliding window) |
| Tool hangs or floods output | Subprocess sandbox with timeout + output cap |
| "What did the agent do?" | Append-only JSONL audit log for every call |
| Hidden capability expansion | All tools are opt-in in policy; disable any with one line |
The policy is the source of truth. The LLM can't bypass what the runtime won't execute.
What's included
Five curated tools, each a clean reimplementation with no heavyweight dependencies:
| Tool | Purpose | Policy checks |
|---|---|---|
sec_port_scan | Async TCP connect scan | target allowlist, max_ports, rate limit |
sec_dns_lookup | A/AAAA resolution via stdlib | target allowlist, rate limit |
sec_metadata_scrub | Strip EXIF (JPEG) / tEXt (PNG) | rate limit |
sec_vuln_scan | Static secret/anti-pattern scan of a source tree | target allowlist (paths), rate limit |
sec_file_hash | md5/sha1/sha256/sha512/blake2b over a file | rate limit |
Quickstart
git clone https://github.com/joemunene-by/secure-mcp.git
cd secure-mcp
pip install -e .
# Sanity check
pytest -q
# Start the MCP server (stdio transport)
python -m secure_mcp.server
Wire into Claude Desktop
Add examples/claude_desktop_config.json to your Claude Desktop config (update absolute paths):
{
"mcpServers": {
"secure-mcp": {
"command": "python",
"args": ["-m", "secure_mcp.server"],
"env": {
"SECURE_MCP_POLICY": "/absolute/path/to/secure-mcp/policies/default.yaml",
"SECURE_MCP_AUDIT": "/absolute/path/to/secure-mcp/audit.jsonl",
"PYTHONPATH": "/absolute/path/to/secure-mcp/src"
}
}
}
}
Restart Claude Desktop. The five sec_* tools appear in the tools panel.
Policy
Policy lives in policies/default.yaml. Example:
tools:
port_scan:
enabled: true
target_allowlist:
- "127.0.0.1"
- "10.0.0.0/8"
max_ports: 100
rate_limit:
per_minute: 10
target_allowlistsupports IPv4/IPv6, CIDR (10.0.0.0/8), and suffix wildcards (*.example.com).*matches everything — use sparingly.- An empty or missing
target_allowlistfor a target-requiring tool denies all targets. Fail closed. - Point
SECURE_MCP_POLICYat a different file to run multiple profiles (lab vs. prod-safe).
Audit log
Every tool call writes one JSON object per line to audit.jsonl:
{"ts":"2026-04-17T18:42:11+00:00","pid":1234,"tool":"port_scan","args":{"host":"127.0.0.1","ports":[22,80]},"outcome":"ok"}
{"ts":"2026-04-17T18:42:14+00:00","pid":1234,"tool":"port_scan","args":{"host":"8.8.8.8","ports":[22]},"outcome":"denied","detail":"policy: target '8.8.8.8' is not permitted for tool 'port_scan'"}
Outcomes: ok, denied (policy), error (execution). Tail with jq -c for a live view.
Architecture
LLM / Agent
│ (MCP protocol)
▼
┌───────────────────────┐
│ FastMCP server │ src/secure_mcp/server.py
│ ├─ policy guard │ src/secure_mcp/policy.py
│ ├─ sandbox runner │ src/secure_mcp/sandbox.py
│ └─ audit logger │ src/secure_mcp/audit.py
└───────────────────────┘
│
▼
Tool implementations src/secure_mcp/tools/
Each tool is gated by _guard(name, target?) → check_enabled → check_target → check_rate_limit. Violations raise PolicyViolation and are logged as denied without executing.
Roadmap
v0.2— Docker-based sandbox profile, MCP resources for audit log tail, expanded tool set (traffic capture, TLS inspection).v0.3— Policy DSL: per-role allowlists, time-of-day gates, cost budgets.v0.4— Web dashboard for audit log + policy editing.
Related projects
Built by @joemunene-by. Companion repos:
ghostguard— policy-pipeline proxy for LLM tool callsghostsiem— SIGMA-based detection and alertingghostforensics— memory forensics automation
License
MIT. See LICENSE.