HBV API v1 Documentation

Overview

HBV API v1 provides core REST endpoints for HoneyBadger Vanguard tools to beacon, submit results, and query data from self-hosted instances.

Note: This documentation describes the API specification. To run a functional backend, see the self-hosting guide.

Base URL

https://your-api.local/api/v1

Features

API key authentication
Rate limiting (100 requests/min)
JSON request/response format
Health monitoring endpoints
Agent registration and beaconing
Results submission and querying

Authentication

All protected endpoints require an API key passed via header:

# Option 1: X-API-Key header
curl -H "X-API-Key: hbv_your_api_key_here" \
  https://your-api.local/api/v1/agents

# Option 2: Authorization Bearer token
curl -H "Authorization: Bearer hbv_your_api_key_here" \
  https://your-api.local/api/v1/agents

Generate API keys using the self-hosted deployment:

docker-compose exec api npm run generate-api-key -- "My Key"

Endpoints

GET /api/v1/status

Public endpoint - Health check and service status

Response Example

{
  "status": "operational",
  "version": "1.0.0",
  "timestamp": "2025-12-19T12:00:00Z",
  "services": {
    "database": "healthy",
    "cache": "healthy"
  }
}

GET /api/v1/modules

Public endpoint - List available HBV modules

Response Example

{
  "modules": [
    {
      "name": "port-scan",
      "description": "Network port scanning and service detection",
      "version": "1.0.0",
      "category": "recon"
    },
    {
      "name": "subdomain-enum",
      "description": "Subdomain enumeration and discovery",
      "version": "1.0.0",
      "category": "recon"
    }
  ],
  "count": 2
}

POST /api/v1/beacon

Protected endpoint - Agent check-in and registration

Request Body

{
  "agent_id": "agent-001",
  "hostname": "recon-box-01",
  "platform": "linux",
  "version": "1.0.0",
  "metadata": {
    "location": "datacenter-1"
  }
}

Response Example

{
  "success": true,
  "agent_id": "agent-001",
  "timestamp": "2025-12-19T12:00:00Z"
}

cURL Example

curl -X POST https://your-api.local/api/v1/beacon \
  -H "X-API-Key: hbv_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent-001",
    "hostname": "recon-box-01",
    "platform": "linux"
  }'

POST /api/v1/results

Protected endpoint - Submit scan/recon results

Request Body

{
  "agent_id": "agent-001",
  "module": "port-scan",
  "target": "example.com",
  "result_type": "open_ports",
  "data": {
    "ports": [80, 443, 22],
    "scan_time": 2.5
  },
  "severity": "low"
}

Response Example

{
  "success": true,
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2025-12-19T12:00:00Z"
}

GET /api/v1/results

Protected endpoint - Query submitted results

Query Parameters

agent_id - Filter by agent ID
module - Filter by module name
severity - Filter by severity (low, medium, high, critical)
limit - Results per page (default: 100)
offset - Pagination offset (default: 0)
since - ISO 8601 timestamp to filter results after

Response Example

{
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "agent_id": "agent-001",
      "module": "port-scan",
      "target": "example.com",
      "data": {"ports": [80, 443]},
      "timestamp": "2025-12-19T12:00:00Z"
    }
  ],
  "count": 1,
  "limit": 100,
  "offset": 0
}

cURL Example

curl -H "X-API-Key: hbv_your_key" \
  "https://your-api.local/api/v1/results?agent_id=agent-001&limit=50"

GET /api/v1/agents

Protected endpoint - List registered agents

Query Parameters

active_only - Filter active agents only (default: true)

Response Example

{
  "agents": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "agent_id": "agent-001",
      "hostname": "recon-box-01",
      "platform": "linux",
      "first_seen": "2025-12-19T10:00:00Z",
      "last_seen": "2025-12-19T12:00:00Z",
      "is_active": true
    }
  ],
  "count": 1
}

Error Codes

Code	Description	Solution
`400`	Bad Request	Check request body format and required fields
`401`	Unauthorized	Provide valid API key in headers
`429`	Too Many Requests	Rate limit exceeded, wait before retrying
`500`	Internal Server Error	Check server logs for details

Code Examples

Python Client

import requests

class HBVClient:
    def __init__(self, api_url, api_key):
        self.api_url = api_url
        self.headers = {'X-API-Key': api_key}

    def beacon(self, agent_id, hostname, platform):
        response = requests.post(
            f'{self.api_url}/api/v1/beacon',
            headers=self.headers,
            json={
                'agent_id': agent_id,
                'hostname': hostname,
                'platform': platform
            }
        )
        return response.json()

    def submit_result(self, agent_id, module, target, data):
        response = requests.post(
            f'{self.api_url}/api/v1/results',
            headers=self.headers,
            json={
                'agent_id': agent_id,
                'module': module,
                'target': target,
                'data': data
            }
        )
        return response.json()

# Usage
client = HBVClient('https://your-api.local', 'hbv_your_key')
client.beacon('agent-001', 'recon-box', 'linux')
client.submit_result('agent-001', 'port-scan', 'example.com', {'ports': [80, 443]})

← Back to API Gateway