solql

solql is a composable static analysis framework for Solidity, written in TypeScript. It runs 17 analysis commands over Solidity ASTs, provides a query command for custom analyses, and serves as an MCP server for AI agents. Built for security auditors who want deterministic answers, not heuristics.

Note: This is beta software. Use at your own risk and please provide feedback.

• solql
  • Features
  • Usage
  • How to Install
    • Using pnpm (Recommended)
    • Using npm
    • Agent Setup
    • Shell Completions
  • Commands
  • Makefile
  • Composable Queries
  • MCP Server (Optional)
  • Global Options
  • How It Works
  • Getting Help
  • Development
  • License

Features

• 17 analysis commands covering data flow, control flow, call graphs, pattern detection, and more
• Forward taint analysis with path-sensitive (CFG-aware) mode
• CEI compliance checking and reentrancy risk detection
• State variable lifecycle analysis with coupled state and ordering edge detection
• Cross-contract trust boundary analysis
• Graph intersection queries: vulnerability = reachable(CFG) ∩ tainted(DDG) ∩ ¬guarded
• Composable query command with 30+ primitives available as TypeScript globals
• First-class MCP server support for AI agents (Claude, etc.)
• Average execution time of less than 1 second per command (after initial build)

Usage

Run solql on a Foundry project:

solql overview .

Point it at a project in another directory:

solql overview ~/projects/my-protocol

Analyze a specific contract:

solql surface Vault ~/projects/my-protocol

Trace where a parameter flows:

solql taint amount ~/projects/my-protocol --contract Vault --function deposit

Use --skip-build to reuse cached Forge artifacts for repeated analysis.

How to Install

Note solql requires Node.js >= 22 and Foundry (for forge build --ast).

Using pnpm (Recommended)

git clone https://github.com/0xJasonn/solql.git && cd solql
pnpm install && pnpm build
pnpm link --global

Using npm

git clone https://github.com/0xJasonn/solql.git && cd solql
npm install && npm run build
npm install -g .

solql is now available system-wide.

Agent Setup

Register solql as an MCP server with your AI agent:

# Auto-detect and register with all installed agents
solql mcp add

# Or target a specific agent
solql mcp add --agent cursor

Supported agents: Claude Code, Cursor, VS Code, Codex, Amp, Gemini CLI, GitHub Copilot CLI, Cline, Goose, Zed, OpenCode.

For Claude Code, you can also install skills (lighter on tokens):

solql skills add

Shell Completions

eval "$(solql completions bash)"    # add to ~/.bashrc
eval "$(solql completions zsh)"     # add to ~/.zshrc
solql completions fish | source     # add to ~/.config/fish/config.fish

Commands

| Num | Command | What it Does | | --- | -------------------- | ------------------------------------------------------------------------------------------- | | 1 | overview | List all contracts, files, and inheritance chains | | 2 | surface | Entry points, state vars, modifiers for a contract | | 3 | recon | Full protocol recon: access control, state writes, parameter flow | | 4 | taint | Forward taint: trace where a parameter flows | | 5 | branch-taint | CFG-aware taint with branch condition tracking | | 6 | state-changes | State variables a function mutates | | 7 | msg-sender | Trace msg.sender flow and constraints | | 8 | impact | Blast radius: transitive state changes + external calls | | 9 | cfg | Control flow graph (branches, loops, returns, reverts) | | 10 | cei | Checks-Effects-Interactions compliance / reentrancy risk | | 11 | guards | Conditions on the path from entry to a target node | | 12 | callgraph | Call paths to/from a function | | 13 | patterns | AST anti-patterns (unchecked-return, tx-origin, etc.) | | 14 | modifiers | Modifier usage, flag unguarded state-changers | | 15 | lifecycle | State variable lifecycle: writers, readers, coupled state | | 16 | trust-boundary | Cross-contract trust boundaries and callback risks | | 17 | graph-intersection | Reachable ∩ tainted ∩ ¬guarded vulnerability query |

For full documentation with usage examples and JSON output format for every command, see the Command Documentation.

Makefile

Commands can get verbose. The repo ships a Makefile with shorthand targets for every command:

# Before
solql taint to . --contract Token --function transfer --skip-build

# After
make taint C=Token F=transfer P=to

Run make help to see all targets.

| Variable | Meaning | Example | | -------- | ---------- | ----------------------- | | ROOT | Project | ROOT=~/my-protocol | | C | Contract | C=Vault | | F | Function | F=deposit | | P | Parameter | P=amount | | V | Variable | V=totalSupply | | N | Node ID | N=1234 | | FILE | Query file | FILE=queries/recon.ts |

Composable Queries

The query command lets you write TypeScript scripts with access to all analysis primitives as globals:

solql query . --skip-build --inline '
  const CONTRACT = "MyVault";
  const eps = stateChangingEntryPoints(CONTRACT);
  return eps.map(ep => ({
    name: ep.name || ep.kind,
    stateChanges: stateChanges(CONTRACT, ep.name),
    cei: cei(CONTRACT, ep.name),
    impact: impact(CONTRACT, ep.name),
  }));
'

32 reusable query templates ship in the queries/ directory. See the query documentation for the full list of available globals.

MCP Server (Optional)

The MCP server is not required — the CLI works standalone. MCP adds structured JSON responses for AI agents.

The recommended setup is solql mcp add (see Agent Setup). To configure manually:

{
  "mcpServers": {
    "solql": {
      "command": "npx",
      "args": ["solql", "--mcp"]
    }
  }
}

All 17 CLI commands become MCP tools. Use solql --llms to output an agent-readable command manifest.

Global Options

Every command supports these built-in flags:

| Flag | Description | | ------------------------ | ----------------------------------------------------- | | --json | Output as JSON instead of default TOON format | | --format <fmt> | Output format: toon, json, yaml, md | | --filter-output <keys> | Filter output by key paths (e.g. contractList.name) | | --skip-build | Reuse cached Forge artifacts | | --schema | Show JSON Schema for a command's args/options | | --llms | Print agent-readable command manifest | | --help | Show help |

How It Works

1. Load — Runs forge build --ast and parses the Solidity compiler's JSON AST output
2. Index — Builds O(1) node lookup, contract registry, and C3 linearization from solc
3. Analyze — 15 modular analysis engines (taint, CFG, guards, CEI, dominance, etc.) operate as pure functions over the index
4. Query — Compose primitives in TypeScript scripts or call them individually via CLI/MCP

Getting Help

• See the Command Documentation for detailed usage and output format for every command
• Run make help for a quick reference of all Makefile targets
• Open an issue for bugs or feature requests

Development

pnpm build        # Compile TypeScript
pnpm dev          # Watch mode
pnpm test         # Run tests
pnpm check:all    # Type check + lint + test

License

MIT