[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-2016":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":8,"language":10,"languages":8,"totalLinesOfCode":8,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":15,"stars7d":16,"stars30d":17,"stars90d":15,"forks30d":15,"starsTrendScore":15,"compositeScore":18,"rankGlobal":8,"rankLanguage":8,"license":19,"archived":20,"fork":20,"defaultBranch":21,"hasWiki":20,"hasPages":20,"topics":22,"createdAt":8,"pushedAt":8,"updatedAt":23,"readmeContent":24,"aiSummary":25,"trendingCount":15,"starSnapshotCount":15,"syncStatus":13,"lastSyncTime":26,"discoverSource":27},2016,"claude-mcp-sentinel","soy-rafa\u002Fclaude-mcp-sentinel","soy-rafa",null,"https:\u002F\u002Fwww.youtube.com\u002F@So%C3%B1ar-IA","Python",164,22,2,6,0,5,23,4.09,"MIT License",false,"main",[],"2026-06-12 02:00:35","# MCP Sentinel\n\nSecurity agent for Claude Code and Cowork. **v2 blocks malicious tool calls in real time** — a PreToolUse hook stops credential exfiltration, known-bad domains (`giftshop.club` from the Postmark MCP backdoor is hardcoded), reverse shells, and `curl|bash` pipes before they execute. The v1 static scanner is still here: vulnerability database scanning, source integrity verification, and coherence analysis.\n\n**Author:** Rafael Tunón Sánchez ([@soy-rafa](https:\u002F\u002Fgithub.com\u002Fsoy-rafa))\n**License:** [MIT](.\u002FLICENSE)\n**Latest version:** 2.0 — April 2026 ([changelog](.\u002FCHANGELOG.md))\n\n---\n\n> ## ⚠️ Build the habit: always vet a skill or MCP before installing it\n>\n> The whole reason MCP Sentinel exists is that **skills and MCPs cannot be trusted by default**. 36% of public skills contain security flaws ([Snyk ToxicSkills 2025](https:\u002F\u002Fsnyk.io\u002Fblog\u002Ftoxicskills-malicious-ai-agent-skills-clawhub\u002F)) and supply-chain attacks like the Postmark MCP backdoor have already exfiltrated thousands of users' emails through a single line of code added in an update.\n>\n> So before you install **anything** — including this project — make it a habit to:\n>\n> - **Open Claude and ask it to review the files first.** A quick conversation explaining what you're about to install, asking what each file does, what permissions it needs, what network endpoints it touches, and whether the behaviour matches the stated purpose. If anything looks off, stop.\n> - **Check the official source.** Compare the files you have against the canonical repo. The git commit history is your timestamped record of authorship — a fork or a stranger's zip is not.\n> - **Read the diff on every update.** Yesterday's clean version doesn't guarantee today's is safe. The Postmark attack landed on version v1.0.16 after fifteen clean releases.\n>\n> MCP Sentinel automates the runtime side of this once it's installed — but **the install itself is on you**. Treat that habit as non-negotiable, every time, for every skill, every MCP, every update. That single behaviour is the biggest security upgrade you can give your AI workflow.\n\n---\n\n## Why\n\nThe AI skills ecosystem is growing fast — but so are the attacks. [Snyk's ToxicSkills study](https:\u002F\u002Fsnyk.io\u002Fblog\u002Ftoxicskills-malicious-ai-agent-skills-clawhub\u002F) found that **36% of skills contain security flaws**, including 76 with confirmed malicious payloads. And in September 2025 the [Postmark MCP incident](https:\u002F\u002Fthehackernews.com\u002F2025\u002F09\u002Ffirst-malicious-mcp-server-found.html) became the canonical supply-chain attack in this ecosystem: fifteen clean versions followed by a single-line update that silently BCC'd every outgoing email to `phan@giftshop.club`.\n\nStatic analysis of v1.0.15 would have found nothing — it was clean. That's the gap v2 closes.\n\n## What's new in v2 — Runtime blocking\n\nA **PreToolUse hook** runs before every tool call Claude makes. It inspects the call against a local IOC library plus your allowlist, then allows or blocks it:\n\n- **Sensitive paths** — reads of `~\u002F.ssh\u002F`, `~\u002F.aws\u002F`, `~\u002F.env`, `credentials.json`, `\u002Fetc\u002Fshadow` are blocked.\n- **Known-malicious domains** — hardcoded from confirmed incidents. `giftshop.club` is in there by default and cannot be allowlisted.\n- **Exfiltration services** — pastebin.com, transfer.sh, webhook.site, requestbin, ngrok, serveo, raw-IP URLs.\n- **Dangerous commands** — `curl … | bash`, `nc -e`, `bash -i >& \u002Fdev\u002Ftcp\u002F…`, base64 | curl chains, appends to `.bashrc`.\n- **Sensitive env vars** — `ANTHROPIC_API_KEY`, `AWS_SECRET_ACCESS_KEY`, `GITHUB_TOKEN`, `DATABASE_URL`, and the generic `*_API_KEY` \u002F `*_SECRET` \u002F `*_TOKEN` \u002F `*_PASSWORD` patterns.\n\n**Zero LLM cost.** Pure local Python (~30–80 ms per call). Only blocked calls add a short message to the conversation.\n\n**Fail-open.** Missing IOCs, malformed stdin, hook crash — all default to `allow`. The hook will never break Claude Code.\n\n**Whitelistable.** Legitimate false positives go in `.security\u002Fsentinel-allowlist.json` (project) or `~\u002F.claude\u002Fsentinel-allowlist.json` (global). Confirmed-malicious domains are not overrideable.\n\n## v1 — Static scanning (still included)\n\n**1. Threat intelligence scanning**\nChecks every installed skill and MCP server against 6 live databases maintained by the community: GitHub Advisory DB, vulnerablemcp.info, mcpscan.ai, Snyk, ClawHub\u002FVirusTotal, and Reddit r\u002FClaudeAI.\n\n**2. Source integrity verification**\nWhen you're about to install a skill, Sentinel finds the official original source and compares it against your copy. If someone took a trusted skill, injected malicious code, and redistributed it — Sentinel catches the difference.\n\n**3. Coherence analysis**\nAnalyzes whether everything a skill does matches its stated purpose. A token optimizer that tries to access your SSH keys? A markdown formatter that sends your credentials to an external server? Sentinel flags the mismatch and shows you exactly which actions belong and which don't.\n\n**4. Update diff detection**\nStores a snapshot of every installed skill. If an update changes something, Sentinel diffs it and runs coherence analysis on the new code. This catches supply chain attacks — when a trusted skill pushes a poisoned update.\n\n**5. Scheduled monitoring**\nRuns automatically every morning to re-scan everything. A skill that was safe yesterday might have a new CVE reported today.\n\n---\n\n## Installation — step by step\n\n### Requirements\n\n- Claude Code CLI **or** Claude desktop app with Cowork mode\n- Python 3.8+ (for the v2 runtime hook)\n- `jq` (for the install script — usually preinstalled on macOS, `apt install jq` on Linux)\n- Git (only if you want to clone the repo instead of downloading the zip)\n\nVerify with:\n\n```bash\npython3 --version\njq --version\n```\n\n### Method 1 — Install from the `.skill` file (recommended)\n\nThis is the easiest path and works for both Claude Code and Cowork.\n\n1. Go to the [Releases page](..\u002F..\u002Freleases) of this repo.\n2. Download `mcp-sentinel.skill` from the latest release.\n3. Double-click the `.skill` file. Your Claude app will prompt you to install it.\n4. Confirm in the install dialog.\n5. Enable the runtime hook (see \"Enable the v2 runtime hook\" below).\n\n### Method 2 — Clone the repo (for developers \u002F contributors)\n\n```bash\n# 1. Clone\ngit clone https:\u002F\u002Fgithub.com\u002Fsoy-rafa\u002Fclaude-mcp-sentinel.git\ncd claude-mcp-sentinel\n\n# 2. Install as a global skill\nmkdir -p ~\u002F.claude\u002Fskills\u002Fmcp-sentinel\ncp -R . ~\u002F.claude\u002Fskills\u002Fmcp-sentinel\u002F\n\n# 3. Or install only for the current project\nmkdir -p .claude\u002Fskills\u002Fmcp-sentinel\ncp -R . .claude\u002Fskills\u002Fmcp-sentinel\u002F\n```\n\n### Method 3 — Manual download (no git, no .skill file)\n\n1. Click the green **Code** button at the top of this repo → **Download ZIP**.\n2. Unzip it.\n3. Copy the unzipped folder into:\n   - `~\u002F.claude\u002Fskills\u002Fmcp-sentinel\u002F` — for global use across all projects\n   - `.claude\u002Fskills\u002Fmcp-sentinel\u002F` — for the current project only\n4. Continue with the runtime hook setup below.\n\n### Enable the v2 runtime hook\n\nThe hook is what gives you real-time blocking. **Without it, you only get the v1 static scanner.**\n\nFrom inside the `mcp-sentinel` folder:\n\n```bash\n# Globally (recommended) — runs on every project\nbash hooks\u002Finstall_hooks.sh --user\n\n# Or only for this project\nbash hooks\u002Finstall_hooks.sh --project\n```\n\nThe script:\n- Backs up your current `~\u002F.claude\u002Fsettings.json` (or `.claude\u002Fsettings.json` for `--project`) to `*.bak.\u003Ctimestamp>`\n- Adds the `PreToolUse` hook entry pointing to `sentinel_preflight.py`\n- Verifies Python and `jq` are available\n- Prints a confirmation with the installed path\n\n### Verify the install\n\n```bash\n# 1. Confirm the hook is registered\ncat ~\u002F.claude\u002Fsettings.json | jq '.hooks.PreToolUse'\n\n# 2. Run the regression suite\ncd ~\u002F.claude\u002Fskills\u002Fmcp-sentinel  # or wherever you installed it\npython3 -m pytest tests\u002Ftest_hook.py -v\n```\n\nYou should see **20 passed**. If anything fails, the install didn't go through cleanly — open an issue with the test output.\n\n### Uninstall\n\n```bash\nbash hooks\u002Funinstall_hooks.sh --user      # or --project\nrm -rf ~\u002F.claude\u002Fskills\u002Fmcp-sentinel      # or .claude\u002Fskills\u002Fmcp-sentinel\n```\n\nThe uninstall script restores your previous `settings.json` from the backup it made on install.\n\n---\n\n## Usage\n\nJust talk to Claude:\n\n- *\"Scan my project for security issues\"*\n- *\"Is this MCP server safe to install?\"*\n- *\"Check if this skill has been tampered with\"*\n- *\"Run a security audit\"*\n\nMCP Sentinel triggers automatically when it detects you're about to install something or when you mention security concerns.\n\n## How it works\n\nMCP Sentinel is a Claude skill — a `.md` file with structured instructions that tells Claude how to act as a security agent. The **v1 scanner** uses Claude's built-in tools (WebSearch, Read, Write, Bash, Glob, Grep) to scan files, search databases, and generate reports. No external dependencies, no API keys, no infrastructure.\n\nThe **v2 runtime hook** is a local Python script (`hooks\u002Fsentinel_preflight.py`) that Claude Code executes before every tool call. It reads the call on stdin, pattern-matches against the IOC library (`references\u002Fiocs.json`) plus your allowlist, and returns an allow\u002Fdeny decision on stdout. No LLM involvement, no network calls.\n\nAll analysis happens locally + public web searches (for v1 scanning). Your code and credentials never leave your machine.\n\n## Threat database\n\nSentinel maintains a local JSON database at `.security\u002Fmcp-sentinel-threats.json` that grows with each scan. It stores:\n\n- Inventory of installed skills\u002FMCPs with content snapshots\n- Known threats with CVE IDs and severity scores\n- Community alerts from Reddit and Discord\n- Change history for update diff detection\n- Structured threat reports compatible with future community sharing\n\n## Benchmarks\n\n### v1 static scan (5 scenarios: full audit, pre-install check, suspicious skill investigation, source integrity verification, coherence analysis)\n\n| | With MCP Sentinel | Without (baseline) |\n|---|---|---|\n| Detection rate | **100%** | 43–67% |\n| Source verification | Yes | No |\n| Coherence map | Yes | No |\n| Threat database | Yes | No |\n\n### v2 runtime hook (20 regression cases in `tests\u002Ftest_hook.py`)\n\n| Category | Cases | Result |\n|---|---|---|\n| Benign tool calls correctly allowed | 5 | ✅ 5\u002F5 |\n| Credential-harvesting attacks blocked | 4 | ✅ 4\u002F4 |\n| Network exfil blocked (incl. Postmark `giftshop.club` IOC) | 4 | ✅ 4\u002F4 |\n| Dangerous commands blocked (`curl\\|bash`, reverse shell, `.bashrc` hijack) | 4 | ✅ 4\u002F4 |\n| Fail-open on malformed \u002F empty input | 3 | ✅ 3\u002F3 |\n| **Total** | **20** | **✅ 20\u002F20** |\n\nOverhead: ~30–80 ms per tool call. Zero LLM tokens in normal operation.\n\n## Contributing\n\nFound a bug? Have an idea? Open an issue or PR. This is a community project.\n\n## Legal\n\n### License\n\nThis project is licensed under the [MIT License](.\u002FLICENSE). Copyright (c) 2026 Rafael Tunón Sánchez.\n\nYou are free to use, copy, modify, merge, publish, distribute, sublicense, and sell copies of this software, provided that the original copyright notice and this permission notice are included in all copies or substantial portions of the software.\n\n### Attribution\n\nIf you redistribute this project, in whole or in part, or create derivative works based on it, you must give appropriate credit to the original author. This includes:\n\n- Keeping the copyright notice in the LICENSE file intact\n- Mentioning the original project and author in any derivative work's documentation\n\n### Original work\n\nMCP Sentinel was conceived, designed, and developed by **Rafael Tunón Sánchez** in April 2026. The concept, architecture, skill instructions, coherence analysis methodology, update diff detection system, and threat database schema are original work by the author.\n\nThe full commit history of this repository serves as a public, timestamped record of authorship.\n\n### Disclaimer\n\nThis software is provided \"as is\", without warranty of any kind. MCP Sentinel is a security tool that helps detect potential threats, but it does not guarantee the detection of all vulnerabilities or malicious code. Users are responsible for their own security decisions. The author is not liable for any damages arising from the use of this software.\n\n### Trademarks\n\n\"MCP Sentinel\" is the project name chosen by the author. GitHub, Claude, Anthropic, Snyk, and other product names mentioned in this repository are trademarks of their respective owners.\n\n---\n\nBuilt with care by [@soy-rafa](https:\u002F\u002Fgithub.com\u002Fsoy-rafa)\n","MCP Sentinel 是一个用于Claude Code和Cowork的安全代理，旨在实时阻止恶意工具调用。其核心功能包括通过PreToolUse钩子在执行前拦截凭证泄露、已知恶意域名访问（如Postmark MCP后门中的`giftshop.club`）、反向shell以及`curl|bash`管道等行为。此外，它还保留了v1版本的静态扫描功能，支持漏洞数据库扫描、源代码完整性验证及一致性分析。该项目适用于需要增强AI技能或MCP安装安全性的场景，特别是面对日益增长的针对AI生态系统的攻击时，能够提供额外的安全保障层。","2026-06-11 02:47:36","CREATED_QUERY"]