🔒 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
• ⚡ 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)

---

Milestone Summary

All 15 development milestones are complete, and M16's Parallel Chain Auditing is 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

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: 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 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 configs	forge-guard ci --platform github
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

# 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

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)

# ── 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/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	🔄 In Progress — Parallel Chain Auditing ✅, Dashboard & Trends pending