ggshield-scanner

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

# ggshield Secret Scanner

A MoltHub skill that wraps [GitGuardian's ggshield](https://github.com/GitGuardian/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**:
   ```bash
   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:
   ```bash
   echo 'GITGUARDIAN_API_KEY=your-api-key-here' > .env
   ```

## Installation

### From MoltHub

```bash
npx molthub@latest install ggshield-scanner
```

### Manual

Clone this repo into your skills directory:
```bash
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...