ggshield Scanner Skill for OpenClaw

OpenClaw ggshield Scanner Skill Overview

The ggshield Scanner skill brings GitGuardian's powerful secret detection engine into your OpenClaw workflow. Instead of memorizing ggshield CLI flags and output formats, you can ask OpenClaw to scan your code for leaked secrets using plain English.

ggshield detects over 500 types of hardcoded secrets — API keys, database credentials, cloud tokens, private keys, and more. The OpenClaw ggshield scanner skill wraps this capability into a conversational interface, making it easy to run scans on demand, set up pre-commit hooks, and interpret results without leaving your development flow.

Typical workflow:

1. Ask OpenClaw to scan your project for secrets.
2. The agent runs ggshield secret scan against your codebase or specific files.
3. Results are returned in a readable summary highlighting any detected secrets, their types, and locations — no need to parse raw CLI output.

Whether you're auditing an existing repo or adding secret scanning to your development process, this skill handles the heavy lifting. Pair it with the 1Password skill for a complete secrets management workflow.

Prerequisites for ggshield Scanner Skill

Before installing the ggshield Scanner skill, make sure you have:

• OpenClaw installed and running (v1.0+)
• ggshield installed — official installation guide
• Python 3.9+ (if installing via pip/pipx) or use standalone packages
• Git installed for repository scanning
• clawhub CLI installed for skill management — install guide

Install ggshield using your preferred method:

# macOS (Homebrew)
brew install gitguardian/tap/ggshield

# All platforms (pipx — recommended)
pipx install ggshield

# All platforms (pip)
pip install --user ggshield

Verify your setup:

ggshield --version

How to Install the ggshield Scanner Skill

Install the ggshield Scanner skill with a single command:

npx clawhub@latest install ggshield-scanner

To verify the installation:

clawhub list

You should see ggshield-scanner in your installed skills list. The skill requires ggshield to be available in your PATH.

ggshield Scanner Skill Configuration

GitGuardian Authentication

The ggshield Scanner skill requires a GitGuardian API key for secret detection. You can authenticate in two ways:

Interactive login (recommended for local development):

ggshield auth login

This opens your browser and generates a personal access token automatically.

Environment variable (recommended for CI/CD):

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

Environment Setup

| Variable | Required | Description | |----------|----------|-------------| | GITGUARDIAN_API_KEY | Yes | Personal access token from GitGuardian | | GITGUARDIAN_INSTANCE | No | Custom instance URL for on-premise GitGuardian |

Important: Never hardcode your API key in configuration files. Use environment variables or a secret manager like 1Password or Bitwarden.

Pre-commit Hook Setup

To catch secrets before they are committed:

# Install hook for current repo
ggshield install --mode local

# Install hook globally for all repos
ggshield install --mode global

ggshield Scanner Skill Usage Examples

1. Scan a Project Directory for Secrets

You: "Scan my project directory for any hardcoded secrets"

The agent runs ggshield secret scan path -r . against your working directory and returns a summary of any detected secrets, including the file path, line number, and secret type. If no secrets are found, you get a clean report confirming your code is safe.

2. Audit Git Repository History

You: "Check my entire git history for leaked secrets"

The agent runs ggshield secret scan repo . to scan all commits in your repository. This is useful for auditing legacy codebases or ensuring that previously committed secrets have been properly rotated and removed.

3. Scan a Docker Image Before Deployment

You: "Scan the nginx:latest Docker image for secrets"

The agent executes ggshield secret scan docker nginx:latest to inspect all layers of the Docker image. This catches secrets that may have been baked into container images during the build process — a common source of credential leaks in production.

4. Set Up Pre-commit Protection

You: "Install a pre-commit hook to block secrets from being committed"

The agent runs ggshield install --mode local to add a git pre-commit hook to your repository. Every future commit will be automatically scanned, and commits containing detected secrets will be blocked before they reach your repository.

Security & Best Practices

Follow these guidelines to stay safe when using the ggshield Scanner skill:

• Use read-only scans by default. The skill should only scan and report — avoid auto-remediation without careful review of each finding.
• Review before confirming. When the agent suggests removing or rotating a detected secret, verify the finding is a true positive before taking action.
• Rotate exposed secrets immediately. If ggshield detects a real secret in your repository history, rotate the credential right away — removing the commit is not enough.
• Enable pre-commit hooks. Prevention is better than detection. Set up hooks with ggshield install to catch secrets before they enter version control.
• Keep ggshield updated. New secret patterns are added regularly. Run pipx upgrade ggshield or brew upgrade ggshield to stay current.

Troubleshooting Common Errors

"Error: Invalid API key"

Your GitGuardian API key is missing or expired. Re-authenticate with ggshield auth login or verify your GITGUARDIAN_API_KEY environment variable is set correctly. Check that the token has not been revoked in the GitGuardian dashboard.

"Error: ggshield command not found"

ggshield is not installed or not in your PATH. Install it with pipx install ggshield or brew install gitguardian/tap/ggshield. If installed via pip, ensure your Python scripts directory is in your PATH.

"Error: Docker is not available"

Docker image scanning requires a running Docker daemon. Start Docker Desktop or the Docker service, then retry. If you only need to scan source code, use ggshield secret scan path or ggshield secret scan repo instead.