214 lines
9.2 KiB
Markdown
214 lines
9.2 KiB
Markdown
# Attackathon
|
|
|
|
![image info](hackerman.jpg)
|
|
|
|
## Task
|
|
|
|
In this attackathon, your task will be to write a program that performs
|
|
a [channel jamming attack](https://bitcoinops.org/en/topics/channel-jamming-attacks/)
|
|
against a test lightning network. Your goal is to **completely jam a
|
|
routing node for an hour.**
|
|
|
|
Your program should:
|
|
- Accept the public key of the node being attacked as a parameter.
|
|
- Write an attack against the [hybrid approach to jamming mitigations](https://research.chaincode.com/2022/11/15/unjamming-lightning/)
|
|
which is deployed on the network.
|
|
- Open any channels required to perform the attack, and close them
|
|
when the attack has competed.
|
|
|
|
The final deliverable for the attackathon is a [run script](./setup/run.sh)
|
|
that downloads, installs and runs your attack in a kubernetes cluster.
|
|
|
|
## Jamming Definition
|
|
|
|
We're aiming to jam a routing node, which we define as:
|
|
```
|
|
The target node is unable to facillitate forwading of HTLCs on behalf
|
|
of of nodes in the network.
|
|
```
|
|
|
|
Conventionally, this is achieved when:
|
|
```
|
|
All of the target node's local(/outbound) HTLC slots are occupied.
|
|
OR
|
|
All of the target node's local(/outbound) liquidity is occupied.
|
|
```
|
|
|
|
However, given that we are operating within the context of a specific
|
|
mitigation, we need to consider the possibility that the attack may
|
|
try to use the mitigation _itself_ to disrupt quality of service.
|
|
|
|
In general, our reputation and resource bucketing mitigation may be
|
|
abused by an attacker to jam a channel if:
|
|
```
|
|
All of its general bucket's local(/outbound) liquidity OR slots are occupied.
|
|
AND
|
|
Peers looking to use the channel have low reputation.
|
|
```
|
|
|
|
When the attacker manages to successfully sabotage the reputation and
|
|
fill up **general slots**, the channel is effectively jammed because
|
|
peers looking to use the channel do not have access to the
|
|
**projected slots** that are reserved for high reputation peers. This
|
|
may be abused in various ways, and we encourage you to explore them!
|
|
|
|
### Development Environment
|
|
|
|
The attack you develop will be tested against a [warnet](https://warnet.dev/)
|
|
running a network of [LND](https://github.com/carlaKC/lnd/tree/attackathon)
|
|
nodes that have the jamming attack mitigation implemented* (via an
|
|
external tool called circuitbreaker).
|
|
|
|
To assist with local development, we've provided a test network that
|
|
can be used to run your attacks against. Prerequisites to set up this
|
|
network are:
|
|
* Python3
|
|
* Docker
|
|
* Kubernetes (see [docker desktop instructions if relevant](https://docs.docker.com/desktop/kubernetes/))
|
|
* [Just](https://github.com/casey/just)
|
|
|
|
Clone the attackathon repo:
|
|
`git clone https://github.com/carlaKC/attackathon`
|
|
|
|
*Do not change directory.*
|
|
|
|
The scripts will pull the relevant repositories to your current working
|
|
directory and set up your network. They expect the `attackathon`
|
|
repository to be in the current directory.
|
|
* Warnet server: [./attackathon/scripts/start_warnet.sh](./scripts/start_warnet.sh)
|
|
sets up the warnet server, which is responsible for orchestration of
|
|
the network.
|
|
* You'll only need to do this once, but leave it running!
|
|
* When you're done with it, bring it down with
|
|
[./attackathon/scripts/stop_warnet.sh](./scripts/stop_warnet.sh)
|
|
* Start network: [./attackathon/scripts/start_network.sh ln_10](/.scripts/start_network.sh)
|
|
brings up your lightning network, opens channels, simulates
|
|
random payments in the network and mines blocks every 5 minutes.
|
|
* If you want to kill your test network and start fresh, you can
|
|
use [./attackathon/scripts/stop_network.sh ln_10](./scripts/stop_network.sh)
|
|
* Start attacking pods: [./attackathon/scripts/start_attacker.sh ln_10](./scripts/start_attacker.sh)
|
|
brings up three lightning nodes that you will use for your attack,
|
|
a bitcoin node and an empty `flagship` container to run your attack
|
|
from.
|
|
* You can use [./attackathon/scripts/stop_attacker.sh](./scripts/stop_attacker.sh)
|
|
to tear this down if you'd like to start over at any point.
|
|
|
|
Once you have brought your cluster up, you'll be able to execute your
|
|
program from *inside* of the cluster's `flagship` pod:
|
|
* `kubectl exec -it flagship -n warnet-armada -- bash`
|
|
* Update `run.sh` to:
|
|
* Install your program.
|
|
* Run your program using the credentials provided inline.
|
|
|
|
⚠️ Remember that we're using a [fork](https://github.com/carlaKC/lnd/tree/attackathon)
|
|
of LND so you'll need to account for that if you're using common RPC
|
|
client libraires to have access to `endorsement` fields (golang client
|
|
is available [here](https://github.com/carlaKC/lndclient/tree/attackathon)).
|
|
|
|
The following utilities are available for your convenience:
|
|
* `source ./lncli.sh` provides aliases for your LND nodes (`lncli0`,
|
|
`lncli1`, `lncli2`)
|
|
* `./fund.sh` funds each of your LND nodes.
|
|
* `./connect_nodes.sh` connects the attacking nodes to the network
|
|
so that they can sync gossip.
|
|
* `bitcoin-cli` provides access to the bitcoin node that all three
|
|
LND nodes are connected to.
|
|
|
|
## Network Information
|
|
|
|
Some relevant characteristics of the network:
|
|
- The reputation system has been primed with historical forwarding
|
|
data, so nodes in the network have already had a chance to build
|
|
up reputation before the attack begins.
|
|
- Each node in the network:
|
|
- Allows 483 HTLCs in flight per channel.
|
|
- Allows 45% of its channel's capacity in flight.
|
|
- Allocates 50% of these resources to "general" traffic, and 50% to
|
|
protected traffic.
|
|
- The graph was obtained by reducing the mainnet graph using a
|
|
random walk around our target node, and real-world routing policies
|
|
are used.
|
|
- When you run the attack, the non-malicious nodes in the network will
|
|
be executing [randomly generated payments](https://simln.dev) to
|
|
mimic an active network.
|
|
|
|
Some APIS to note:
|
|
- [AddHoldInvoice](https://lightning.engineering/api-docs/api/lnd/invoices/add-hold-invoice)
|
|
creates an invoice that can be manually [settled](https://lightning.engineering/api-docs/api/lnd/invoices/settle-invoice)
|
|
or [canceled](https://lightning.engineering/api-docs/api/lnd/invoices/cancel-invoice)
|
|
- Endorsement signals can be set on the [SendToRoute](https://lightning.engineering/api-docs/api/lnd/router/send-to-route-v2)
|
|
or [SendPayment](https://lightning.engineering/api-docs/api/lnd/router/send-payment-v2)
|
|
APIs.
|
|
|
|
\* Note that endorsement signaling and reputation tracking are fully
|
|
deployed on the test network, but unconditional fees are not. You should
|
|
assume that they will be 1% of your success-case fees, and we will
|
|
account for them during attack analysis.
|
|
|
|
## Assessment
|
|
|
|
Attacks will be assessed using the following measures:
|
|
- Did the attack achieve a jamming attack as described above?
|
|
- What was the total cost of the attack, considering:
|
|
- On-chain fees: for channel opens and closes, sending funds between
|
|
nodes on-chain will node be included for simplicity's sake.
|
|
- Off-chain fees: the sum of fees paid for successful off-chain
|
|
payments plus 1% of the success-case fees for *all* payments that
|
|
are sent to represent unconditional fees.
|
|
- Opportunity cost of capital: for each channel that is opened, 5%
|
|
p.a. charged on the total capital deployed in the channels,
|
|
assuming 10 minute blocks.
|
|
- When compared to the operation of the network _without_ a jamming
|
|
attack, how many honest htlcs were dropped as a result of the attack?
|
|
|
|
### HackNicePlz
|
|
|
|
We're trying to break channel jamming mitigations, not our setup itself
|
|
so please be a good sport and let us know if there's anything buggy!
|
|
Real attackers won't be able to take advantage of our test setup, so
|
|
neither should we.
|
|
|
|
|
|
## Network Creation
|
|
|
|
Participants do not need to read the following section, it contains
|
|
instructions on how to setup a warnet network to run the attackathon
|
|
on.
|
|
|
|
<details>
|
|
<summary>Setup Instructions</summary>
|
|
|
|
To get started, you will need to clone the following repos *in the same
|
|
working directory*:
|
|
1. [This repo](https://github.com/carlaKC/attackathon)
|
|
2. [Warnet](https://github.com/bitcoin-dev-project/warnet)
|
|
3. [SimLN](https://github.com/bitcoin-dev-project/sim-ln)
|
|
3. [Circuitbreaker](https://github.com/lightningequipment/circuitbreaker)
|
|
|
|
You will need to provide:
|
|
1. A `json` file with the same format as LND's `describegraph` output
|
|
which describes the graph that you'd like to simulate.
|
|
2. The duration of time, expressed in seconds, that you'd like the
|
|
setup script to generate fake historical forwards for all the nodes
|
|
in the network for.
|
|
|
|
The setup script provided will generate all required files and docker
|
|
images for you:
|
|
`./attackathon/setup/create_network.sh {path to json file} {duration in seconds}`
|
|
|
|
Note that you *must* run this from your directory containing `warnet`,
|
|
`simln` and `circuitbreaker` because it moves between directories to
|
|
achieve various tasks! The name that you give the `json` file is
|
|
considered to be your `network_name`.
|
|
|
|
Once the script has completed, check in any files that it generated and
|
|
provide your students with the following:
|
|
1. The `network_name` for your attackathon.
|
|
2. The attackathon repo (/branch) with all files checked in.
|
|
|
|
The script currently hardcodes the docker hub account for images to
|
|
`carlakirkcohen` and tries to push to it, so you'll need to search and
|
|
replace if you want to test the full flow.
|
|
|
|
</details>
|