npm package: @0xjasonn/solql
Description: CodeQL for Solidity — composable static analysis for AI agents
Latest version: 0.1.0

# solql

[![CI](https://github.com/0xJasonn/solql/actions/workflows/ci.yml/badge.svg)](https://github.com/0xJasonn/solql/actions/workflows/ci.yml)

**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](#solql)
  - [Features](#features)
  - [Usage](#usage)
  - [How to Install](#how-to-install)
    - [Using pnpm (Recommended)](#using-pnpm-recommended)
    - [Using npm](#using-npm)
    - [Agent Setup](#agent-setup)
    - [Shell Completions](#shell-completions)
  - [Commands](#commands)
  - [Makefile](#makefile)
  - [Composable Queries](#composable-queries)
  - [MCP Server (Optional)](#mcp-server-optional)
  - [Global Options](#global-options)
  - [How It Works](#how-it-works)
  - [Getting Help](#getting-help)
  - [Development](#development)
  - [License](#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:

```console
solql overview .
```

Point it at a project in another directory:

```console
solql overview ~/projects/my-protocol
```

Analyze a specific contract:

```console
solql surface Vault ~/projects/my-protocol
```

Trace where a parameter flows:

```console
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](https://getfoundry.sh/) (for `forge build --ast`).

### Using pnpm (Recommended)

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

### Using npm

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

```console
# 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):

```console
solql skills add
```

### Shell Completions

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

For full documentation with usage examples and JSON output format for every command, see the [Command Documentation](docs/commands.md).

## Makefile

Commands can get verbose. The repo ships a [`Makefile`](Makefile) with shorthand targets for every command:

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

```console
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/`](queries/) directory. See the [query documentation](docs/commands.md#query) 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](#agent-setup)). To configure manually:

```json
{
  "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](docs/commands.md) for detailed usage and output format for every command
- Run `make help` for a quick reference of all Makefile targets
- [Open an issue](https://github.com/0xJasonn/solql/issues) for bugs or feature requests

## Development

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

## License

MIT