# Semgrep Secret Scan

> Run Semgrep Secrets scanning to detect leaked credentials, API keys, passwords, and access tokens in source code. Use this skill whenever the user asks to scan for secrets, detect leaked credentials, find API keys in code, run secret detection, check for hardcoded passwords, or mentions "semgrep secrets", "secret scan", "credential scan", "key leak", or "token exposure". Also trigger when the user wants to scan Git history for leaked secrets, validate whether detected secrets are still active, or audit a repository for sensitive data exposure. This skill connects to the Semgrep AppSec Platform cloud instance for enhanced detection with semantic analysis, entropy analysis, and HTTP validation of discovered secrets.

- Skill: `vchirrav-eng/semgrep-secret-scan` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add vchirrav-eng/semgrep-secret-scan`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vchirrav-eng/semgrep-secret-scan/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: vchirrav-eng (https://skillmd.com/u/vchirrav-eng)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/vchirrav-eng/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.

| Variable | Required | Purpose |
|---|---|---|
| `SEMGREP_APP_TOKEN` | **Yes** | Auth token from Semgrep AppSec Platform (Settings > Tokens) |
| `SEMGREP_APP_URL` | No | Defaults to `https://semgrep.dev`. Set only for single-tenant deployments. |
| `SEMGREP_REPO_NAME` | No | Override auto-detected repo name for findings linking |

### Quick check

Run the preflight script to validate the environment before scanning:

```bash
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
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**:

```bash
# 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:

| State | Meaning | Action |
|---|---|---|
| **Confirmed Valid** | Secret is active and grants access | **Rotate immediately** |
| **Confirmed Invalid** | Secret has been revoked or expired | Triage as resolved |
| **No Validator** | No automated check available | Manual verification needed |
| **Validation Error** | Check failed (network issue, rate limit) | Retry or verify manually |

## 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):

```bash
export SEMGREP_APP_TOKEN="your-token-here"
```

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

```bash
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:

```yaml
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

```bash
# 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

| Symptom | Fix |
|---|---|
| `Secrets rules not available` | Ensure Secrets is enabled in platform Settings > General > Secrets |
| `Error: Not logged in` | Ensure `SEMGREP_APP_TOKEN` is exported in your shell |
| Historical scan too slow | Repos with >5 GiB history are partially scanned. Consider limiting scope. |
| Generic secrets not working | Requires Semgrep v1.86.0+ and Multimodal enabled in platform |
| Ignoring files doesn't work | Secrets ignores `.semgrepignore`; configure path ignores in the platform |

## 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