Gatekeeper

A security assessment layer for Claude skills and plugins.

Gatekeeper scans every skill and plugin before it enters your environment, decides whether it is safe, and — wired into your Git hooks and CI — blocks the ones that are not. It is the enforcement layer that turns "we should review new skills" into "unreviewed skills cannot get in."

Detection is grounded in the Gatekeeper Detection Methodology v1.0 and the OWASP Agentic AI Top 10, extended with enterprise controls for agent permissions, credential handling, and supply-chain integrity.

The problem

Traditional security tools scan code. The risk in an AI environment lives somewhere they do not look: in the natural-language instructions of a skill, in the permissions an agent is granted, in the provenance of a plugin or MCP server. A skill that quietly reads credentials, follows instructions from untrusted content, or grants an agent admin reach across systems is not a code vulnerability — and so it sails past conventional scanners. Gatekeeper exists to close that gap.

How it works

Gatekeeper has two layers.

1. Intelligence — what to look for. A scanning engine assesses each artefact against nine threat categories and produces a structured report with a clear verdict. It runs as fast, deterministic Python (no API key, milliseconds per file) and is mirrored by a Claude skill (skills/gatekeeper) for deeper, human-led semantic review.

2. Enforcement — making it mandatory at three points in the lifecycle.

| When | Mechanism | Bypassable? | |---|---|---| | Before install | Claude Code PreToolUse hook (ships in the plugin) intercepts the tool calls that bring an artefact in — writing a SKILL.md/manifest, or a shell git clone / npm install / /plugin install — and denies on BLOCK, asks on WARN. Other agents enforce via instruction files + the Gatekeeper MCP server. | Local, advisory | | Before commit | pre-commit hook scans staged artefacts and fails closed (a staged skill/plugin with no working gate refuses the commit). | Yes (--no-verify) | | Before merge | GitHub Actions / GitLab CI gate runs server-side on every push and PR. | No (required check) |

The before-install hook is the new piece that turns "the agent should scan first" into "the agent cannot write or install an unsafe artefact." The CI gate remains the one wall that cannot be skipped — make it a required check.

Each assessment ends in one of four decisions:

| Decision | Meaning | |---|---| | BLOCK | Rejected. Must be remediated and resubmitted. | | WARN | Held for a security owner to approve or reject. | | PASS WITH NOTES | Allowed; findings logged with remediation guidance. | | CLEAN PASS | No findings. |

What's in the box

gatekeeper/
├── .claude-plugin/
│   ├── plugin.json                      Claude Code plugin manifest (hooks, commands, skills, MCP)
│   └── marketplace.json                 Makes it installable via /plugin install
├── hooks/
│   ├── hooks.json                       Registers the PreToolUse gate with Claude Code
│   ├── gatekeeper_pretooluse.py         BEFORE-INSTALL gate: scans writes/installs, denies unsafe
│   └── pre-commit                       BEFORE-COMMIT gate (fails closed)
├── commands/gatekeeper-scan.md          /gatekeeper-scan slash command (plugin)
├── skills/
│   ├── gatekeeper/SKILL.md              Intelligence layer (semantic / human review)
│   └── gatekeeper-setup/SKILL.md        Interactive setup wizard
├── scripts/
│   ├── gatekeeper.py                    Orchestrator: detect type, decide, report
│   ├── scan_skill.py                    Skill (SKILL.md) scanner
│   ├── scan_plugin.py                   Plugin / MCP manifest scanner
│   ├── report_generator.py             Text + JSON report builder
│   └── gatekeeper_mcp.py                MCP server (gatekeeper_scan, gatekeeper_setup)
├── ci/{github-actions.yml, gitlab-ci.yml}   Server-side gate (the non-bypassable wall)
├── config/
│   ├── gatekeeper-config.json           Behaviour + known-vulnerable blocklist
│   ├── approved-sources.json            Trusted domains / servers / plugins
│   └── custom-rules.json                Your own rules, overrides, exclusions
├── .mcp.json                            Project-scoped MCP registration (Cursor, Cline, ...)
├── AGENTS.md / GEMINI.md                Instruction layer for Codex / Gemini / others
├── .cursor/rules/*.mdc                  Cursor rules · .github/copilot-instructions.md (Copilot)
├── .claude/{commands,skills}            Project-mode equivalents (when opened directly, not installed)
├── SYSTEM_PROMPT.md                     Paste-able reviewer prompt for any model
├── tests/                               Intentionally-vulnerable verification fixtures
├── examples/                            One clean skill, one flagged skill, a sample report
└── README.md / INSTALL.md / INTEGRATION.md

The tests/ and examples/ folders contain deliberately unsafe artefacts used to prove detection works. Exclude both from your live gate (see INSTALL.md).

Quick start

# 1. Place this folder in your repo (e.g. as .gatekeeper/)
cp -r gatekeeper .gatekeeper

# 2. Assess a single skill or plugin
python3 .gatekeeper/scripts/gatekeeper.py path/to/SKILL.md \
    --config .gatekeeper/config/gatekeeper-config.json

# 3. Prove detection works against the bundled fixtures (each should BLOCK)
python3 .gatekeeper/scripts/gatekeeper.py .gatekeeper/tests \
    --config .gatekeeper/config/gatekeeper-config.json

Exit codes: 0 allowed · 1 WARN (held) · 2 BLOCK. The hook and CI read these.

To turn on enforcement, follow INSTALL.md (hook + CI) and INTEGRATION.md (wiring into an existing repo).

Coding-agent compatibility

Gatekeeper enforces at whatever depth each host actually allows. It is honest about the difference between a hard gate and an instruction the agent is told to follow.

| Agent | Before-install enforcement | How it loads | |---|---|---| | Claude Code | Hard gate — PreToolUse hook denies unsafe writes/installs | setup.ps1 / setup.sh, or /plugin install from a local path | | GitHub Copilot CLI | Hard gate — preToolUse command hook (fail-closed; exit 2 denies) | setup.ps1 / setup.sh registers ~/.copilot/hooks/hooks.json; or commit .github/hooks/ in-repo | | OpenAI Codex CLI | Hard gate — PreToolUse hook (exit 2 + stderr denies) | setup.ps1 / setup.sh writes ~/.codex/hooks.json; or commit .codex/hooks.json in-repo | | Google Antigravity | Hard gate — plugin hook in ~/.gemini/config/plugins/gatekeeper/ | setup.ps1 / setup.sh installs the plugin and merges ~/.gemini/config/mcp_config.json | | Cursor | Instruction + MCP tool | .cursor/rules/*.mdc (always-apply) + .mcp.json | | Gemini CLI | Instruction + MCP tool | GEMINI.md + .mcp.json | | Cline / Roo / any MCP client | MCP tool (gatekeeper_scan) | .mcp.json | | Amp / Jules / generic AGENTS.md | Instruction | AGENTS.md | | Any model (custom GPT, paste-in) | Instruction | paste SYSTEM_PROMPT.md |

Every agent additionally gets the before-commit (pre-commit) and before-merge (CI) gates, which are language- and agent-agnostic.

Install across every detected coding agent (live before-install gate)

From the unzipped package root, run the bundled setup script. It detects every coding agent installed on this machine and registers Gatekeeper as a real plugin in each — wiring up the PreToolUse (or equivalent) hook, the gatekeeper_scan MCP tool, the slash command, and the engine skill.

# Windows (PowerShell)
.\setup.ps1

# macOS / Linux
./setup.sh

Supported agents (detected automatically; absent ones are skipped):

• Claude Code — installs into ~/.claude/plugins/gatekeeper/, registers the plugin in ~/.claude/settings.json.
• GitHub Copilot CLI — drops hooks.json (camelCase event names, flat output) into ~/.copilot/hooks/.
• OpenAI Codex CLI — drops hooks.json into ~/.codex/hooks.json and adds an [mcp_servers.gatekeeper] block to ~/.codex/config.toml.
• Google Antigravity — installs into ~/.gemini/config/plugins/gatekeeper/ and merges the MCP server into ~/.gemini/config/mcp_config.json.

From then on, an attempt to write a SKILL.md / manifest that fails the scan is denied, a WARN prompts for confirmation, and curl … | sh-style installers are blocked outright. The hook auto-detects the Python interpreter (python / python3 / py -3) and, if Python is missing, pauses for human confirmation rather than silently allowing — the gate is never silently disabled.

Pass -Mode repo (PowerShell) or --mode repo (bash) to also vendor the package into the current repository and install the before-commit and before-merge gates.

Wire it into an existing repo (all agents + CI)

Vendor the package and let the MCP gatekeeper_setup tool (or INSTALL.md) place the per-agent files, the pre-commit hook, and the CI gate:

cp -r gatekeeper .gatekeeper      # then follow INSTALL.md, or call the gatekeeper_setup MCP tool

Threat coverage

Nine categories, each with numbered detection rules (full detail in the methodology document):

1. Prompt Injection — attempts to override the agent's instructions or treat untrusted content as commands.
2. Insecure Tool Use — unvalidated command execution or unbounded tool scope.
3. Excessive Agency & Overprivilege — admin reach, multi-system access, or consequential action with no human gate.
4. Insufficient Sandboxing — environment-variable access, subprocess execution, unscoped file access.
5. Insecure Output Handling — AI output flowing into execution, queries, or rendering without validation.
6. Sensitive Data Exposure — credential-file access, secret leakage, over-broad data return.
7. Hidden Instructions & Obfuscation — encoded payloads, invisible or bidirectional control characters.
8. Supply Chain & Provenance — unverified sources, unpinned or known-vulnerable dependencies.
9. Unbounded Consumption — unbounded loops, calls, or input.

Configuration

Everything is tunable through JSON, no code changes required:

• gatekeeper-config.json — detection behaviour and the known-vulnerable package blocklist (a living list; add advisories as they publish).
• approved-sources.json — trusted domains (suppresses false positives) plus registries of reviewed servers and plugins.
• custom-rules.json — your own detection patterns, severity overrides, and the ability to disable built-in rules.

Honest limitations

Gatekeeper is a strong gate, not a silver bullet:

• The fast layer is static analysis — pattern and structure based. The Claude skill layer adds semantic depth, but neither replaces human judgement on a WARN.
• A local pre-commit hook can be bypassed with git commit --no-verify. That is a property of every Git hook; the server-side CI gate is the non-bypassable layer and must be a required check.
• The "sandbox" for assessment is an isolated behavioural evaluation, not a full container.
• The blocklist and approved-sources lists are only as current as you keep them. Treat them as living documents.

Used together — fast local feedback, mandatory server-side enforcement, and human review on WARN — these layers give defence in depth.

Documentation

• INSTALL.md — install the hook and the CI gate, step by step.
• INTEGRATION.md — wire Gatekeeper into an existing enterprise repository, with configuration guidance.
• Gatekeeper Detection Methodology v1.0 — the full specification of every rule, score, and decision.