forge-guard 0.3.6

Pre-deployment smart contract auditing framework for Foundry
Documentation

🔒 Forge Guard

The most comprehensive pre-deployment smart contract auditing framework for Foundry.

License: MIT Rust Foundry CI Nightly Audit Dependabot Crates.io Changelog

📋 Table of Contents

Overview

Forge Guard transforms security auditing from an optional step into a mandatory pre-deployment process. It blocks unsafe deployments by default while providing detailed vulnerability reports, exploit path analysis, and comprehensive security scoring.

Built with Rust for maximum performance, forge-guard integrates directly into your Foundry workflow as a drop-in CLI tool.

Key Features

  • 🔍 50+ Vulnerability Checks — Reentrancy, access control, delegatecall, flash loans, MEV, oracles, signatures, and more
  • 🛡️ Deployment Guard — Blocks unsafe deployments by default; --force bypass available with warnings
  • ✅ On-Chain Verification — Auto-verify contracts on Etherscan, Basescan, Arbiscan, and 14 more explorers
  • 📡 Bytecode Matching — Compare local vs on-chain bytecode via RPC eth_getCode with metadata hash stripping
  • 🔐 MEV Analysis — Detect sandwich, flash loan, oracle, and value extraction attack vectors during simulation
  • 🤖 AI-Powered Auditing — OpenAI GPT-5, Anthropic Claude 5, and Ollama integration with consensus engine
  • ⛓️ Multi-Chain — 17 supported EVM chains with auto-detected explorer URLs
  • ⚡ Parallel Chain Auditing — --all-chains audits all 17 chains concurrently via Rayon with --max-parallel-chains concurrency control, producing an aggregated report with chain-labeled findings
  • 🔌 Plugin Architecture — Extensible design for custom security rules; built-in + external (IPC subprocess) plugins
  • 📊 Rich Reports — Terminal, JSON, and Markdown output with detailed findings, scores, and remediation
  • 💥 Exploit Engine — Generates attack vectors and proof-of-concept exploit paths
  • 🩺 Project Doctor — Comprehensive health analysis: Foundry version, Solc version, project structure, dependencies, RPC, compiler settings
  • 🔎 Dependency Scanner — 30+ known vulnerability entries covering OpenZeppelin, Solmate, Solady, Chainlink, Wormhole, LayerZero, forge-std, PRBMath, solc, and more
  • ⚡ High Performance — Parallel execution via Rayon, filesystem caching, incremental SHA-256 content-hash analysis (unchanged files skipped on re-runs)
  • ⚡ Quick Mode — forge-guard audit --quick skips parser-heavy checks, ~5x faster for rapid feedback
  • 📋 Executive Summary — forge-guard audit --summary shows concise PASS/FAIL verdict with action items
  • 🏗️ CI/CD Ready — Generate pipeline configs for GitHub Actions, GitLab CI, Bitbucket Pipelines, Azure DevOps
  • 🎯 Audit Templates — Prebuilt profiles (ERC20, ERC721, DeFi, Bridge, Upgradeable) that adjust checks, scoring weights, and readiness gates; custom templates supported
  • 📦 SBOM Generation — CycloneDX 1.6 / SPDX 2.3 bills of materials with --ci GitHub Actions export for supply-chain compliance
  • 🪝 Git Pre-Commit Hook — One-command install that audits staged .sol files and blocks commits with HIGH/CRITICAL findings
  • 🔄 Foundry Config Sync — forge-guard doctor --sync imports src/test/lib/remappings/solc_version from foundry.toml
  • 🔌 External Analyzer Import — forge-guard import ingests Slither, Mythril, and Semgrep JSON results with severity mapping, dedup, and unified reporting
  • 📢 Webhook Notifications — forge-guard notify sends Slack/Discord alerts with rich payloads; --notify on audit/deploy/deploy-safe
  • ⛔ Suppression Files — .forge-guard-suppressions hides accepted risks and known false positives (--suppressions, --show-suppressed, --generate-suppressions)
  • 📈 Historical Trend Tracking — opt-in SQLite history database (~/.forge-guard/history.db); report --history shows score trends over time, report --regression highlights findings new since the last audit
  • 📊 Dashboard Mode — forge-guard dashboard serves a local web dashboard (http://127.0.0.1:9090) of the last audit with score gauges, severity charts, a score-over-time trend chart from the history DB, interactive filtering, and WebSocket auto-refresh (including --watch re-audit on file changes)

Milestone Summary

All 15 development milestones are complete, and M16's Parallel Chain Auditing, Historical Trend Tracking, and Dashboard Mode are shipped. Here's what each delivered:

# Milestone Key Deliverables
🏗️ M1 — Core Architecture Cargo project, error handling, config system, module structure
🎮 M2 — CLI Framework 18 subcommands via clap, global flags (--json, --strict, --offline, etc.)
🔒 M3 — Security Engine 50+ vulnerability checks across 5 severity levels, 11-category scoring system
🔌 M4 — Plugin Architecture Plugin trait, built-in + IPC subprocess plugins, lifecycle management
⛓️ M5 — Multi-Chain 17 EVM chains, alias resolution, chain registry with RPC testing
📊 M6 — Report Engine Terminal (color-coded), JSON, and Markdown reports with findings & scores
🛡️ M7 — Deployment Guard Pre-deployment check pipeline, deploy-safe (non-bypassable), MEV detection
💥 M8 — Exploit Engine Attack vector generation from findings, storage collision analysis
✅ M9 — Contract Verification 17-chain explorer registry, forge verify-contract, RPC bytecode match, auto-verify
🔧 M10 — Gas/Deps/Fuzz/CI Gas analysis, 30-entry vulnerability DB, fuzzing adapter, 4-platform CI templates
🤖 M11 — AI Auditing OpenAI, Claude, Ollama providers, consensus engine, structured Solidity prompts
🧪 M12 — Testing & Docs 850+ tests, comprehensive README, CONTRIBUTING.md, CI workflows
⚡ M13 — Post-MVP Polish Quick mode (~5x faster), executive summary, incremental file analysis, --summary flag
🎯 M14 — Developer Experience Applied audit templates (ERC20, ERC721, DeFi, Bridge, Upgradeable) with check/scoring/gates, SBOM --ci workflow export, per-file pre-commit hook, real foundry.toml sync, custom user templates
🔗 M15 — External Tooling & Interop Slither/Mythril/Semgrep import with severity mapping + dedup + unified reports, Slack/Discord webhook notifications (notify, --notify), suppression files for accepted risks
⚡ M16 — Performance & Visualization Parallel chain auditing: --all-chains audits all 17 chains concurrently via Rayon, --max-parallel-chains concurrency bound, aggregated report with chain-labeled findings; historical trend tracking: opt-in SQLite history, report --history trends, report --regression new-finding diff; dashboard mode: local HTTP server with score gauges, severity charts, interactive filtering, and WebSocket live updates

Detailed breakdown: milestone-based-roadmap.md

Installation

Prerequisites

Option 1: Install via Cargo

cargo install forge-guard

Option 2: Docker (pre-configured with Foundry)

Multi-arch image (linux/amd64 + linux/arm64) published to GitHub Container Registry on every release — no Rust or Foundry install needed:

docker pull ghcr.io/codetibo/forge-guard:latest

# Audit your project from a container (mount the project at /workspace)
docker run --rm -v "$PWD":/workspace ghcr.io/codetibo/forge-guard audit

# Full run with a custom working directory
docker run --rm -v "$PWD":/workspace -w /workspace ghcr.io/codetibo/forge-guard audit --full

# The image also ships forge, cast, anvil, and chisel
# (e.g. docker run --rm --entrypoint forge ghcr.io/codetibo/forge-guard --version)

Option 3: Homebrew (macOS & Linux)

Formula auto-generated by cargo-dist on every release and published to the codetibo/homebrew-tap tap:

brew install codetibo/tap/forge-guard
# or, once the tap is added:
brew tap codetibo/tap
brew install forge-guard

Option 4: Add to PATH & Verify

# The forge-guard binary is installed to ~/.cargo/bin/
# Add to your .bashrc or .zshrc if not already in PATH:
export PATH="$HOME/.cargo/bin:$PATH"

Verify Installation

forge-guard --version
forge-guard audit --help

Quick Start

Navigate to a Foundry project and run:

cd my-foundry-project

# Run a comprehensive security audit
forge-guard audit

# Audit with strict mode (fail on any finding)
forge-guard audit --strict

# Full audit including exploit paths and gas analysis
forge-guard audit --full

# Check deployment readiness
forge-guard audit --production

# Generate Markdown report
forge-guard audit --markdown --report

Example Output

═══════════════════════════════════════════════
           FORGE GUARD — SECURITY REPORT       
═══════════════════════════════════════════════

📋 Project:  .
⛓️  Chain:    ethereum
🕐 Duration:  0.00s
📁 Files:     1

── Findings ──
  🛑 Critical:  0
  🔴 High:     0
  🟡 Medium:   0
  🔵 Low:      0
  ⚪ Info:     0

── Scores ──
  🔐 Access Control:       100/100
  🛡️  Security:            100/100
  🎯 Fuzzing:             100/100
  ⛽ Gas:                  100/100
  🏗️  Architecture:        100/100
  ⬆️  Upgradeability:     100/100

Overall Score: 100
Risk Level: MINIMAL
Production Ready: ✅ YES
Deployment: ✅ APPROVED

All Commands

Command Description Example
forge-guard audit Run security audit with 50+ checks forge-guard audit --full --chain base
forge-guard audit --quick Quick audit (skips parser-heavy checks) forge-guard audit --quick
forge-guard audit --summary Executive summary report forge-guard audit --summary
forge-guard deploy Deploy with security guard forge-guard deploy --force
forge-guard deploy-safe Deploy with mandatory security pass forge-guard deploy-safe Counter
forge-guard fuzz Run fuzzing campaigns forge-guard fuzz --runs 50000
forge-guard invariant Run invariant tests forge-guard invariant --runs 2000
forge-guard simulate Deployment simulation forge-guard simulate --blocks 200
forge-guard gas Gas usage analysis forge-guard gas --all
forge-guard report Generate audit reports forge-guard report --format markdown
forge-guard report --history Show score trends over time from the SQLite history DB forge-guard report --history
forge-guard report --regression Highlight findings new since the last audit forge-guard report --regression
forge-guard dashboard Launch a local web dashboard of the last audit forge-guard dashboard --port 9090
forge-guard verify Verify contract deployments forge-guard verify --all
forge-guard doctor Project health analysis forge-guard doctor --fix
forge-guard watch Watch for changes and re-audit forge-guard watch --dirs src
forge-guard ci Generate CI/CD or VS Code configs forge-guard ci --platform github · forge-guard ci --vscode
forge-guard benchmark Performance benchmarks forge-guard benchmark --iterations 50
forge-guard scan Dependency vulnerability scan forge-guard scan --update
forge-guard upgrade-check Upgrade path analysis forge-guard upgrade-check --all
forge-guard plugins Manage plugins forge-guard plugins list
forge-guard chain Chain configuration forge-guard chain list
forge-guard security Security configuration forge-guard security list
forge-guard sbom Generate Software Bill of Materials forge-guard sbom --format cyclonedx
forge-guard install-hook Install git pre-commit hook forge-guard install-hook
forge-guard import Import external analyzer findings (Slither, Mythril, Semgrep) forge-guard import --from slither results.json
forge-guard notify Send webhook notifications (Slack, Discord) forge-guard notify --findings reports/audit.json --on-critical

📖 Full command reference: See COMMANDS.md for detailed documentation of every subcommand, flag, and example.

Common Flags

--chain <NAME>     # Target chain (default: ethereum)
--json             # JSON output
--markdown         # Markdown output
--html             # HTML output
--strict           # Fail on any MEDIUM+ finding
--offline          # Skip RPC calls
--production       # Production mode (extra checks)
--report           # Generate report files
--project-root <PATH> # Project root path (default: .)

Detailed Usage Examples

Security Audit

# Standard audit
forge-guard audit

# Full audit with everything
forge-guard audit --full

# Cross-chain audit
forge-guard audit --chain arbitrum
forge-guard audit --chain base --chain polygon
forge-guard audit --all-chains
forge-guard audit --all-chains --max-parallel-chains 2   # bound concurrent chain audits

# Output formats
forge-guard audit --json
forge-guard audit --markdown
forge-guard audit --json --report   # Save to file

# Analysis scope
forge-guard audit --strict           # Fail on any MEDIUM+ finding
forge-guard audit --production       # Production readiness check
forge-guard audit --offline          # Skip network calls
forge-guard audit --exploit          # Include exploit path generation
forge-guard audit --gas              # Include gas analysis
forge-guard audit --enable-history   # Record the audit in the SQLite history database

# Historical trend tracking (after running audit --enable-history)
forge-guard report --history        # Score trends over time
forge-guard report --regression     # Findings new since the last audit

# Dashboard mode — visual dashboard of the last audit
forge-guard dashboard               # http://127.0.0.1:9090
forge-guard dashboard --port 8080   # Custom port
forge-guard dashboard --watch       # Re-audit on file changes + live WebSocket updates
forge-guard dashboard --open        # Open in the default browser
# The Score Trend panel charts audits recorded with --enable-history

# Audit templates
forge-guard audit --template erc20   # ERC20-focused audit
forge-guard audit --template defi    # DeFi-focused audit
forge-guard audit --list-templates   # List all available templates

Deployment Guard

# Safe deploy (blocked by issues)
forge-guard deploy

# Deploy with bypass (warnings still shown)
forge-guard deploy --force

# Deploy specific contract
forge-guard deploy MyContract

# Mandatory security pass (no bypass)
forge-guard deploy-safe MyContract

# Create2 deployment
forge-guard deploy --salt 0xabc...

# Deploy with auto-verification
forge-guard deploy MyContract --verify --api-key YOUR_ETHERSCAN_KEY

Contract Verification

# Verify a single contract
forge-guard verify --address 0x... --name MyContract

# Bulk verify all deployments from forge script
forge-guard verify --all

# Verify on a specific chain
forge-guard verify --address 0x... --name MyContract --chain base

# Explorer and bytecode match are attempted automatically

Quick Mode & Executive Summary

# Quick audit — skip parser-heavy checks for ~5x faster results
forge-guard audit --quick

# Show executive summary (concise PASS/FAIL verdict with action items)
forge-guard audit --summary

# Combine both for fastest feedback loop
forge-guard audit --quick --summary

# Still get the full report with --report
forge-guard audit --quick --report

AI-Powered Auditing

# Run audit with AI (uses OPENAI_API_KEY env var)
forge-guard audit --ai

# Use Claude instead
forge-guard audit --ai --ai-provider claude --ai-model claude-5-sonnet-20260701

# Full AI audit (security + gas + logic auditors)
forge-guard audit --ai --ai-full

# Use local Ollama
forge-guard audit --ai --ai-provider ollama --ai-model llama3

Deployment Simulation

# Run deployment simulation
forge-guard simulate

# With MEV analysis
forge-guard simulate --mev

# Custom block range and deployer
forge-guard simulate --blocks 200 --deployer 0x...

Dependency Scanning

# Scan project dependencies
forge-guard scan

# Deep scan (include indirect dependencies)
forge-guard scan --depth 2

# Update vulnerability database
forge-guard scan --update

# JSON output
forge-guard scan --json

# Fail fast on critical vulnerabilities
forge-guard scan --fail-fast

Project Health

# Full health check
forge-guard doctor

# Verbose output
forge-guard doctor --verbose

# Auto-fix issues
forge-guard doctor --fix

# Check specific category
forge-guard doctor --check dependencies

# Sync config from foundry.toml
forge-guard doctor --sync

# Preview sync changes without writing
forge-guard doctor --sync --dry-run

# Show diff of sync changes
forge-guard doctor --sync --diff

Plugin Management

# List installed plugins
forge-guard plugins list

# Create a new plugin scaffold
forge-guard plugins new my-custom-check

# Install from source
forge-guard plugins install my-check https://github.com/user/my-check.git

# Enable/disable
forge-guard plugins enable my-custom-check
forge-guard plugins disable my-custom-check

# Remove
forge-guard plugins remove my-custom-check

CI/CD Generation

# GitHub Actions
forge-guard ci --platform github

# GitLab CI
forge-guard ci --platform gitlab

# With deployment pipeline
forge-guard ci --platform github --include-deploy

# Custom output directory
forge-guard ci --output .github/workflows

# Overwrite existing configs
forge-guard ci --overwrite

# VS Code extension config (.vscode/settings.json, tasks.json, extensions.json)
forge-guard ci --vscode

Git Pre-Commit Hook

Automatically audit staged .sol files before each commit. Blocks commits with HIGH/CRITICAL findings.

# Install pre-commit hook
forge-guard install-hook

# Force overwrite existing hook
forge-guard install-hook --force

# Uninstall the hook
forge-guard install-hook --uninstall

# Install in specific project
forge-guard install-hook --project /path/to/project

Bypass the hook temporarily:

FORGE_GUARD_SKIP_HOOK=1 git commit -m "urgent fix"

SBOM Generation

Generate a CycloneDX 1.6 or SPDX 2.3 Software Bill of Materials for your Foundry project.

# Generate CycloneDX SBOM (stdout)
forge-guard sbom

# SPDX format
forge-guard sbom --format spdx

# Save to file
forge-guard sbom --output sbom.json

# Also write a GitHub Actions workflow for automated SBOM publishing
forge-guard sbom --ci

The --ci flag writes .github/workflows/sbom.yml, a workflow that generates both CycloneDX and SPDX SBOMs on every push to main/master and uploads them as build artifacts — useful for supply-chain compliance (EO 14028 / NTIA minimum elements).

External Analyzer Import

Adopt Forge Guard incrementally by importing findings from the tools you already run:

# Import Slither results
forge-guard import --from slither slither_results.json

# Import Mythril results and deduplicate against your last forge-guard audit
forge-guard import --from mythril mythril_out.json --findings reports/audit.json

# Import Semgrep results as a unified JSON report
forge-guard import --from semgrep semgrep_results.json --json --output unified.json

Severity scales are mapped automatically (Slither impact, Mythril severity/type, Semgrep ERROR/WARNING/INFO), and findings that duplicate Forge Guard's own are removed.

Webhook Notifications

Get Slack/Discord alerts without watching the CI tab:

# Summarize the last audit to a Slack webhook
forge-guard notify --findings reports/audit.json --webhook https://hooks.slack.com/services/T/B/X

# Discord embed, only when critical findings exist
forge-guard notify --findings reports/audit.json --on-critical

# Preview the exact payload without sending
forge-guard notify --findings reports/audit.json --dry-run

# Notify automatically after an audit / deployment
forge-guard audit --notify
forge-guard deploy --notify
forge-guard deploy-safe --notify

Configure webhooks once in forge-guard.toml (see Configuration); blocked deployments always notify, successful runs respect min_severity.

Suppression Files

Permanently silence known false positives and accepted risks (see examples/.forge-guard-suppressions for the file format):

# Generate a suppression file from the current findings
forge-guard audit --generate-suppressions

# Use it on subsequent audits (matching findings are hidden from scoring)
forge-guard audit --suppressions .forge-guard-suppressions

# Show suppressed findings (visually marked) instead of hiding them
forge-guard audit --suppressions .forge-guard-suppressions --show-suppressed

File format — one entry per line, FINDING_ID [file] # comment:

FA-H-001 # Known false positive in Vault.sol
FA-M-004 src/oracle/PriceFeed.sol

Audit Templates

Use predefined audit templates to focus on specific contract types. Templates don't just print a banner — they actually adjust the audit: template enabled_checks/disabled_checks are wired into the security engine, focus_areas weight categories 2× in the overall score, and min_scores gate production readiness.

# List available templates
forge-guard audit --list-templates

# ERC20 token audit
forge-guard audit --template erc20

# DeFi protocol audit
forge-guard audit --template defi

# Upgradeable contract audit
forge-guard audit --template upgradeable

Built-in Templates

Template Focus
erc20 Approval bugs, permit replay, token-specific vulnerabilities
erc721 NFT patterns, royalties, metadata integrity
defi Lending, AMM, oracles, flash loans, MEV resistance
bridge Cross-chain messaging, validator sets, replay attacks
upgradeable Proxy patterns, storage layouts, initializers

Custom Templates

Drop a JSON file into ~/.forge-guard/templates/ to define your own template or override a built-in by name:

{
  "name": "my-protocol",
  "description": "My protocol's audit profile",
  "enabled_checks": ["FA-H-011", "FA-H-016"],
  "disabled_checks": ["FA-L-001"],
  "min_scores": { "exploit_resistance": 85 },
  "focus_areas": ["exploit_resistance", "security"]
}

Run it with forge-guard audit --template my-protocol.

Configuration

Forge Guard reads configuration from forge-guard.toml in the project root. All fields are optional.

💡 Ready-to-edit templates: see examples/forge-guard.toml for a fully commented config (including Slack/Discord webhooks) and examples/.forge-guard-suppressions for a sample suppression file.

Minimal Configuration

# forge-guard.toml
src_dirs = ["src", "contracts"]

Full Configuration Reference

# ── Source Settings ──
src_dirs = ["src", "contracts"]           # Source directories to scan
exclude = ["test", "mock", "interfaces"]  # Exclusion patterns

# ── Chain ──
chain = "ethereum"                        # Default target chain

# ── Security Engine ──
[security]
enable_high = true                        # Enable HIGH severity checks
enable_medium = true                      # Enable MEDIUM severity checks
enable_low = true                         # Enable LOW severity checks
enable_info = false                       # Enable INFORMATIONAL checks
exploit_analysis = true                   # Enable exploit path analysis
gas_analysis = false                      # Enable gas analysis
max_findings_per_check = 50               # Max findings per check type

# ── Deployment Guard ──
[deployment]
min_score = 70                            # Minimum score to deploy (0-100)
block_on_critical = true                  # Block on critical findings
block_on_high = true                      # Block on high findings
block_on_medium = false                   # Block on medium findings
require_fuzzing = true                    # Require fuzzing to pass
require_invariants = true                 # Require invariants to pass
simulate_deployment = true                # Run deployment simulation
require_verification = false              # Require on-chain verification
auto_verify = false                       # Auto-verify after deployment
explorer_api_key = null                   # Explorer API key (reads env var when null)

# ── Report Settings ──
[report]
include_snippets = true                   # Include code snippets
include_exploit_paths = true              # Include exploit demonstrations
include_recommendations = true            # Include fix recommendations
output_dir = "reports"                    # Report output directory

# ── Caching ──
[cache]
enabled = false                           # Enable caching (disable for CI)
directory = ".forge-guard-cache"          # Cache directory
max_size_mb = 500                         # Maximum cache size
ttl_seconds = 3600                        # Cache TTL (1 hour)

# ── Historical Trend Tracking ──
[history]
enabled = false                           # Persist audits to SQLite (opt-in)
db_path = "~/.forge-guard/history.db"    # Optional DB path override (~ is expanded)

# ── Plugin Configuration ──
[plugins]
directories = [".forge-guard/plugins"]    # Plugin search paths
disabled = ["forge-guard-example"]        # Disable specific plugins
allow_external = false                    # Allow external plugin loading

# ── AI Auditors ──
[ai]
provider = "openai"                       # AI provider: openai, claude, ollama
model = "gpt-5"                            # Model identifier
temperature = 0.1                         # Sampling temperature (0.0-1.0)
max_tokens = 4000                         # Max tokens per response
min_confidence = 0.5                      # Minimum confidence (0.0-1.0)
full_audit = false                        # Run all auditors (security + gas + logic)

# ── Webhook Notifications ──
[notifications.slack]
webhook = "https://hooks.slack.com/services/T000/B000/XXXX"  # Slack incoming webhook
min_severity = "high"                    # Notify when findings are at least this severe

[notifications.discord]
webhook = "https://discord.com/api/webhooks/123/abc"         # Discord webhook
min_severity = "critical"

Command-Line Overrides

CLI flags override config file values:

forge-guard audit --strict         # Overrides security config
forge-guard audit --chain base     # Overrides default chain
forge-guard audit --offline        # Skips RPC

Architecture

                    ┌─────────────┐
                    │   CLI Layer  │  (clap argument parsing)
                    └──────┬──────┘
                           │
              ┌────────────┼────────────┐
              ▼            ▼            ▼
       ┌──────────┐ ┌──────────┐ ┌──────────┐
       │  Audit   │ │  Deploy  │ │   CI     │  ... 18 commands
       └────┬─────┘ └────┬─────┘ └────┬─────┘
            │             │            │
            ▼             ▼            ▼
       ┌─────────────────────────────────────┐
       │           Security Engine            │
       │  ┌──────┐ ┌──────┐ ┌─────────────┐  │
       │  │CEI   │ │Access│ │Delegatecall │  │ 50+ checks
       │  │Analysis│ │Control││             │  │
       │  └──────┘ └──────┘ └─────────────┘  │
       └────────────────┬────────────────────┘
                        │
              ┌─────────┴─────────┐
              ▼                   ▼
       ┌──────────────┐ ┌──────────────────┐
       │Plugin Registry│ │  Chain Registry   │
       │ Built-in/IPC  │ │  17 EVM Chains    │
       └──────────────┘ └──────────────────┘
                        │
              ┌─────────┴─────────┐
              ▼                   ▼
       ┌──────────────┐ ┌──────────────────┐
       │Deployment    │ │  Report Engine    │
       │Guard         │ │  JSON / Markdown  │
       └──────────────┘ └──────────────────┘
                        │
              ┌─────────┴─────────┐
              ▼                   ▼
       ┌──────────────┐ ┌──────────────────┐
       │  Exploit     │ │  Doctor / Scan   │
       │  Engine      │ │  Health Checks   │
       └──────────────┘ └──────────────────┘

Module Breakdown

Module Purpose
src/core/ Types, config, error handling, audit results
src/security/ 50+ vulnerability checks + scoring engine
src/plugins/ Plugin trait, built-in + external (IPC) plugins
src/chains/ Chain registry with 17 EVM chains
src/deployment/ Deployment guard + on-chain contract verifier
src/deployment/verifier/ Block explorer registry, forge verify, RPC bytecode match
src/reports/ JSON and Markdown report generation
src/exploit/ Attack vector and exploit path generation
src/dependencies/ 30+ known vulnerability entries, online updates
src/doctor/ Project health analysis
src/gas/ Gas usage analysis and optimization suggestions
src/fuzzing/ Fuzzing adapter interface
src/ci/ CI/CD pipeline template generation
src/benchmark/ Performance benchmarking
src/parser/ Solidity source code parser
src/ai/ AI auditing: providers (OpenAI, Claude, Ollama), auditors, consensus engine
src/ai/providers/ OpenAI, Claude, Ollama HTTP client implementations
src/ai/auditors/ Security, Gas, Logic auditor agents with Solidity prompts
src/ai/consensus/ Cross-provider validation with confidence boosting
src/importer/ External analyzer import: Slither/Mythril/Semgrep parsers, severity mapping, dedup
src/notify/ Slack/Discord webhook payloads and sender, severity gating
src/suppressions/ Suppression file parsing, matching, and generation
src/history/ SQLite history database, score trends, regression diffing
src/dashboard/ Local HTTP dashboard (axum): score gauges, severity charts, WebSocket live updates
src/utils/ Caching, formatting utilities

Security Checks

HIGH Severity (blocks deployment)

ID Check Description
FA-H-001 Reentrancy CEI violations, callback reentrancy, read-only reentrancy, self-call paths
FA-H-002 Access Control Missing modifiers, inline access checks, role-based access in initialize functions
FA-H-003 Delegatecall Unsafe delegatecall patterns
FA-H-004 tx.origin tx.origin for authentication
FA-H-005 CREATE2 CREATE2 address precomputation risks
FA-H-006 DoS Unbounded loops, denial of service
FA-H-007 Storage Collision Upgradeable contract storage gaps
FA-H-008 Unsafe Assembly Inline assembly blocks
FA-H-009 Selfdestruct selfdestruct usage
FA-H-010 Proxy Vulnerabilities Unsafe proxy patterns
FA-H-011 Oracle Manipulation Price oracle manipulation risks
FA-H-012 Signature Vulnerabilities Signature malleability, EIP-2098 issues
FA-H-013 Replay Attacks Cross-chain replay, missing nonces
FA-H-014 ERC20 Issues Approve race conditions
FA-H-015 Bridge Vulnerabilities Cross-chain bridge patterns
FA-H-016 Flash Loan Issues Flash loan attack surface
FA-H-017 MEV Issues Slippage, sandwich vulnerabilities
FA-H-018 Cross-Chain Issues Chain ID handling, message verification
FA-H-019 Dependency Vulnerabilities Known vulnerable dependencies
FA-H-020 Unsafe Imports HTTP/github imports
FA-H-021 Unsafe Initializers Missing initializer modifiers
FA-H-022 Unsafe Upgrade Paths UUPS/Transparent proxy paths
FA-H-023 Clone Vulnerabilities Minimal proxy clones

MEDIUM Severity

ID Check Description
FA-M-001 Gas Problems Inefficient patterns
FA-M-002 Unsafe Casting Unsafe type conversions
FA-M-003 Timestamp Manipulation block.timestamp in critical logic
FA-M-004 Storage Inefficiencies Unpacked storage variables
FA-M-005 Unsafe Events Sensitive data in events
FA-M-006 Poor Visibility Public mappings
FA-M-007 Bad Modifiers Modifiers making external calls
FA-M-008 Unsafe Math Unchecked arithmetic
FA-M-009 Poor Access Patterns Storage vs memory

LOW & INFORMATIONAL

  • Naming conventions
  • Code duplication
  • Optimization suggestions
  • Style issues
  • Missing documentation
  • Line length

Plugin Development

Built-in Plugin

Create a built-in plugin by implementing the Plugin trait:

use forge_guard::plugins::{Plugin, PluginContext, PluginResult};

pub struct MyCustomCheck;

impl Plugin for MyCustomCheck {
    fn name(&self) -> &'static str { "my-custom-check" }
    fn version(&self) -> &'static str { "0.1.0" }
    fn description(&self) -> &'static str { "My custom security check" }

    fn execute(&self, ctx: &PluginContext) -> PluginResult {
        // Your analysis logic here
        // ctx.source_files contains the Solidity files to analyze
        // ctx.config has the project configuration
        Ok(Vec::new()) // Return findings
    }
}

External Plugin (IPC Subprocess)

Plugins can also be external binaries communicating via JSON IPC:

# Create a plugin scaffold
forge plugins new my-external-check
cd .forge-guard/plugins/my-external-check
cargo build --release
forge plugins list

The protocol:

  • stdin: JSON PluginIpcInput with context
  • stdout: JSON PluginIpcOutput with findings
  • stderr: Diagnostic logs

CI/CD Integration

GitHub Actions (auto-generated)

# Run: forge-guard ci --platform github
name: Forge Guard Security Check
on: [push, pull_request]
jobs:
  security-audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          submodules: recursive
      - uses: foundry-rs/foundry-toolchain@v1
        with:
          version: nightly
      - name: Install Forge Guard
        run: cargo install forge-guard
      - name: Security Audit
        run: forge-guard audit --strict
      - name: Scan Dependencies
        run: forge-guard scan --depth 1
      - name: Generate Report
        run: forge-guard audit --report --markdown

With Deployment Protection

name: Deploy
on:
  push:
    branches: [main]
jobs:
  security-audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: foundry-rs/foundry-toolchain@v1
      - name: Security check
        run: forge-guard audit --strict --production
      - name: Safe deploy
        run: forge-guard deploy-safe
        env:
          ETH_RPC_URL: ${{ secrets.ETH_RPC_URL }}
          PRIVATE_KEY: ${{ secrets.DEPLOYER_PRIVATE_KEY }}

Performance

  • Parallel execution via Rayon — all file analysis runs in parallel across CPU cores
  • Filesystem caching — analysis results cached with TTL; only changed files re-analyzed
  • Memory-efficient — streaming reads for large codebases
  • Incremental — re-audits only process modified files
  • Benchmark mode — measure and compare performance across versions
# Run benchmarks
forge-guard benchmark --iterations 50

# Benchmark specific module
forge-guard benchmark --module source_discovery

# Compare with baseline
forge-guard benchmark --compare baseline.json

Development

Building

git clone https://github.com/codetibo/forge-guard.git
cd forge-guard
cargo build
cargo build --release    # Production build
# The binary is at target/release/forge-guard

Testing

# Run all tests (850+)
cargo test

# Run specific test suites
cargo test --lib              # Unit tests
cargo test --test cli_tests   # CLI & end-to-end binary tests
cargo test --test mod         # Integration tests
cargo test --lib dependencies # Dependency scanner tests
cargo test --lib plugins      # Plugin tests

# Run with output
cargo test -- --nocapture

Linting & Formatting

# Check formatting
cargo fmt --check

# Apply formatting
cargo fmt

# Lint
cargo clippy -- -D warnings

Test Coverage

Module Tests Status
AI providers (OpenAI, Claude, Ollama) ✅ 11 in-module tests
AI auditors (prompts, parsing, chunking) ✅ 12 in-module tests
AI consensus (dedup, boost, filtering) ✅ 9 in-module tests
Contract verifier (explorer URLs, bytecode) ✅ 11 in-module tests
Core types/config ✅ 13 integration_tests
Security engine (incl. template filtering) ✅ 34 security_tests
CLI end-to-end (audit, deploy, templates, sync, SBOM, hook) ✅ 104 cli_tests
Plugin architecture ✅ 25 plugin_tests
Dependency scanner ✅ 14 in-module tests
Parser ✅ 39 in-module tests
Chains ✅ 8 in-module tests
Deployment ✅ 6 in-module tests
Reports ✅ 3 in-module tests
Exploit engine ✅ 2 in-module tests
Utils ✅ 6 in-module tests
Gas analysis ✅ 3 in-module tests
CI generator (incl. SBOM workflow) ✅ 21 in-module tests
Doctor (incl. foundry.toml sync) ✅ 18 in-module tests
SBOM formats (CycloneDX/SPDX) ✅ 56 in-module tests
Templates (apply, override, serialization) ✅ 16 in-module tests
Pre-commit hook (install/uninstall/script) ✅ 13 in-module tests

Supported Chains

Chain Chain ID Currency Status
Ethereum 1 ETH ✅
Base 8453 ETH ✅
Arbitrum 42161 ETH ✅
Optimism 10 ETH ✅
Polygon 137 MATIC ✅
BNB Chain 56 BNB ✅
Avalanche 43114 AVAX ✅
Scroll 534352 ETH ✅
Linea 59144 ETH ✅
Unichain 130 ETH ✅
ZKSync 324 ETH ✅
HyperEVM 999 HYPE ✅
Monad 10143 MON ✅
Sonic 146 S ✅
Blast 81457 ETH ✅
Mantle 5000 MNT ✅
Robinhood 31753 ETH ✅

Future Support

Solana · Tron · Sui · Aptos

Contributing

See CONTRIBUTING.md for detailed guidelines.

Key points:

  • Run cargo test && cargo fmt && cargo clippy before submitting PRs
  • Add tests for new functionality
  • Document public APIs
  • Follow Rust standard conventions

License

MIT — see LICENSE for details.

Roadmap

See milestone-based-roadmap.md for the complete development roadmap.

Milestone Status
M1: Core Architecture ✅ Complete
M2: CLI Framework ✅ Complete
M3: Security Engine ✅ Complete
M4: Plugin Architecture ✅ Complete
M5: Multi-Chain Support ✅ Complete
M6: Report Engine ✅ Complete
M7: Deployment Guard ✅ Complete
M8: Exploit Engine ✅ Complete
M9: Contract Verification ✅ Complete
M10: Gas/Deps/Fuzz/CI/Bench ✅ Complete
M11: AI-Powered Auditing ✅ Complete
M12: Testing & Documentation ✅ Complete
M13: Post-MVP Polish ✅ Complete
M14: Developer Experience & Integrations ✅ Complete
M15: External Tooling & Interoperability ✅ Complete
M16: Performance & Visualization ✅ Complete — Parallel Chain Auditing, Historical Trend Tracking, Dashboard Mode
M17: CI/CD & Platform Expansion ✅ Complete — Docker Image (ghcr.io multi-arch), Homebrew Tap (cargo-dist formula), VS Code Extension Config