ggshield Secret Scanner

Detect 500+ types of hardcoded secrets (API keys, credentials, tokens) before they leak into git. Wraps GitGuardian's ggshield CLI.

Security Scan

The skill appears to implement a legitimate ggshield wrapper and only needs a GitGuardian API key, but there are metadata/source inconsistencies and minor privacy/handling claims that don't fully add up — review the origin and where you store the API key before installing.

Purpose & Capability

The skill's name, README, SKILL.md, pyproject.toml and code all consistently implement a wrapper around the ggshield CLI and therefore legitimately need the ggshield binary and GITGUARDIAN_API_KEY. However, the registry metadata at the top of the report claimed no required binaries/env vars while SKILL.md and ggshield_skill.py require ggshield and GITGUARDIAN_API_KEY — an incoherence in published metadata. The repository/homepage fields also disagree in places (references to both GitGuardian and a third-party repo 'achillemascia'), which weakens provenance trust.

Instruction Scope

SKILL.md and the code constrain actions to scanning repos/files/staged changes/docker images and installing hooks. The implementation invokes the ggshield CLI via subprocess and only pulls the API key from GITGUARDIAN_API_KEY. It does not instruct reading arbitrary system files or other credentials. That said, SKILL.md asserts that ONLY metadata (hashes, path, line no.) is sent — this is a claim about ggshield/ GitGuardian behavior rather than the skill itself; if you need stronger guarantees review ggshield/GitGuardian docs and consider on-prem scanning options.

Install Mechanism

This is an instruction-only skill (no installer in the registry). The SKILL.md instructs users to pip install ggshield (a normal, low-risk package install from PyPI). The package includes a pyproject.toml listing dependencies (ggshield, pygitguardian) but no automated download-from-unknown-URL behavior. Overall install risk is low, but verify you install ggshield/pygitguardian from the official PyPI and confirm the skill repo origin before running any install commands.

Credentials

The only secret required by the code and documentation is GITGUARDIAN_API_KEY, which is proportionate to the stated purpose. Two caveats: (1) registry metadata omitted this required env var (incoherent metadata), and (2) SKILL.md suggests persisting the API key in shell profiles or a .env file — storing long-lived API keys in shell startup files or plaintext .env can increase exposure risk. Consider using ephemeral credentials or restricting the key and using GitGuardian's enterprise/on-prem options if you need stricter data controls.

Persistence & Privilege

The skill does not request permanent platform-wide presence (always: false) and does not modify other skills or global agent settings. It runs as an ordinary skill wrapper and uses subprocess calls to ggshield; autonomous invocation is allowed (platform default) but is not combined with elevated privileges here.

What to consider before installing

What to check before installing: - Verify provenance: the package references GitGuardian and also a third-party repo; confirm the skill's homepage/repository and author are legitimate before installing. The registry metadata in this listing omitted required fields (ggshield binary and GITGUARDIAN_API_KEY) — treat that as a red flag about bookkeeping/maintainer quality. - Install ggshield from the official source (pip install ggshield) and confirm package authenticity (check PyPI project page and upstream GitHub). - Protect your API key: avoid long-lived keys in plaintext ~/.bashrc, ~/.zshrc, or committed .env files. Use least privilege keys, rotate them regularly, and consider using on-prem or restricted GitGuardian options if you cannot risk metadata transmission. - Review ggshield/GitGuardian privacy docs to confirm what is sent by scans; the skill relies on ggshield for network behavior. - Consider running the skill in a controlled environment first (local repo, test data) to verify behavior. If you need higher assurance, request an official maintainer confirmation or use an enterprise/on-prem deployment model.

Overview

ggshield is a CLI tool that detects hardcoded secrets in your codebase. This Moltbot skill brings secret scanning capabilities to your AI agent.

What Are "Secrets"?

Secrets are sensitive credentials that should NEVER be committed to version control:

• AWS Access Keys, GCP Service Accounts, Azure credentials
• API tokens (GitHub, Slack, Stripe, etc.)
• Database passwords and connection strings
• Private encryption keys and certificates
• OAuth tokens and refresh tokens
• PayPal/Stripe API keys
• Email server credentials

Why This Matters

A single leaked secret can:

• 🔓 Compromise your infrastructure
• 💸 Incur massive cloud bills (attackers abuse your AWS account)
• 📊 Expose customer data (GDPR/CCPA violation)
• 🚨 Trigger security incidents and audits

ggshield catches these before they reach your repository.

Features

Commands Available

1. scan-repo

Scans an entire git repository for secrets (including history).

@clawd scan-repo /path/to/my/project

Output:

🔍 Scanning repository...
✅ Repository clean: 1,234 files scanned, 0 secrets found

Output on detection:

❌ Found 2 secrets:

- AWS Access Key ID in config/prod.py:42
- Slack API token in .env.backup:8

Use 'ggshield secret ignore --last-found' to ignore, or remove them.

2. scan-file

Scans a single file for secrets.

@clawd scan-file /path/to/config.py

3. scan-staged

Scans only staged git changes (useful pre-commit check).

@clawd scan-staged

This runs on your git add-ed changes only (fast!).

4. install-hooks

Installs ggshield as a git pre-commit hook.

@clawd install-hooks

After this, every commit is automatically scanned:

$ git commit -m "Add config"
🔍 Running ggshield pre-commit hook...
❌ Secrets detected! Commit blocked.
Remove the secrets and try again.

5. scan-docker

Scans Docker images for secrets in their layers.

@clawd scan-docker my-app:latest

Installation

Prerequisites

1. ggshield CLI: Install via pip

   pip install ggshield>=1.15.0
   

2. GitGuardian API Key: Required for secret detection

   • Sign up: https://dashboard.gitguardian.com (free)
   • Generate API key in Settings
   • Set environment variable:

export GITGUARDIAN_API_KEY="your-api-key-here"

3. Python 3.8+: Required by ggshield

Install Skill

clawdhub install ggshield-scanner

The skill is now available in your Moltbot workspace.

In Your Moltbot Workspace

Start a new Moltbot session to pick up the skill:

moltbot start
# or via messaging: @clawd list-skills

Usage Patterns

Pattern 1: Before Pushing (Security Check)

Dev: @clawd scan-repo .
Moltbot: ✅ Repository clean. All good to push!

Dev: git push

Pattern 2: Audit Existing Repo

Dev: @clawd scan-repo ~/my-old-project
Moltbot: ❌ Found 5 secrets in history!
         - AWS keys in config/secrets.json
         - Database password in docker-compose.yml
         - Slack webhook in .env.example
Moltbot: Recommendation: Rotate these credentials immediately.
         Consider using git-filter-repo to remove from history.

Pattern 3: Pre-Commit Enforcement

Dev: @clawd install-hooks
Moltbot: ✅ Installed pre-commit hook

Dev: echo "SECRET_TOKEN=xyz" > config.py
Dev: git add config.py
Dev: git commit -m "Add config"
Moltbot: ❌ Pre-commit hook detected secret!
Dev: rm config.py && git reset
Dev: (add config to .gitignore and to environment variables instead)
Dev: git commit -m "Add config" # Now works!

Pattern 4: Docker Image Security

Dev: @clawd scan-docker my-api:v1.2.3
Moltbot: ✅ Docker image clean

Configuration

Environment Variables

These are required for the skill to work:

Variable	Value	Where to Set
GITGUARDIAN_API_KEY	Your API key from https://dashboard.gitguardian.com	~/.bashrc or ~/.zshrc
GITGUARDIAN_ENDPOINT	https://api.gitguardian.com (default, optional)	Usually not needed

Optional ggshield Config

Create ~/.gitguardian/.gitguardian.yml for persistent settings:

verbose: false
output-format: json
exit-code: true

For details: https://docs.gitguardian.com/ggshield-docs/

Privacy & Security

What Data is Sent to GitGuardian?

✅ ONLY metadata is sent:

• Hash of the secret pattern (not the actual secret)
• File path (relative path only)
• Line number

❌ NEVER sent:

• Your actual secrets or credentials
• File contents
• Private keys
• Credentials

Reference: GitGuardian Enterprise customers can use on-premise scanning with no data sent anywhere.

How Secrets Are Detected

ggshield uses:

1. Entropy-based detection: Identifies high-entropy strings (random tokens)
2. Pattern matching: Looks for known secret formats (AWS key prefixes, etc.)
3. Public CVEs: Cross-references disclosed secrets
4. Machine learning: Trained on leaked secrets database

Troubleshooting

"ggshield: command not found"

ggshield is not installed or not in your PATH.

Fix:

pip install ggshield
which ggshield  # Should return a path

"GITGUARDIAN_API_KEY not found"

The environment variable is not set.

Fix:

export GITGUARDIAN_API_KEY="your-key"
# For persistence, add to ~/.bashrc or ~/.zshrc:
echo 'export GITGUARDIAN_API_KEY="your-key"' >> ~/.bashrc
source ~/.bashrc

"401 Unauthorized"

API key is invalid or expired.

Fix:

# Test the API key
ggshield auth status

# If invalid, regenerate at https://dashboard.gitguardian.com → API Tokens
# Then: export GITGUARDIAN_API_KEY="new-key"

"Slow on large repositories"

Scanning a 50GB monorepo takes time. ggshield is doing a lot of work.

Workaround:

# Scan only staged changes (faster):
@clawd scan-staged

# Or specify a subdirectory:
@clawd scan-file ./app/config.py

Advanced Topics

Ignoring False Positives

Sometimes ggshield flags a string that's NOT a secret (e.g., a test key):

# Ignore the last secret found
ggshield secret ignore --last-found

# Ignore all in a file
ggshield secret ignore --path ./config-example.py

This creates .gitguardian/config.json with ignore rules.

Integrating with CI/CD

You can add secret scanning to GitHub Actions / GitLab CI:

# .github/workflows/secret-scan.yml
name: Secret Scan
on: [push]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: pip install ggshield
      - run: ggshield secret scan repo .
        env:
          GITGUARDIAN_API_KEY: ${{ secrets.GITGUARDIAN_API_KEY }}

Enterprise: On-Premise Scanning

If your company uses GitGuardian Enterprise, you can scan without sending data to the cloud:

export GITGUARDIAN_ENDPOINT="https://your-instance.gitguardian.com"
export GITGUARDIAN_API_KEY="your-enterprise-key"

Related Resources

• ggshield Documentation: https://docs.gitguardian.com/ggshield-docs/
• GitGuardian Dashboard: https://dashboard.gitguardian.com (view all secrets found)
• Moltbot Skills: https://docs.molt.bot/tools/clawdhub
• Secret Management Best Practices: https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html

Support

• Bug reports: https://github.com/GitGuardian/ggshield-skill/issues
• Questions: Open an issue or comment on ClawdHub
• ggshield issues: https://github.com/GitGuardian/ggshield/issues

License

MIT License - See LICENSE file

Contributors

• GitGuardian Team
• [Your contributions welcome!]

---

Version: 1.0.0 Last updated: January 2026 Maintainer: GitGuardian