references/v3/bof-runtime-api.md
GitHubOC2 V3 BOF Runtime API
Command registration
@command(
name="mytool",
description="...",
support=[CommandSupport(OperatingSystem.WINDOWS, Architecture.INTEL_X64)],
)
async def mytool(ctx: CommandContext) -> None:
...
CommandSupport is required whenever the BOF is OS/arch specific. Without it the command is offered on every implant.
parser = DefaultArgumentParser(prog="mytool", description="...")
parser.add_argument(...)
args = await ctx.split_and_parse_arguments(parser=parser)
if args is None:
return
Argument packing
from oc2_sdk_python.bof import BofArgumentEncoding, bof_pack, bof_pack_for_task
bof_pack([(encoding, value), ...]) returns one base64 blob for argument_list. Tuple order is the BOF ABI order.
After base64 decoding, the V3 blob is one message header followed by an ordered sequence of argument TLVs:
message type (2-byte LE, 7)
message version (2-byte LE, 1)
total message length (4-byte LE, including the 8-byte header)
repeat for each argument:
encoding (4-byte LE)
value length (4-byte LE)
value bytes
The TLV value bytes are:
| Encoding | Code | Python value | Value bytes |
|---|---|---|---|
WSTR |
10 |
str |
NUL-terminated UTF-16LE |
STR |
20 |
str |
NUL-terminated UTF-8 |
BUFFER |
30 |
bytes |
Bytes unchanged (see 4-byte rule) |
INT |
40 |
int |
Signed 32-bit little-endian |
SHORT |
50 |
int |
Signed 16-bit little-endian |
Use tuples ("WSTR", val) or BofArgumentEncoding.WSTR. Not Cobalt Z/z/i/s/b type strings (those are the builtin operator exec_bof CLI only).
Always construct packed arguments with the SDK rather than hand-building the serialized message.
Four-byte BUFFER contract
A 4-byte BUFFER is a candidate binary reference:
- The implant interprets it as a little-endian unsigned ID.
- It substitutes the attached binary only when a matching
TaskBinaryItemid exists. - If no matching binary exists, the 4 bytes remain inline data.
Collision: a genuine 4-byte inline BUFFER whose integer value matches another attached binary ID can be substituted unintentionally. ID 0 is reserved for the BOF object. Extra binaries start at 1. IDs must be unique.
bof_pack vs bof_pack_for_task
- If you have the bytes and a large
BUFFERshould be offloaded, usebof_pack_for_task. The SDK writes the 4-byte id and returns extraTaskBinaryItems (ids1+). - If you only have a catalog artifact id, do not use
bof_pack_for_task. AttachTaskBinaryItem.from_artifact(artifact.id, id=N)and packBUFFER=N.to_bytes(4, "little", signed=False).
bof_pack_for_task defaults:
BUFFERvalues of 64 bytes or fewer remain inline in the TLV.- Larger
BUFFERvalues becomeTaskBinaryItems, starting at id1; the TLV contains the 4-byte id. - Offloaded values of 65,536 bytes or fewer use inline task-binary content. Larger values use an upload session.
The keyword arguments buffer_inline_threshold, first_buffer_payload_id, and max_inline_payload_bytes override those defaults. If the task also attaches binaries manually, set first_buffer_payload_id high enough to avoid duplicate ids.
Binary and Execution Selection
Binaries
bof_bytes = await asyncio.to_thread(read_manifest_artifact, "mytool_bof_x64")
artifact_id, _ = await upsert_artifact(ctx.api_client, name="mytool_bof_x64", data=bof_bytes)
await ctx.schedule_task(
name="exec_bof",
argument_list=[packed], # omit if the BOF takes no args
binaries=[
TaskBinaryItem(id=0, label="bof", artifact_id=artifact_id),
],
)
Catalog refs: ctx.fetch_artifact("@artifacts/...") returns metadata only. Then TaskBinaryItem.from_artifact(artifact.id, id=N, label=artifact.name).
Implant opcodes
Choose the execution mode with schedule_task(name=...):
| Name | When |
|---|---|
exec_bof |
Default. New thread, full exception handling (stability). |
exec_bof_async |
Long-running. Stop with cancel + task UID; tag the task to find it. |
The current V3 SDK and server documentation define only exec_bof and exec_bof_async. V2 also used exec_bof_non_threaded, but that task name is not documented by the supplied V3 SDK or server. Treat it as implant-dependent: use it only after verifying that the target V3 implant/Stage1 supports the opcode. Do not assume support from V2 or silently replace it with exec_bof, because changing the execution mode can change behavior.
Common imports
from oc2_sdk_python.application import Application, read_manifest_artifact
from oc2_sdk_python.artifacts import upsert_artifact
from oc2_sdk_python.bof import BofArgumentEncoding, bof_pack, bof_pack_for_task
from oc2_sdk_python.command import (
CommandContext,
CommandSupport,
DefaultArgumentParser,
command,
)
from oc2_sdk_python.task import TaskBinaryItem
from oc2_sdk_python.types import Architecture, OperatingSystem