🐝 bee 🐝

The bee is the public facing endpoint in the Alvarium honeypot project.

It can:

• Register itself with the Beekeeper using a registration token
• Periodically send statistics as a heartbeat to the Beekeeper
• Connect to Beehives automatically via WireGuard when needed
• Read packets from the specified interface and forward them to the respective Beehive according to the currently active forwarding rules

Requirements

Right now, a Linux system like Ubuntu or Debian is required. We might extend the program to Windows and others in the future.

Because we need to drop the Kernel responses to incoming traffic (to avoid that the Kernel sends RST packets for closed ports), we apply an nftables configuration automatically. Open ports are excluded from the rules to avoid that running services like SSH are blocked.

Note: We currently only support nftables. If your system is using legacy iptables (not iptables-nft), disable automatic nftables generation using the -disableNftables flag. Then, please make sure that you apply proper iptables rules, similar to the nftables rules the program would apply.

Also, make sure that your endpoint configuration in the frontend blocks your open ports!

Usage

1. Make sure the requirements for running the Bee are met on your system.
2. Create a new endpoint in the Beekeeper using the frontend or API directly.
3. Copy the registration token.
4. Note: Both versions (Docker and binary) choose an IP address to bind to by default based on your default routes. Usually, this should be correct. If your host retrieves the external traffic on a separate IP address, adjust it using the -bind <ipAddress> flag.

Docker (recommended)

1. Make sure that your machine has docker with its compose plugin installed.
2. Copy the compose.yaml to your machine.
3. If you need to adjust one of the flags described above, do so with the command field in the compose file (the entrypoint of the Docker image is set to the binary).
4. Set the BEE_REGISTRATION_TOKEN environment variable to the value you copied above.

5. Start the container

   docker compose up -d

Binary

1. Make sure your system has nftables installed, since the program uses the nft tool.

2. Do one of the following to get your binary.

   • Get the latest prebuild binary for your architecture from the releases (note that this is currently specifically build for the latest Debian, so it might not work on your local system).
   • Build the binary locally.

3. Currently, the binary requires elevated privileges because of the network operations. Hence, either run the binary with sudo, or set the necessary capabilities using sudo setcap cap_net_admin,cap_net_raw=eip ./bee. Remember to also set the flags described above if needed.

   sudo ./bee

4. Finally, you should be asked to input the registration token copied above.

5. The Bee should now be up and running. Note that it stores relevant data in a bee.store file. If that file is lost, you need to reregister the Bee.

Build

1. Go must be installed on the machine. Please follow this instruction from the official Go website to install the latest version.

2. Make sure that the bin folder of your Go installation is part of your PATH, e.g. export PATH+=:~/go/bin.

3. Building the binary requires the libpcap header files, which are part of the libpcap-dev package on Debian-based distros. Adjust the command according to your package manager.

   sudo apt install libpcap-dev

4. Clone the project.

   git clone --recurse-submodules git@github.com:Cybersecurity-and-Enterprise-Security/bee.git
   cd bee

5. Install dependencies.

   make generate-deps

6. Build the binary.

   make build