forge-guard 0.3.5

# 🔒 Forge Guard

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

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Rust](https://img.shields.io/badge/Rust-1.85%2B-orange)](https://www.rust-lang.org)
[![Foundry](https://img.shields.io/badge/Foundry-compatible-blue)](https://book.getfoundry.sh/)
[![CI](https://github.com/codetibo/forge-guard/actions/workflows/ci.yml/badge.svg)](https://github.com/codetibo/forge-guard/actions/workflows/ci.yml)
[![Nightly Audit](https://github.com/codetibo/forge-guard/actions/workflows/nightly-audit.yml/badge.svg)](https://github.com/codetibo/forge-guard/actions/workflows/nightly-audit.yml)
[![Dependabot](https://img.shields.io/badge/dependabot-enabled-025E8C?logo=dependabot)](https://github.com/codetibo/forge-guard/blob/main/.github/dependabot.yml)
[![Crates.io](https://img.shields.io/crates/v/forge-guard?logo=rust&label=version)](https://crates.io/crates/forge-guard)
[![Changelog](https://img.shields.io/badge/changelog-latest-blue?logo=github)](CHANGELOG.md)

---

## 📋 Table of Contents

- [Overview](#overview)
- [Key Features](#key-features)
- [Milestone Summary](#milestone-summary)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [All Commands](#all-commands)
- [Usage Examples](#detailed-usage-examples)
- [Configuration](#configuration)
- [Architecture](#architecture)
- [Security Checks](#security-checks)
- [Plugin Development](#plugin-development)
- [CI/CD Integration](#cicd-integration)
- [Performance](#performance)
- [Development](#development)
- [Supported Chains](#supported-chains)
- [Changelog](CHANGELOG.md)
- [Contributing](#contributing)
- [License](#license)
- [Roadmap](#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`)
- 📈 **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](milestone-based-roadmap.md)

---

## Installation

### Prerequisites

- **Rust** 1.85+ — [Install](https://www.rust-lang.org/tools/install)
- **Foundry** — [Install](https://book.getfoundry.sh/getting-started/installation)

### Option 1: Install via Cargo

```bash
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:

```bash
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](https://opensource.axo.dev/cargo-dist/) on every release and published to the [codetibo/homebrew-tap](https://github.com/codetibo/homebrew-tap) tap:

```bash
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

```bash
# 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

```bash
forge-guard --version
forge-guard audit --help
```

---

## Quick Start

Navigate to a Foundry project and run:

```bash
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 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](COMMANDS.md) for detailed documentation of every subcommand, flag, and example.

### Common Flags

```bash
--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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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.

```bash
# 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:
```bash
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.

```bash
# 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:

```bash
# 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:

```bash
# 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](#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`](examples/.forge-guard-suppressions) for the file format):

```bash
# 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`:

```text
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.

```bash
# 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**:

```json
{
  "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`](examples/forge-guard.toml) for a fully commented config (including Slack/Discord webhooks) and [`examples/.forge-guard-suppressions`](examples/.forge-guard-suppressions) for a sample suppression file.

### Minimal Configuration

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

### Full Configuration Reference

```toml
# ── 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:

```bash
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:

```rust
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:

```bash
# 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)

```yaml
# 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

```yaml
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

```bash
# 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

```bash
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

```bash
# 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

```bash
# 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](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](LICENSE) for details.

---

## Roadmap

See [milestone-based-roadmap.md](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 | 🔄 In Progress — Docker Image ✅ (ghcr.io multi-arch), Homebrew Tap ✅ (cargo-dist formula), VS Code config pending |