🔒 Forge Guard

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

📋 Table of Contents

Overview
Key Features
Milestone Summary
Installation
Quick Start
All Commands
Usage Examples
Configuration
Architecture
Security Checks
Plugin Development
CI/CD Integration
Performance
Development
Supported Chains
Changelog
Contributing
License
Roadmap

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
🔌 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 audit --quick skips parser-heavy checks, ~5x faster for rapid feedback
📋 Executive Summary — forge 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

Milestone Summary

All 13 development milestones are complete. 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	200+ tests, comprehensive README, CONTRIBUTING.md, CI workflows
⚡	M13 — Post-MVP Polish	Quick mode (~5x faster), executive summary, incremental file analysis, `--summary` flag

Detailed breakdown: milestone-based-roadmap.md

Installation

Prerequisites

Rust 1.85+ — Install
Foundry — Install

Option 1: Install via Cargo

cargo install forge-guard

Option 2: Build from Source

git clone https://github.com/codetibo/forge-guard.git
cd forge-guard
cargo build --release
cp target/release/forge-guard ~/.foundry/bin/

Option 3: Add to PATH

# Add to your .bashrc or .zshrc:
export PATH="$HOME/.foundry/bin:$PATH"

Verify Installation

forge audit --version
forge audit --help

Quick Start

Navigate to a Foundry project and run:

cd my-foundry-project

# Run a comprehensive security audit
forge audit

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

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

# Check deployment readiness
forge audit --production

# Generate Markdown report
forge 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 audit`	Run security audit with 50+ checks	`forge audit --full --chain base`
`forge audit --quick`	Quick audit (skips parser-heavy checks)	`forge audit --quick`
`forge audit --summary`	Executive summary report	`forge audit --summary`
`forge deploy`	Deploy with security guard	`forge deploy --force`
`forge deploy-safe`	Deploy with mandatory security pass	`forge deploy-safe Counter`
`forge fuzz`	Run fuzzing campaigns	`forge fuzz --runs 50000`
`forge invariant`	Run invariant tests	`forge invariant --runs 2000`
`forge simulate`	Deployment simulation	`forge simulate --blocks 200`
`forge gas`	Gas usage analysis	`forge gas --all`
`forge report`	Generate audit reports	`forge report --format markdown`
`forge verify`	Verify contract deployments	`forge verify --all`
`forge doctor`	Project health analysis	`forge doctor --fix`
`forge watch`	Watch for changes and re-audit	`forge watch --dirs src`
`forge ci`	Generate CI/CD configs	`forge ci --platform github`
`forge benchmark`	Performance benchmarks	`forge benchmark --iterations 50`
`forge scan`	Dependency vulnerability scan	`forge scan --update`
`forge upgrade-check`	Upgrade path analysis	`forge upgrade-check --all`
`forge plugins`	Manage plugins	`forge plugins list`
`forge chain`	Chain configuration	`forge chain list`
`forge security`	Security configuration	`forge security list`

Common Flags

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

Detailed Usage Examples

Security Audit

# Standard audit
forge audit

# Full audit with everything
forge audit --full

# Cross-chain audit
forge audit --chain arbitrum
forge audit --chain base --chain polygon
forge audit --all-chains

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

# Analysis scope
forge audit --strict           # Fail on any MEDIUM+ finding
forge audit --production       # Production readiness check
forge audit --offline          # Skip network calls
forge audit --exploit          # Include exploit path generation
forge audit --gas              # Include gas analysis

Deployment Guard

# Safe deploy (blocked by issues)
forge deploy

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

# Deploy specific contract
forge deploy MyContract

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

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

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

Contract Verification

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

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

# Verify on a specific chain
forge 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 audit --quick

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

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

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

AI-Powered Auditing

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

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

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

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

Deployment Simulation

# Run deployment simulation
forge simulate

# With MEV analysis
forge simulate --mev

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

Dependency Scanning

# Scan project dependencies
forge scan

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

# Update vulnerability database
forge scan --update

# JSON output
forge scan --json

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

Project Health

# Full health check
forge doctor

# Verbose output
forge doctor --verbose

# Auto-fix issues
forge doctor --fix

# Check specific category
forge doctor --check dependencies

Plugin Management

# List installed plugins
forge plugins list

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

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

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

# Remove
forge plugins remove my-custom-check

CI/CD Generation

# GitHub Actions
forge ci --platform github

# GitLab CI
forge ci --platform gitlab

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

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

# Overwrite existing configs
forge ci --overwrite

Configuration

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

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)

# ── 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)

Command-Line Overrides

CLI flags override config file values:

forge audit --strict         # Overrides security config
forge audit --chain base     # Overrides default chain
forge 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/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 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 audit --strict
      - name: Scan Dependencies
        run: forge scan --depth 1
      - name: Generate Report
        run: forge 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 audit --strict --production
      - name: Safe deploy
        run: forge 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 benchmark --iterations 50

# Benchmark specific module
forge benchmark --module source_discovery

# Compare with baseline
forge 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

Testing

# Run all tests (200+)
cargo test

# Run specific test suites
cargo test --lib              # Unit tests
cargo test --test mod         # Integration tests
cargo test --test integration # Quick mode & incremental analysis 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	✅ 8	integration_tests
Security engine	✅ 6	security_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	✅ 5	in-module tests
Doctor	✅ 4	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

forge-guard 0.1.2