ace-git-secrets 0.13.0

data/handbook/guides/security.g.md

@@ -0,0 +1,155 @@
+---
+doc-type: guide
+title: Security Guidelines
+purpose: Documentation for ace-git-secrets/handbook/guides/security.g.md
+ace-docs:
+  last-updated: 2026-01-08
+  last-checked: 2026-03-21
+---
+
+# Security Guidelines
+
+## Goal
+
+This guide outlines essential security practices, checklists, and procedures to follow during development to
+minimize vulnerabilities and protect project assets and user data.
+
+## 1. Security Review Checklist
+
+- **Input Validation**
+  - All user inputs are sanitized (e.g., against injection attacks like SQLi, XSS)
+  - File paths are canonicalized and validated against allowed directories (prevent path traversal)
+  - URLs are validated and checked against allowlists if applicable
+
+- **Authentication & Authorization**
+  - Secrets (API keys, passwords, tokens) are securely stored (e.g., using vaults, environment variables, not
+    hardcoded)
+  - Access tokens have appropriate lifespans and are rotated/refreshed securely
+  - Permissions and roles are correctly enforced for all actions
+
+- **Data Protection**
+  - Sensitive data is encrypted at rest and in transit
+  - No secrets or sensitive information are included in logs
+  - Secure methods are used for data deletion when required
+
+- **Network Security**
+  - Use TLS/SSL (HTTPS) for all external network communication
+  - Ensure proper certificate validation
+  - Configure reasonable network timeouts to prevent resource exhaustion
+
+- **Dependency Management**
+  - Regularly scan dependencies for known vulnerabilities using appropriate tools for your language/ecosystem
+    (e.g., GitHub Dependabot or language-specific scanners)
+  - Keep dependencies updated
+
+- **Secure Defaults**
+  - Configure services and libraries with security in mind (e.g., disable default accounts, enable security features)
+
+### 2. Best Practices Examples (Conceptual)
+
+**Secure Configuration:**
+Load sensitive configuration like API keys, encryption keys, and database credentials from secure sources
+(environment variables, secrets management systems) rather than hardcoding them. Configure security settings
+like TLS versions and timeouts appropriately.
+
+```plaintext
+// Pseudocode for loading configuration securely
+config = loadConfiguration();
+
+// Fetch sensitive keys from environment or secret manager
+config.encryptionKey = getSecret("ENCRYPTION_KEY");
+config.apiKey = getSecret("API_KEY");
+
+// Set security-related options
+config.requestTimeout = 30; // seconds
+config.sslVerification = true;
+config.minTlsVersion = "TLSv1.2";
+
+applyConfiguration(config);
+```
+
+**Secure File Handling:**
+When handling file paths provided by users or external systems, always validate and sanitize them.
+Canonicalize the path (resolve `..`, symbolic links) and ensure it falls within permitted base directories
+to prevent path traversal attacks.
+
+```plaintext
+// Pseudocode for safe file path validation
+function getSafeFilePath(untrustedPath, allowedBaseDir) {
+  // Normalize the path (e.g., resolve '.', '..')
+  normalizedPath = normalizePath(untrustedPath);
+
+  // Get the absolute path
+  absolutePath = resolveAbsolutePath(normalizedPath);
+
+  // Ensure the absolute path starts with the allowed base directory
+  if (!absolutePath.startsWith(allowedBaseDir)) {
+    throw new SecurityError("Access denied: Path traversal attempt detected.");
+  }
+
+  // Optional: Check if the specific file exists and has correct permissions
+  if (!fileExists(absolutePath) || !checkPermissions(absolutePath)) {
+    throw new Error("File not accessible.");
+  }
+
+  return absolutePath;
+}
+```
+
+**Secure Process Execution:**
+Avoid executing external commands based directly on user input. If dynamic command execution is necessary, use
+an allowlist of permitted commands and strictly sanitize any arguments passed to them. Execute commands with the
+minimum required privileges and within restricted environments (e.g., specific working directory, chroot jail
+if applicable).
+
+```plaintext
+// Pseudocode for safer command execution
+function executeAllowedCommand(commandName, arguments) {
+  allowedCommands = ["list_files", "show_content", "find_text"]; // Example allowlist
+
+  if (!allowedCommands.includes(commandName)) {
+    throw new SecurityError("Command not allowed: " + commandName);
+  }
+
+  // Sanitize each argument rigorously based on expected format
+  sanitizedArgs = arguments.map(arg => sanitizeArgument(arg));
+
+  // Execute the command with sanitized arguments in a controlled environment
+  options = {
+    workingDirectory: "/path/to/safe/directory",
+    environmentVariables: { "PATH": "/usr/bin:/bin" } // Minimal PATH
+  };
+  result = runSystemCommand(commandName, sanitizedArgs, options);
+  return result;
+}
+```
+
+### 3. Language/Environment-Specific Examples
+
+For specific code examples demonstrating security best practices, configuration of security tools (e.g.,
+dependency scanners, static analysis security testing - SAST), or framework-specific security features, please
+refer to the examples in the [./security/](./security/) sub-directory.
+
+### 4. Security Disclosure Process
+
+1. **Reporting**
+   - Email: <security@example.com>
+   - Include detailed reproduction steps
+   - Provide impact assessment
+
+2. **Response Timeline**
+   - Initial response: 24 hours
+   - Assessment: 72 hours
+   - Fix timeline: Based on severity
+
+3. **Severity Levels**
+   - Critical: System compromise
+   - High: Data exposure
+   - Medium: Limited impact
+   - Low: Minor issues
+
+## Related Documentation
+
+- [Coding Standards](guide://coding-standards)
+- [Quality Assurance](guide://quality-assurance) (Code Review)
+- [Error Handling](guide://error-handling) (Avoid leaking sensitive info)

data/handbook/skills/as-git-security-audit/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: as-git-security-audit
+description: Perform security audits to detect leaked authentication tokens
+# bundle: wfi://git/security-audit
+# context: no-fork
+# agent: Bash
+user-invocable: true
+allowed-tools:
+  - Bash(ace-git-secrets:*)
+  - Bash(ace-bundle:*)
+  - Read
+argument-hint: "[scan|check-release] [--since=SINCE] [--confidence=LEVEL] [options]"
+last_modified: 2026-01-09
+source: ace-git-secrets
+integration:
+  targets:
+    - claude
+    - codex
+    - gemini
+    - opencode
+    - pi
+  providers: {}
+skill:
+  kind: workflow
+  execution:
+    workflow: wfi://git/security-audit
+---
+
+Load and run `ace-bundle wfi://git/security-audit` in the current project, then follow the loaded workflow as the source of truth and execute it end-to-end instead of only summarizing it.

data/handbook/skills/as-git-token-remediation/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: as-git-token-remediation
+description: Run token remediation and cleanup workflow for git history exposure incidents
+# bundle: wfi://git/token-remediation
+# context: no-fork
+# agent: Bash
+user-invocable: true
+allowed-tools:
+  - Bash(ace-git-secrets:*)
+  - Bash(ace-bundle:*)
+  - Read
+argument-hint: "[scan-only|full]"
+last_modified: 2026-03-12
+source: ace-git-secrets
+skill:
+  kind: workflow
+  execution:
+    workflow: wfi://git/token-remediation
+---
+
+Load and run `ace-bundle wfi://git/token-remediation` in the current project, then follow the loaded workflow as the source of truth and execute it end-to-end instead of only summarizing it.

data/handbook/workflow-instructions/git/security-audit.wf.md

@@ -0,0 +1,247 @@
+---
+doc-type: workflow
+title: Security Audit Workflow
+purpose: security-audit workflow instruction
+ace-docs:
+  last-updated: 2026-02-23
+  last-checked: 2026-03-21
+---
+
+# Security Audit Workflow
+
+## Purpose
+
+Detect and report leaked authentication tokens in Git repositories using ace-git-secrets - scan history, identify risks, and provide remediation guidance.
+
+## Core Responsibilities
+
+**DETECT** and **REPORT** security issues, not automatically remediate:
+- 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
+
+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
+```
+
+## 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)"
+```
+
+## Important Notes
+
+- **Detection Only**: This workflow 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**: For cleanup, use `ace-bundle wfi://git/token-remediation`
+
+## Command Reference
+
+### scan
+- `--since SINCE`: Scan since date (e.g., "30 days ago")
+- `--branch BRANCH`: Scan specific branch
+- `--confidence LEVEL`: Minimum confidence (low, medium, high)
+- `--format FORMAT`: Output format (table, json, summary)
+- `--output FILE`: Save to file
+
+### check-release
+- `--strict`: Fail on any findings
+- `--format FORMAT`: Output format