Skip to content
ucsb-seclabPublic

About

Houston: Real-Time Anomaly Detection of Attacks against Ethereum DeFi Protocols

Resources

Stars

6 stars

Watchers

0 watching

Forks

Latest commit

 

History

4 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

HOUSTON: Real-Time Anomaly Detection of Attacks against Ethereum DeFi Protocols

299f4f15-9c1a-468e-9018-b8c2717f4cd6_1904x640

Artwork By Peter Kacherginsky at blockthreat.com

This repository contains the code for the core implementation of HOUSTON.

Note: This repository contains the research prototype used for the experiments in the paper. Some auxiliary components and internal tooling used during development are not included.

💻 Install

./install.sh
Mods to solc compiler

To properly emit storage layout reports for contracts, we had to perform some modifications to old version of the Solidity compiler. More specifically, we fixed the following solc versions:

  • solc-v0.5.8
  • solc-v0.5.10
  • solc-v0.5.11
  • solc-v0.5.12

You can find these binaries in the solc-binaries folder.

be02011efd6c6afd27cda02871bd70b3  solc-v0.5.10
95a6e066632d86a3991ba647908a87aa  solc-v0.5.11
81355fdac6ef2e8beecb272058d77e0d  solc-v0.5.12
4821f4120ba07eb89166fcc31274e282  solc-v0.5.8

Place these binaries in ~/.ethcx/solc/.

🐲 Erigon Node

To properly run, HOUSTON requires access to an Erigon archive node (there are some Erigon specific requests in the code). Additionally, the Erigon node should install our plugin houston.go.

💾 Blockchain Index Database

HOUSTON requires access to a blockchain index database that can provide historical information regarding Ethereum's transactions.

Specifically, the index database should provide 3 methods:

  • get_created_by_deployer(address) --> returns all the contracts created by a certain deployer. Refer to our implementation in the pg.py file.

  • get_all_transactions_by_address_and_block(addr, max_block) --> returns all the transaction (and internal transaction) for which addr was either the sender or the receiver. The max_block set the last block to consider for collection. Refer to our implementation in the pg.py file.

  • get_all_transactions_by_address_and_block_and_start_at(addr, min_block, max_block) --> returns all the transaction (and internal transaction) for which addr was either the sender or the receiver. The min_block set the first block to consider for collection. The max_block set the last block to consider for collection. Refer to our implementation in the pg.py file.

Finally, export the following enviornment variables:

export WEB3_ENDPOINT_URL="ws://yourErigonEndpointURL:8545"
export HOUSTON_WORKDIR="/path/to/houston-release/"

🏃🏻 Run

The first step is collecting all the data regarding the transactions that interacted with the protocol prior to the attack. To do so, an entry in the defi-incidents.csv is required.

This is the format:

Protocol Name | Attacked Contract | Protocol Type | Attack Date | Attack Block | Attack Transaction
Polynetwork,0x838bf9e95cb12dd76a54c9f9d2e3082eaf928270,Bridge,08/10/2021,12996659,0xb1f70464bd95b774c6ce60fc706eb5f9e35cb5f06e6cfe7c17dcda46ffd59581

Then, simply:

python run.py

To reproduce the setup for historical DeFi incidents, run the following:

python -m houston.protocol --proto <proto_name> [--noreload]
python -m houston.splitter --proto <proto_name>

These commands generate intermediate data for the collected transactions under workspace/. The Interaction Model also uses this step to generate the necessary transaction signatures.

Run the Invariant Model

We implemented a minimalistic invariant engine in carrot.py (we think it’s tastier than Daikon).

To extract invariants from past transactions, put the target protocols in input/targets.txt and run:

./run_bunny_run.sh --targets targets.txt --action train --jobs <n_jobs>

Once invariants are extracted, check invariant violations on new transactions in the evaluation period:

./run_bunny_run.sh --targets targets.txt --action test --jobs <n_jobs>

Detection results

To view the results:

python -m houston.checker --target targets.txt --debug

This will start an interactive session where you can inspect:

  • df: a summary of the processed transactions
  • vios: invariant violations
  • inv_alarms: alerts raised by the Invariant Model
  • int_alarms: alerts raised by the Interaction Model

Defi-incidents dataset

In the /dataset folder, we have shared the collection of DeFi incidents used to evaluate our work. The dataset includes information about each attack analyzed by HOUSTON, including a write-up, the reference transaction hash, and the corresponding block number.

In this repo, we include only the Polynetwork example due to the large size of the raw data required.

Use Case: the Polynetwork Heist

d7098ea2-7510-4671-a579-2dbe5f697ff6_1904x640

Artwork By Peter Kacherginsky at blockthreat.com

In the folder example/polynetwork, we place all the data generated by running our pipeline on the Polynetwork protocol.

In example/polynetwork/proto you can find all the data generated when analyzing the protocol (e.g., contracts addresses, transactions, contracts' analyses).

In example/polynetwork/data you can find all the information collected regarding Polynetwork transactions from block 0, up to block 12996659 - the block of the Polynetwork attack transaction.

For historical DeFi incident example Polynetwork, run the following:

python -m houston.protocol --proto polynetwork --noreload
python -m houston.splitter --proto polynetwork
./run_bunny_run.sh --targets targets.txt --action train --jobs 10
./run_bunny_run.sh --targets targets.txt --action test --jobs 10
python -m houston.checker --target targets.txt --debug

Note that the code here assumes HOUSTON is initialized with historical transactions and evaluates on the last 30 days of traffic (instead of cold start with zero history). This behavior can be changed by setting EVAL_DAYS in input/config.py. The LLM-based comparable-pair selection component is also not included in this repository.

For the PolyNetwork example:

  • The Interaction Model raises no alerts during the evaluation period.
  • The Invariant Model flags one single suspicious transaction — the actual attack.

✅ Result: HOUSTON successfully identifies the attack with zero false positives.

About

Houston: Real-Time Anomaly Detection of Attacks against Ethereum DeFi Protocols

Resources

Stars

6 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages