Merge pull request #93 from Raftersecurity/betterleaks-migration

Betterleaks migration

Author: Raftersecurity

.github/copilot-instructions.md

@@ -13,7 +13,7 @@ Rafter is a security CLI for AI coding agents. It ships as two feature-identical
 
 - `node/src/commands/` — CLI commands (commander.js)
 - `node/src/core/` — Command interceptor, audit logger, config manager
-- `node/src/scanners/` — Gitleaks integration + regex-based secret scanner
+- `node/src/scanners/` — Betterleaks integration + regex-based secret scanner
 - `node/src/commands/agent/init.ts` — Per-platform installation logic (8 platforms)
 - `python/rafter_cli/` — Mirrors the Node structure with typer
 - `shared-docs/CLI_SPEC.md` — Canonical output contracts and exit codes
@@ -29,7 +29,7 @@ Rafter is a security CLI for AI coding agents. It ships as two feature-identical
 ## Key Patterns
 
 - Commands export a `createXCommand()` factory (Node) or use `@app.command()` decorators (Python)
-- Scanners use dual-engine: Gitleaks binary first, regex fallback. Patterns defined in `secret-patterns.ts` / `secret_patterns.py`
+- Scanners use dual-engine: Betterleaks binary first, regex fallback. Patterns defined in `secret-patterns.ts` / `secret_patterns.py`
 - Risk classification: critical > high > medium > low
 - Audit log: JSONL format, append-only, documented schema in CLI_SPEC.md
 - MCP server: 4 tools + 2 resources over stdio transport

.pre-commit-hooks.yaml

@@ -1,6 +1,6 @@
 - id: rafter-scan
   name: Rafter Secret Scanner
-  description: Scan staged files for secrets (21+ patterns, Gitleaks integration)
+  description: Scan staged files for secrets (21+ patterns, Betterleaks integration)
   entry: rafter scan local --staged --quiet
   language: system
   stages: [pre-commit]

CHANGELOG.md

@@ -17,6 +17,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **CI `Validate Release` test-build job green** (rf-6s9l, rf-b9l8, rf-blvo). 13 Node tests across 4 files updated to match shape changes that already landed on main: rf-0pch (`rafter scan local --json` now wraps results in `{_note, scan_mode, triage_applied, results, _suppressed?}`), rf-d8s (`Suppression` gained a `source: ".rafterignore" | ".rafter.yml"` field), and rf-zgwj (OpenClaw skill install path moved to the canonical ClawHub `~/.openclaw/workspace/skills/rafter-security/SKILL.md`). Test-only changes; no production behavior shift.
 
 ### Changed
+- **Secret-scanning engine migrated from gitleaks to betterleaks** (Node + Python, rc-ksy / rc-963). [Betterleaks](https://github.com/betterleaks/betterleaks) v1.1.2 is the gitleaks successor maintained by the same authors. JSON report shape is unchanged; what changed is the binary, the CLI subcommand (`detect --no-git -s` → `dir <path>`), the release URL, and the checksum filename.
+  - **Breaking:** the legacy CLI surface has been removed entirely. `--with-gitleaks`, `--engine gitleaks`, and `rafter agent update-gitleaks` now error out (unknown option / invalid engine / unknown command). Use `--with-betterleaks`, `--engine betterleaks`, and `rafter agent update-betterleaks`.
+  - **Soft landing for existing installs:** `rafter agent verify` and `rafter agent status` continue to detect a leftover `~/.rafter/bin/gitleaks` (or `gitleaks` on PATH) and emit "legacy gitleaks at X — run: rafter agent update-betterleaks" instead of a confusing "not found". Verify exits 0 in this case (was a hard fail before this fix).
+  - **Supply-chain hardening:** SHA256 hashes for the bundled `BETTERLEAKS_VERSION` are pinned in source, so the default install no longer trusts the release-page `checksums.txt` to authenticate itself. Tar/zip extraction now rejects symlink/hardlink/device entries (mitigates a malicious-release symlink-redirect that the subsequent `chmod +x` would have followed). Downloads refuse non-https URLs. The optional `--version` flag is validated against `^[A-Za-z0-9._-]+$` to neutralize URL injection. Targets passed to betterleaks are preceded by `--` so a path beginning with `-` isn't parsed as a flag.
+  - Internal renames: `GitleaksScanner` → `BetterleaksScanner`, `*_gitleaks` methods → `*_betterleaks`, `GITLEAKS_VERSION` → `BETTERLEAKS_VERSION`. New tests cover pinned-hash table completeness, `--version` validation, non-https refusal, and the alias-removal contract.
+
 - **OpenClaw integration rebuilt as a ClawHub-shaped skill** (Node + Python, rf-zgwj). Previously rafter wrote a single markdown file at `~/.openclaw/skills/rafter-security.md` — a path OpenClaw never read at runtime. ClawHub auto-discovers skills from `<workspace>/skills/<name>/SKILL.md`. The new install:
   - Writes `~/.openclaw/workspace/skills/rafter-security/SKILL.md` (the canonical ClawHub path).
   - Adds the ClawHub-required top-level frontmatter (`name`, `description`, `version`) alongside the existing `openclaw:` runtime block. Now passes ClawHub's metadata schema check.

CLAUDE.md

@@ -32,15 +32,15 @@ cd python && poetry install && pytest
 │   │   │   ├── audit-logger.ts         # JSONL audit trail
 │   │   │   └── config-manager.ts       # .rafter.yml + global config
 │   │   └── scanners/
-│   │       ├── gitleaks.ts             # Gitleaks binary integration
+│   │       ├── betterleaks.ts          # Betterleaks binary integration
 │   │       ├── secret-patterns.ts      # DEFAULT_SECRET_PATTERNS array (21+ patterns)
 │   │       └── regex-scanner.ts        # RegexScanner class (imports secret-patterns)
 │   └── tests/               # Vitest test files
 ├── python/                  # Python implementation (rafter-cli on PyPI)
 │   ├── rafter_cli/
 │   │   ├── commands/        # CLI commands (typer)
 │   │   ├── core/            # Mirrors node/src/core/
-│   │   └── scanners/        # secret_patterns.py + regex_scanner.py + gitleaks.py
+│   │   └── scanners/        # secret_patterns.py + regex_scanner.py + betterleaks.py
 │   └── tests/               # pytest test files
 ├── shared-docs/             # Canonical specs (both implementations follow these)
 │   └── CLI_SPEC.md          # Output contracts, exit codes, JSON schemas
@@ -58,7 +58,7 @@ cd python && poetry install && pytest
 
 **Risk classification**: Commands are classified into 4 tiers (critical/high/medium/low) by pattern matching in `command-interceptor.ts`. Policy files (`.rafter.yml`) can override defaults.
 
-**Secret scanning**: Dual-engine — tries Gitleaks binary first (higher accuracy), falls back to built-in regex patterns (21+ patterns, zero dependencies). Deterministic for a given version.
+**Secret scanning**: Dual-engine — tries Betterleaks binary first (higher accuracy), falls back to built-in regex patterns (21+ patterns, zero dependencies). Deterministic for a given version. Betterleaks is the gitleaks successor maintained by the original gitleaks authors. Existing installs with a leftover `~/.rafter/bin/gitleaks` are detected by `agent verify`/`status` so users get an upgrade hint, but the legacy CLI flags (`--with-gitleaks`, `--engine gitleaks`, `update-gitleaks`) have been removed.
 
 **MCP server**: `rafter mcp serve` exposes 4 tools (`scan_secrets`, `evaluate_command`, `read_audit_log`, `get_config`) and 2 resources (`rafter://config`, `rafter://policy`) over stdio.
 

Dockerfile

@@ -17,7 +17,7 @@ FROM node:22-alpine
 
 RUN apk add --no-cache git \
     && npm install -g @rafter-security/cli \
-    && rafter agent init --with-gitleaks 2>/dev/null || true
+    && rafter agent init --with-betterleaks
 
 WORKDIR /workspace
 

README.md

@@ -50,7 +50,7 @@ rafter secrets .
 ```sh
 rafter agent init --all
 # → Installs all detected integrations
-# → Downloads Gitleaks (or falls back to built-in scanner)
+# → Downloads Betterleaks (or falls back to built-in scanner)
 ```
 
 **3. Try to commit—hook blocks it**
@@ -184,7 +184,7 @@ This command:
 - Creates `~/.rafter/` config and audit log (or `./.rafter/` with `--local` for ephemeral / containerized / benchmark setups)
 - Auto-detects Claude Code, Codex CLI, OpenClaw, Gemini, Cursor, Windsurf, Continue.dev, and Aider
 - With `--with-*` or `--all`: installs Rafter skills/extensions to opted-in agents
-- With `--with-gitleaks` or `--all`: downloads [Gitleaks](https://github.com/gitleaks/gitleaks) for enhanced secret scanning (falls back to built-in 21-pattern regex scanner)
+- With `--with-betterleaks` or `--all`: downloads [Betterleaks](https://github.com/betterleaks/betterleaks) (the gitleaks successor maintained by the original gitleaks authors) for enhanced secret scanning. Falls back to built-in 21-pattern regex scanner.
 
 Use `rafter agent list/enable/disable` for granular per-component control after the initial install — toggle any platform on or off without re-running `init`.
 
@@ -197,7 +197,7 @@ rafter secrets .              # scan directory
 rafter secrets ./config.js    # scan specific file
 rafter secrets --staged       # scan git staged files only
 rafter secrets --diff HEAD~1  # scan files changed since a git ref
-rafter secrets --history      # scan full git history (requires gitleaks engine)
+rafter secrets --history      # scan full git history (requires betterleaks engine)
 rafter secrets --json         # structured output
 rafter secrets --quiet        # silent unless secrets found (CI-friendly)
 ```
@@ -223,7 +223,7 @@ Exit code 1 if secrets found, 0 if clean.
 
 Raw secret values are never included in output. Pipe to `jq`, feed to CI gates, or hand to any tool that reads JSON.
 
-**Engine selection:** Uses Gitleaks when available (more patterns), falls back to built-in regex. Override with `--engine gitleaks|patterns|auto`.
+**Engine selection:** Uses Betterleaks when available (more patterns), falls back to built-in regex. Override with `--engine betterleaks|patterns|auto`.
 
 ### Pre-Commit Hook
 
@@ -524,7 +524,7 @@ Exit codes are part of Rafter's output contract — CI pipelines and orchestrato
 ~/.rafter/
 ├── config.json        # Configuration
 ├── audit.jsonl        # Security event log (JSON lines)
-├── bin/gitleaks       # Gitleaks binary
+├── bin/betterleaks    # Betterleaks binary
 ├── patterns/          # Custom patterns (reserved)
 └── git-hooks/         # Global pre-commit hook (if --global)
 ```

SKILL.md

@@ -32,8 +32,8 @@ rafter agent init --with-continue      # MCP server
 rafter agent init --with-aider         # MCP server
 rafter agent init --with-openclaw      # Skills
 
-# Also download Gitleaks for enhanced scanning (optional, falls back to built-in 21-pattern regex)
-rafter agent init --with-claude-code --with-gitleaks
+# Also download Betterleaks for enhanced scanning (optional, falls back to built-in 21-pattern regex)
+rafter agent init --with-claude-code --with-betterleaks
 ```
 
 **What init does per platform:**

action.yml

@@ -1,6 +1,6 @@
 # Rafter Security — GitHub Action
 #
-# Deterministic secret scanning for CI. 21+ credential patterns via Gitleaks,
+# Deterministic secret scanning for CI. 21+ credential patterns via Betterleaks,
 # stable exit codes (0 = clean, 1 = findings, 2 = error), structured JSON output.
 # No API key required. No code leaves the runner.
 #

drafts/show-hn/faq.md

@@ -4,11 +4,11 @@ Responses written in founder voice. Adapt as needed based on the actual question
 
 ---
 
-## "How is this different from gitleaks / trufflehog?"
+## "How is this different from betterleaks (or gitleaks) / trufflehog?"
 
-Rafter actually wraps gitleaks when it's available -- if the binary is on your PATH, we use it as the primary scanner because it's excellent. Our built-in regex engine (21+ patterns) is the fallback for zero-dependency environments.
+Rafter actually wraps betterleaks (the gitleaks successor) when it's available -- if the binary is on your PATH, we use it as the primary scanner because it's excellent. Our built-in regex engine (21+ patterns) is the fallback for zero-dependency environments.
 
-The difference is everything around the scan. Gitleaks and trufflehog are standalone secret scanners. Rafter adds command interception (blocking `curl | bash` before your agent runs it), audit logging of agent sessions, MCP integration so the agent itself can check for secrets, pre-commit hooks, and one-command setup for 8 different AI platforms. If you're just scanning repos for secrets, gitleaks is great and you don't need us. If you're running AI coding agents and want guardrails around the whole session, that's what Rafter is for.
+The difference is everything around the scan. Betterleaks and trufflehog are standalone secret scanners. Rafter adds command interception (blocking `curl | bash` before your agent runs it), audit logging of agent sessions, MCP integration so the agent itself can check for secrets, pre-commit hooks, and one-command setup for 8 different AI platforms. If you're just scanning repos for secrets, betterleaks is great and you don't need us. If you're running AI coding agents and want guardrails around the whole session, that's what Rafter is for.
 
 ---
 

drafts/show-hn/post.md

@@ -4,7 +4,7 @@ If you use Claude Code, Codex CLI, Cursor, Gemini CLI, or similar tools, your AI
 
 **What it does:**
 
-- **Secret scanning**: 21+ built-in regex patterns plus optional Gitleaks integration. Deterministic for a given version. Stable exit codes for CI.
+- **Secret scanning**: 21+ built-in regex patterns plus optional Betterleaks integration (the gitleaks successor). Deterministic for a given version. Stable exit codes for CI.
 - **Command interception**: Classifies commands into risk tiers (critical/high/medium/low) and enforces approval policies before execution.
 - **Audit logging**: JSONL trail of every command your agent runs and every secret scan result.
 - **MCP server**: 4 tools (`scan_secrets`, `evaluate_command`, `read_audit_log`, `get_config`) so AI agents can query security status natively.