Configuring the Ethiack Beacon - v2 (current)

What's new in v2?

• Outbound-only connectivity: No inbound firewall rules or port forwarding are required, the beacon initiates the tunnel automatically.
• Automatic CIDR detection: The beacon discovers reachable CIDRs from the host network interfaces. A beacon can also analyze multiple CIDRs.
• Automatic internal IP discovery: Once the tunnel is up, Ethiack automatically discovers reachable IPs within the exposed CIDRs after you add them to a test.
• Scalable deployments: Deploy using a single install script, an Ansible playbook, raw Kubernetes YAML, or a Helm chart.

1. Requirements

Host / VM Requirements (Install Script)

Note: If Docker is not installed, you can install it by following the official Docker documentation.

Kubernetes Requirements

Network Requirements

Important: The beacon machine must have network access to the internal CIDRs you intend to expose. If the host sits in a DMZ or restricted VLAN, ensure routing to those subnets is in place before deploying.

2. Deployment Options

As a quick start, navigate to https://portal.ethiack.com/surface/beacons and follow the on-screen instructions. Please note that only one beacon per network is required.

All methods use the same public container image:

europe-docker.pkg.dev/ethiack/public/beacon:latest

Option A: Single VM / Quick Install

Best for a single VM or quick proof of concept. This method detects Docker or runs natively, configures everything in one shot, and sets the beacon up as a system service that auto-restarts on reboot.

1. Retrieve your API Key and API Secret from the Ethiack Portal Settings.
2. Run the install script on the target machine:
   
   Interactive:
   curl -fsSL https://portal.ethiack.com/scripts/beacon/install | bash
   
   Non-interactive (automated / scripted):
   ETHIACK_API_KEY=your_api_key \
ETHIACK_API_SECRET=your_api_secret \
ETHIACK_BEACON_NAME=your_beacon_name \
ETHIACK_PENTEST_SLUG=example-m6 \
ETHIACK_ASSUME_DETECTED_CIDRS=1 \
  curl -fsSL https://portal.ethiack.com/scripts/beacon/install | bash

   Note: You can unset the environment variables after the beacon is running, if you prefer.
3. Verify the beacon is running by analyzing the output of the command

Then go to Portal > Beacons and confirm the beacon status is Active. It should appear within a minute of the service starting.

Option B: Scalable Deployments (Ansible, Helm, Kubernetes YAML)

1. Clone or download the templates from: https://github.com/ethiack/beacon-deployments
2. Provide your credentials and beacon name:
   • ETHIACK_API_KEY
   • ETHIACK_API_SECRET
   • ETHIACK_BEACON_NAME
3. Configure network scoping: set ETHIACK_BEACON_CIDRS (e.g., 10.0.0.0/8) or use ETHIACK_ASSUME_DETECTED_CIDRS=1 for automatic detection. Please note that if neither variable is set, the beacon will fail to start with an error.

After deploying, confirm beacons appear as Active in the portal.

3. Network Scoping (CIDRs)

You can control which internal networks the beacon exposes in two ways:

Example: restrict to a specific subnet:

ETHIACK_BEACON_CIDRS=10.10.0.0/16

Multiple CIDRs can be comma-separated, e.g. 10.10.0.0/16,192.168.1.0/24.

4. Managing Your Beacons (CLI)

Install the Ethiack Beacon CLI on the beacon host:

pip install ethiack-beacon
beacon --help

Or via Docker:

docker exec ethiack-beacon beacon --help

Common Commands

5. Adding Internal Assets

Once your beacon is Active in the portal:

1. Navigate to your pentest scope in https://portal.ethiack.com.
2. Associate the beacon with the scope and link the CIDRs or detected networks you want assessed.
3. The Ethiack Engine will automatically discover reachable IPs within those ranges and begin assessment.

6. Uninstalling a Beacon

On a VM (install script):

# List beacons to retrieve the ID
docker exec ethiack-beacon beacon list
# Remove the beacon
beacon delete <beacon-id>
# Stop the service from the beacon directory
docker compose down

You can also remove the beacon entry from the Portal > Beacons page if it wasn't deleted via the CLI.

7. Troubleshooting

Beacon registers but stays "Offline"

• • The most common cause is a firewall blocking outbound UDP to beacon-rh.ethiack.com. Confirm the UDP port shown in the portal is open outbound from the beacon host.
  • Check the service logs: docker logs ethiack-beacon (Docker)

Beacon fails to start (Kubernetes)

• • Ensure the pod has NET_ADMIN and SYS_MODULE capabilities. Without these, we cannot configure the network interface.

CIDRs not detected correctly

• • Override automatic detection by setting ETHIACK_BEACON_CIDRS explicitly (see Section 3).
  • Auto-detection may pick up unintended interfaces (Docker bridge networks, VPN tunnels). Use manual CIDRs for precise control.

pip install ethiack-beacon fails with "externally managed environment"

• • This is a restriction on newer Ubuntu/Debian systems. Use pipx instead or create a virtual environment:

pipx install ethiack-beacon

Beacon is active but internal IPs are not being discovered

• • Verify the beacon host can actually reach the exposed CIDRs (test with ping or curl from the host and the container).
  • Ensure no host-based firewall (e.g., ufw, iptables) is blocking traffic to internal subnets. If you are reusing a machine from a previous beacon version, it’s recommended to create a new one.

Reach out to our support team via the support portal (support.ethiack.com).