Skip to content

πŸš€ The fast, Pythonic way to build MCP servers and clients.

Add gitleaks secret scanning to prek (#5355)

Bill Easton6d6aee416823
diff --git a/.github/actions/setup-gitleaks/action.yml b/.github/actions/setup-gitleaks/action.yml
new file mode 100644
index 000000000..0aba01f40
--- /dev/null
+++ b/.github/actions/setup-gitleaks/action.yml
@@ -0,0 +1,18 @@
+name: "Setup gitleaks"
+description: "Install the gitleaks binary onto PATH for the gitleaks prek hook"
+
+inputs:
+ version:
+ description: "gitleaks release version (without leading v)"
+ required: false
+ default: "8.30.1"
+
+runs:
+ using: "composite"
+ steps:
+ - name: Install gitleaks
+ shell: bash
+ run: |
+ curl -sSfL "https://github.com/gitleaks/gitleaks/releases/download/v${{ inputs.version }}/gitleaks_${{ inputs.version }}_linux_x64.tar.gz" \
+ | tar -xz -C /usr/local/bin gitleaks
+ gitleaks version
diff --git a/.github/workflows/run-static.yml b/.github/workflows/run-static.yml
index 40d34ddfa..0069efbeb 100644
--- a/.github/workflows/run-static.yml
+++ b/.github/workflows/run-static.yml
@@ -34,6 +34,9 @@ jobs:
with:
resolution: locked
+ - name: Setup gitleaks
+ uses: ./.github/actions/setup-gitleaks
+
- name: Test workflows
run: node --test .github/scripts/test-*.mjs
diff --git a/.github/workflows/run-upgrade-checks.yml b/.github/workflows/run-upgrade-checks.yml
index fe1f87e3b..482ee5e23 100644
--- a/.github/workflows/run-upgrade-checks.yml
+++ b/.github/workflows/run-upgrade-checks.yml
@@ -28,6 +28,9 @@ jobs:
with:
resolution: upgrade
+ - name: Setup gitleaks
+ uses: ./.github/actions/setup-gitleaks
+
- name: Run prek
uses: j178/[email protected]
env:
diff --git a/.gitleaks.toml b/.gitleaks.toml
new file mode 100644
index 000000000..5e1518334
--- /dev/null
+++ b/.gitleaks.toml
@@ -0,0 +1,46 @@
+title = "fastmcp gitleaks config"
+
+[extend]
+# Keep every built-in detection rule; this file only adds an allowlist on top.
+useDefault = true
+
+[allowlist]
+description = "Non-source directories and known placeholder/example values"
+
+# Regexes, not exact paths: gitleaks doesn't read .gitignore for `detect
+# --no-git`, so build artifacts (e.g. __pycache__ from a local test run) can
+# otherwise surface as new findings unrelated to any real change.
+paths = [
+ '''(^|/)\.venv/''',
+ '''(^|/)__pycache__/''',
+ '''(^|/)node_modules/''',
+ '''(^|/)\.git/''',
+ '''(^|/)dist/''',
+ '''(^|/)build/''',
+ '''(^|/)\.pytest_cache/''',
+ # Local env files are gitignored and routinely hold real credentials for
+ # whatever provider a developer is testing against - never git-controlled,
+ # so there's nothing here for the scan to protect against committing.
+ '''(^|/)\.env($|\.)''',
+ '''(^|/)\.direnv/''',
+]
+
+# Matched against the detected secret text itself, not file:line - stable
+# across edits elsewhere in the file, unlike a fingerprint allowlist keyed on
+# line number. Each entry below is a placeholder/example value, not a real
+# credential; see the PR that added this file for the per-entry review.
+regexes = [
+ '''YOUR_API_KEY''',
+ '''YOUR_TOKEN_HERE''',
+ '''GOCSPX-abc123\.\.\.''',
+ '''GOCSPX-test123''',
+ '''Ov23liAbcDefGhiJkLmN''',
+ '''tv2ObNgaZAWWhhycr7Bz1LU2mxlnsmsB''', # Auth0 example CLIENT_ID (not a secret) in docs
+ '''835f09b6-0f0f-40cc-85cb-f32c5829a149''',
+ '''08541b6e-646d-43de-a0eb-834e6713d6d5''',
+ '''c361ed56e7bdc1a48a38773c40120b39''', # public Amplitude browser key, docs/fastmcp-analytics.js
+ '''f7207cf0a5c56081d275ebae4cf615249323385d''', # pinned git commit hash used as a test fixture id
+ '''s3kr1t-material''',
+ '''Ed25519PrivateKey''', # a type name, not a key
+ '''-----BEGIN PRIVATE KEY-----" in private_pem''', # test asserts a string literal, not an embedded key
+]
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 8321b5bde..5f6ef5b6d 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -40,6 +40,21 @@ repos:
pass_filenames: false
verbose: true
+ - id: gitleaks
+ name: gitleaks (secret scanning)
+ # Full working-tree scan rather than the official `gitleaks git --staged`
+ # hook: that mode fingerprints findings by commit SHA, which would
+ # churn a fingerprint-based ignore list on every unrelated commit to
+ # an ignored file. .gitleaks.toml's allowlist is matched against the
+ # detected secret text instead, so it's stable regardless of commit
+ # or line number. Its path allowlist also excludes local build
+ # artifacts (e.g. __pycache__), which `--no-git` doesn't consult
+ # .gitignore for. Requires gitleaks on PATH (e.g. `brew install
+ # gitleaks`).
+ entry: gitleaks detect --source . --no-git --config .gitleaks.toml --redact -v
+ language: system
+ pass_filenames: false
+
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v6.0.0
hooks:
diff --git a/AGENTS.md b/AGENTS.md
index 341219ec8..23027c2ce 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -16,9 +16,11 @@ uv run pytest -n auto # Run full test suite
In addition, you must pass static checks. This is generally done as a pre-commit hook with `prek` but you can run it manually with:
```bash
-uv run prek run --all-files # Ruff + Prettier + ty
+uv run prek run --all-files # Ruff + Prettier + ty + gitleaks
```
+The gitleaks hook needs the `gitleaks` binary on `PATH` (`brew install gitleaks`, or see [gitleaks releases](https://github.com/gitleaks/gitleaks/releases)) β€” it isn't a `uv`-managed dependency, so `uv sync` alone won't provide it.
+
**Tests must pass and lint/typing must be clean before committing.**
## Repository Structure