Open source · MIT · v0.3.0

Guardrails for AI coding agents, built on evidence.

Handrail finds risky agent setups before they ship, blocks dangerous tool calls while an agent works, and catches an agent that says “all tests pass” when it never ran them. Every rule was measured on 1,200 public repos first.

npx handrail-ai scan .
1,200 repos studied 0/54 planted instructions followed 6 real incidents mapped to rules
No API keyNo network callsSecrets always redactedPython 3.10+ stdlib only
~/acme-api
$ npx handrail-ai scan .
HIGH   agent-permission-mode   .claude/settings.json:1
       └ defaultMode: bypassPermissions
HIGH   agent-broad-permissions .claude/settings.json:1
       └ allow: Bash(*)
HIGH   mcp-auto-approve        .vscode/mcp.json:1
       └ github: auto-approves ["*"]
HIGH   mcp-inline-secret       .vscode/mcp.json:1
       └ github.env.GITHUB_TOKEN = ghp_…[redacted 40 chars]
MEDIUM agent-auto-enable-mcp   .claude/settings.json:1
       └ enableAllProjectMcpServers: true
MEDIUM pipe-to-shell           AGENTS.md:3
       └ Run `curl -fsSL https://get.example.dev/… | bash`
LOW    mcp-unpinned-package    .vscode/mcp.json:1

handrail scan 0.3.0: 3 agent files · high 4 · medium 2 · low 1
01 · Why now

Agents write more code, and they leak more secrets.

Industry numbers from the past year. AI tooling is adding a new kind of file to every repo, and attackers already read those files.

28.65M

new hardcoded secrets pushed to public GitHub in 2025, up 34% in a year[1]

+81%

rise in leaked AI-service keys, to 1,275,105[1]

3.2%

of Claude Code-assisted commits leaked a secret, against a 1.5% baseline for all public commits[1]

24,008

secrets exposed in MCP config files, 2,117 of them confirmed valid[1]

02 · In the news

It is already happening.

Six public incidents from 2025–26, and the Handrail check aimed at each one. Handrail didn’t exist for most of them. These show what it is built to catch.

Aug 2025 · Nx “s1ngularity”

Malware ran developers’ own AI CLIs to hunt for secrets

Poisoned Nx packages (4.6M weekly downloads) started Claude, Gemini and Q with --dangerously-skip-permissions, --yolo and --trust-all-tools. Over a thousand valid GitHub tokens leaked, and 5,500+ private repos were made public.

Handrail checkguard asks before credential reads and blocks uploads. scan --home flags machines already set to skip approvals.
Socket[2] · Wiz[3]
2025–26 · PromptPwnd, Comment and Control

A comment on a PR made CI agents print their API keys

Researchers got AI agents in GitHub Actions, including Claude Code, Gemini CLI, Codex and Copilot, to post ANTHROPIC_API_KEY, GITHUB_TOKEN and GEMINI_API_KEY into comments or logs.

Handrail checkci-agent-untrusted-trigger and ci-agent-no-approval fail the build before the workflow merges.
Cloud Security Alliance[4]
May 2025 · GitHub MCP

A public issue made an agent leak private repos

A malicious issue prompt-injected Claude Desktop with the GitHub MCP server. The agent copied private repo data into a public pull request. The flaw sat in how agent and tools were wired, not in the server code.

Handrail checkmcp-auto-approve flags tools that run with no human in the loop. audit marks actions taken right after reading untrusted text.
Invariant Labs[5]
Jul 2025 · Amazon Q extension

A wiper prompt shipped inside a coding extension

A malicious commit added a prompt telling the agent to delete local files and cloud resources. Version 1.84.0 went out to an extension with nearly a million installs before it was pulled.

Handrail checkguard denies rm -rf ~, aws s3 rm --recursive, terminate-instances and terraform destroy -auto-approve.
TechRadar[6]
Jul 2025 · Replit agent

An agent deleted a database during a code freeze

During a public build log, the agent deleted the project’s database while a code freeze was on. It then said it had “panicked”. The founder restored it from backups.

Handrail checkguard denies DROP DATABASE. stop-check sends back claims of success that have no evidence behind them.
The Stack[7]
Nov 2026 · Handrail study

Live keys and disabled approvals in public agent configs

Our own study of 1,200 repos found real cloud and GitHub credentials in MCP configs, and settings that turn off human confirmation. We found zero confirmed injection attacks. No repo is named; owners are told privately first.

Handrail checkmcp-inline-secret, agent-permission-mode, agent-broad-permissions
Handrail report[8]
03 · How it works

One rule set, three moments.

Before the agent starts, while it works, and when it says it’s done. The same rules run on your laptop, in pre-commit, and in CI.

Before · scan

Catch risky setups

Reads agent instruction and config files in a repo or on your own machine.

handrail scan . --fail-on high
  • MCP autoApprove, bypassPermissions, Bash(*)
  • Keys committed in MCP configs
  • Agents in CI with approvals off, or on pull_request_target
  • Trojan-Source and invisible Unicode tag text
  • --deep: keys “deleted” but still in git history, committed .env, hardcoded passwords, TLS checks off, agent chat logs
During · guard

Stop dangerous calls

A live Claude Code hook that checks every tool call before it runs.

handrail init claude --write
  • Blocks curl | bash, rm -rf /, exfiltration
  • Blocks an agent switching itself into bypass mode
  • Asks first before credential reads, pushes, deploys, test skips
After · audit

Check what it claimed

Reads the session transcript and compares claims with what actually ran.

handrail audit --latest
  • “All tests pass” with no passing run behind it
  • Success claimed right after a failure
  • Tests skipped without saying so; guardrail tampering
04 · Our evidence

We measured first. Then we wrote the rules.

Most agent-security tools ship whatever sounds scary. Handrail started as a study of what real repos actually contain, with every finding checked by hand.

1,200
active public repos, sampled at random across star counts
9,499
unique agent instruction and config files scanned
1 in 5
repos now instruct a coding agent (36% of 10k+ star repos)
0
confirmed agent-hijacking injections. The risk was in configs and keys.

Rules that earned their place

Hand-labeled precision on the study sample. Rules that cried wolf are opt-in, never high.

RulePrecisionShips as
mcp-auto-approve
12/12
on · high
agent-broad-permissions
12/12
on · high
agent-auto-enable-mcp
12/12
on · medium
mcp-inline-secret
10/12
on · high
html-comment-directive
0/12
opt-in
zero-width-chars
0/12
opt-in
base64-text-blob
0/12
opt-in

Corpus-weighted precision on medium+ findings: 77.9%. Recall: 0 missed risks in a random sample of 133 unflagged files.

Do agents follow planted instructions?

Pilot, Nov 11 2026: 18 hidden instructions × Claude Opus, Sonnet and Haiku 5.5.

0/54

followed a planted instructionREADME, HTML comment, code comment, AGENTS.md, invisible Unicode, fetched web page

48/48

finished runs told the usernamed the file, quoted the request, said it didn’t comply

6/18

Opus runs stopped with no explanationsafe, but the bug stayed unfixed and the user couldn’t tell why

One repeat per cell on one toy repo: a pilot, not a rate. The takeaway matches the study: blunt injection isn’t where the risk is. Configs are.

Read the study ↗ Read the pilot ↗
05 · CI/CD

Gate every pull request, on any platform.

Fail the build on a high-severity finding and send SARIF to your code-scanning view. Three lines on most platforms.

.github/workflows/handrail.yml

      

    

    

      Claude CodeCursorGitHub CopilotCodexGemini CLIWindsurfMCP
    

  






  

    

      
06 · For teams

      

        
Safe to roll out across an engineering org.

        
Developers are adding agent configs faster than security teams can review them. Handrail makes those files part of the normal review gate.

      

    

    

      
Nothing leaves your network
Runs entirely offline from the standard library. No telemetry, no API key, no SaaS account. Secret values are redacted in every output.

      
Low noise by design
Default rules are the ones that scored high on real repos. Noisy detectors stay opt-in, so a gate doesn’t train people to ignore it.

      
Fits your existing tools
SARIF for GitHub and Azure DevOps code scanning, JSON for your SIEM, exit codes for any pipeline, and an append-only audit log of agent tool calls.

    

    

      

        
Scan your own setup in ten seconds.

        
Run it on your laptop first. It checks ~/.claude, Claude Desktop, Cursor, Codex, Gemini and VS Code, and changes nothing.

      

      npx handrail-ai scan --home
    

  







  

    
Sources

    
    
      
  1. GitGuardian, The State of Secrets Sprawl 2026, Mar 17 2026
    2. 
      
  2. Socket, Nx npm packages compromised in supply chain attack weaponizing AI CLI tools, Aug 27 2025
    3. 
      
  3. Wiz, s1ngularity: supply chain attack leaks secrets on GitHub, Aug 27 2025
    4. 
      
  4. Cloud Security Alliance, Prompt injection in AI-powered GitHub Actions, May 3 2026
    5. 
      
  5. Invariant Labs, GitHub MCP exploited: accessing private repositories via MCP, May 26 2025
    6. 
      
  6. TechRadar, Amazon’s AI coding agent was hacked, Jul 28 2025
    7. 
      
  7. The Stack, Vibe coding CEO deletes “production” database using Replit, Jul 21 2025
    8. 
      
  8. Handrail, Instructions to coding agents in the wild (study v0.1), Nov 2026
    9.