{"id":51469291,"url":"https://github.com/joemunene-by/secure-mcp","last_synced_at":"2026-07-06T15:00:55.442Z","repository":{"id":364370757,"uuid":"1213657414","full_name":"joemunene-by/secure-mcp","owner":"joemunene-by","description":"MCP server exposing security tools to AI agents with policy gates, subprocess sandboxing, and audit trails.","archived":false,"fork":false,"pushed_at":"2026-06-12T18:30:16.000Z","size":44,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-12T20:15:44.485Z","etag":null,"topics":["ai-agents","ai-safety","audit-log","claude","llm-security","mcp","model-context-protocol","policy-enforcement","sandbox","security"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/joemunene-by.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-17T16:08:00.000Z","updated_at":"2026-06-12T18:28:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/joemunene-by/secure-mcp","commit_stats":null,"previous_names":["joemunene-by/secure-mcp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/joemunene-by/secure-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joemunene-by%2Fsecure-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joemunene-by%2Fsecure-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joemunene-by%2Fsecure-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joemunene-by%2Fsecure-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/joemunene-by","download_url":"https://codeload.github.com/joemunene-by/secure-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joemunene-by%2Fsecure-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35195590,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-06T02:00:07.184Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","ai-safety","audit-log","claude","llm-security","mcp","model-context-protocol","policy-enforcement","sandbox","security"],"created_at":"2026-07-06T15:00:54.586Z","updated_at":"2026-07-06T15:00:55.432Z","avatar_url":"https://github.com/joemunene-by.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# secure-mcp\n\n**An MCP server that exposes security tools to AI agents, with policy gates, sandboxing, and audit trails.**\n\nDrop it into Claude Desktop, Cursor, or any MCP-compatible client and give your agent a _constrained_ security toolbox.\nEvery call is checked against a YAML policy, run in a sandboxed subprocess when relevant, and written to an append-only audit log.\n\n![Python](https://img.shields.io/badge/python-3.10+-3776AB?style=flat-square\u0026logo=python\u0026logoColor=white)\n![MCP](https://img.shields.io/badge/MCP-1.0+-6C9CFF?style=flat-square)\n![License](https://img.shields.io/badge/license-MIT-green?style=flat-square)\n\n\u003c/div\u003e\n\n\u003e **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.\n\n---\n\n## Why\n\nLLM 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:\n\n| Concern | How `secure-mcp` addresses it |\n| --- | --- |\n| Agent scans arbitrary IPs | `target_allowlist` per tool (CIDR + wildcard matching) |\n| Agent spams tools | Per-tool rate limits (sliding window) |\n| Tool hangs or floods output | Subprocess sandbox with timeout + output cap |\n| \"What did the agent do?\" | Append-only JSONL audit log for every call |\n| Hidden capability expansion | All tools are opt-in in policy; disable any with one line |\n\nThe policy is the source of truth. The LLM can't bypass what the runtime won't execute.\n\n## What's included\n\nSeven curated tools, each a clean reimplementation with no heavyweight dependencies:\n\n| Tool | Purpose | Policy checks |\n| --- | --- | --- |\n| `sec_port_scan` | Async TCP connect scan | target allowlist, `max_ports`, rate limit |\n| `sec_dns_lookup` | A/AAAA resolution via stdlib | target allowlist, rate limit |\n| `sec_metadata_scrub` | Strip EXIF (JPEG) / tEXt (PNG) | rate limit |\n| `sec_vuln_scan` | Static secret/anti-pattern scan of a source tree | target allowlist (paths), rate limit |\n| `sec_file_hash` | md5/sha1/sha256/sha512/blake2b over a file | rate limit |\n| `sec_tls_inspect` | TLS cert summary: subject, issuer, SANs, expiry, protocol, cipher | target allowlist, rate limit |\n| `sec_http_headers` | Security header audit (HSTS, CSP, XFO, ...) with an A to F grade | target allowlist (URL hostname), rate limit |\n\nPlus one MCP resource: `audit://recent` exposes the last 50 audit entries, so the agent (and you, from the client) can review what was actually executed.\n\n## Quickstart\n\n```bash\ngit clone https://github.com/joemunene-by/secure-mcp.git\ncd secure-mcp\npip install -e .\n\n# Sanity check\npytest -q\n\n# Start the MCP server (stdio transport)\npython -m secure_mcp.server\n```\n\n### Wire into Claude Desktop\n\nAdd `examples/claude_desktop_config.json` to your Claude Desktop config (update absolute paths):\n\n```json\n{\n  \"mcpServers\": {\n    \"secure-mcp\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"secure_mcp.server\"],\n      \"env\": {\n        \"SECURE_MCP_POLICY\": \"/absolute/path/to/secure-mcp/policies/default.yaml\",\n        \"SECURE_MCP_AUDIT\": \"/absolute/path/to/secure-mcp/audit.jsonl\",\n        \"PYTHONPATH\": \"/absolute/path/to/secure-mcp/src\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop. The seven `sec_*` tools appear in the tools panel.\n\n## Policy\n\nPolicy lives in `policies/default.yaml`. Example:\n\n```yaml\ntools:\n  port_scan:\n    enabled: true\n    target_allowlist:\n      - \"127.0.0.1\"\n      - \"10.0.0.0/8\"\n    max_ports: 100\n    rate_limit:\n      per_minute: 10\n```\n\n- `target_allowlist` supports IPv4/IPv6, CIDR (`10.0.0.0/8`), suffix wildcards (`*.example.com`), and, new in 0.2, absolute directory paths (`/home/me/projects`) for filesystem tools like `vuln_scan`. Path entries match the directory and anything inside it, with `..` and symlinks resolved before matching. `*` matches everything, so use it sparingly.\n- An empty or missing `target_allowlist` for a target-requiring tool denies **all** targets. Fail closed.\n- Point `SECURE_MCP_POLICY` at a different file to run multiple profiles (lab vs. prod-safe).\n\n## Audit log\n\nEvery tool call writes one JSON object per line to `audit.jsonl`:\n\n```json\n{\"ts\":\"2026-04-17T18:42:11+00:00\",\"pid\":1234,\"tool\":\"port_scan\",\"args\":{\"host\":\"127.0.0.1\",\"ports\":[22,80]},\"outcome\":\"ok\"}\n{\"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'\"}\n```\n\nOutcomes: `ok`, `denied` (policy), `error` (execution). Tail with `jq -c` for a live view.\n\n## Architecture\n\n```\n  LLM / Agent\n      │  (MCP protocol)\n      ▼\n┌───────────────────────┐\n│  FastMCP server       │   src/secure_mcp/server.py\n│  ├─ policy guard      │   src/secure_mcp/policy.py\n│  ├─ sandbox runner    │   src/secure_mcp/sandbox.py\n│  └─ audit logger      │   src/secure_mcp/audit.py\n└───────────────────────┘\n      │\n      ▼\n  Tool implementations   src/secure_mcp/tools/\n```\n\nEach tool is gated by `_guard(name, target?)` → `check_enabled` → `check_target` → `check_rate_limit`. Violations raise `PolicyViolation` and are logged as `denied` without executing.\n\n## Roadmap\n\n- `v0.2` (shipped): MCP resource for the audit log tail, TLS inspection, HTTP security header audit, path allowlists.\n- `v0.3`: Docker-based sandbox profile, policy DSL with per-role allowlists, time-of-day gates, and cost budgets.\n- `v0.4`: Web dashboard for the audit log and policy editing, traffic capture tool.\n\n## Related projects\n\nBuilt by [@joemunene-by](https://github.com/joemunene-by). Companion repos:\n\n- [`ghostguard`](https://github.com/joemunene-by/ghostguard): policy-pipeline proxy for LLM tool calls\n- [`ghostsiem`](https://github.com/joemunene-by/ghostsiem): SIGMA-based detection and alerting\n- [`ghostforensics`](https://github.com/joemunene-by/ghostforensics): memory forensics automation\n\n## License\n\nMIT. See [LICENSE](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoemunene-by%2Fsecure-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjoemunene-by%2Fsecure-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoemunene-by%2Fsecure-mcp/lists"}