Skip to content
Back to search

secret-preflight

MarketplaceWorks with Claude CodeGitHub

secret-preflight: go/no-go check for leaked secrets before commit or push

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/medenor--secret-preflight/badge.svg)](/listings/medenor--secret-preflight)

HTML

<a href="/listings/medenor--secret-preflight"><img src="/api/listings/medenor--secret-preflight/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.

Requirements: Python 3.8+ and git. No dependencies.

Claude Code: plugin (recommended)

In a Claude Code session:

/plugin marketplace add Medenor/secret-preflight
/plugin install secret-preflight@secret-preflight

On Claude Code 2.1.275 or later, one step is enough: `/plugin install secret-preflight --marketplace Medenor/secret-preflight`.

Claude Code installs only the plugin folder (manifest + skill) into its plugin cache, so nothing from this repo lands in your skills directory. The skill triggers on its own ("is it safe to push?"), or you can run it explicitly with `/secret-preflight:secret-preflight`.

Claude Code: standalone skill

Each release carries a ZIP that holds only the skill folder:

curl -fsSL -o /tmp/secret-preflight-skill.zip \
  https://github.com/Medenor/secret-preflight/releases/latest/download/secret-preflight-skill.zip
unzip -q /tmp/secret-preflight-skill.zip -d ~/.claude/skills/ && rm /tmp/secret-preflight-skill.zip

To share it with a team through a project, unzip into `<project>/.claude/skills/` instead.

Claude apps

Download `secret-preflight-skill.zip` from the [latest release](https://github.com/Medenor/secret-preflight/releases/latest) and upload it in Claude's skills settings. The `staged` and `push` modes need a git repository in Claude's environment.

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 · 15 lines
  1. {
  2. "name": "secret-preflight",
  3. "description": "secret-preflight: go/no-go check for leaked secrets before commit or push",
  4. "owner": {
  5. "name": "Medenor",
  6. "url": "https://github.com/Medenor"
  7. },
  8. "plugins": [
  9. {
  10. "name": "secret-preflight",
  11. "source": "./plugins/secret-preflight",
  12. "description": "Go/no-go check for leaked secrets, private keys, credential files and PII before a commit, push or PR."
  13. }
  14. ]
  15. }
README.md · README · 140 lines
  1. # secret-preflight
  2. **A go/no-go check for leaked secrets before you commit or push.** An agent skill for [Claude Code](https://docs.claude.com/en/docs/claude-code) and Claude.
  3. Ask *"is it safe to push?"* and Claude runs a deterministic scanner over exactly what is about to leave your machine, then answers **GO**, **HOLD** or **NO-GO**, with the one action to take first.
  4. ```markdown
  5. ## 🛫 Secret preflight — NO-GO
  6. `push` · `my-repo` · 3 commits ahead of `origin/main` · 412 files
  7. **1 blocker must be fixed before pushing.** 1 item to review · 37 notices.
  8. ### ⛔ Blockers
  9. | ID | Where | What | Exposure | First action |
  10. |---|---|---|---|---|
  11. | C1 | `deploy.sh:2` | GitHub token `ghp_****… (40 chars)` | pushed in `a1b2c3d` | Revoke the token now |
  12. | H1 | `keys/server.pem` | Private key file | untracked, not ignored | Add to `.gitignore` |
  13. ...
  14. ```
  15. ## Why another secret scanner?
  16. Most agent-based scanners ask the model to grep for patterns. That has three problems this skill is built to avoid.
  17. | Problem | What secret-preflight does |
  18. |---|---|
  19. | **Grep puts the raw secret into the conversation** (and into logs and transcripts) | Detection runs in `scripts/scan.py`, which masks every value before printing. The agent only sees `ghp_****… (40 chars)`. |
  20. | **The wrong scope.** Scanning the working tree misses what actually gets pushed. | Three modes: `staged` (pre-commit), `push` (every unpushed commit, including a secret added and then deleted) and `tree` (including files committed despite `.gitignore`). |
  21. | **"Delete the line" is the wrong fix once a secret is pushed** | The script checks remote-tracking history. Pushed secrets become **CRITICAL**, and the first action is *rotate*, not *edit*. |
  22. Other differences:
  23. - **Fewer false positives.** Placeholders, `${ENV}` references, variable names and field-name keys (`password_field_name`) are filtered out. PII is reported only when its checksum validates (Luhn, IBAN mod-97, Chinese ID, Belgian national number). Test, fixture and docs paths are downgraded, not hidden.
  24. - **Honest coverage.** Every report says what was skipped, what was allowlisted, and what a GO does *not* guarantee.
  25. - **Read-only by default.** Fixes are proposed and applied only after you approve them.
  26. - **Tested.** `scripts/selftest.py` builds a throwaway repo with runtime-generated fake secrets and checks every mode, the masking and the false-positive filters. No literal token appears anywhere in this repo, so it passes GitHub push protection.
  27. On Django (7,100 files) a full `tree` scan takes about 8 s and returns HOLD with 4 items to review.
  28. ## What it detects
  29. | Category | Examples | Default severity |
  30. |---|---|---|
  31. | Provider tokens | AWS, GitHub, GitLab, Anthropic, OpenAI, Stripe, Slack (token and webhook), Google, Square, npm, Hugging Face, JWT | HIGH |
  32. | Key material | `-----BEGIN … PRIVATE KEY-----` blocks, GCP service-account keys, `.pem`, `.key`, `.p12`, `.pfx`, `.jks`, `id_rsa`, … | HIGH |
  33. | Credentials in URLs | `postgres://user:pass@host` and similar | HIGH |
  34. | Credential files | `.env*`, `credentials.json`, `service-account*.json`, `.npmrc`, `.pypirc`, `.netrc`, `.aws/credentials`, `.docker/config.json`, `*.tfstate` | HIGH with values, LOW without |
  35. | Generic assignments | `api_key = "…"`, `PASSWORD: …`, `client_secret => …` | MEDIUM (the agent assesses each one) |
  36. | PII | email addresses, payment cards, IBANs, Chinese ID and mobile numbers, Belgian national numbers | LOW |
  37. Severity is raised to **CRITICAL** when the value is found in remote-tracking history.
  38. ## Install
  39. Requirements: Python 3.8+ and git. No dependencies.
  40. ### Claude Code: plugin (recommended)
  41. In a Claude Code session:
  42. ```
  43. /plugin marketplace add Medenor/secret-preflight
  44. /plugin install secret-preflight@secret-preflight
  45. ```
  46. On Claude Code 2.1.275 or later, one step is enough: `/plugin install secret-preflight --marketplace Medenor/secret-preflight`.
  47. Claude Code installs only the plugin folder (manifest + skill) into its plugin cache, so nothing from this repo lands in your skills directory. The skill triggers on its own ("is it safe to push?"), or you can run it explicitly with `/secret-preflight:secret-preflight`.
  48. ### Claude Code: standalone skill
  49. Each release carries a ZIP that holds only the skill folder:
  50. ```bash
  51. curl -fsSL -o /tmp/secret-preflight-skill.zip \
  52. https://github.com/Medenor/secret-preflight/releases/latest/download/secret-preflight-skill.zip
  53. unzip -q /tmp/secret-preflight-skill.zip -d ~/.claude/skills/ && rm /tmp/secret-preflight-skill.zip
  54. ```
  55. To share it with a team through a project, unzip into `<project>/.claude/skills/` instead.
  56. ### Claude apps
  57. Download `secret-preflight-skill.zip` from the [latest release](https://github.com/Medenor/secret-preflight/releases/latest) and upload it in Claude's skills settings. The `staged` and `push` modes need a git repository in Claude's environment.
  58. ## Repository layout
  59. ```
  60. .claude-plugin/marketplace.json marketplace catalog (this repo)
  61. plugins/secret-preflight/ the plugin: the only part that gets installed
  62. ├── .claude-plugin/plugin.json
  63. └── skills/secret-preflight/
  64. ├── SKILL.md
  65. ├── scripts/scan.py masking scanner (JSON out)
  66. ├── scripts/selftest.py self-test suite
  67. └── references/remediation.md rotation and history-rewrite guide
  68. .github/workflows/ CI self-test + release ZIP
  69. README.md, LICENSE, ACKNOWLEDGMENTS.md, CHANGELOG.md
  70. ```
  71. ## Use
  72. Ask in plain language:
  73. - "Is it safe to push?" → `push` mode
  74. - "Check for secrets before I commit" → `staged` mode
  75. - "Run a security check on this repo" → `tree` mode
  76. Or run the scanner directly. It prints JSON, and its exit code fits CI and git hooks (`1` = NO-GO):
  77. ```bash
  78. python3 <skill-dir>/scripts/scan.py --mode push --root .
  79. ```
  80. To silence a known false positive, add `secret-preflight:ignore` to the line. Allowlisted lines are always listed in the report's Coverage section.
  81. ## Limits
  82. - It is not a full-history auditor. For that, use [gitleaks](https://github.com/gitleaks/gitleaks) or [trufflehog](https://github.com/trufflesecurity/trufflehog). If one is installed, the skill offers to run it as a second opinion.
  83. - The pushed check relies on your local remote-tracking refs. Run `git fetch` first for an exact answer.
  84. - Pattern-based detection misses secrets with no recognisable shape or key name. A GO lowers the risk; it does not prove there is none.
  85. - PII patterns cover a few locales. Add your own in `scripts/scan.py` (pattern + checksum), then run the self-test.
  86. ## Development
  87. ```bash
  88. S=plugins/secret-preflight/skills/secret-preflight/scripts
  89. python3 $S/selftest.py # must print "OK"
  90. python3 $S/scan.py --root . # the repo must scan GO
  91. claude plugin validate . # marketplace + plugin manifests
  92. ```
  93. To release, bump `version` in `plugins/secret-preflight/.claude-plugin/plugin.json`, then publish a GitHub release tagged `v<version>`. The release workflow checks that the tag matches the version, runs the self-test and attaches `secret-preflight-skill.zip`.
  94. Pull requests are welcome. Every new pattern needs a positive and a look-alike case in `selftest.py`, built at runtime (never commit a literal token).
  95. ## Credits
  96. Inspired by [mercury0993/secret-scanner](https://github.com/mercury0993/secret-scanner). See [ACKNOWLEDGMENTS.md](ACKNOWLEDGMENTS.md).
  97. <a href="https://tcp-up.org/pages/label-aic.html"><img src="https://tcp-up.org/img/badges/svg/badge_aic_co.svg" alt="TCP/UP: AIC — AI Content" height="28"></a>
  98. ## License
  99. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

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