# Forge Guard — Milestone-Based Roadmap
> ✅ **All 13 core milestones are complete.** The framework is production-ready.
> All features below are **non-breaking additions** — they add new capabilities without
> modifying or risking any existing functionality.
---
## Milestones 1–13: Core Framework (✅ Complete)
| 🏗️ | M1 — Core Architecture | ✅ Cargo project, error handling, config system, module structure |
| 🎮 | M2 — CLI Framework | ✅ 18 subcommands via clap, global flags |
| 🔒 | M3 — Security Engine | ✅ 50+ vulnerability checks, 11-category scoring |
| 🔌 | M4 — Plugin Architecture | ✅ Plugin trait, built-in + IPC plugins, lifecycle mgmt |
| ⛓️ | M5 — Multi-Chain | ✅ 17 EVM chains, alias resolution, chain registry |
| 📊 | M6 — Report Engine | ✅ Terminal, JSON, Markdown, HTML reports |
| 🛡️ | M7 — Deployment Guard | ✅ Pre-deployment pipeline, deploy-safe, MEV detection |
| 💥 | M8 — Exploit Engine | ✅ Attack vector generation, storage collision analysis |
| 🩺 | M9 — Contract Verification | ✅ 17-chain explorer registry, forge verify, RPC match |
| 🔧 | M10 — Gas/Deps/Fuzz/CI | ✅ Gas analysis, 30-entry vuln DB, fuzzing, CI templates |
| 🤖 | M11 — AI Auditing | ✅ OpenAI, Claude, Ollama, consensus engine |
| 🧪 | M12 — Testing & Docs | ✅ 200+ tests, README, CONTRIBUTING.md |
| ⚡ | M13 — Post-MVP Polish | ✅ Quick mode, summary, incremental analysis |
---
## 🚀 M14 — Developer Experience & Integrations (✅ Complete)
*New features only — zero changes to existing commands or APIs.*
### 📦 SBOM Generation (`forge-guard sbom`)
- [x] Generate **CycloneDX** and **SPDX** SBOMs from Foundry dependencies
- [x] Parse Solidity imports and forge remappings to build dependency trees
- [x] Include license, version, and source URL for each dependency
- [x] `--format cyclone|spdx` flag for format selection
- [x] `--output` flag for file output
- [x] CI/CD export for supply-chain compliance — `forge-guard sbom --ci` writes `.github/workflows/sbom.yml`
*Why: Compliance requirements (EO 14028, NTIA minimum elements) demand SBOMs. Entirely new subcommand — no risk to existing features.*
### 🪝 Git Pre-Commit Hook Installer (`forge-guard install-hook`)
- [x] Install a git pre-commit hook via `forge-guard install-hook`
- [x] Hook runs `forge-guard audit --quick` on staged `.sol` files before commit
- [x] Blocks commit on HIGH/CRITICAL findings unless `--force` or env var override
- [x] `--uninstall` to remove the hook cleanly
- [x] Respects `.gitignore` and staged-only files for minimal latency (audits each staged file via `--sources`)
*Why: Catches vulnerabilities before they reach CI. New subcommand — isolated from all existing code.*
### 🔄 Foundry Config Sync (`forge-guard doctor --sync`)
- [x] Read `foundry.toml` and auto-populate matching `forge-guard.toml` settings
- [x] Sync `src`, `test`, `lib`, `remappings`, `solc_version` into audit config
- [x] `--dry-run` to preview changes without writing
- [x] `--diff` to show what would change
*Why: Reduces duplicated configuration. Extension of existing `doctor` command — adds a flag, modifies no existing behavior.*
### 📋 Template Library (`forge-guard audit --template <name>`)
- [x] Pre-built audit profile templates for common contract types:
- `erc20` — focuses on ERC20 compliance, approval bugs, permit replay
- `erc721` — focuses on NFT-specific patterns, royalties, metadata
- `defi` — focuses on lending, AMM, oracle dependencies
- `bridge` — focuses on cross-chain messaging, validator sets
- `upgradeable` — focuses on proxy patterns, storage layouts, initializers
- [x] Each template adjusts enabled checks, severity thresholds, and scoring weights
- [x] `forge-guard audit --list-templates` to show available templates
- [x] Templates are JSON files in `~/.forge-guard/templates/` — user-customizable
*Why: Makes audit results more relevant by focusing on the contract's risk profile. New flag on existing `audit` command — additive only.*
---
## 🚀 M15 — External Tooling & Interoperability (✅ Complete)
### 🔌 External Analyzer Import (`forge-guard import`)
- [x] `forge-guard import --from slither results.json` — import Slither JSON findings into Forge Guard format
- [x] `forge-guard import --from mythril results.json` — import Mythril results
- [x] `forge-guard import --from semgrep results.json` — import Semgrep results
- [x] Severity mapping between tool-specific scales and Forge Guard's 5-level scale
- [x] Deduplication against Forge Guard's own findings
- [x] Unified reporting: generate combined report from all sources
*Why: Lets teams adopt Forge Guard incrementally alongside existing tools. New subcommand — zero risk.*
### 📢 Webhook Notifications (`forge-guard notify`)
- [x] `forge-guard notify --webhook <URL>` after audit/scan commands
- [x] Built-in formatters for **Slack** (rich message blocks) and **Discord** (embeds)
- [x] Customizable notification levels: `--on-critical`, `--on-high`, `--on-failure`
- [x] Configurable via `forge-guard.toml`: `[notifications.slack]` / `[notifications.discord]`
- [x] Support for `--notify` flag on `audit`, `deploy`, `deploy-safe` commands
*Why: Teams want CI/CD alerts without checking the Actions tab. New module — isolated.*
### 📄 Suppression File Support
- [x] `forge-guard audit --suppressions .forge-guard-suppressions`
- [x] Suppression file format: `FA-H-001 # Known false positive in Vault.sol`
- [x] `--show-suppressed` to include suppressed findings in output (visually marked)
- [x] `forge-guard audit --generate-suppressions` to create a suppression file from current findings
- [x] Persist across audit runs — useful for accepted risks and known false positives
*Why: Audit tools that can't suppress known issues force teams to scroll past noise. New flag — additive only.*
---
## 🚀 M16 — Performance & Visualization
### ⚡ Parallel Chain Auditing
- [x] Audit multiple chains in parallel via Rayon when `--all-chains` is specified
- [x] Configurable `--max-parallel-chains` to avoid RPC rate limits
- [x] Aggregated report across all chains with chain-specific findings labeled
*Why: `--all-chains` currently audits sequentially; parallel would cut time from O(n) to near-constant. Performance improvement only — no API change.*
### 📊 Dashboard Mode (`forge-guard dashboard`)
- [x] Starts a local HTTP server (default `127.0.0.1:9090`, `--host`/`--port` configurable)
- [x] Real-time display of the last audit result with interactive filtering (severity chips, search, chain filter)
- [x] Severity charts, score gauges, finding lists with expandable details
- [x] WebSocket auto-refresh — the page live-updates on every new audit; `--watch` re-audits on file changes and pushes the result
- [x] `--port` flag for custom port binding (`--open` opens the browser)
*Why: Visual exploration complements terminal output. New subcommand — isolated.*
### 📈 Historical Trend Tracking
- [x] Audit results are persisted in a local SQLite database (~/.forge-guard/history.db)
- [x] `forge-guard report --history` shows score trends over time
- [x] `forge-guard report --regression` highlights new findings since last audit
- [x] Optional — opt-in via `[history]` config section or `--enable-history` flag
- [x] Hot path unaffected: recording is opt-in and best-effort — a failed write never fails the audit
*Why: Teams want to track security posture improvement over time. New report option — additive only.*
---
## 🚀 M17 — CI/CD & Platform Expansion
### 🐳 Docker Image
- [x] Multi-arch Docker image published to GitHub Container Registry (ghcr.io)
- [x] `docker pull ghcr.io/codetibo/forge-guard:latest`
- [x] Pre-configured with Foundry and forge-guard
- [x] Image builds automated via GitHub Actions on tag push
*Why: CI users without Rust can pull a pre-built image. Complements cargo-dist binaries.*
### 🍺 Homebrew Tap
- [ ] `brew install codetibo/tap/forge-guard`
- [ ] Auto-generated formula via cargo-dist
- [ ] Updated on each release
*Why: macOS developers prefer Homebrew for tooling. Already partially supported by cargo-dist.*
### 🔐 VS Code Extension Config Generator
- [ ] `forge-guard ci --vscode` generates `.vscode/settings.json` with:
- Custom Solidity validation rules
- Audit-on-save integration for Solidity files
- Problem matcher for forge-guard output in VS Code Problems panel
*Why: Developer experience improvement for VS Code users. Extension of existing `ci` command.*
---
## 🚀 M18 — Advanced Security Analysis
### 🔍 Code Complexity Metrics
- [ ] Cyclomatic complexity analysis per function
- [ ] Nesting depth warnings (> 4 levels deep)
- [ ] Function length warnings (> 50 lines)
- [ ] State variable count warnings (> 10 state variables)
- [ ] Integration into audit report as LOW severity findings
*Why: Complex code is harder to audit and more error-prone. New checks for existing security engine.*
### 🔄 Upgrade Path Simulation
- [ ] `forge-guard upgrade-check --simulate` — simulate upgrade transactions
- [ ] Storage collision detection between old and new implementations
- [ ] Function selector clash detection
- [ ] UUPS vs Transparent proxy pattern validation
- [ ] State variable ordering verification
*Why: Storage collisions during upgrades have caused multi-million-dollar exploits. Enhancement to existing `upgrade-check` command.*
### 📦 Multi-Version Solidity Analysis
- [ ] Detect when a project uses conflicting Solidity versions
- [ ] Report version-specific known vulnerabilities per compiler version
- [ ] Flag unsafe version pragmas (`^0.8.0` vs `pragma solidity >=0.8.0 <0.9.0`)
*Why: Solidity version mismatches can introduce subtle bugs. New checks — additive.*