Get Blocklight up and running and create your first detection rule in minutes.
Step 1: Install Blocklight
Choose the installation method that fits your use case:
| Use Case | Method | Setup Command |
|---|
| Production Server | Docker Compose | docker-compose up -d |
| Rule Development | Local CLI | make build |
| Security Research | Global Install | make install |
Option A: Docker (Production)
For: 24/7 monitoring, production servers, team deployments
Why Docker? Auto-restart, operational metrics, resource isolation, easy updates
git clone https://github.com/blocklightsec/blocklight.git
cd blocklight
cp env.template .env
# Edit .env with your RPC URLs and alert webhooks
# Core engine only (production minimal)
docker-compose up -d
# OR with REST API (for external integrations)
docker-compose --profile api up -d
# OR with Prometheus (operational metrics)
docker-compose --profile observability up -d
# OR full stack (API + Prometheus)
docker-compose --profile api --profile observability up -d
# Verify it's running
docker-compose logs -f blocklight-core
The API is optional. The core detection engine works standalone. Only enable the REST API (--profile api) if you need HTTP endpoints for dashboards or external integrations.
Option B: Local CLI (Development)
For: Rule development, backtesting exploits, testing
git clone https://github.com/blocklightsec/blocklight.git
cd blocklight
make build
# Verify installation
./blocklight version
Option C: Global Install (Daily Use)
For: Using Blocklight like other security tools from the command line
# Clone and install
git clone https://github.com/blocklightsec/blocklight.git
cd blocklight
# System-wide install (requires sudo)
make install
# OR user-only install (no sudo)
make install-user
# Verify installation
blocklight version
Step 2: Write Your First Rule
Best Practice: For new rules, start by creating them in rules/testing/ to test safely, then move to rules/custom/ when ready. Rules in rules/testing/ are never loaded in production.
rules/custom/my_first_rule.yaml (or rules/testing/my_first_rule.yaml for testing):
rules/custom/my_first_rule.yaml
- rule: Large ETH Transfer
desc: Detects transfers over 100 ETH
tags: ["finance", "high-value"]
condition: >
tx.value > 100 ether and
tx.to != null
output: >
Large transfer: %tx.value_eth ETH from %tx.from to %tx.to
priority: WARNING
chain: ["ethereum"]
enabled: true
Step 3: Validate the Rule
# If using global install
blocklight validate --rule rules/custom/my_first_rule.yaml
# If using local CLI
./blocklight validate --rule rules/custom/my_first_rule.yaml
# If using Docker
docker-compose exec core /app/blocklight validate --rule /app/rules/custom/my_first_rule.yaml
Step 4: Test Against Real Transactions
# Test your specific rule against a real transaction
blocklight dry-run \
--tx 0x9e5c7835e4fcd9a289820c4e42c623c4ab80bd50896b4e5b27e3c18f79be6341 \
--rule rules/custom/my_first_rule.yaml \
--network ethereum
# OR test all rules against the transaction
blocklight dry-run \
--tx 0x9e5c7835e4fcd9a289820c4e42c623c4ab80bd50896b4e5b27e3c18f79be6341 \
--network ethereum
# dry-run automatically includes rules from rules/testing/ if it exists
# Output shows which rules matched:
# MATCHED: Large ETH Transfer
# Severity: WARNING
# Output: Large transfer: 111.67 ETH from 0x742d... to 0x123f...
# Execution: 0.245ms
Step 5: Deploy & Activate
# Using Docker (production)
docker-compose up -d
# Rules are loaded automatically - hot reload enabled!
# No restart needed when you add/edit rules
Hot Reload: Blocklight watches your rules directories. When you add or modify .yaml files, rules reload automatically—no restart required!
Next Steps
