Shieldbot — AI Security Code Review for Claude Code

Shieldbot is an AI-powered security scanner that runs directly inside Claude Code. It combines deep dataflow analysis, 5,000+ static analysis rules, and advisory-database lookups with Claude's reasoning to detect vulnerabilities, hardcoded secrets, and CVE-affected dependencies — then synthesizes findings into a prioritized, actionable report.

One command. Full security audit. Zero context switching.

What It Scans

All scanners run in parallel. Findings are deduplicated, ranked by exploitability, and explained in plain English.

Auto-installed tools (CodeQL, osv-scanner, Dependabot CLI, Trivy) are downloaded automatically on first scan — no package manager or sudo required. Supports macOS and Linux on x86_64 and arm64. Trivy and Dependabot CLI require Docker at runtime (image builds / ecosystem updaters). Trivy scan strategy: (1) docker build → full image scan; (2) docker pull <base_image> → base image scan if build fails; (3) trivy fs filesystem fallback. When Docker build fails (e.g. network restrictions in CI), a prominent SCAN GAP warning is emitted and the base image is scanned directly. Pass --image <tag> / extra_images to scan a pre-built image directly.

Related MCP server: Claude Code Starter Kit MCP

Install as a Claude Code Plugin (Recommended)

Step 1 — Add the Shieldbot marketplace:

/plugin marketplace add BalaSriharsha/shieldbot

Step 2 — Install the plugin:

/plugin install shieldbot

Step 3 — Reload plugins:

/reload-plugins

Step 4 — Run a scan:

/shieldbot .
/shieldbot /path/to/repo
/shieldbot . --git-history

Or just ask Claude naturally:

• "scan this repo for security vulnerabilities"

• "check my code for hardcoded secrets"

• "audit my Python dependencies for CVEs"

Install as a Standalone MCP Server

Add to your MCP client config (.mcp.json or claude_desktop_config.json):

{
  "mcpServers": {
    "shieldbot": {
      "command": "uvx",
      "args": ["shieldbot-mcp"]
    }
  }
}

Or install via pip:

pip install shieldbot-mcp

Pre-install Scanner Tools

CodeQL, osv-scanner, and Dependabot CLI are downloaded automatically on first scan, but you can pre-install them with the bundled CLI:

shieldbot-install              # install all four
shieldbot-install --codeql     # CodeQL only
shieldbot-install --osv        # osv-scanner only
shieldbot-install --dependabot # Dependabot CLI only
shieldbot-install --trivy      # Trivy only
shieldbot-install --force      # reinstall / upgrade to latest

Binaries are placed in ~/.local/bin. Add it to your shell profile if needed:

export PATH="$HOME/.local/bin:$PATH"

All three tools are fully open-source and installed from their official GitHub releases — no package manager, no sudo, no API keys:

MCP Tools

scan_repository parameters

Dockerfile / docker-compose fix utilities

Shieldbot includes a command-line fixer that the agent uses to analyse and patch Dockerfiles and compose files:

# Analyse a Dockerfile and generate a fix plan from scan results
python -m shieldbot.fixers.dockerfile_fixer analyze Dockerfile shieldbot-report.json

# List all FROM stages and their detected package managers
python -m shieldbot.fixers.dockerfile_fixer list-stages Dockerfile

# List all RUN install commands and their packages
python -m shieldbot.fixers.dockerfile_fixer list-installs Dockerfile

# List all image: references in a docker-compose file
python -m shieldbot.fixers.dockerfile_fixer list-compose-images docker-compose.yml

# Check Docker Hub for a newer/patched base image tag
python -m shieldbot.fixers.dockerfile_fixer suggest-base-upgrade ubuntu:20.04

GitHub Actions Integration

Add Shieldbot to any repository in 3 lines. Findings appear in the Security > Code Scanning tab via SARIF upload.

# .github/workflows/shieldbot.yml
name: Shieldbot Security Scan
on:
  push:
    branches: [main, master]
  pull_request:
    branches: [main, master]
  schedule:
    - cron: '0 8 * * 1'  # Weekly scan

permissions:
  contents: read
  security-events: write  # Required for Code Scanning upload

jobs:
  shieldbot:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: BalaSriharsha/shieldbot@main

All available inputs:

Outputs: total-findings, risk-score, sarif-file

See .github/workflows/shieldbot-example.yml for the full annotated example.

Exit Codes (CI/CD Integration)

Use exit codes to gate deployments in GitHub Actions, GitLab CI, or any pipeline.

How It Works

1. Detect — Shieldbot profiles the repository (languages, package managers, git history)

2. Auto-install — Any missing scanner tools (CodeQL, osv-scanner, Dependabot CLI) are downloaded from GitHub releases for the current OS and architecture

3. Scan — All applicable scanners run in parallel via asyncio.gather()

4. Deduplicate — Findings are deduplicated by exact hash and proximity (±3 lines), with scanner priority: CodeQL → Semgrep → Bandit → detect-secrets → Dependabot/osv-scanner → pip-audit/npm-audit → Trivy

5. Analyze — Claude synthesizes raw scanner output into prioritized findings with context

6. Report — Structured output with executive summary, risk score, and remediation steps

Requirements

• Python 3.11+

• Claude Code (for plugin mode)

• Docker (optional — required at runtime for Trivy image scanning and Dependabot CLI's ecosystem updaters)

Contributing

Issues and pull requests welcome at github.com/BalaSriharsha/shieldbot.

License

MIT — see LICENSE