Semgrep Secret Scan

Semgrep Secrets Scan Skill

Run secrets detection scans on source code repositories using Semgrep Secrets, connected to the organization's Semgrep AppSec Platform cloud instance. Semgrep Secrets uses semantic analysis, improved entropy analysis, and HTTP validation to accurately surface sensitive credentials in code.

Prerequisites

Before running a scan, verify the following environment variables are configured. If any are missing, inform the user and point them to the Environment Setup section below.

Quick check

Run the preflight script to validate the environment before scanning:

bash /path/to/semgrep-secret-scan/scripts/preflight.sh

If the preflight fails, do NOT proceed with the scan — resolve the issues first.

Important: Enable Secrets in Semgrep AppSec Platform

Secrets scanning must be enabled at the organization level before it works:

1. Sign in to https://semgrep.dev/orgs/vchirrav_personal_org
2. Go to Settings > General > Secrets
3. Click the Secrets scans toggle to enable it
4. (Optional) Enable Generic secrets for AI-powered detection of non-specific credentials
5. (Optional) Enable Historical scanning to scan Git commit history for past leaks

How to Run a Secrets Scan

Step 1: Preflight

Always run the preflight check first:

bash <skill-dir>/scripts/preflight.sh

This validates that semgrep is installed, SEMGREP_APP_TOKEN is set, the current directory is a Git repository, and Secrets scanning is accessible.

Step 2: Execute the scan

Run the scan script from the root of the target project:

# Standard secrets scan
bash <skill-dir>/scripts/run-secret-scan.sh

# Secrets scan including Git history (finds past leaks — takes longer)
bash <skill-dir>/scripts/run-secret-scan.sh --historical

# Secrets scan with JSON output saved to a file
bash <skill-dir>/scripts/run-secret-scan.sh --output json

# Secrets scan with SARIF output
bash <skill-dir>/scripts/run-secret-scan.sh --output sarif

# Diff-aware scan (only check changed files — for PR/MR pipelines)
bash <skill-dir>/scripts/run-secret-scan.sh --diff-aware

Step 3: Review results

After the scan completes:

1. Terminal output shows discovered secrets with validation status.
2. Semgrep AppSec Platform at https://semgrep.dev/orgs/vchirrav_personal_org has the full Secrets dashboard with:
   • Validation status: Confirmed (secret is active), Confirmed Invalid, or No Validator
   • Secret type: e.g., AWS key, GitHub token, generic password
   • Code location: clickable links to the exact file and line
   • Remediation guidance: steps to rotate and revoke the leaked credential
3. If --output json or --output sarif was used, the report file is saved in the current directory as semgrep-secrets-results.<format>.

Scan Modes Explained

Standard scan (semgrep ci --secrets): Scans all files in the current codebase for secrets. Semgrep Secrets scans all files including those in .semgrepignore, since secrets can appear in non-code files. To ignore specific files for secrets scanning, configure path ignores in the Semgrep AppSec Platform under Projects > [your project] > Settings > Path Ignores.

Historical scan (semgrep ci --secrets with historical enabled): Also scans Git commit history to find secrets that were committed and later removed. Only surfaces validated/confirmed secrets from history to maintain a high true-positive rate. Requires Semgrep v1.65.0+.

Diff-aware scan (semgrep ci --secrets with SEMGREP_BASELINE_REF): Only scans changed files since the baseline. Use for PR/MR pipelines. Historical scanning is not performed in diff-aware mode.

Generic secrets (AI-powered): When enabled in platform settings, uses Semgrep Multimodal to detect non-specific credentials by analyzing keywords (auth, key, password) and nearby values. Requires Semgrep v1.86.0+ and Multimodal enabled.

Secret Validation States

Semgrep Secrets validates discovered secrets via HTTP to check if they are still active:

Environment Setup for Project Teams

Project teams need to do the following one-time setup to use this skill:

1. Generate a SEMGREP_APP_TOKEN

1. Sign in to https://semgrep.dev/orgs/vchirrav_personal_org
2. Go to Settings > Tokens
3. Click Create new token
4. Copy the token value

2. Configure the token in your environment

For Claude Code / local development:

Add to your shell profile (~/.bashrc, ~/.zshrc, or equivalent):

export SEMGREP_APP_TOKEN="your-token-here"

Or create a .env file in your project root (add .env to .gitignore!):

SEMGREP_APP_TOKEN=your-token-here

For CI/CD (GitHub Actions):

1. Go to your repo Settings > Secrets and variables > Actions
2. Add a new repository secret: SEMGREP_APP_TOKEN with the token value
3. Reference it in your workflow:

env:
  SEMGREP_APP_TOKEN: ${{ secrets.SEMGREP_APP_TOKEN }}

For CI/CD (GitLab CI):

1. Go to Settings > CI/CD > Variables
2. Add SEMGREP_APP_TOKEN as a masked variable

For CI/CD (Other providers):

Set SEMGREP_APP_TOKEN as a secret/environment variable in your CI provider's configuration. See https://semgrep.dev/docs/semgrep-ci/sample-ci-configs for provider-specific examples.

3. Install Semgrep CLI

# macOS
brew install semgrep

# pip (any OS)
pip install semgrep

# Docker (no local install needed)
docker run --rm -v "${PWD}:/src" semgrep/semgrep semgrep ci --secrets

4. Enable Secrets in the platform

This is a one-time step for the organization admin:

1. Sign in to https://semgrep.dev/orgs/vchirrav_personal_org
2. Go to Settings > General > Secrets
3. Enable the Secrets scans toggle
4. Optionally enable Generic secrets and Historical scanning

Troubleshooting

Reference

• Semgrep AppSec Platform: https://semgrep.dev/orgs/vchirrav_personal_org
• Secrets Overview: https://semgrep.dev/docs/semgrep-secrets/overview
• Getting Started with Secrets: https://semgrep.dev/docs/semgrep-secrets/getting-started
• Historical Scanning: https://semgrep.dev/docs/semgrep-secrets/historical-scanning
• Generic Secrets (AI): https://semgrep.dev/docs/semgrep-secrets/generic-secrets