Guardog

Secret scanning in your codebase, the FOSS way.

What is Guardog?

Guardog is a fast, zero-config secret scanner that scans your codebase (not git history) for leaked secrets using regex pattern matching and Shannon entropy analysis. Designed for Forgejo Actions on Codeberg, invoked via npx with zero setup.

Why Guardog?

• Codeberg/Forgejo-native: Built for self-hosted Forgejo instances
• FOSS: 100% open source, MIT licensed
• EU-friendly: No data leaves your infrastructure
• Zero config: Works out of the box with sensible defaults
• Minimal: Only essential dependencies

Installation

Via npx (recommended)

npx guardog scan .

Via npm install

npm install -g guardog
guardog scan .

Usage

Basic usage

guardog scan .

Scan the current directory for secrets.

Scan a specific path

guardog scan /path/to/repo

Options

| Flag | Description | Default | |------|-------------|---------| | --config <file> | Path to config file | .guardog.yml | | --entropy-threshold <number> | Entropy threshold override | 5.0 | | --no-entropy | Disable entropy analysis | enabled | | --json | Output findings as JSON | human-readable | | --quiet | Suppress all output except exit code | false | | --fail-on-warning | Treat low-confidence findings as failures | false |

Exit codes

• 0 — No findings
• 1 — One or more high-confidence findings
• 2 — Config or runtime error

Configuration

Create a .guardog.yml file in your repository root:

ignore:
  - "**/*.test.ts"
  - "test/fixtures/**"

allowlist:
  - "EXAMPLE"
  - "your-placeholder-here"

entropy_threshold: 5.0
entropy_min_length: 20

custom_patterns:
  - name: "Internal service token"
    regex: "svc_[a-zA-Z0-9]{32}"
    severity: high

Configuration reference

| Field | Type | Description | |-------|------|-------------| | ignore | string[] | Glob patterns to ignore | | allowlist | string[] | Strings that suppress findings | | entropy_threshold | number | Shannon entropy threshold (default: 5.0) | | entropy_min_length | number | Minimum token length for entropy check | | custom_patterns | array | Custom regex patterns |

Forgejo Actions Integration

name: Secret Scan

on:
  push:
    branches: ["*"]
  pull_request:

jobs:
  guardog:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: Run Guardog
        run: npx --yes guardog scan .

Detected Patterns

Guardog detects numerous secret patterns including:

• AWS Access Key ID / Secret Key
• GitHub Personal Access Token / OAuth Token
• GitLab PAT
• Stripe Secret Key
• OpenAI API Key
• Anthropic API Key
• SendGrid API Key
• Twilio Account SID / Auth Token
• Mailgun API Key
• Slack Bot/User Token / Webhook URL
• Discord Bot Token / Webhook URL
• Google API Key
• Firebase API Key
• JWT Token
• PEM Private Key
• Generic API keys, secrets, and passwords
• URL with embedded credentials

Development

Requirements

• Node.js 18+
• npm

Setup

npm install

Build

npm run build

Test

npm test

Development mode

npm run dev

Contributing

Contributions are welcome.

License

AGPL-3.0-only