Skip to content
Back to search

agent-safeguard

MarketplaceWorks with Claude CodeGitHub

Supply-chain guardrails for Claude Code

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/gitgitgetitgrl--agent-safeguard-gate/badge.svg)](/listings/gitgitgetitgrl--agent-safeguard-gate)

HTML

<a href="/listings/gitgitgetitgrl--agent-safeguard-gate"><img src="/api/listings/gitgitgetitgrl--agent-safeguard-gate/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

From Claude Code, in your terminal:

claude plugin marketplace add gitgitgetitgrl/agent-safeguard-gate
claude plugin install agent-safeguard-gate@agent-safeguard

Or inside a Claude Code session: `/plugin install agent-safeguard-gate --marketplace gitgitgetitgrl/agent-safeguard-gate`.

Then restart Claude Code (or run `/reload-plugins`). The hook is active as soon as the plugin is enabled.

Check that it works

In a scratch folder, ask Claude to install an old package version with a known vulnerability, for example `npm install lodash@4.17.20 --ignore-scripts`. Before anything installs, you should get a prompt whose reason starts with `agent-safeguard-gate:` and lists the vulnerabilities. Decline it.

Optional: block Claude from reading credential files

This plugin never changes your Claude Code settings. If you also want Claude Code to refuse to read common credential files, add these rules yourself under `permissions.deny` in `~/.claude/settings.json`:

{
  "permissions": {
    "deny": [
      "Read(~/.aws/credentials)",
      "Read(~/.ssh/id_*)",
      "Read(~/.config/gcloud/**)",
      "Read(~/.docker/config.json)",
      "Read(~/.npmrc)",
      "Read(~/.pypirc)",
      "Read(~/.git-credentials)",
      "Read(~/.kube/config)"
    ]
  }
}

If the file already has a `permissions` section, add the rules to its existing `deny` list.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 19 lines
  1. {
  2. "name": "agent-safeguard",
  3. "description": "Supply-chain guardrails for Claude Code",
  4. "owner": {
  5. "name": "gitgitgetitgrl"
  6. },
  7. "plugins": [
  8. {
  9. "name": "agent-safeguard-gate",
  10. "source": "./",
  11. "description": "Always-on guardrail for Claude Code that blocks risky package installs, pipe-to-shell downloads, credential leaks and unsafe CI edits before they run."
  12. },
  13. {
  14. "name": "agent-safeguard-lite",
  15. "source": "./lite",
  16. "description": "Instructions-only edition: teaches Claude to vet packages, downloads and repos before trusting them. No hooks or scripts, so it also works in claude.ai chat."
  17. }
  18. ]
  19. }
README.md · README · 144 lines · 1 finding marked
  1. # Agent Safeguard Gate
  2. **Agent Safeguard Gate** is a Claude Code plugin that checks Claude's actions before they happen. When Claude is about to install a package, download and run a script, edit a GitHub Actions workflow, or write a file, the plugin checks it first. Anything known to be malicious is blocked. Anything risky, like a package with known vulnerabilities or a download piped straight into a shell, pauses so you decide. It never approves anything on its own.
  3. It also adds a skill that scans a repo for vulnerable dependencies, leaked secrets and weak CI settings, then fixes only what you approve. It runs on the Python standard library, so there's nothing extra to install, and it sends only package names and versions to public vulnerability databases.
  4. ## Requirements
  5. | Need | Why |
  6. |---|---|
  7. | **Claude Code v2.1.295 or later** (terminal, desktop app, or IDE), or **Cowork** | The hook fails closed (blocks) if it crashes, which needs this version |
  8. | **Python 3.9 or later** on your `PATH` as `python3` | The hook and scanner are Python scripts. Python 3.11+ is needed to read poetry/uv lockfiles |
  9. | **macOS or Linux** | Windows is untested. The hook calls `python3`, which often doesn't exist on Windows |
  10. | Optional: [`osv-scanner`](https://google.github.io/osv-scanner/) | Lets the scanner also check `pnpm-lock.yaml` and `yarn.lock`. On a Mac: `brew install osv-scanner` |
  11. **Where it works:** the always-on hook runs in Claude Code and Cowork. In claude.ai chat, only the scan skill loads, because chat doesn't run plugin hooks.
  12. **Lite edition:** [`lite/`](lite/) holds **Agent Safeguard Lite**, an instructions-only version with no hooks or scripts. It works everywhere, including claude.ai chat, but relies on Claude following its checklists instead of blocking anything automatically. Install it with `claude plugin install agent-safeguard-lite@agent-safeguard` after adding the marketplace below.
  13. ## Install
  14. From Claude Code, in your terminal:
  15. ```bash
  16. claude plugin marketplace add gitgitgetitgrl/agent-safeguard-gate
  17. claude plugin install agent-safeguard-gate@agent-safeguard
  18. ```
  19. Or inside a Claude Code session: `/plugin install agent-safeguard-gate --marketplace gitgitgetitgrl/agent-safeguard-gate`.
  20. Then restart Claude Code (or run `/reload-plugins`). The hook is active as soon as the plugin is enabled.
  21. ### Check that it works
  22. In a scratch folder, ask Claude to install an old package version with a known vulnerability, for example `npm install lodash@4.17.20 --ignore-scripts`. Before anything installs, you should get a prompt whose reason starts with `agent-safeguard-gate:` and lists the vulnerabilities. Decline it.
  23. ### Optional: block Claude from reading credential files
  24. This plugin never changes your Claude Code settings. If you also want Claude Code to refuse to read common credential files, add these rules yourself under `permissions.deny` in `~/.claude/settings.json`:
  25. ```json
  26. {
  27. "permissions": {
  28. "deny": [
  29. "Read(~/.aws/credentials)",
  30. "Read(~/.ssh/id_*)",
  31. "Read(~/.config/gcloud/**)",
  32. "Read(~/.docker/config.json)",
  33. "Read(~/.npmrc)",
  34. "Read(~/.pypirc)",
  35. "Read(~/.git-credentials)",
  36. "Read(~/.kube/config)"
  37. ]
  38. }
  39. }
  40. ```
  41. If the file already has a `permissions` section, add the rules to its existing `deny` list.
  42. ## Use
  43. - **Scan a repo:** ask Claude to "scan this repo with agent-safeguard-gate". It writes a report to `<repo>/.security-gate/`, explains the findings and lists fix IDs. Claude applies only the fixes you approve, and backs up every file it changes.
  44. - **Install packages as usual.** The hook checks each package against OSV (known vulnerabilities and OpenSSF `MAL-` malicious-package records) and against the registry before the install command runs.
  45. - **In CI:** `python3 scripts/scan.py <repo> --fail-on high` exits with 1 when it finds anything at or above that level.
  46. ## What the hook decides
  47. | Action | Decision |
  48. |---|---|
  49. | Install a package flagged `MAL-` in OSV, or one on your IOC blocklist | deny |
  50. | curl/wget piped into sh/bash/python/node, `bash <(curl …)` | deny |
    • Note: Runs a downloaded script through process substitution (bash <(curl …))
    • Line 71 on GitHub
  51. | Read credential files + network tool in one command; `env` piped to curl/nc | deny |
  52. | pip `--trusted-host` or an `http://` index | deny |
  53. | Checkout or merge of a branch on your IOC blocklist | deny |
  54. | Workflow: `pull_request_target` + PR head checkout, `${{ github.event.*.title/body }}` injection, secrets piped to network | deny |
  55. | Writing a live-looking secret into source code | deny |
  56. | Install with known vulns, a nonexistent package name, lifecycle scripts enabled, no lockfile, URL/git sources, `--extra-index-url`, requirements without `--require-hashes` | ask |
  57. | `npx`/`pnpm dlx`/`uvx`/`pipx run`, download + `chmod +x`, raw-IP downloads | ask |
  58. | Workflow actions not SHA-pinned, `write-all`, no `permissions:` block | ask |
  59. | Writes to `.bashrc`/`.zshrc`, git hooks, LaunchAgents, cron, `authorized_keys`, Claude settings | ask |
  60. | Network failure during verification | ask (never silently allow) |
  61. "Ask" hands the decision to you. Nothing is ever approved automatically.
  62. ## Fixes available (approval required, backups kept)
  63. | Fix | What it changes |
  64. |---|---|
  65. | `npmrc-ignore-scripts` | Sets `ignore-scripts=true` in the project `.npmrc` |
  66. | `pin-actions` | Pins workflow actions to commit SHAs via `git ls-remote`, keeping a `# tag` comment |
  67. | `add-permissions` | Adds top-level `permissions: contents: read` to workflows |
  68. | `pip-pin` | Bumps a vulnerable `requirements*.txt` pin to the highest fixed version OSV lists |
  69. | `npm-upgrade` | Runs `npm install pkg@fixed --package-lock-only --ignore-scripts` in the scanned project |
  70. | `gitignore-env` | Adds `.env` patterns to `.gitignore` |
  71. ## What it runs, sends and stores
  72. - **Network requests from the hook:** `https://api.osv.dev` (vulnerability lookups), `https://registry.npmjs.org` and `https://pypi.org` (to confirm a package exists and find its latest version). Only package names and versions are sent, never file contents, commands or secrets.
  73. - **Network requests from the scanner and fixes, only when you run them:** the same OSV lookups for the scanned project's dependencies. `pin-actions` runs `git ls-remote` against `https://github.com/<owner>/<repo>` for each workflow action. If you have the GitHub CLI (`gh`) installed, the scan runs `gh pr list` on the scanned repo with your own `gh` login to look for blocklisted PR titles. If `osv-scanner` is installed, the scan runs it on the project.
  74. - **Commands it runs locally:** `git` (read-only: refs, log, file list) in the scanned repo. The `npm-upgrade` fix runs `npm install … --package-lock-only --ignore-scripts`, only after you approve that fix.
  75. - **Files it writes:** a decision log at `~/.security-gate/decisions.jsonl` for every deny or ask decision, including the first 400 characters of the command or edit. Scan reports and backups go to `<repo>/.security-gate/`. Approved fixes edit the project files listed above. It never edits your Claude Code settings.
  76. - **Settings:** `SECURITY_GATE_TIMEOUT` (default 8 s per lookup) and `SECURITY_GATE_OFFLINE=1` (no network; every package check becomes `ask`).
  77. ## Your own blocklist
  78. The bundled list in `data/iocs.json` ships empty. Add indicators from security advisories you trust to `~/.security-gate/iocs.local.json`. That file is merged with the bundled list and survives plugin updates:
  79. ```json
  80. {
  81. "git_branches": [{"value": "evil-branch", "campaign": "example"}],
  82. "pr_titles": [{"value": "suspicious PR title", "campaign": "example"}],
  83. "blocked_packages": {"npm": [{"name": "bad-pkg", "version": "1.2.3"}], "PyPI": []},
  84. "blocked_domains": [{"value": "evil.example", "campaign": "example"}]
  85. }
  86. ```
  87. Leave out `version` to block every version of a package.
  88. ## Run the tests
  89. From a clone of this repository:
  90. ```bash
  91. python3 -m unittest discover -s tests
  92. ```
  93. The tests are offline. Network lookups are replaced with fake results.
  94. ## Limits
  95. - **Best-effort parsing.** It's a guardrail, not a sandbox. A determined attacker can disguise a shell command, for example by writing a downloader in inline Python. Use it alongside least-privilege tokens and normal review.
  96. - **False positives.** It matches command text. A command that mentions both a `.env` file and a URL is denied, even when it's harmless.
  97. - **Not covered:** `uv add` and `poetry add` aren't checked. pnpm and yarn lockfiles need `osv-scanner`.
  98. - **Version ranges.** For ranges like `^1.2.0`, the hook checks the latest published version, which is what npm/pip will most likely install.
  99. ## Uninstall
  100. ```bash
  101. claude plugin uninstall agent-safeguard-gate@agent-safeguard
  102. ```
  103. ## License
  104. MIT. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.