GitHub - tokamak-network/Argus: Real-time Ethereum attack detection and post-hack forensics toolkit

Paste a tx hash. Get a forensic report. No setup required to read one.

Argus turns any Ethereum transaction into a structured forensic report — attack patterns, fund flows, revert reasons — in seconds.

Real reports from mainnet transactions:

One command to run it yourself (archive RPC required):

export ALCHEMY_API_KEY=your_key
argus tx 0xabc...   # outputs a markdown forensic report

No RPC key? Read the sample reports above — no installation needed.

The Hundred-Eyed Guardian for Ethereum

Real-time attack detection, post-hack forensics, and time-travel debugging for EVM transactions.

Built for: Protocol security teams, security researchers, and node operators seeking self-hosted Ethereum monitoring.

Existing security tools (Slither, Mythril, Echidna) analyze contracts before deployment. Argus protects after deployment — detecting attacks as they happen and analyzing them when they've already occurred.

See It in Action

$ cargo run --example sentinel_realtime_demo

 ┌─────────────────────────────────────────────────────┐
 │  Argus Sentinel — Real-Time Attack Detection Demo   │
 └─────────────────────────────────────────────────────┘

 Demo 1  Multi-TX Block Scanning
   TX 0: Simple ETH transfer (21k gas, success)  →  CLEAN
   TX 1: Flash loan via Aave (2.5M gas)          →  CLEAN
   TX 2: 5 ETH transfer, reverted (950k gas)     →  FLAGGED

   ⚠ Alert #2
     Priority: High   Score: 0.75
     Reason:   HighValueWithRevert, UnusualGas, SelfDestruct

 Demo 3  Mempool Pre-Filter (Pending TX Scanning)
   Mempool TXs scanned:  4
   Mempool TXs flagged:  3

 Demo 4  Auto-Pause Circuit Breaker
   Score below threshold — no pause triggered
   (Pre-filter-only alerts may not reach confidence threshold)

No RPC key needed — demos run against local LEVM. Try it (~5 min first build, instant after): git clone https://github.com/tokamak-network/Argus.git && cd Argus && cargo run --example sentinel_realtime_demo

Quick path guide: Security researcher? → Run the demo. DevOps? → Use Docker. Developer? → Build from source.

What Argus Does

Core features (pre-filter, deep analyzer, alerts, forensics, debugger) are implemented and tested (864 tests). Some features (mempool monitoring, auto-pause, ML pipeline) are available in embedded mode only — not yet wired in the RPC-mode CLI. See sentinel.toml.example for details. Argus is currently running on Ethereum mainnet via AWS ECS Fargate — see Deployment Guide and Roadmap.

Sentinel — Real-Time Attack Detection

A 2-stage detection pipeline integrated at the block processing level:

• Pre-filter: Receipt-based heuristics (~10-50μs/tx — see latency bench) eliminate 99% of benign transactions
• Deep analyzer: Full opcode-level replay on suspicious transactions only
• Mempool monitoring: Detect attacks before they're included in a block (embedded mode only; not yet in RPC-mode CLI)
• Auto-pause circuit breaker: Optionally halt processing on critical alerts (embedded mode only; disabled by default due to slashing risk)
• Multi-channel alerts: JSONL, Webhook (Slack/Discord/PagerDuty), WebSocket, Prometheus

Autopsy Lab — Post-Hack Forensics

Replay any mainnet transaction and generate a forensic report:

• Attack pattern classification: Reentrancy, flash loans, price oracle manipulation, access control bypasses
• Fund flow tracing: Track ETH and ERC-20 token movements through the attack
• Markdown report generation: Structured timeline with attack phases, evidence, and suggested fixes

Time-Travel Debugger

GDB-style interactive replay at opcode granularity:

• Forward/backward stepping through execution
• Breakpoints on program counter (PC)
• Full state inspection at any point in execution
• Fast step navigation

Quick Start

Run the Sentinel demo

git clone https://github.com/tokamak-network/Argus.git
cd Argus
cargo run --example sentinel_realtime_demo

This simulates a block containing both benign and malicious transactions, showing Sentinel's detection pipeline in action:

Demo 1  Multi-TX Block Scanning
  TX 0: Simple ETH transfer (21k gas, success)
  TX 1: Flash loan via Aave (2.5M gas, 6 ERC-20 transfers)
  TX 2: 5 ETH transfer, reverted (950k gas)

  Alert #2:
    Priority: High
    Score:    0.75
    Summary:  Pre-filter alert: high-value-revert, unusual-gas, self-destruct
    Reason:   HighValueWithRevert { value_wei: 5000000000000000000 }

Demo 3  Mempool Pre-Filter (Pending TX Scanning)
  Mempool TXs scanned:  4
  Mempool TXs flagged:  3

Demo 4  Auto-Pause Circuit Breaker
  Critical alert → block processing HALTED

Run the Autopsy demo

cargo run --example reentrancy_demo

Deploys a vulnerable contract, executes a reentrancy attack, and runs full forensic analysis:

Phase 1  Deploy & Execute
  Execution: SUCCESS (gas_used=82107)
  Opcode steps recorded: 80

Phase 2  Verify Attack
  Max call depth: 4  (need >= 3 for reentrancy)
  CALL opcodes:   4
  SSTORE opcodes: 4  (attacker counter writes)
  Result: CONFIRMED — reentrancy pattern detected

Phase 3  AttackClassifier
  Reentrancy (target=0x...0043)
    confidence: 90.0%
    evidence: Re-entrant call at step 47
    evidence: State modified at step 69
    evidence: Value transfer during re-entry

Phase 4  FundFlowTracer
  ETH drain confirmed (victim -> attacker)

Phase 6  Summary
  Pre-filter: no receipt-level alert (TX succeeded with normal gas)
  Reentrancy was detected by the opcode-level classifier (Phase 3).

Live Operation

Argus is running on Ethereum mainnet via AWS ECS Fargate (since March 2026).

• 14-day continuous operation completed — see operations report
• Zero downtime, $7/month on Fargate
• No confirmed exploit interceptions yet — building baseline data

Historical Validation

The following are retroactive, hypothetical analyses of past exploits. Argus was not running at the time of these attacks. These demonstrate what the detection pipeline would likely produce on similar patterns. Some signals shown are planned but not yet implemented — see each analysis for details.

Retroactive Analysis: $128M Balancer V2 Exploit

$128M drained via rounding error in Balancer V2's batchSwap (Nov 2025). Argus's pre-filter would likely flag the unusual gas + ERC-20 transfer count; deep analyzer classifies as price manipulation (82% confidence).

Retroactive Analysis: $1.5B Bybit Exploit

$1.5B drained from Bybit's cold wallet via supply chain attack on Safe{Wallet} (Feb 2025). Argus's pre-filter would likely flag unusual gas pattern from the multisig; deep analyzer identifies proxy implementation overwrite. Full detection of proxy upgrade anomalies requires planned signal additions.

How It Compares

* Argus mempool monitoring is available in embedded mode only; not yet wired in RPC-mode CLI.

** Forta Firewall provides pre-execution screening for rollups, not L1 mempool monitoring (details).

Argus is early-stage but running on Ethereum mainnet via AWS ECS Fargate with zero downtime at $7/month. No confirmed exploit interceptions yet. Its primary differentiator is being fully open-source and self-hostable. See competitive analysis for an honest, detailed comparison.

Architecture

Interactive module map with file-level detail: docs/argus-architecture.html

                    ┌─────────────────────────────────────┐
                    │          Ethereum Network            │
                    └──────────────┬──────────────────────┘
                                   │
                    ┌──────────────▼──────────────────────┐
                    │           Mempool Monitor            │
                    │     (pre-execution calldata scan)    │
                    └──────────────┬──────────────────────┘
                                   │
              ┌────────────────────▼────────────────────────┐
              │              Sentinel Pipeline               │
              │                                              │
              │  ┌──────────┐    ┌────────────────────────┐ │
              │  │Pre-filter │───▶│    Deep Analyzer        │ │
              │  │ ~10-50μs  │    │ (opcode-level replay)  │ │
              │  │  per tx   │    │                        │ │
              │  └──────────┘    └───────────┬────────────┘ │
              └──────────────────────────────┼──────────────┘
                                             │
                    ┌────────────────────────▼─────────┐
                    │         Alert Dispatcher          │
                    │  JSONL / Webhook / WS / Prometheus │
                    └────────────────────────┬─────────┘
                                             │
                    ┌────────────────────────▼─────────┐
                    │      Auto-Pause Circuit Breaker   │
                    │   (halt on Critical severity)     │
                    └──────────────────────────────────┘

Features

Building

# Default (Sentinel + Autopsy)
cargo build

# With CLI debugger
cargo build --features cli

# All features
cargo build --all-features

Requirements: Rust 1.85+ (edition 2024)

Docker

# Build and run locally
docker build -t argus-demo .

# Run Sentinel on mainnet
docker run -d \
  -e ARGUS_RPC_URL="https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY" \
  -p 9090:9090 \
  argus-demo

# Or run in prefilter-only mode (foreground — no archive RPC needed, logs shown directly)
docker run -e ARGUS_RPC_URL="https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY" argus-demo

Configuration

Copy the example config and adjust for your setup:

cp sentinel.toml.example sentinel.toml
# The argus binary requires the `cli` feature flag
cargo build --release --features cli
cargo run --release --features cli -- sentinel \
  --rpc https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY --config sentinel.toml

See sentinel.toml.example for all available options with inline documentation.

For production deployment on AWS ECS Fargate, see Deployment Guide.

Powered By

Argus uses ethrex LEVM as its EVM execution engine — a minimal, fast Ethereum Virtual Machine implementation in Rust. Argus depends on Tokamak Network's fork which includes the tokamak-debugger feature.

Contributors

Currently maintained by Jason Hwang with AI-assisted development. Looking for contributors — see CONTRIBUTING.md to get started!

License

Dual-licensed under MIT or Apache 2.0.

Built by Tokamak Network.