ggshield-scanner – OpenClaw Skill

---

name: ggshield-scanner description: Detect 500+ types of hardcoded secrets (API keys, credentials, tokens) before they leak into git. Wraps GitGuardian's ggshield CLI. homepage: https://github.com/GitGuardian/ggshield-skill metadata: clawdbot: requires: bins: ["ggshield"] env: ["GITGUARDIAN_API_KEY"]

ggshield Secret Scanner

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

ggshield Secret Scanner

A MoltHub skill that wraps GitGuardian's ggshield CLI for detecting hardcoded secrets in your code.

What is a MoltHub Skill?

MoltHub skills are capabilities for AI agents (like Cursor, Claude Code, Moltbot, etc.). When you install this skill, your AI agent gains the ability to scan code for secrets.

This is NOT a CLI tool you run in the terminal. Instead, you ask your AI agent to use it:

You: "Scan this repository for secrets"
Agent: [uses ggshield skill] ✅ Repository clean: 0 secrets found

The skill provides the AI agent with methods it can call on your behalf.

What This Skill Does

Scans your code for 500+ types of hardcoded secrets before they're committed to git:

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

Prerequisites

This skill wraps the ggshield CLI - it doesn't embed it. Users need:

1. ggshield installed:

   pip install ggshield
   # or
   uv add ggshield
   

2. GitGuardian API Key (free):

   • Sign up at https://dashboard.gitguardian.com
   • Generate an API key in Settings
   • Create a .env file:

   echo 'GITGUARDIAN_API_KEY=your-api-key-here' > .env
   

Installation

From MoltHub

npx molthub@latest install ggshield-scanner

Manual

Clone this repo into your skills directory:

git clone https://github.com/achillemascia/ggshield-skill.git ~/.moltbot/skills/ggshield-scanner

Available Methods

Method	Description
scan_repo(path)	Scan entire git repository for secrets
scan_file(path)	Scan a single file
scan_staged()	Scan only staged git changes (fast pre-commit)
install_hooks(type)	Install git pre-commit or pre-push hook
scan_docker(image)	Scan Docker image layers for secrets

How AI Agents Use This Skill

When an AI agent has this skill installed, you can ask it to scan for secrets in natural language:

You say	Agent does
"Scan this repo for secrets"	Calls scan_repo(".")
"Check if config.py has any hardcoded keys"	Calls scan_file("config.py")
"Are my staged changes safe to commit?"	Calls scan_staged()
"Set up a pre-commit hook to catch secrets"	Calls install_hooks("pre-commit")
"Scan my Docker image for secrets"	Calls scan_docker("myapp:latest")

Example conversation:

You: Before I push, can you check if there are any secrets in my staged changes?

Agent: I'll scan your staged changes for secrets.

       ✅ Staged changes are clean

       No hardcoded secrets detected. Safe to commit!

Local Development & Testing

1. Set up environment

cd ggshield-skill

# Install dependencies
uv sync

# Create .env file with your API key
echo 'GITGUARDIAN_API_KEY=your-api-key-here' > .env

2. Test the module imports

uv run python -c "from ggshield_skill import GGShieldSkill; s = GGShieldSkill(); print(s.name)"
# Output: ggshield

3. Test scanning

Create a test file with fake secrets:

mkdir -p test-data
echo 'AWS_KEY="AKIAIOSFODNN7EXAMPLE"' > test-data/secrets.py
echo 'SLACK_TOKEN="xoxb-1234567890-abcdefghij"' >> test-data/secrets.py

Run a scan (loads API key from .env):

export $(cat .env | xargs) && uv run python -c "
import asyncio
from ggshield_skill import GGShieldSkill

async def test():
    skill = GGShieldSkill()
    result = await skill.scan_file('./test-data/secrets.py')
    print(result)

asyncio.run(test())
"

4. Test all methods

export $(cat .env | xargs) && uv run python -c "
import asyncio
from ggshield_skill import GGShieldSkill

async def test_all():
    s = GGShieldSkill()

    print('=== scan_repo ===')
    print(await s.scan_repo('.'))

    print('\n=== scan_file ===')
    print(await s.scan_file('./ggshield_skill.py'))

    print('\n=== scan_staged ===')
    print(await s.scan_staged())

    print('\n=== scan_file (missing - should error) ===')
    print(await s.scan_file('/nonexistent.py'))

asyncio.run(test_all())
"

5. Run with pytest (optional)

uv add --dev pytest pytest-asyncio

cat > test_skill.py << 'EOF'
import pytest
from ggshield_skill import GGShieldSkill

def test_skill_initialization():
    """
    GIVEN a GGShieldSkill class
    WHEN instantiated
    THEN it should have correct metadata
    """
    skill = GGShieldSkill()
    assert skill.name == "ggshield"
    assert skill.version == "1.0.0"
    assert skill.requires_api_key is True

@pytest.mark.asyncio
async def test_scan_file_not_found():
    """
    GIVEN a non-existent file path
    WHEN scan_file is called
    THEN it should return an error message
    """
    skill = GGShieldSkill()
    result = await skill.scan_file("/nonexistent/file.py")
    assert "File not found" in result
    assert "❌" in result

@pytest.mark.asyncio
async def test_scan_repo_not_found():
    """
    GIVEN a non-existent directory path
    WHEN scan_repo is called
    THEN it should return an error message
    """
    skill = GGShieldSkill()
    result = await skill.scan_repo("/nonexistent/dir")
    assert "Path not found" in result
    assert "❌" in result
EOF

uv run pytest test_skill.py -v

Testing with Moltbot (Local Integration Test)

Before publishing, you can test the skill with a local Moltbot installation.

1. Install Moltbot

# Quick install
curl -fsSL https://molt.bot/install.sh | bash

# Or via npm
npm install -g moltbot@latest

# Run onboarding
moltbot onboard --install-daemon

2. Set up the API key in your shell

Add to your ~/.zshrc or ~/.bashrc:

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

Then reload: source ~/.zshrc

This way Moltbot picks up the key from your environment - no need to put it in config files.

3. Add your skill locally

# Create the managed skills folder
mkdir -p ~/.clawdbot/skills

# Symlink your skill for live development
ln -s "$(pwd)" ~/.clawdbot/skills/ggshield-scanner

4. Verify your skill is recognized

# List all skills
moltbot skills list

# Check if it's eligible (requirements met)
moltbot skills list --eligible

# Get info about your skill
moltbot skills info ggshield-scanner

5. Test with the agent

# Start an interactive chat
moltbot tui

# Or send a message directly
moltbot message "Scan the current directory for secrets"

Publishing to MoltHub

1. Login to MoltHub

npx molthub@latest login

This opens a browser for GitHub authentication.

2. Publish

npx molthub@latest publish . \
  --slug ggshield-scanner \
  --name "ggshield Secret Scanner" \
  --version 1.0.0 \
  --changelog "Initial release: secret scanning for AI agents"

3. Verify

npx molthub@latest search "ggshield"

Visit: https://clawdhub.com/skills/ggshield-scanner

Project Structure

ggshield-skill/
├── SKILL.md           # MoltHub metadata + documentation
├── ggshield_skill.py  # Main Python implementation
├── pyproject.toml     # uv/pip dependencies
├── README.md          # This file
├── .env               # Your API key (not committed)
├── .env.example       # Example .env file
├── .gitignore
└── LICENSE            # MIT

How It Works

The skill is a Python class that:

1. Wraps ggshield CLI - Calls ggshield via subprocess
2. Handles errors gracefully - Missing API key, ggshield not installed, file not found
3. Returns user-friendly messages - With emoji indicators (✅ ❌ 🔍)
4. Async methods - Compatible with async AI agent frameworks

class GGShieldSkill:
    async def scan_repo(self, path: str) -> str: ...
    async def scan_file(self, path: str) -> str: ...
    async def scan_staged(self) -> str: ...
    async def install_hooks(self, hook_type: str = "pre-commit") -> str: ...
    async def scan_docker(self, image: str) -> str: ...

Privacy & Security

• Local scanning - ggshield sends only metadata (hashes, not actual secrets) to GitGuardian
• Enterprise option - GitGuardian Enterprise supports on-premise scanning with zero data transmission
• See ggshield privacy docs for details

Related

• ggshield GitHub
• GitGuardian Dashboard
• MoltHub Registry

License

MIT