Clawdbot Gateway Honeypot – Project Overview and How It Works

Project Overview

The Clawdbot Gateway Honeypot is a production‑ready, Docker‑based service that imitates the real Clawdbot Gateway API.
By presenting a believable endpoint, it lures automated bots and manual attackers, captures every interaction, and stores the data in structured JSONL logs for later threat‑intel analysis.

Why does it matter?
* Organizations that run Clawdbot for automation can see how adversaries probe the same endpoints without exposing their live systems.
* Researchers obtain real‑world reconnaissance patterns (WebSocket calls, malformed payloads, timing attacks) that would otherwise be invisible.
* All of this is achieved with a low‑interaction honeypot – it mimics the service enough to be attractive but never grants access to a real backend.

Key Features

Accurate protocol emulation – WebSocket RPC, HTTP static assets, and mDNS announcements follow the real gateway’s specifications.
Comprehensive JSONL logging – every HTTP request, WebSocket message, and connection event is appended to log files that survive container restarts.
Configurable fake data – session lists, node inventories, and channel states can be tweaked in source files to match any scenario.
Docker‑Compose deployment – one‑command startup, isolated environment, and easy version upgrades.
Method‑coverage test suite – a built‑in scanner validates that all 32 gateway methods respond as expected, giving confidence that the honeypot behaves like the production service.
Real‑world realism tweaks – random response delays (50‑200 ms) and a tiny error injection rate (≈0.5 %) make traffic look less “scripted”.

Architecture Overview

TEXT

[Attacker] ──► [Nginx (optional reverse‑proxy)] ──► [gateway‑mock (Node.js)]
                                                       │
                                                       ▼
                                                [JSONL log files]

The attacker talks to the honeypot over TCP (port 18789) or mDNS‑discovered service.
gateway-mock handles the WebSocket RPC protocol, serves a tiny static UI, and writes logs to a Docker volume mounted at /var/log/honeypot.
An auxiliary mdns-announcer container advertises the service on the local network.

How It Works

1️⃣ WebSocket RPC Handlers

The core of the honeypot lives in gateway-mock/src/websocket.ts.
Each RPC method is mapped to a simple JavaScript function that returns a JSON‑RPC‑compatible response.

// gateway-mock/src/websocket.ts (excerpt)
type RpcHandler = (params: unknown, client: ClientState) => RpcResponse;

const methodHandlers: Record<string, RpcHandler> = {
  health: () => ({
    ok: true,
    payload: { status: 'ok', version: '1.0.0' },
  }),

  connect: () => ({
    ok: true,
    payload: { [REDACTED] },
  }),

  // …additional method handlers added during Phase 4…
};

When a message arrives, the server looks up the method name, invokes the handler, and sends the result back to the client.

2️⃣ Logging Connection Events

Every WebSocket lifecycle event is recorded in connections.jsonl.
The snippet below shows how a disconnect is appended to the log file.

// gateway-mock/src/websocket.ts (excerpt)
ws.on('close', () => {
  const logEntry = {
    timestamp: new Date().toISOString(),
    ip: ws._socket?.remoteAddress ?? 'unknown',
    event: 'disconnected',
  };
  fs.appendFileSync(
    '/var/log/honeypot/connections.jsonl',
    JSON.stringify(logEntry) + '\n',
  );
});

Similar open and message listeners write request and response data, giving a complete picture of each client session.

3️⃣ Serving Static Assets

The HTTP server now serves files from the public/ directory (instead of dist/).
This change is reflected in gateway-mock/src/http.ts.

// gateway-mock/src/http.ts (excerpt)
import * as path from 'path';
import { logHttpRequest } from './logger.js';

const STATIC_DIR = path.resolve('./public/');   // ← updated directory

function getContentType(filePath: string): string {
  const ext = path.extname(filePath).toLowerCase();
  // …
}

The public/ folder contains a minimal UI that can be accessed with curl http://<host>:18789/ for quick health checks.

4️⃣ Realism Enhancements (Phase 4)

During the final development phase the following runtime tweaks were added:

Feature	Implementation
Response delay	`await new Promise(r => setTimeout(r, randomMs(50,200)))` in each handler
Random error injection	0.5 % chance to return `{ ok: false, error: 503, message: 'Service temporarily unavailable' }`
Fixed `sessions.reset` handler	Added missing case in the method‑switch statement (see commit `f48218c`)

These changes make traffic patterns resemble a live production gateway, helping the honeypot blend in with legitimate services.

Getting Started

Clone the repository
BASH
```
git clone [REDACTED]
cd clawdbot-honeypot/gateway-mock
```
Build and start the containers
BASH
```
docker compose up -d --build
```
Verify the service
BASH
```
docker ps --format 'table {{.Names}}\t{{.State}}\t{{.Status}}'
curl http://localhost:18789/health   # should return {"status":"ok"}
```
Run the method‑coverage scanner (optional but recommended)
BASH
```
cd ../clawdbot-scanner
npm run build
node dist/index.js --host 127.0.0.1 --port 18789 --probe-all --output scan.json
```

All logs are written to the Docker volume mounted at /var/log/honeypot inside the container and are persisted across restarts.

Recent Developments

The project has reached Phase 4 (completed 2026‑01‑27).
Key milestones include:

Timing variations and random error injection to better mimic production latency and occasional failures.
Logrotate compatibility – the copytruncate option prevents Docker‑mounted log files from being truncated mid‑write (commit 0061bc5).
Persistent log storage – Docker volumes and a corrected logrotate configuration guarantee that logs survive container restarts (commits 9dde48c & 61b2a35).

These updates are documented in the newly added CHANGELOG.md and COMPLETION_SUMMARY.md files.

Conclusion

The Clawdbot Gateway Honeypot offers a lightweight yet highly realistic environment for capturing attacker behavior against Clawdbot services. By providing accurate protocol emulation, thorough JSONL logging, and easy Docker deployment, it enables security teams to gather actionable intelligence without exposing production assets.

Deploy the honeypot, run the built‑in scanner, and start turning noisy reconnaissance traffic into valuable threat‑intel data. The project is open‑source and welcomes contributions that further improve realism, logging, or integration with analysis pipelines.