w3goaudit

README

W3GoAudit

A Go-based CLI & SDK for auditing Solidity smart contracts using rule-based templates with WQL query language.

---

Quick Start

# Install (templates download on first run; embedded pack is the offline fallback)
go install github.com/th13vn/w3goaudit/cmd/w3goaudit@latest

# Scan contracts → writes a ./contracts result folder
w3goaudit ./contracts/

# Scan one file into a named folder
w3goaudit Token.sol -o audit/

# Use a custom template directory
w3goaudit ./contracts/ -t ./my-templates/

# Only high + critical findings
w3goaudit ./contracts/ -s high,critical

# Print the summary only, write nothing
w3goaudit ./contracts/ -q

# Build database
w3goaudit build ./contracts/ -o database.json

# Extract contract info — every extract subcommand can build from a source
# path (like the scan) or load a pre-built database with --db
w3goaudit extract main ./contracts/
w3goaudit extract inheritance MyToken ./contracts/
w3goaudit extract entry MyToken --db database.json

Example console output:

▶ Reading sources: ./contracts/
▶ Building database: 74 files, 164 contracts, 1203 functions
▶ Scanning: 25 templates (~/.w3goaudit/templates)
▶ Writing report: ./contracts-audit

81 findings: 65 HIGH, 16 MEDIUM · scanned 74 contracts in 51ms
── Findings ──────────────────────────────────────────────
  🟠 HIGH (65 findings)
  1. Arbitrary transferFrom Call
  2. Unchecked ERC20 transfer / transferFrom Return Value
  ... (titles only on console; full detail in findings.md, or use --verbose)

📂 Results written to: ./contracts-audit

Results land in a folder — overview.md, findings.md, results.sarif, run.log, a machine-readable corpus/ (JSON + DB), and one sub-folder per main contract with per-entry workflow files and a state-change report. See Result folder layout.

---

Features

• AST Parsing - Parse Solidity using solast-go
• Contract Database - Comprehensive database with inheritance, entry points, call graphs
• Semantic Type Facts - Parameters, state variables, locals, casts, and call receivers carry lightweight type facts so WQL can stay simple while call classification becomes more precise
• C3 Linearization - Proper Solidity inheritance resolution
• Function Selectors - Calculate 4-byte keccak256 selectors
• Call Graph - Recursive tracing with filtered built-ins and optimized styling
• WQL Templates - Powerful query language for security pattern matching, with load-time validation (regex, preset names, filter/match placement) so typos fail fast instead of producing silent zero-finding scans. Includes scope-aware source_regex for rare raw-source predicates.
• Result Folder - One opinionated folder per scan: overview.md, findings.md, always-on results.sarif + run.log, a machine-readable corpus/ (database.json reusable via --db, findings.json, overview.json), and one sub-folder per main contract. Opt-in HTML mirror with --html.
• Per-Entry Workflow Files - For every entry function, a self-contained context block (signature, auth / access control, guards & checks, branch conditions, transitive state effects, Mermaid call workflow) — built to be fed to a human or an AI auditor.
• State-Change Matrix - Per contract, each state variable mapped to the functions that write it and the entry points that reach a writer (reverse call-graph walk).
• Self-Provisioning Templates - Downloads the latest w3goaudit-templates release on first run (nuclei-style, no git clone), refreshable with --update-templates; embedded official pack is the always-available offline fallback.
• Reachability-Aware Findings - Every finding can carry the full call chain from an externally-callable entry down to the function that hosts the dangerous statement: structured reachability.steps[] + entryPoint (auditor's fix-here pointer) + primaryAst in JSON, relatedLocations in SARIF, dotted-level trace block in Markdown / HTML, ↳ via … continuation line on the --verbose console.
• SARIF 2.1.0 - Always emitted (results.sarif) for GitHub Code Scanning, with portable relative URIs + srcRoot; fail-closed template loading, NO_COLOR-aware console.
• Project Detection - Auto-detect Foundry, Hardhat, Truffle
• Git Integration - Auto-detect git repos and generate clickable file links to GitHub/GitLab
• Advanced Metrics - nSLOC, Access Control Analysis, Grouped Entry Points
• Source Extraction - Extract function source, context bundles, and full transitive workflow source

---

Documentation

Comprehensive guides available in docs/:

• Workflows - Detailed internal workflows with diagrams
• Usage Guide - Complete CLI and SDK reference
• SDK Documentation - Comprehensive SDK API reference and integration guide
• WQL Syntax - Template writing reference
• Project Overview - Architecture and design

---

Installation

From Source

# Clone the repository
git clone https://github.com/th13vn/w3goaudit
cd w3goaudit

# Build
go build -o w3goaudit ./cmd/w3goaudit

# Move to PATH (optional)
sudo mv w3goaudit /usr/local/bin/

Via Go Install

go install github.com/th13vn/w3goaudit/cmd/w3goaudit@latest

Self-Update

w3goaudit --update   # re-runs `go install …@latest` (requires the Go toolchain)

---

Result Folder Layout

Every scan (unless --stdout/-q) writes a result folder, optimized to feed a human or AI auditor:

<output>/
├── overview.md            # all main contracts; pragma version per contract
├── findings.md            # human-readable findings
├── results.sarif          # SARIF 2.1.0 (always)
├── run.log                # full verbose detail (always; replaces --log)
├── corpus/                # machine-readable JSON
│   ├── database.json      # canonical DB — reuse via --db corpus/database.json
│   ├── findings.json
│   └── overview.json
└── <MainContract>/        # one folder per main contract (Name__<filestem> on collision)
    ├── state-changes.md   # state var → Written By (fns) → Reachable From (entries)
    └── workflows/
        ├── <entryFn>.md             # one file per entry function
        └── <entryFn>__<selector>.md # overloads disambiguated by 4-byte selector

The default folder name is the scanned project dir name (or .sol file stem); -o/--output overrides it, and -audit is appended if the default would collide with the scanned directory. Each workflows/<entryFn>.md records the signature (selector, 4-byte, payable, version), auth / access control (modifiers, msg.sender checks, ⚠ Unprotected, ⚠ tx.origin), guards/checks, branch conditions, transitive state effects, and a Mermaid call-workflow diagram.

---

CLI Quick Reference

Commands

Command	Description
(default)	Scan contracts — stats, overview, findings
build	Build contract database (JSON)
extract main	Main (deployable) contracts in a project
extract entry	Entry point functions for a contract
extract inheritance	C3 linearization (derived → base) — must be a main contract
extract statevar	State variables (including inherited, storage order)
extract selector	Function selectors (4-byte hashes)
extract involve	Every entry-point workflow that reaches a function, one Mermaid chart per entry
extract workflow	Full transitive source for an entry function (report-ready)
extract bundle	LLM-ready one-document context: source + callers + callees + state + inheritance + selectors
extract context	Combined context package for a function
extract source	Raw Solidity source for a function
extract diff	Compare two pre-built databases
completion	Generate shell completions
version	Show version information

The root command is the scan (there is no scan subcommand). Every scan flag has a long and short form: -o/--output, -t/--template, -d/--db, -v/--verbose, -s/--severity (exact set), -m/--min-severity (threshold), -i/--include, -e/--exclude, -l/--list-templates, -H/--html, -q/--stdout, -T/--update-templates, -u/--update. --severity and --min-severity are mutually exclusive.

extract subcommands are listed widest-scope first (project → contract → function → utility). Like the scan, each one (except diff) can build from a source path — extract <name> ./contracts/ — or load a pre-built database with --db. Extract output defaults to markdown; pass --format=json (or -o file.json) for the machine-readable shape.

Examples

# Default scan → writes a ./contracts result folder
w3goaudit ./contracts/

# Scan one file into a named folder
w3goaudit Token.sol -o audit/

# Use a custom template directory
w3goaudit ./contracts/ -t ./templates/official/

# Only high + critical (exact set), or a threshold + exclude glob
w3goaudit ./contracts/ -s high,critical
w3goaudit ./contracts/ -m medium -e 'HIGH-WEAK-PRNG'

# Also emit the HTML mirror, or print the summary only (write nothing)
w3goaudit ./contracts/ -H
w3goaudit ./contracts/ -q

# List the active template set (no path needed)
w3goaudit -l

# Re-scan a pre-built database (e.g. the corpus DB from a previous run)
w3goaudit -d ./contracts/corpus/database.json

# Refresh templates from the latest release; update the tool itself
w3goaudit --update-templates
w3goaudit --update

# Extract directly from source (builds the database on the fly)
w3goaudit extract main ./contracts/
w3goaudit extract statevar MyToken ./contracts/

# …or build once and reuse the database across many extracts
w3goaudit build ./contracts/ -o db.json
w3goaudit extract entry MyToken --db db.json
w3goaudit extract selector MyToken --db db.json
w3goaudit extract diff --db1 old.json --db2 new.json

# LLM-ready bundle: one markdown document with source + callers/callees + state + inheritance
w3goaudit extract bundle withdraw --db db.json --contract MyToken -o bundle.md

# Every workflow that reaches a function, as markdown for AI agents
w3goaudit extract involve withdraw --db db.json --format=md

# Shell completion
source <(w3goaudit completion bash)

For complete usage, see Usage Guide.

---

SDK Quick Reference

import (
    "github.com/th13vn/w3goaudit/pkg/reader"
    "github.com/th13vn/w3goaudit/pkg/builder"
    "github.com/th13vn/w3goaudit/pkg/engine"
)

// Read sources
r := reader.New()
sources, _ := r.Read("./contracts/")

// Build database
b := builder.New()
db, _ := b.Build(sources)

// Execute template
e := engine.New(db)
tmpl, _ := engine.LoadTemplate("./template.yaml")
findings := e.Execute(tmpl)

For complete SDK documentation, see Usage Guide.

---

WQL Template Example

meta:
  id: SEC-REEN-001
  title: Potential Reentrancy
  severity: HIGH
  confidence: MEDIUM
  description: External call before state variable update
  recommendation: Apply Check-Effects-Interactions pattern

query:
  scope: entrypoint  # Public/external functions only
  filter:
    not:
      modifier: (?i)(nonReentrant|lock|guard)
  match:
    # Find: external call → state modification
    contains:
      sequence:
        - kind: outgoing_call
        - kind: state_write

For complete WQL syntax, see WQL Syntax Guide.

---

Project Structure

w3goaudit/
├── cmd/w3goaudit/          # CLI entry point (root scan, build, extract, completion)
├── pkg/
│   ├── reader/             # File discovery and loading
│   ├── builder/            # Database construction (7 phases incl. per-fn effects)
│   ├── engine/             # WQL template execution
│   ├── home/               # ~/.w3goaudit config + template home (release download)
│   ├── types/              # Core data structures
│   └── report/             # Result-folder bundle, state matrix, console/MD/HTML/SARIF
├── templates/              # WQL detection templates (official/ embedded via go:embed)
│   ├── official/              # Curated official pack (embedded fallback; split by severity: critical/ high/ medium/)
│   └── test/                  # Engine feature-exercise templates
├── test-data/              # Test contracts (core/, security/)
└── docs/                   # Comprehensive documentation

---

Key Workflows

1. Scan Workflow

Input → Reader → Builder → Database → Engine → Findings → Result-folder bundle

1. Discover .sol files
2. Parse with solast-go
3. Build database (inheritance, call graph, selectors, per-function effects)
4. Load WQL templates (home → embedded fallback)
5. Execute queries
6. Generate findings
7. Write the result folder (overview, findings, SARIF, run.log, corpus, per-contract workflows + state-changes)

2. Build Workflow

Build phases:

1. Parse files
2. Build ASTs, data flow, and semantic type facts
3. Calculate selectors
4. Build inheritance (C3)
5. Build call graph
6. Calculate entry points
7. Analyze per-function effects (state writes, guards, access control)

3. Default Scan (Combined) Workflow

The default scan combines stats, overview, and findings:

• Statistics (files, contracts, functions, nSLOC)
• Contract hierarchy with call graphs (Mermaid diagrams)
• Security findings (when templates provided)

For detailed workflows, see Workflows Documentation.

---

Database Structure

The contract database contains:

• Contracts - All contracts with kind, inheritance, functions, state variables
• Functions - Visibility, modifiers, parameters, selectors, AST trees
• Inheritance - C3 linearization for proper method resolution
• Call Graph - Internal/external call edges with line numbers
• Entry Points - Public/external functions per main contract
• Main Contracts - Deployable contracts ranked by inheritance depth

---

Testing

# Build database
w3goaudit build test-data/core/build-database/ -o test-db.json --verbose

# Security scan → writes a test-data/security result folder
w3goaudit test-data/security/ --template templates/official/ -o scan-report/

# Project overview (always part of the scan — see overview.md in the folder)
w3goaudit test-data/core/build-database/ -o overview-out/

Test contracts are documented in:

• test-data/security/README.md
• test-data/core/build-database/README.md

---

Roadmap

Current Features

• AST parsing and contract database
• C3 inheritance linearization
• Recursive call graph building
• Per-function effects analysis (state writes, guards, access control)
• WQL query language
• Result-folder output: Markdown + SARIF + JSON corpus + per-entry workflows + state-change matrix
• Self-provisioning template home (~/.w3goaudit) with release download + embedded fallback
• CLI and SDK
• Source/context/workflow extraction for report writing

Planned Features 🔜

• Repository scanning (GitHub)
• On-chain contract fetching (Etherscan API)
• Enhanced data flow analysis
• Visualization exports (Mermaid, DOT)
• LSP integration for IDE support
• Template marketplace

For complete roadmap, see Project Overview.

---

Contributing

Contributions are welcome — especially new detectors, which you can write in YAML without touching Go. See CONTRIBUTING.md for a "write your first detector in 5 minutes" walkthrough, the dev setup, and the PR checklist.

To report a vulnerability in the tool itself, see SECURITY.md (please don't open a public issue).

---

License

MIT © th13vn. Third-party dependency and trademark notices are in NOTICE.

---

Links

• Documentation: docs/
• Templates: templates/
• Test Data: test-data/
• AST Parser: solast-go