Skip to main content

Gitleaks Guide for Bike4Mind

This document provides detailed information about our Gitleaks implementation for detecting and preventing secrets from being committed to the repository.

What is Gitleaks?​

Gitleaks is a SAST (Static Application Security Testing) tool designed to detect sensitive information such as passwords, API keys, and tokens in code repositories. It helps prevent the accidental exposure of secrets through the codebase.

Setup Instructions​

We've simplified the setup process with an installation script:

# Run from the project root
bash install-hooks.sh

What the installation script does:​

  1. Installs gitleaks if not already present (via Homebrew on macOS)
  2. Sets up a gitleaks pre-commit hook as part of our Husky configuration
  3. Tests the installation to ensure everything works correctly

Manual Installation (if needed)​

If the installation script doesn't work for your environment:

  1. Install gitleaks manually:

    # macOS
    brew install gitleaks

    # Linux
    sudo apt-get install gitleaks

    # Or download from github.com/gitleaks/gitleaks/releases

  2. Make sure gitleaks is in your PATH and executable:

    which gitleaks
    chmod +x $(which gitleaks)

  3. Create the gitleaks script in the Husky directory:

    cp .husky/gitleaks-pre-commit.sh.example .husky/gitleaks-pre-commit.sh
    chmod +x .husky/gitleaks-pre-commit.sh

  4. Update the pre-commit hook to include gitleaks:

    # Add to .husky/pre-commit
    . "$(dirname -- "$0")/gitleaks-pre-commit.sh"

How It Works​

Every time you attempt to commit changes:

  1. The Husky pre-commit hook runs automatically
  2. It runs lint-staged for code quality checks
  3. It then runs the gitleaks script which:
    • Collects all staged files
    • Copies them to a temporary directory
    • Scans the files for potential secrets
  4. If secrets are found, the commit is blocked with detailed information
  5. If no secrets are found, the commit proceeds normally

Common Commands​

Testing Your Setup​

To verify gitleaks is working:

# Check installation
gitleaks version

# Create a test file with a secret
echo 'private_key="-----BEGIN RSA PRIVATE KEY-----"' > test-secret.txt
git add test-secret.txt
git commit -m "test secret detection"

Bypassing the Hook​

Only use when absolutely necessary and you're sure no real secrets are included:

git commit --no-verify -m "your commit message"

Full Codebase Scan​

To scan your entire codebase for secrets:

# Using our helper script
./review-secrets.sh

# Or manually
gitleaks detect --verbose --redact --path .

Handling Detections​

When gitleaks blocks your commit due to detected secrets:

  1. Review the findings - Look at the specific files and lines it flagged
  2. Remove the secrets - Replace with:
    • SST Secrets: secrets.VARIABLE_NAME
    • Environment variables: process.env.VARIABLE_NAME
    • References to a secrets manager
  3. Commit again - After removing the secrets

Types of Secrets Detected​

Gitleaks can detect many types of secrets, including:

  • AWS access keys and secret keys
  • API keys for various services
  • Database connection strings
  • Private keys (RSA, SSH, etc.)
  • Passwords and authentication tokens
  • JWT tokens
  • OAuth credentials

Troubleshooting​

Gitleaks Not Found​

If you get an error that gitleaks is not found:

# Re-run the install script
bash install-hooks.sh

# Or manually install gitleaks
brew install gitleaks  # macOS

False Positives​

If you believe gitleaks has flagged a false positive:

  1. Examine the flagged content to confirm it's not actually sensitive
  2. Either:
    • Reformat the code to avoid triggering the detection
    • Use git commit --no-verify (with caution)
    • Add a note in your PR/commit explaining why it was bypassed

Hook Not Running​

If the gitleaks hook isn't running:

# Check if Husky is properly installed
ls -la .husky/pre-commit .husky/gitleaks-pre-commit.sh

# Ensure both files are executable
chmod +x .husky/pre-commit .husky/gitleaks-pre-commit.sh

# Reinstall Husky if needed
npm run prepare

Best Practices​

  1. Never hardcode secrets - Even temporarily
  2. Use SST Secrets - Our preferred method for managing secrets
  3. Use environment variables - As a secondary option
  4. Create API endpoints - For client-side code that needs access to protected services
  5. Avoid test credentials - Even example credentials can trigger detections
  6. Scan regularly - Run full scans periodically with ./review-secrets.sh

Support​

If you have questions or issues with the Gitleaks setup:

  1. Consult this guide first
  2. Reach out to the security team
  3. File a report if you believe you've found a bug in our implementation