shubhamrao6/chaos-bridge repository overview

⁠chaos-bridge

chaos-bridge is the local agent for ChaosAI⁠ — an autonomous AI-driven penetration testing platform. It extends ChaosAI's scan coverage into private networks, internal subnets, and VPN environments that are not reachable from the internet.

⁠How It Works

ChaosAI runs its discovery agents in AWS ECS. For internet-facing targets, those agents scan directly. For internal targets, chaos-bridge acts as the execution surface inside your private environment:

ChaosAI Cloud (AWS ECS)
        │
        │  commands over WebSocket (outbound TLS port 443)
        │
chaos-bridge container (your machine / VPC)
        │
        │  runs nmap, gobuster, etc. locally
        │
Internal targets (192.168.x.x, 10.x.x.x, VMs, routers, local apps)

The container establishes an outbound-only connection to ChaosAI. No inbound ports need to be opened. The container receives scan commands, executes them locally, and streams output back in real time.

⁠Quick Start

Step 1 — Get your token from ChaosAI

In ChaosAI, go to Settings → Bridges → Add Bridge and copy your ENTROPY_TOKEN.

Step 2 — Run the container

docker run -d \
  --name chaos-bridge \
  --restart unless-stopped \
  -e ENTROPY_TOKEN=<your_token> \
  -e ENTROPY_WSS_URL=<your_wss_url> \
  -e BRIDGE_LABEL=my-network \
  shubhamrao6/chaos-bridge:latest

Step 3 — Check it connected

docker logs chaos-bridge

You should see:

[BRIDGE] chaos-bridge v1.0.0 starting...
[BRIDGE] Registered as bridge_id=brg_xxx  label="my-network"
[BRIDGE] Ready — waiting for scan commands...

The bridge will now appear as online in ChaosAI. Create an operation, select your bridge as the scan environment, and target anything on your internal network.

⁠Environment Variables

⁠Supported Platforms

The container runs on any platform with Docker:

Same docker run command on all platforms. No OS-specific setup.

⁠Installed Security Tools

The container includes the full Kali Linux discovery tool set:

All tools run natively on your network — results reflect your actual internal environment.

⁠Security

• Outbound-only connection — the container initiates a WebSocket connection to ChaosAI. No inbound ports are required.
• Token authentication — the ENTROPY_TOKEN is validated server-side and scoped to your account.
• Command whitelist — only approved security tools can be executed. Destructive commands (rm -rf, shutdown, iptables, etc.) are blocked at the container level.
• Stateless — no credentials or scan data are persisted to disk. Stopping the container severs the connection immediately.
• Session-coupled — the bridge stays active as long as your ChaosAI session is active.

⁠Stopping and Removing

# Stop
docker stop chaos-bridge

# Remove
docker rm chaos-bridge

Once stopped, the bridge appears as offline in ChaosAI within 90 seconds.

⁠Versions

⁠Links

• ChaosAI⁠ — the platform this container integrates with
• Documentation⁠ — full setup guide
• Support⁠ — get help

chaos-bridge is part of the ChaosAI autonomous penetration testing platform.