Officer

The approved Windows full-surface engineering program is in progress. Track verified coverage and remaining requirements in the living capability matrix. Live delivery now uses the durable encrypted journal. Historical phase notes below do not establish completion or production qualification.

Officer is the Windows endpoint agent for Panopticon, an EDR/XDR capstone project. Its job is to observe security-relevant activity on a Windows endpoint, turn source-specific records into a stable Panopticon event format, deliver those events to a Panopticon Manager, and execute a closed set of authorized response actions on that same endpoint.

Status: active capstone/research project, not a production security product. Telemetry collection and normalization are real and validated (see "Current status" below). The response module executes real Win32 actions (process termination, file quarantine, host isolation) rather than simulating them, but end-to-end live verification against a running Manager, on an elevated host, has not yet been demonstrated in this environment — see RESPONSE.md for exactly what has and has not been exercised.

This repository contains the agent only. It does not contain Panopticon's detection engine, response-policy engine, orchestration Manager, or investigation console — see "Integration with other Panopticon repositories" below.

Where Officer fits

flowchart LR
    A["Windows endpoint"] --> B["ETW / Sysmon / Windows Event Log"]
    B --> C["Officer collectors"]
    C --> D["Raw source-neutral events"]
    D --> E["Enrichment and normalization"]
    E --> F["Versioned Panopticon events"]
    F -. "future delivery" .-> G["Panopticon ingestion"]
    G --> H["Detection and correlation"]
    H --> I["Analyst console and response"]

Loading

Different Windows telemetry sources describe similar activity in different ways. Officer hides those differences behind source-neutral C++ contracts. The rest of Panopticon should not need to know whether a process event originated from ETW, Sysmon, or another supported adapter.

Officer will eventually own:

• Windows telemetry collection through independent source adapters.
• Source-neutral raw event contracts.
• Local enrichment such as file hashes and account resolution.
• Normalization into versioned Panopticon events.
• Bounded queues and batching. Durable local spooling for telemetry delivery is implemented (docs/architecture/phase-9-telemetry-durability.md), with its own component verified in this repository's dev environment; native Windows/MSVC verification of the full delivery path is still pending.
• Authenticated delivery to Panopticon ingestion.
• Agent configuration, identity, health, and Windows service lifecycle.

Detection rules remain configurable on the Panopticon side. Collection code does not contain detection logic, and source adapters do not produce JSON or communicate with the server directly.

Current status

The agent connects independent live Windows sources to the Phase 1 contracts, normalizes their records, and prints one compact JSON object per observation. Live ETW and Sysmon process-start collection is joined, from the V3 multi-family telemetry work, by Sysmon-based network, file, registry, and image-load collection, all normalized to Panopticon Schema 0.3.

Implemented now:

• A source-neutral raw process-start contract with source provenance.
• A separate enrichment contract so observed facts are not overwritten.
• Panopticon normalized event schema 0.3 with source provenance; Schema 0.2 process events remain valid under it (the change is additive).
• Deterministic event IDs and PID-reuse-safe process entity IDs.
• Windows CNG SHA-256 identity derivation.
• Strict JSON serialization, deserialization, and malformed-input rejection.
• Native Windows ARM64 contract and parser tests.
• Raw Windows ETW subscription to Microsoft-Windows-Kernel-Process.
• Live Sysmon subscription through Windows Event Log EvtSubscribe.
• Schema 0.3 multi-family telemetry: network, file, registry, and image-load events decoded from Sysmon Event IDs 3, 7, 11, 12, 13, 14, 23, and 26, each carrying process context. Metadata only, with a scoped reference Sysmon configuration under docs/sysmon/.
• Clean Ctrl+C shutdown for both collector lifecycles.
• officer-query, the preserved EyeTrace v0.1 historical Sysmon reader.
• HTTPS delivery of normalized events to a Panopticon Manager (--manager-url), built on a WinHTTP-based client with certificate verification by default.
• An opt-in (--enable-response, requires --manager-url) response module that enrolls with the Manager, polls for typed commands, and dispatches all 7 closed-set actions (KILL_PROCESS, COLLECT_PROCESS_INFO, COLLECT_NETWORK_CONNECTIONS, COLLECT_FILE, QUARANTINE_FILE, ISOLATE_HOST, RELEASE_HOST_ISOLATION) to real Win32 implementations, gated by agent/host binding, expiry, and durable replay protection before any command executes. See RESPONSE.md for the full design, including the PID-reuse defense used by KILL_PROCESS and what has and has not been verified end-to-end. Off by default; behavior is byte-identical to the telemetry-only agent unless explicitly enabled.

Not implemented yet:

• The bounded event bus and backpressure handling for telemetry.
• Windows service installation and lifecycle management.
• DNS and process-stop schemas, and ETW-based (non-Sysmon) file and registry providers.
• A privilege-separated helper process for response actions (isolation and every other response handler currently run inside the already-elevated officer-agent.exe, unlike the split used by panopticon-linux-agent).

The next phase moves normalization off acquisition callback threads and onto a bounded queue with explicit health and loss counters.

See the Phase 2 design, the roadmap, the future ingestion boundary, the Phase 1 design, the process identity decision, and the current JSON Schema.

Build and test on Windows ARM64

Run these commands from an Arm64 Developer PowerShell for Visual Studio:

cmake -S . -B build-officer-arm64 -G Ninja `
  -DCMAKE_TOOLCHAIN_FILE="C:/Program Files/Microsoft Visual Studio/18/Community/VC/vcpkg/scripts/buildsystems/vcpkg.cmake" `
  -DVCPKG_TARGET_TRIPLET=arm64-windows

cmake --build build-officer-arm64
ctest --test-dir build-officer-arm64 --output-on-failure

The build produces:

• officer-agent.exe - the live console agent.
• officer-collectors.lib - independent ETW and Sysmon acquisition adapters.
• officer-core-tests.exe - identity, normalization, and JSON contract tests.
• officer-collector-tests.exe - sanitized source-decoder and interface tests.
• officer-query.exe - the historical Sysmon query and diagnostic utility.
• officer-tests.exe - sanitized Sysmon parser tests.

Build and test on Windows x64

Officer's build system is triplet-driven and contains no ARM64-specific or x64-specific source code, so x64 is built the same way as ARM64 with a different vcpkg triplet. Run these commands from an x64 Developer PowerShell for Visual Studio (or any shell with VCToolsInstallDir set for the x64 host/target via vcvars64.bat):

cmake -S . -B build-officer-x64 -G Ninja `
  -DCMAKE_TOOLCHAIN_FILE="<path-to-vcpkg>/scripts/buildsystems/vcpkg.cmake" `
  -DVCPKG_TARGET_TRIPLET=x64-windows

cmake --build build-officer-x64
ctest --test-dir build-officer-x64 --output-on-failure

This has been validated end-to-end on real x64 Windows hardware: vcpkg builds nlohmann-json and tinyxml2 from source for x64-windows, all 6 build targets compile and link cleanly under MSVC 14.44 with no warnings, and all 7 CTest cases pass. Live ETW/Sysmon capture on x64 requires the same elevated PowerShell as ARM64 (see below) and has not yet been demonstrated in CI or on this particular machine — build/test validation and live-capture validation are tracked separately.

Run live collection

Open an elevated PowerShell. Start both sources, then launch Notepad from a second terminal or the Start menu:

.\build-officer-arm64\officer-agent.exe --source all   # or build-officer-x64, matching the build you ran

Start-Process notepad.exe

Officer writes status and errors to stderr and one normalized JSON event per line to stdout. Press Ctrl+C to stop both subscriptions and release the ETW session. Use --source etw or --source sysmon to isolate one adapter.

Both sources may report the same process. Their events retain distinct source provenance and event IDs while converging on one process entity ID when their timestamps identify the same Windows process.

Elevation is required to control the system ETW session and read the protected Sysmon channel. If the process is force-killed and leaves the fixed development session behind, clean it from an elevated terminal with:

logman stop Panopticon-Officer-Process -ets

Historical telemetry utility

officer-query remains available to retrieve historical events from a running Sysmon installation. From an elevated PowerShell, query the newest Sysmon process-creation event and write the same NDJSON to the console and a temporary file:

.\build-officer-arm64\tools\query\officer-query.exe `
  --event-id 1 `
  --limit 1 `
  --output "$env:TEMP\officer-process.ndjson"

Get-Content "$env:TEMP\officer-process.ndjson"

This proves the Windows Event Log acquisition and Sysmon parsing path. It is a diagnostic utility, not the future live Officer pipeline. Event IDs 3, 11, 12, 13, and 14 can also inspect network, file, and registry activity. See Officer Query usage.

Example normalized event

The values below are sanitized and formatted for readability. Live output is compact NDJSON and will reflect the source fields actually available.

{
  "schema_version": "0.3",
  "event": {
    "id": "evt_1111111111111111111111111111111111111111111111111111111111111111",
    "category": "process",
    "type": "start",
    "timestamp": "2026-08-13T20:15:42.123Z"
  },
  "source": {
    "kind": "sysmon",
    "provider": "Microsoft-Windows-Sysmon",
    "channel": "Microsoft-Windows-Sysmon/Operational",
    "record_id": 100
  },
  "agent": {
    "id": "agent-sanitized-001",
    "version": "0.3.0"
  },
  "host": {
    "id": "host-sanitized-001",
    "hostname": "OFFICER-LAB",
    "os": {
      "name": "Windows 11",
      "build": "26100"
    }
  },
  "user": {
    "name": "analyst",
    "domain": "LAB",
    "sid": "S-1-5-21-1000000000-1000000001-1000000002-1001"
  },
  "process": {
    "entity_id": "proc_2222222222222222222222222222222222222222222222222222222222222222",
    "pid": 4242,
    "name": "officer-demo.exe",
    "executable": "C:\\Sanitized\\officer-demo.exe",
    "command_line": "\"C:\\Sanitized\\officer-demo.exe\" --safe-test",
    "parent": {
      "entity_id": null,
      "pid": 1000,
      "name": "powershell.exe"
    },
    "hash": {
      "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
    }
  }
}

The identifiers shown above are illustrative. Real evt_ and proc_ values are deterministic SHA-256-derived identities, not repeated placeholder digits.

Repository layout

include/panopticon/officer/   Public agent contracts
src/collectors/                Independent ETW and Sysmon adapters
src/core/                      Stable identity implementation
src/pipeline/                  Normalization and JSON boundary
src/delivery/                  WinHTTP-based telemetry delivery to a Manager
src/response/                  Manager command polling and the 7 response actions
schema/                        Versioned Panopticon JSON contract
tests/                         Sanitized contract, collector, delivery, and response tests
tools/query/                   Historical Sysmon diagnostic utility
docs/architecture/             Phase designs and boundaries
docs/adr/                      Architecture decision records

See the complete roadmap for queues, additional typed event schemas, enrichment, durable spooling, secure delivery, and Windows service hardening, and RESPONSE.md for the response module's design and open architectural questions.

Integration with other Panopticon repositories

Officer is one component of the larger Panopticon-Co platform. It never imports source from, or depends on, another repository's build — the only integration surfaces are its build artifact (officer-agent.exe), the Panopticon event schema, and the Manager's HTTP command/result contract.

• panopticon-detection-engine — consumes Officer's Schema 0.3 NDJSON output and produces detections/alerts.
• panopticon-manager — the orchestration service Officer enrolls with, polls for response commands, and reports results and audit evidence to, when --enable-response is set.
• panopticon-contracts — canonical JSON-schema wire contracts and fixtures shared across repos; this repo's response tests read fixtures from a sibling checkout of it when present (see CMakeLists.txt and .github/workflows/ci.yml) and skip gracefully otherwise.
• Panopticon-Co organization — all repositories, including the response-policy engine that authorizes the commands Officer executes.

Security considerations

• Elevation is required. ETW subscription and the protected Sysmon channel both need an elevated token; the agent detects and reports this rather than silently degrading (see "Run live collection" above).
• PID-reuse protection. KILL_PROCESS re-validates the target process's creation time (GetProcessTimes) against the command's target_start_time_ticks immediately before termination, so a command issued against one process cannot be redirected onto a different process that the OS later assigns the same PID. This narrows, but — absent an atomic Win32 "terminate iff creation-time == X" primitive — does not fully eliminate, the reopen-to-terminate race; see RESPONSE.md for details.
• Closed response action set. Only the 7 actions listed above exist; the agent rejects unknown actions, unknown fields, and malformed command envelopes outright (see tests/response_tests.cpp).
• File operations are root-jailed. COLLECT_FILE and QUARANTINE_FILE resolve every path against a configured allow-listed root and reject absolute paths or traversal outside it.
• Response commands are gated by agent/host binding, expiry, and durable (disk-backed) replay protection before they are ever dispatched.

Privacy and safety

Endpoint telemetry can contain usernames, command lines, paths, URLs, network addresses, and secrets. Never commit raw XML, NDJSON, EVTX files, or captured production telemetry. Repository fixtures and examples must remain sanitized.

Contributing, security reporting, and license

• See CONTRIBUTING.md for the build/test/PR workflow.
• Report suspected vulnerabilities privately per SECURITY.md — please do not open a public issue for a security report.
• This project follows the Contributor Covenant.
• Licensed under the MIT License.

The original EyeTrace Query v0.1 implementation is preserved by the Git tag eyetrace-query-v0.1.