Skip to content

DISCOVERY.md

Latest commit

 

History

History
168 lines (122 loc) · 3.61 KB

DISCOVERY.md

File metadata and controls

168 lines (122 loc) · 3.61 KB
Raw

Clawdbot Gateway Discovery System

Overview

The discovery system can find Clawdbot Gateway instances using two methods:

  1. Shodan API - Search internet-facing instances
  2. mDNS - Discover instances on local network

Installation

npm install
npm run build

Configuration

Create a .env file with your Shodan API key:

cp .env.example .env
# Edit .env and add your Shodan API key

Get a free Shodan API key at: https://account.shodan.io/

Usage

Discover from Shodan

# Basic search (default limit: 100)
node dist/cli-discover.js --source shodan

# Custom limit
node dist/cli-discover.js --source shodan --limit 20

# Save to file
node dist/cli-discover.js --source shodan --limit 50 --output targets.json

Discover from mDNS (Local Network)

# Basic search (default timeout: 30s)
node dist/cli-discover.js --source mdns

# Custom timeout
node dist/cli-discover.js --source mdns --timeout 60

# Save to file
node dist/cli-discover.js --source mdns --output local-targets.json

CLI Options

Option Description Default
--source Discovery source: shodan or mdns shodan
--limit Maximum results from Shodan 100
--timeout mDNS discovery timeout (seconds) 30
--output Output file path (JSON) stdout

Output Format

[
  {
    "id": "shodan-192.168.1.100",
    "ip": "192.168.1.100",
    "port": 18789,
    "source": "shodan",
    "location": {
      "country": "United States",
      "city": "New York"
    },
    "discovered": "2024-01-01T00:00:00.000Z",
    "metadata": {
      "version": "1.2.3",
      "hostname": "gateway-1",
      "service": "websocket"
    }
  }
]

Features

Automatic Filtering

  • Honeypot IPs: Automatically filters out 178.62.226.116
  • Deduplication: Removes duplicate IPs
  • Validation: Ensures valid target format

Shodan Queries

The system tries multiple queries in order:

  1. Primary: port:18789 "_clawdbot-gw._tcp"
  2. Secondary: port:18789 "Clawdbot"
  3. Fallback: port:18789 websocket

mDNS Discovery

Searches for services with type _clawdbot-gw._tcp.local and parses:

  • Hostname and port
  • TXT records (version, service info, etc.)

Integration with Protocol Agent

The discovery system outputs JSON that can be consumed by the Protocol Agent for probing:

# Discover targets
node dist/cli-discover.js --source shodan --output targets.json

# Protocol Agent can read targets.json for probing
# (Protocol Agent integration to be implemented)

Testing

Run the test suite:

npm test

Test coverage includes:

  • Target list management
  • Shodan client (banner parsing, filtering)
  • mDNS discovery (output parsing)
  • CLI argument parsing

Architecture

src/discovery/
├── types.ts          # TypeScript interfaces
├── targets.ts        # Target list management
├── shodan.ts         # Shodan API client
└── mdns.ts           # mDNS discovery wrapper

src/cli-discover.ts   # CLI tool

src/__tests__/
└── discovery/        # Test suites

Limitations

  • Shodan API: Free tier has rate limits (1 request/second, 100 results max)
  • mDNS: Only discovers services on local network
  • dns-sd: Requires dns-sd command-line tool (comes with macOS/Avahi on Linux)

Error Handling

The system gracefully handles:

  • Missing Shodan API key
  • Network errors
  • Invalid responses
  • Timeout conditions

Next Steps

  1. Add your Shodan API key to .env
  2. Run discovery to find Clawdbot instances
  3. Save targets to JSON file
  4. Pass targets to Protocol Agent for probing