Metadata-Version: 2.5
Name: strix-web3
Version: 1.7.4
Summary: Open-source AI smart-contract security auditor for every major chain and language
Project-URL: Homepage, https://github.com/hashward-io/strix-web3
Project-URL: Repository, https://github.com/hashward-io/strix-web3
Project-URL: Changelog, https://github.com/hashward-io/strix-web3/blob/main/CHANGELOG.md
Project-URL: Bug Tracker, https://github.com/hashward-io/strix-web3/issues
Project-URL: Documentation, https://github.com/hashward-io/strix-web3/tree/main/docs
Author-email: hashward-io <halvorsentech@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agent,ai,audit,cli,cybersecurity,evm,security,smart-contract,solidity,web3
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Security
Requires-Python: >=3.12
Requires-Dist: boto3>=1.28.0
Requires-Dist: cryptography<49,>=48.0.1
Requires-Dist: cvss>=3.2
Requires-Dist: docker>=7.1.0
Requires-Dist: google-auth>=2.0.0
Requires-Dist: litellm>=1.101.0
Requires-Dist: markdown-it-py>=3.0.0
Requires-Dist: openai-agents[litellm]<0.20,>=0.19.0
Requires-Dist: openai<3,>=2.45.0
Requires-Dist: pydantic-settings>=2.13.0
Requires-Dist: pydantic>=2.11.3
Requires-Dist: pypdf>=5.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: reportlab>=4.0
Requires-Dist: requests>=2.32.0
Requires-Dist: rich
Description-Content-Type: text/markdown

# Strix Web3

Autonomous, multi-agent security review for smart contracts. Strix Web3 maps a
target, enumerates the invariants it claims to hold, runs specialist attack
lenses over the value-moving paths, and proves every high-severity finding with
a runnable exploit inside the target's own toolchain.

It is a fork of [usestrix/strix](https://github.com/usestrix/strix), re-scoped from
general web penetration testing to smart-contract auditing. The managed cloud, the
HTTP proxy and the browser tooling were removed; the engine, the knowledge pack, the
sandbox and the report format are Web3-native.

> **Authorized use only.** Run Strix Web3 against code you own or have explicit,
> written permission to audit. You are responsible for that authorization.

---

<p align="center">
  <img src=".github/screenshot.png" alt="The Strix Web3 terminal interface: audit phases, the agent graph and the finding list." width="1000">
</p>

## Contents

- [What it does](#what-it-does)
- [Supported ecosystems](#supported-ecosystems)
- [Architecture](#architecture)
- [The audit pipeline](#the-audit-pipeline)
- [Installation](#installation)
- [First audit](#first-audit)
- [Run modes](#run-modes)
- [Output](#output)
- [Continuous integration](#continuous-integration)
- [Editor and agent integrations](#editor-and-agent-integrations)
- [Bug bounty pipeline](#bug-bounty-pipeline)
- [Configuration](#configuration)
- [Security model](#security-model)
- [Development](#development)
- [Credits and lineage](#credits-and-lineage)
- [License](#license)

---

## What it does

| | |
|---|---|
| **Ecosystem detection** | Identifies the target's language, build system and chain, and splits a multi-chain target into separate workstreams. |
| **Reconnaissance** | Maps contracts, roles, value-holding state, entry-point permissions and external integrations, and records the threat model. |
| **Invariant enumeration** | Writes down the conservation laws, bounds, ratios and state transitions the protocol claims, in a form the later phases can test. |
| **Attack lenses** | Twelve chain-agnostic lenses (math precision, access control, economic security, execution trace, invariant, periphery, first principles, asymmetry, boundary, numerical gap, trust gap, flow gap) run over the core subsystems, backed by per-ecosystem bug-class and protocol specialists. |
| **Proof of concept** | Every High and Critical finding carries a runnable exploit in the target's harness, or a complete reachable trace. A lead without proof is filed as a lead, not as a finding. |
| **Reporting** | One deduplicated report with CVSS scoring, an inline fix per finding, SARIF 2.1.0 for code scanning, JSON for tooling and PDF for circulation. |

---

## Supported ecosystems

| Ecosystem | Languages | Toolchain |
|---|---|---|
| EVM | Solidity, Vyper, Yul/Huff, Arbitrum Stylus | Foundry, Slither, Aderyn, Echidna, Medusa, Halmos |
| Solana | Rust, Anchor | Anchor, LiteSVM |
| Move | Sui, Aptos | Move Prover, `sui`/`aptos` CLI, snforge |
| Cairo | Starknet | Scarb, snforge |
| CosmWasm | Rust | CosmWasm tooling |
| TON | FunC, Tact | Blueprint, FunC |
| Substrate | ink! | cargo-contract |
| Fuel | Sway | Forc |
| NEAR | Rust | cargo-near |
| Algorand | TEAL, Puya | AlgoKit |
| Cardano | Aiken, Plutus | Aiken, Plutus |
| ZK | Circom, Noir, Halo2 | circom, snarkjs, nargo, Halo2 |
| Bitcoin | Script | Bitcoin Core |

Vulnerability coverage spans reentrancy, oracle manipulation, precision loss, flash
loans, signature and permit flows, upgradeability, ERC-4626 inflation, token
integration quirks (fee-on-transfer, rebasing), griefing and DoS, MEV and sandwich
attacks, governance, cross-contract consistency, chainlink staleness, slippage and
deadline handling, two-step ownership, bridge messaging, ERC-4337 account
abstraction, and the language-specific bug classes of each ecosystem above.

---

## Architecture

```mermaid
flowchart LR
    subgraph Host["Your machine"]
        CLI["strix CLI"]
        Viewer["Local viewer\n127.0.0.1"]
    end

    subgraph Engine["Agent engine"]
        Root["Root coordinator"]
        Detect["Ecosystem detection"]
        Recon["Reconnaissance\nx-ray"]
        Inv["Invariant enumeration"]
        Lens["Attack lenses\n12 specialists"]
        PoC["PoC engineer"]
        Triage["Triage\ndedupe, verify, rate"]
    end

    subgraph Sandbox["Docker sandbox"]
        Target["Target code"]
        Toolchain["Foundry · Anchor · Move · Circom\nSlither · Echidna · Halmos · …"]
    end

    subgraph Reports["Report writers"]
        MD["audit_report.md"]
        JSON["vulnerabilities.json"]
        SARIF["findings.sarif"]
        PDF["report.pdf"]
    end

    CLI --> Root
    Root --> Detect
    Root --> Recon
    Root --> Inv
    Root --> Lens
    Root --> PoC
    Detect --> Sandbox
    Recon --> Sandbox
    Inv --> Sandbox
    Lens --> Sandbox
    PoC --> Sandbox
    Sandbox --> Target
    Sandbox --> Toolchain
    PoC --> Triage
    Lens --> Triage
    Triage --> Reports
    Reports --> Viewer
```

The engine never runs untrusted code on the host: analysis and proof-of-concept
execution happen inside a container, and the host only receives files.

---

## The audit pipeline

```mermaid
flowchart TD
    P["prep\nresolve scope, toolchain, targets"] --> X["xray\nmap code, roles, value paths"]
    X --> I["invariants\nstate what must hold"]
    I --> A["audit\nlenses over the core subsystems"]
    A --> E["exec_poc\ncompile, run, fix, rerun"]
    E --> T["triage\ndedupe, verify reachability, rate severity"]
    T --> R["report\nMarkdown · JSON · SARIF · PDF"]
    E -. "no proof" .-> L["lead\nfiled as a lead, not a finding"]
    L --> T
```

The proof-of-concept loop is the part that matters:

```mermaid
sequenceDiagram
    participant Ag as Audit agent
    participant Ex as exec_poc
    participant Sc as Sandbox
    Ag->>Ex: write exploit, call exec_poc
    Ex->>Sc: compile (forge build / cargo test / snforge …)
    Sc-->>Ex: compiler output
    Ex->>Sc: run the exploit
    Sc-->>Ex: test output, exit status
    Ex-->>Ag: passed / failed with the real output
    Ag->>Ag: fix the exploit and run it again
```

A pass needs an explicit success marker in the harness output; a failure marker
always wins. Nothing is reported as confirmed without the harness saying so.

---

## Installation

**Requirements:** Docker (running), Python 3.12 or newer, and an API key for one
supported LLM provider.

```bash
git clone https://github.com/hashward-io/strix-web3.git
cd strix-web3
uv sync
uv run strix --version
```

Released versions ship a signed binary for Linux, macOS and Windows, and publish
to PyPI:

```bash
pip install strix-web3
pipx install strix-web3
uv tool install strix-web3
```

Without Python, download the binary from
[the latest release](https://github.com/hashward-io/strix-web3/releases/latest).

The sandbox image is pulled from GitHub Container Registry:

```bash
docker pull ghcr.io/hashward-io/strix-sandbox:latest
```

---

## First audit

```bash
strix init                       # scaffold .strix.yml, .env and instructions
export STRIX_LLM="claude-opus-4-5"
export LLM_API_KEY="your-api-key"
export ETH_RPC_URL="https://your-archive-rpc"   # optional, for EVM fork PoCs

strix --target ./my-protocol
```

The ecosystem is detected automatically. Results are written to
`strix_runs/<run-name>/`.

To work on a deployed contract instead of a repository, point `--target` at the
address and add `--chain` when it is not the default:

```bash
strix --target 0xabc… --chain ethereum
```

---

## Run modes

| Mode | Command | Notes |
|---|---|---|
| Interactive | `strix --target ./repo` | Full TUI: phases, agent graph, transcripts, approvals. |
| Headless | `strix -n --target ./repo` | No UI. Exit `0` no findings, `2` findings filed, `1` fatal error. |
| Scan depth | `--scan-mode quick\|standard\|deep` | `quick` is a fast pass, `deep` runs the full lens set with more budget. |
| Scope | `--scope-mode full\|diff` plus `--diff-base <ref>` | Audit only what changed against a base ref. |
| Budget | `--max-budget 20`, `--max-budget-usd 5` | Hard caps on spend per run. |
| Resume | `strix --resume` | Continue the last interrupted session. |

---

## Output

```text
strix_runs/<run-name>/
├── audit_report.md      assembled report: scope, ranked findings, coverage
├── vulnerabilities/
│   └── <id>.md          one file per finding: root cause, proof, fix
├── vulnerabilities.json machine-readable findings
├── findings.sarif       SARIF 2.1.0, with relatedLocations
└── run.json             status, targets, coverage, llm_usage.cost
```

The local viewer (`strix view`) reads the same directory: findings, the agent
graph and the run history. It binds to `127.0.0.1`, prints a tokenized link and
sends nothing anywhere.

---

## Continuous integration

```yaml
name: strix-audit
on:
  pull_request:
    paths: ["**/*.sol", "**/*.rs", "**/*.move", "foundry.toml", "Anchor.toml"]

permissions:
  contents: read
  security-events: write

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Audit the diff
        env:
          STRIX_LLM: ${{ vars.STRIX_LLM }}
          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
        run: |
          docker pull ghcr.io/hashward-io/strix-sandbox:latest
          strix -n --target . --scope-mode diff --diff-base ${{ github.event.pull_request.base.sha }} \
            --max-budget 10 --fail-on high
      - name: Upload findings
        if: always()
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: strix_runs/*/findings.sarif
```

`strix` also runs as an MCP server, so editors and coding agents can drive it
directly. See `docs/integrations/`.

---

## Editor and agent integrations

Four agent skills describe complete workflows and can be installed with the
`skills` CLI:

```bash
npx skills add hashward-io/strix-web3
```

| Skill | Use it for |
|---|---|
| `auditing-smart-contracts-with-strix` | A full audit of a repository, address or deployment. |
| `find-solidity-vulnerabilities-with-strix` | White-box review of a Solidity or EVM codebase. |
| `fix-solidity-vulnerabilities-with-strix` | Remediate findings and re-run Strix to prove the fix. |
| `ci-smart-contract-scanning-with-strix` | Add a diff-scoped audit gate to a pull request pipeline. |

---

## Bug bounty pipeline

`strix daemon` chains public target discovery, triage and scanning:

```mermaid
flowchart LR
    A["BBRadar\nnew program targets"] --> B["JEV triage\nworth scanning? smart contract?"]
    B --> C["strix -n\nscan"]
    C --> D["JEV triage\nreal vulnerability? material impact?"]
    D --> E["submission draft\n./submissions/<platform>/<handle>/"]
```

```bash
export BBRADAR_API_KEY="your-bbradar-pro-key"
export TYPESAFE_API_KEY="your-jev-key"   # optional, enables model triage
strix daemon --once --dry-run             # discover only
strix daemon --level elite --min-score 75
```

Drafts are written for a human to review and file. Strix does not submit
anything on your behalf.

---

## Configuration

Settings come from the environment, an optional `.env` file, or
`~/.strix/config.yaml`. The full list is in `.env.example`.

| Variable | Purpose |
|---|---|
| `STRIX_LLM` | Model identifier, passed to the configured provider. |
| `LLM_API_KEY` | API key for the provider. |
| `LLM_API_BASE` | Custom base URL for an OpenAI-compatible endpoint. |
| `STRIX_IMAGE` | Sandbox image. Default `ghcr.io/hashward-io/strix-sandbox:latest`. |
| `STRIX_BUDGET_USD` | Spend ceiling for a run. |
| `STRIX_TELEMETRY` | Accepted for compatibility. This fork sends no telemetry. |
| `STRIX_NO_UPDATE_CHECK` | Disable the update check. |

---

## Security model

- **Sandbox.** Target code and every proof of concept run inside a container.
  Nothing from the target executes on the host.
- **No telemetry.** The telemetry package is a no-op shim. No usage data, no
  identifiers, no network calls from the analysis path.
- **Local by default.** The viewer binds to `127.0.0.1` and serves a tokenized
  URL.
- **Scoped access.** The container gets the toolchain it needs, not a shell on
  the host. Capability and resource flags are documented in
  `docs/tools/sandbox.mdx`.
- **Vulnerabilities in Strix Web3** are handled privately. See `SECURITY.md`.

---

## Development

```bash
make dev-install     # install the toolchain
make check-all       # ruff, mypy, bandit
uv run pytest        # test suite
make pre-commit      # hooks
```

- `AGENTS.md` describes the layout for coding agents.
- `CONTRIBUTING.md` explains the release process and the upstream sync.
- `CHANGELOG.md` records every change.
- `UPSTREAM.md` records the merge base with `usestrix/strix`.

---

## Credits and lineage

The agent engine, the tool implementations and the original knowledge pack come
from [usestrix/strix](https://github.com/usestrix/strix), Apache-2.0. The Web3
re-scoping, the ecosystem knowledge pack, the proof-of-concept loop and the
multi-chain sandbox are the work of the Hashward team.

The audit methodology follows the public work of [Pashov Audit
Group](https://github.com/pashov), with audit skills informed by [Trail of
Bits](https://github.com/trailofbits/skills) and [zkSecurity](https://github.com/zksecurity/zk-skills).

---

## License

Apache-2.0. See `LICENSE`.
