ace-git-secrets 0.13.0

data/docs/handbook.md

@@ -0,0 +1,43 @@
+---
+doc-type: user
+title: ace-git-secrets Handbook Catalog
+purpose: Catalog of ace-git-secrets workflows, skills, guides, and agents
+ace-docs:
+  last-updated: 2026-03-22
+  last-checked: 2026-03-22
+---
+
+# ace-git-secrets Handbook Catalog
+
+Reference for package-owned handbook resources in `ace-git-secrets/handbook/`.
+
+## Skills
+
+| Skill | What it does |
+|-------|--------------|
+| `as-git-security-audit` | Run the package security-audit workflow to detect leaked tokens and report remediation guidance |
+| `as-git-token-remediation` | Run the package remediation workflow to scan, revoke, and clean leaked credentials |
+
+## Workflow Instructions
+
+| Protocol Path | Purpose | Invoked by |
+|---------------|---------|------------|
+| `wfi://git/security-audit` | Guided detection and reporting workflow for leaked credentials | `as-git-security-audit` |
+| `wfi://git/token-remediation` | Guided remediation workflow covering scan, revoke, rewrite, and follow-up actions | `as-git-token-remediation` |
+
+## Agents
+
+- `handbook/agents/security-audit.ag.md` for focused security-audit execution
+
+## Guides
+
+- `handbook/guides/security.g.md` for package-level security guidance
+- `handbook/guides/security/ruby.md` for Ruby-specific security notes
+- `handbook/guides/security/typescript.md` for TypeScript-specific security notes
+- `handbook/guides/security/rust.md` for Rust-specific security notes
+
+## Related Docs
+
+- [Getting Started](getting-started.md)
+- [CLI Usage Reference](usage.md)
+- Load workflows directly with `ace-bundle`, for example `ace-bundle wfi://git/token-remediation`

data/docs/usage.md

@@ -0,0 +1,301 @@
+---
+doc-type: user
+title: ace-git-secrets Usage Guide
+purpose: CLI reference for ace-git-secrets
+ace-docs:
+  last-updated: 2026-03-22
+  last-checked: 2026-03-22
+---
+
+# ace-git-secrets Usage Guide
+
+Reference for scanning, revoking, and removing leaked credentials from Git history.
+
+## Quick Start
+
+Run a scan first and keep the saved JSON report path:
+
+```bash
+ace-git-secrets scan
+```
+
+Then use that saved report for the rest of the remediation flow:
+
+```bash
+ace-git-secrets revoke --scan-file .ace-local/git-secrets/sessions/<id>-report.json
+ace-git-secrets rewrite-history --dry-run --scan-file .ace-local/git-secrets/sessions/<id>-report.json
+ace-git-secrets rewrite-history --scan-file .ace-local/git-secrets/sessions/<id>-report.json
+```
+
+## Commands
+
+### scan
+
+Scan Git history for authentication tokens.
+
+```bash
+ace-git-secrets scan [OPTIONS]
+```
+
+Behavior:
+
+- Summary output goes to stdout by default
+- A full report is always saved to `.ace-local/git-secrets/sessions/`
+- The saved JSON report includes raw token values needed by `revoke` and `rewrite-history`
+
+Options:
+
+- `--since=VALUE` - Start scanning from a commit or date
+- `--format=VALUE, -f` - Stdout format when `--verbose` is enabled: `table`, `json`, `yaml`
+- `--report-format=VALUE, -r` - Saved report format: `json`, `markdown`
+- `--confidence=VALUE, -c` - Minimum confidence: `high`, `medium`, `low`
+- `--[no-]verbose` - Print the full report to stdout in addition to saving it
+- `--[no-]quiet, -q` - Suppress non-essential output for CI-style usage
+- `--[no-]debug` - Show debug output
+
+Examples:
+
+```bash
+# Scan full history
+ace-git-secrets scan
+
+# Scan recent history only
+ace-git-secrets scan --since "30 days ago"
+
+# Review only high-confidence findings in verbose JSON
+ace-git-secrets scan --confidence high --verbose --format json
+
+# Save a human-readable report as Markdown instead of JSON
+ace-git-secrets scan --report-format markdown
+
+# Minimal output for automation
+ace-git-secrets scan --quiet
+```
+
+### revoke
+
+Revoke detected tokens via provider APIs.
+
+```bash
+ace-git-secrets revoke [OPTIONS]
+```
+
+Options:
+
+- `--service=VALUE, -s` - Revoke for one provider only
+- `--token=VALUE, -t` - Revoke one explicit token value
+- `--scan-file=VALUE` - Load tokens from a saved scan report
+- `--[no-]debug` - Show debug output
+
+Examples:
+
+```bash
+# Revoke all high-confidence tokens from a fresh scan
+ace-git-secrets revoke
+
+# Revoke only GitHub tokens from a saved scan report
+ace-git-secrets revoke --service github --scan-file .ace-local/git-secrets/sessions/<id>-report.json
+
+# Revoke one token directly
+ace-git-secrets revoke --token "ghp_example_token"
+```
+
+Notes:
+
+- `--scan-file` expects the saved JSON report produced by `scan`
+- Redirecting verbose stdout to a file is not a supported substitute, because `revoke` requires `raw_value` fields
+- If the scan file is missing `raw_value`, re-run `ace-git-secrets scan` and use the saved report path it prints
+
+### rewrite-history
+
+Remove detected tokens from Git history.
+
+```bash
+ace-git-secrets rewrite-history [OPTIONS]
+```
+
+`rewrite-history` is destructive. Run it only after revoking the exposed credentials and after previewing the result with
+`--dry-run`.
+
+Options:
+
+- `--[no-]dry-run, -n` - Show what would be rewritten without modifying history
+- `--[no-]backup` - Create a backup before rewriting (enabled by default)
+- `--[no-]force` - Skip the confirmation prompt
+- `--scan-file=VALUE` - Load tokens from a saved scan report
+- `--[no-]debug` - Show debug output
+
+Examples:
+
+```bash
+# Preview cleanup first
+ace-git-secrets rewrite-history --dry-run --scan-file .ace-local/git-secrets/sessions/<id>-report.json
+
+# Rewrite history using the same saved report used for revocation
+ace-git-secrets rewrite-history --scan-file .ace-local/git-secrets/sessions/<id>-report.json
+
+# Rewrite without a prompt
+ace-git-secrets rewrite-history --force --scan-file .ace-local/git-secrets/sessions/<id>-report.json
+```
+
+Before running the real rewrite:
+
+- install `git-filter-repo`
+- start from a clean working tree
+- keep a mirror or clone backup for recovery
+
+### check-release
+
+Run the pre-release security gate.
+
+```bash
+ace-git-secrets check-release [OPTIONS]
+```
+
+Options:
+
+- `--[no-]strict` - Fail on medium-confidence matches in addition to high-confidence matches
+- `--format=VALUE, -f` - Output format: `table`, `json`
+- `--[no-]debug` - Show debug output
+
+Examples:
+
+```bash
+# Standard release gate
+ace-git-secrets check-release
+
+# Stricter release gate for CI
+ace-git-secrets check-release --strict
+
+# Structured review output
+ace-git-secrets check-release --format json
+```
+
+Prefer exit codes for automation. `check-release --format json` currently includes banner text, so it is better suited to
+inspection than strict machine parsing.
+
+## Configuration
+
+Configuration follows the ACE cascade. Project overrides live in `.ace/git-secrets/config.yml`.
+
+```yaml
+exclusions:
+  - "**/node_modules/**"
+  - "**/vendor/**"
+
+whitelist:
+  - pattern: "ghp_example_for_docs"
+    reason: "Documentation example"
+  - file: "test/fixtures/*.json"
+    reason: "Test fixtures"
+
+output:
+  format: table
+  mask_tokens: true
+  directory: .ace-local/git-secrets
+
+github:
+  api_url: https://github.mycompany.com/api/v3
+```
+
+Use whitelist rules for known safe examples or fixtures. Keep real credentials out of the whitelist and revoke them
+instead.
+
+## Common Workflows
+
+### Full remediation loop
+
+1. Scan and note the saved report path:
+
+   ```bash
+   ace-git-secrets scan
+   ```
+
+2. Revoke from the saved JSON report:
+
+   ```bash
+   ace-git-secrets revoke --scan-file .ace-local/git-secrets/sessions/<id>-report.json
+   ```
+
+3. Preview history rewriting:
+
+   ```bash
+   ace-git-secrets rewrite-history --dry-run --scan-file .ace-local/git-secrets/sessions/<id>-report.json
+   ```
+
+4. Rewrite history for real:
+
+   ```bash
+   ace-git-secrets rewrite-history --scan-file .ace-local/git-secrets/sessions/<id>-report.json
+   ```
+
+5. Re-scan or run the release gate:
+
+   ```bash
+   ace-git-secrets check-release --strict
+   ```
+
+### Human-readable reporting
+
+Generate a Markdown report when you need to share findings with reviewers:
+
+```bash
+ace-git-secrets scan --report-format markdown
+```
+
+### Faster large-repository scans
+
+Limit the scan scope for triage work:
+
+```bash
+ace-git-secrets scan --since "6 months ago"
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | Success, or no tokens found for scan/check workflows |
+| `1` | Tokens found, or partial revocation success/failure |
+| `2` | Command error such as missing dependencies, invalid input, or I/O failure |
+
+## Troubleshooting
+
+### "gitleaks is required"
+
+Install the scanner and re-run:
+
+```bash
+brew install gitleaks
+```
+
+### "git-filter-repo is required"
+
+Install the rewrite tool before using `rewrite-history`:
+
+```bash
+brew install git-filter-repo
+```
+
+### Scan file missing `raw_value`
+
+Re-run `scan` and use the saved JSON report path that the command prints. Do not build the `--scan-file` input by
+redirecting verbose stdout.
+
+### Scan is slow on a large repository
+
+Limit the scan window:
+
+```bash
+ace-git-secrets scan --since "30 days ago"
+```
+
+### False positives
+
+Add a whitelist entry for known safe examples or fixtures in `.ace/git-secrets/config.yml`.
+
+## Related Docs
+
+- [Getting Started](getting-started.md)
+- [Handbook Catalog](handbook.md)
+- Runtime help: `ace-git-secrets --help`

data/exe/ace-git-secrets

@@ -0,0 +1,19 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/ace/git/secrets"
+require "ace/support/cli"
+
+args = ARGV.empty? ? ["--help"] : ARGV
+
+# Start ace-support-cli with exception-based exit code handling (per ADR-023)
+begin
+  # Preload config before dispatch to avoid first-access races in parallel contexts.
+  Ace::Git::Secrets.config
+  Ace::Support::Cli::Runner.new(Ace::Git::Secrets::CLI).call(args: args)
+rescue SystemExit => e
+  exit(e.status)
+rescue Ace::Support::Cli::Error => e
+  warn e.message
+  exit(e.exit_code)
+end

data/handbook/agents/security-audit.ag.md

@@ -0,0 +1,237 @@
+---
+name: security-audit
+description: Perform security audits to detect leaked authentication tokens in Git repositories
+expected_params:
+  required: []
+  optional:
+  - scope: 'Audit scope: full (all history), recent (last 30 days), staged (uncommitted)'
+  - confidence: 'Minimum confidence level: low, medium, high (default: medium)'
+  - format: 'Output format: table, json, summary (default: summary)'
+last_modified: '2025-12-20'
+type: agent
+source: ace-git-secrets
+---
+
+You are a security audit specialist focused on detecting leaked authentication tokens in Git repositories using the **ace-git-secrets** gem.
+
+## Core Responsibilities
+
+Your primary role is to **DETECT** and **REPORT** security issues, not to automatically remediate them:
+- Scan Git history for leaked authentication tokens
+- Identify token types and assess risk levels
+- Provide actionable remediation guidance
+- Report findings in a clear, prioritized format
+
+## Primary Tool: ace-git-secrets
+
+You use **ace-git-secrets** for all security scanning operations. This tool detects:
+- GitHub PATs (ghp_, gho_, ghs_, ghr_, github_pat_)
+- LLM API keys (Anthropic sk-ant-, OpenAI sk-)
+- Cloud credentials (AWS AKIA/ASIA, Google AIza)
+- Other common tokens (Slack xox*, NPM npm_)
+
+## Audit Modes
+
+### Full Audit (Default)
+Scan entire Git history:
+```bash
+ace-git-secrets scan --format table
+```
+
+### Recent Changes
+Scan commits from the last 30 days:
+```bash
+ace-git-secrets scan --since "30 days ago" --format table
+```
+
+### Staged Changes Only
+Check uncommitted changes before commit:
+```bash
+ace-git-secrets scan --branch HEAD --format table
+```
+
+### High Confidence Only
+Filter for high-confidence detections:
+```bash
+ace-git-secrets scan --confidence high --format table
+```
+
+## Output Formats
+
+### Summary (Default)
+Quick overview of findings:
+```bash
+ace-git-secrets scan --format table
+```
+
+### JSON (Automation)
+Machine-readable output:
+```bash
+ace-git-secrets scan --format json --output audit-results.json
+```
+
+### Pre-Release Check
+CI/CD friendly exit codes:
+```bash
+ace-git-secrets check-release --strict
+# Exit 0: Clean
+# Exit 1: Tokens found
+```
+
+## Audit Workflow
+
+### Step 1: Initial Scan
+```bash
+# Run comprehensive scan
+ace-git-secrets scan --format table
+```
+
+### Step 2: Analyze Results
+For each detected token, assess:
+1. **Token Type**: What service does it authenticate to?
+2. **Confidence**: How certain is the detection?
+3. **Location**: Which commit and file?
+4. **Exposure Risk**: Is this in a public/shared branch?
+
+### Step 3: Prioritize Findings
+Order by risk:
+1. **Critical**: High-confidence tokens in public branches
+2. **High**: High-confidence tokens in any branch
+3. **Medium**: Medium-confidence detections
+4. **Low**: Low-confidence detections (review for false positives)
+
+### Step 4: Generate Report
+Provide actionable findings with:
+- Token count by type and confidence
+- Affected commits and files
+- Remediation priority
+- Next steps
+
+## Gitleaks Integration
+
+ace-git-secrets uses gitleaks when available for enhanced detection:
+```bash
+# Check if gitleaks is available
+which gitleaks
+
+# If not installed (recommended for comprehensive scanning)
+brew install gitleaks
+```
+
+When gitleaks is not available, ace-git-secrets falls back to built-in Ruby pattern matching.
+
+## Response Format
+
+### Audit Summary
+```markdown
+## Security Audit Results
+
+**Repository:** [repo path]
+**Scan Scope:** [full history / since date / staged only]
+**Detection Method:** [gitleaks / ruby patterns]
+
+### Findings Summary
+
+| Confidence | Count | Risk Level |
+|------------|-------|------------|
+| High       | N     | Critical   |
+| Medium     | N     | Review     |
+| Low        | N     | Verify     |
+
+### Critical Findings (Immediate Action Required)
+
+1. **[token_type]** in `path/to/file`
+   - Commit: `abc123`
+   - Line: 42
+   - Action: Revoke immediately via [provider dashboard URL]
+
+### Recommendations
+
+1. **Immediate**: Revoke all high-confidence tokens
+2. **Short-term**: Rewrite Git history to remove tokens
+3. **Long-term**: Add pre-commit hooks to prevent future leaks
+```
+
+### Clean Repository
+```markdown
+## Security Audit Results
+
+**Repository:** [repo path]
+**Scan Scope:** [scope]
+**Status:** CLEAN
+
+No authentication tokens detected in the scanned scope.
+
+### Recommendations
+- Continue using pre-commit hooks
+- Schedule periodic audits
+- Review any new credentials before committing
+```
+
+## False Positive Handling
+
+If detections appear to be false positives:
+1. Verify the matched content is not an actual token
+2. Check if it's a placeholder/example in documentation
+3. Recommend adding to whitelist:
+   ```yaml
+   # .ace/git-secrets/config.yml
+   whitelist:
+     - pattern: 'ghp_example_pattern'
+       reason: Documentation example
+   ```
+
+## Integration Points
+
+### Pre-Commit Check
+```bash
+ace-git-secrets check-release --strict
+```
+
+### CI/CD Pipeline
+```yaml
+- name: Security Audit
+  run: ace-git-secrets check-release --strict
+```
+
+### Scheduled Audits
+Run periodic full audits:
+```bash
+ace-git-secrets scan --format json --output weekly-audit.json
+```
+
+## Important Notes
+
+- **Detection Only**: This agent identifies issues but does not automatically remediate
+- **Token Safety**: Never log or display full token values
+- **Gitleaks Priority**: Uses gitleaks when available for comprehensive detection
+- **False Positives**: Always verify medium/low confidence findings
+- **Remediation Workflow**: Direct users to `token-remediation.wf.md` for cleanup
+
+## Common Audit Scenarios
+
+### Pre-Release Audit
+```bash
+# Before publishing a gem or pushing to public repo
+ace-git-secrets check-release --strict
+```
+
+### Post-Incident Audit
+```bash
+# After suspected token exposure
+ace-git-secrets scan --format json --output incident-audit.json
+```
+
+### New Repository Audit
+```bash
+# When onboarding a new repository
+ace-git-secrets scan --confidence medium --format table
+```
+
+### Pull Request Audit
+```bash
+# Check only changes in PR
+ace-git-secrets scan --branch feature-branch --since "$(git merge-base main feature-branch)"
+```
+
+Remember: Your role is to **detect and report** security issues. For remediation actions (revoking tokens, rewriting history), direct users to follow the `token-remediation.wf.md` workflow instruction.

data/handbook/guides/security/ruby.md

@@ -0,0 +1,27 @@
+# Ruby Security Examples
+
+This file provides Ruby-specific examples related to the main [Security Guide](../security.g.md).
+
+* **Dependency Scanning:** `bundler-audit`, GitHub Dependabot/Security Alerts
+* **Static Analysis (SAST):** `brakeman` (for Rails)
+* **Input Validation:** ActiveModel validations (Rails), custom validation logic.
+* **Secure Configuration:** Using environment variables, Rails credentials.
+
+```ruby
+# Example: Secure file path handling (avoiding directory traversal)
+require 'pathname'
+
+BASE_DIR = Pathname.new('/safe/base/path').realpath
+
+def read_user_file(user_input)
+  requested_path = BASE_DIR.join(user_input)
+
+  # Basic check (more robust checks might be needed)
+  unless requested_path.realpath.to_s.start_with?(BASE_DIR.to_s)
+    raise ArgumentError, "Invalid file path: #{user_input}"
+  end
+
+  # Proceed with reading requested_path if valid
+  File.read(requested_path)
+end
+```

data/handbook/guides/security/rust.md

@@ -0,0 +1,51 @@
+# Rust Security Examples
+
+This file provides Rust-specific examples related to the main [Security Guide](../security.g.md).
+
+* **Dependency Scanning:** `cargo audit`, GitHub Dependabot
+* **Static Analysis (SAST):** `cargo clippy` (catches some security issues), potentially external SAST tools.
+* **Input Validation:** Using Rust's type system, crates like `validator`.
+* **Secure Configuration:** Environment variables, configuration files with restricted permissions, secrets management services.
+* **Memory Safety:** Rust's core safety features prevent many common vulnerabilities (e.g., buffer overflows, use-after-free).
+
+```rust
+use std::path::{Path, PathBuf};
+use std::fs;
+use std::io;
+
+// Example: Secure file path handling
+fn get_safe_path(base_dir: &Path, user_input: &str) -> io::Result<PathBuf> {
+    let joined_path = base_dir.join(user_input);
+    // Canonicalize resolves '..' and symlinks
+    let canonical_path = fs::canonicalize(&joined_path)?;
+
+    // Ensure the canonical path is still within the base directory
+    if canonical_path.starts_with(base_dir) {
+        Ok(canonical_path)
+    } else {
+        Err(io::Error::new(
+            io::ErrorKind::PermissionDenied,
+            format!("Path traversal attempt detected: {}", user_input),
+        ))
+    }
+}
+
+fn main() -> io::Result<()> {
+    let base = PathBuf::from("/safe/base/path");
+    // Simulate creating the directory if it doesn't exist for the example
+    // fs::create_dir_all(&base)?;
+
+    let user_input = "safe_file.txt";
+    match get_safe_path(&base, user_input) {
+        Ok(path) => println!("Accessing safe path: {:?}", path),
+        Err(e) => eprintln!("Error: {}", e),
+    }
+
+    let malicious_input = "../outside_file.txt";
+    match get_safe_path(&base, malicious_input) {
+        Ok(path) => println!("Accessing malicious path: {:?}", path),
+        Err(e) => eprintln!("Error: {}", e), // Should print PermissionDenied error
+    }
+    Ok(())
+}
+```

data/handbook/guides/security/typescript.md

@@ -0,0 +1,33 @@
+# TypeScript Security Examples
+
+This file provides TypeScript-specific examples related to the main [Security Guide](../security.g.md).
+
+* **Dependency Scanning:** `npm audit`, `yarn audit`, Snyk, GitHub Dependabot
+* **Static Analysis (SAST):** ESLint security plugins (e.g., `eslint-plugin-security`), SonarQube/SonarCloud
+* **Input Validation:** Libraries like `zod`, `joi`, `class-validator`.
+* **Secure Configuration:** Environment variables, secrets management services (e.g., AWS Secrets Manager, HashiCorp Vault).
+
+```typescript
+import path from 'path';
+
+// Example: Secure file path handling
+const ALLOWED_BASE_DIR = path.resolve('/safe/base/path');
+
+function getSafeFilePath(userInput: string): string {
+  const resolvedPath = path.resolve(path.join(ALLOWED_BASE_DIR, userInput));
+
+  // Check if the resolved path is still within the allowed directory
+  if (!resolvedPath.startsWith(ALLOWED_BASE_DIR)) {
+    throw new Error(`Invalid file path requested: ${userInput}`);
+  }
+  return resolvedPath;
+}
+
+// Example: Escaping output to prevent XSS (conceptual - use a library)
+import { escape } from 'your-html-escaping-library';
+
+function renderUserComment(comment: string): string {
+  const escapedComment = escape(comment);
+  return `<div class="comment">${escapedComment}</div>`;
+}
+```