agent-secret-guard

Read this in your language: English | 简体中文 | 繁體中文 | 日本語 | 한국어 | Español | Français | Deutsch | Português | Русский | العربية | हिन्दी | Bahasa Indonesia

5-minute safety scanner for AI agent repos, MCP configs, local automation notes, and risky GitHub Actions permissions.

agent-secret-guard is a 5-minute safety check for agent-era repos. It looks for the places normal secret scanners often miss: MCP command args, AI coding rules, local automation notes, browser profile paths, credential store references, and over-permissive GitHub Actions workflows.

Use it before you publish an AI agent, share a local automation repo, ask a coding agent to work near real credentials, or open a pull request that touches CI/CD environment variables.

Need a quick asset map before sharing a repo? Start with docs/agent-surface-inventory.md.

Need a human launch-readiness check? I offer a focused AI Agent Repo Safety Audit for agent, MCP, GitHub Actions, and local automation repositories. See the sample report and outreach kit.

Good first checks:

• Before commit or PR: npx agent-secret-guard scan . --fail-on high
• In GitHub Actions: add the Marketplace Action
• For agent-generated changes: scan after the agent edits files and before you copy logs or release notes into public channels

Why This Exists

AI coding agents and MCP servers make local automation faster, but they also move secrets into new places:

• MCP configs can pass tokens through args, where they can leak into process listings and logs.
• Agent instruction files can contain copied shell commands, broad filesystem paths, or private setup notes.
• Browser profiles and credential stores can unlock sessions far outside the repo.
• GitHub Actions can accidentally give package-publishing jobs broad write access.

agent-secret-guard turns those patterns into concrete findings with a short explanation and a safer replacement.

Quick Start

Run the local check:

npx agent-secret-guard scan

Fail CI when high or critical findings are present:

npx agent-secret-guard scan . --fail-on high

Print machine-readable output:

npx agent-secret-guard scan . --format json

Generate SARIF for GitHub Code Scanning:

npx agent-secret-guard scan . --format sarif --output agent-secret-guard.sarif --fail-on high

Prefer a copyable workflow? Use the dedicated agent-secret-guard-action wrapper for a short Marketplace setup path.

Choose Your Path

Goal	Start here
Check a local repo before commit or PR	npx agent-secret-guard scan . --fail-on high
Add a short GitHub Actions setup	Use the agent-secret-guard-action wrapper or copy examples/ci/agent-secret-guard.yml.
See one safe example and one failing example	Start with examples/safe and examples/unsafe.
Compare it with broader secret scanners	Read docs/comparison.md.
Fix findings safely after a scan	Start with docs/remediation.md.

Typical text output:

HIGH mcp-token-in-args .mcp.json:6
MCP args include --token. Move the value to an environment variable or secret store.

What It Catches

Risk	Why it matters
MCP tokens in args	Command-line args can leak through process listings, logs, shell history, and agent transcripts.
Hardcoded API keys and package tokens	Agent context, commits, package tarballs, and logs can spread the value further.
Broad filesystem roots	Giving an agent /, C:\, /Users, or C:\Users makes accidental data exposure more likely.
Dangerous shell commands	Agents may run copied setup commands without human-level caution.
Browser profile exposure	Personal profiles can contain cookies, sessions, history, and autofill data.
Credential store exposure	Local token stores can unlock services far outside the project.
GitHub Actions over-permission	Broad workflow tokens can turn a compromised build step into write access.

Example

Unsafe MCP config:

{
  "mcpServers": {
    "demo": {
      "command": "npx",
      "args": ["demo-mcp", "--token", "<real-service-token>"]
    }
  }
}

Safer config:

{
  "mcpServers": {
    "demo": {
      "command": "npx",
      "args": ["demo-mcp"],
      "env": {
        "DEMO_API_KEY": "${DEMO_API_KEY}"
      }
    }
  }
}

Examples

The examples directory contains copyable safe patterns and intentionally unsafe fixtures:

• examples/safe uses environment-variable injection and a scoped workspace path.
• examples/unsafe contains risky MCP args and agent instructions for scanner tests.
• examples/ci/agent-secret-guard.yml shows a minimal GitHub Actions integration.

Try the safe fixture:

npx agent-secret-guard scan examples/safe --fail-on high

The unsafe fixture is excluded from normal repository scans. To test the failure path explicitly, override the exclusion:

npx agent-secret-guard scan examples/unsafe --fail-on critical --exclude never-match

GitHub Action

Create .github/workflows/agent-secret-guard.yml:

name: Agent Secret Guard

on:
  pull_request:
  push:
    branches: [main]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: aolingge/agent-secret-guard@v0.2.3
        with:
          fail-on: high

To upload findings to GitHub Code Scanning:

name: Agent Secret Guard

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read
  security-events: write

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: aolingge/agent-secret-guard@v0.2.3
        with:
          fail-on: high
          format: sarif
          output: agent-secret-guard.sarif
      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: agent-secret-guard.sarif

Pre-commit

Install pre-commit and add this to .pre-commit-config.yaml:

repos:
  - repo: https://github.com/aolingge/agent-secret-guard
    rev: v0.2.3
    hooks:
      - id: agent-secret-guard

Then run:

pre-commit install

Files Scanned

By default, the CLI scans:

• .env, .env.*
• .mcp.json, mcp.json, settings.json
• .cursor/mcp.json, .vscode/mcp.json, .claude/settings.json, .codex/config.toml
• .npmrc, .pypirc
• .cursorrules, .windsurfrules, .cursor/rules/*.mdc
• AGENTS.md, CLAUDE.md, GEMINI.md, CODEX.md, README.md
• docker-compose.yml, docker-compose.yaml
• .github/workflows/*.yml, .github/workflows/*.yaml

It skips common generated folders such as .git, node_modules, dist, coverage, .next, .turbo, and .cache.

Configuration

Create .agent-secret-guard.json to exclude known fixtures or generated examples:

{
  "exclude": ["examples/unsafe/**"]
}

You can also pass exclusions at runtime:

npx agent-secret-guard scan . --exclude examples/unsafe/**

How It Compares

agent-secret-guard is not a replacement for GitHub Secret Scanning, GitGuardian, gitleaks, or TruffleHog. Use those too.

This tool focuses on agent-specific configuration risks that are easy to miss in normal secret scanning: MCP command args, browser profile exposure, credential store paths, broad filesystem roots, and dangerous automation instructions.

See docs/comparison.md for a practical comparison with other scanners.

Privacy Model

The CLI scans local files and prints local reports. It does not call a remote service, upload findings, or verify credentials against providers. Findings are redacted where possible, but SARIF/JSON/text reports may still contain private file paths and surrounding evidence, so treat reports as sensitive artifacts.

See docs/privacy.md for the full data-handling note.

Fix Guide

Found something? Start with docs/remediation.md. It explains how to rotate exposed tokens, move MCP secrets into environment variables, narrow filesystem access, and harden GitHub Actions permissions.

If you want to list what an agent can reach before it becomes a finding, use docs/agent-surface-inventory.md.

Development

npm install
npm test
npm run build
npm run lint

Run the local build:

npm run build
node dist/cli.js scan examples/unsafe --fail-on high

Publishing

Future npm releases are designed to run through GitHub Actions Trusted Publishing, so maintainers do not need to keep entering local npm 2FA prompts. See docs/publishing.md.

Maintainer automation, branch protection, Dependabot auto-merge, and repository health checks are documented in docs/github-maintenance.md.

Maintainers can use docs/launch-kit.md for release notes, X/LinkedIn/Reddit copy, and a short demo script. Chinese launch copy is available in docs/launch-kit.zh-CN.md.

Use docs/growth-checklist.md before a public launch. It keeps the repository page, npm page, demo, release notes, and community posts aligned around one narrow promise.

GitHub Actions Marketplace

This repository includes a composite action for direct use from GitHub Actions. The dedicated Marketplace wrapper is aolingge/agent-secret-guard-action; see docs/marketplace-action.md for the wrapper layout and release checklist.

Roadmap

• More MCP client formats and schema-aware checks.
• Rule suppression with inline justification.
• A small website with before/after examples.
• More language packs for report text.

Security

This tool reports suspicious values and tries to redact secret evidence. Do not paste full scan output into public issues if it contains private paths or unredacted material. See SECURITY.md.

License

MIT

Support

Need the right path for feedback or fixes?

• Report a scanner bug or false positive: Bug report
• Suggest a new detection: Rule request
• Open a tightly scoped implementation task: Agent task
• Start with fixes first: Remediation guide
• Book a focused launch-readiness audit: AI Agent Repo Safety Audit
• Handling sensitive reports: SECURITY.md

If this project saves you time, you can support future maintenance here: Buy Me a Coffee.