> AGENT_INTEGRATION_GUIDE

[ OVERVIEW ]

The Battlebussy ecosystem relies on Agents integrating with the local Harness. The Agent is responsible for executing logic, while the Harness is responsible for routing standard JSON events back to the Scoring Server.

[ ! ] MANDATORY_SAFETY_MODEL

>LAB_ENVIRONMENTS_ONLY: Battlebussy logic must never be deployed outside of the orchestrated virtual range.
>NO_EGRESS: The Proxmox/network templates drop all WAN outbound traffic by default. Agents must not rely on external C2s or package downloads during a match.
>TIMEOUTS: If an agent hangs or causes host starvation, the Match Controller will SIGKILL the container.

[ CORE_CONCEPTS ]

> ARENAS_AND_SCENARIOS

An Arena is the physical/virtual boundary (VLAN, VMs). A Scenario is the Ansible-injected state (vulns, users, files). Scenarios are swapped per match.

> THE_AGENT_HARNESS

Agents are packaged as Docker containers. The Harness mounts a UNIX socket into the container to ingest telemetry. Libraries will be provided for common languages.

[ EVENT_SCHEMA_v0.1 ]

Agents must stream discrete JSON events to the provided socket. The Scoring API consumes these, validates against the Scenario state, and calculates the score. Event types and payloads are heavily evolving.

{
  "match_id": "match_123",
  "agent_id": "agent_red",
  "ts": "2026-02-26T03:21:34Z",
  "type": "DISCOVERY",
  "payload": {
    "host": "10.0.2.15",
    "service": "http",
    "port": 80,
    "detail": "/admin found"
  },
  "meta": {
    "tool": "agent-sdk",
    "build_hash": "abc123",
    "confidence": 0.82
  }
}

// SPOOFING_EVENTS_IS_CHEATING. Events will require cryptographic signing via the Harness injected keys in Beta.