Getting Started

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 runtime security 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.

Create 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!

Your rule is now active! Blocklight will alert you when large ETH transfers are detected.

Next Steps

Learn more about writing rules
Configure alert channels

Welcome

Rules

Deployment

CLI Tools

Features

Production

Step 1: Install Blocklight

Option A: Docker (Production)

Option B: Local CLI (Development)

Option C: Global Install (Daily Use)

Step 2: Write Your First Rule

Step 3: Validate the Rule

Step 4: Test Against Real Transactions

Step 5: Deploy & Activate

Next Steps

​Step 1: Install Blocklight

​Option A: Docker (Production)

​Option B: Local CLI (Development)

​Option C: Global Install (Daily Use)

​Step 2: Write Your First Rule

​Step 3: Validate the Rule

​Step 4: Test Against Real Transactions

​Step 5: Deploy & Activate

​Next Steps

Step 1: Install Blocklight

Option A: Docker (Production)

Option B: Local CLI (Development)

Option C: Global Install (Daily Use)

Step 2: Write Your First Rule

Step 3: Validate the Rule

Step 4: Test Against Real Transactions

Step 5: Deploy & Activate

Next Steps