QControl: Control Framework
Architecture-first technical deep dive — plugin SDK, event stream, entity model, and observation tiers for security engineers evaluating integration
Section 1 — Hero
Runtime Agent Control — Built for Engineers
A plugin SDK, a universal event stream, and three tiers of observation. One binary. No infrastructure changes.
12 Entity Types
Fully correlated agent activity model
4 Observation Surfaces
Native telemetry, filesystem, process hooks, backup proxy
HOW IT WORKS
Two Vantage Points. One Event Stream.
Inside the Process
Agent doesn't cooperate. Corrupted agent can't hide.
Outside on the Surface
OS-level observation independent of agent runtime.
CONVERGENCE DIAGRAM
Inside Process
file, net, tool, API
Normalized Event Stream
typed, correlated, sequenced
Outside Surface
process, telemetry, config
Plugin Pipeline
observe / block / modify
DATA MODEL
12 Entity Types. Fully Correlated.
Session
session_id
start_time
agent
user
Agent
name
version
harness
capabilities
User
id
role
Endpoint
hostname
os
arch
Model
provider
model_id
tier
API Key
key_hash
scope
provider
MCP Server
name
url
tools_count
Agent Capability
type: terminal
type: file
type: network
type: mcp
File
path
operation
sensitivity
Secondary Call
destination
method
status_code
LLM Turn
role
token_count
tool_calls
Tool Call
name
arguments_hash
duration_ms
ENTITY CORRELATION CHAIN
Every entity carries correlation keys. A single tool call traces through the full chain to endpoint and user.
SAMPLE CORRELATION PAYLOAD
{
"event": "tool_call.invoke",
"tool_call_id": "tc_8f3a...",
"session_id": "sess_a1b2...",
"user_id": "usr_mark@acme.com",
"endpoint_id": "ep_dev-mac-01",
"agent_id": "ag_claude-code-1.0.33",
"model_id": "mdl_claude-opus-4-6",
"tool": "Bash",
"arguments_hash": "sha256:e4c9...",
"timestamp": "2026-05-04T14:32:01.337Z"
}DEPTH OF VISIBILITY
Three Tiers. Choose Your Depth.
T1 — Foundational
Works with any agent from day one.
Coverage: all file I/O, all outbound connections, all child process spawns.
T2 — Robust Client Support
Known primitive interpolation.
Coverage: tool call reconstruction, LLM turn boundaries, MCP request/response pairing.
T3 — Client-Specific
Native governance hooks.
Coverage: agent reasoning chain, pre-decision interception, policy-as-code enforcement.
EVENTS
A Normalized Stream. Every Agent. Every Action.
Agent
File
Connection
HTTP
Exec
MCP
Process
Correlation Keys
session_id
request_id
connection_id
call_id
exchange_id
file_id
exec_id
entity_id
Every event carries one or more correlation keys. Join across the full entity model.
PLUGINS
Observe, Block, or Modify — Any Agent Action
Stable ABI: C, C++, Rust, Zig. Plugins receive events, return decisions (allow / block / modify), can mutate payloads. Same plugin binary works against CLI and embedded library.
destination-allowlist
Block connections to unapproved destinations. Default-deny for agent network.
PSEUDO-CODE
fn on_connection_open(event: &ConnectionEvent) -> Decision {
if allowlist.contains(&event.destination) {
Decision::Allow
} else {
log!("blocked: {} -> {}", event.session_id, event.destination);
Decision::Block {
reason: "destination not in allowlist"
}
}
}secret-redactor
Intercept file reads and replace credential patterns before agent sees content.
PSEUDO-CODE
fn on_file_read(event: &mut FileEvent) -> Decision {
let matches = scan(&event.content, &CREDENTIAL_PATTERNS);
if matches.is_empty() {
Decision::Allow
} else {
for m in matches {
event.content.replace_range(m.range, "REDACTED_BY_POLICY");
}
Decision::Modify
}
}trust-score-annotator
Add contextual headers to outbound HTTP requests for perimeter enforcement.
PSEUDO-CODE
fn on_http_request(event: &mut HttpEvent) -> Decision {
let score = trust_engine.score(&event.session_id);
event.headers.insert("X-Agent-Id", &event.agent_id);
event.headers.insert("X-Agent-Trust-Score", &score.to_string());
event.headers.insert("X-Session-Id", &event.session_id);
Decision::Allow
}DISCOVERY
Find Every Agent. Including the Ones That Hide.
Process Signature
Match process name and arguments against known agent catalog. Continuously updated.
claude, cursor, codex, continue, windsurf, opencode
File Signature
Inspect application bundles, config directories, MCP manifests, on-disk fingerprints.
~/.cursor/, ~/.claude/, mcp.json, package.json[ai-*]
Embedded Detection
Identify agent runtimes embedded in other apps. Coding assistants in IDEs, browser-based agents, vertical SaaS.
Library signatures, runtime behavior patterns, IPC hooks
External Signal
Network/kernel/identity layer flags agentic traffic. Partnership discovery point.
Network sees agent-shaped traffic -> QControl confirms on endpoint
ENFORCEMENT
QControl Produces Signal. Your Stack Enforces.
SIGNAL FLOW
Agent
tool call
QControl Plugin
observe + annotate
Outbound Request
+ context headers
Perimeter
matches X-Agent-*
Decision
context-aware
INTEGRATION TARGETS
EDR
SIEM
IdP
MCP Gateway
LLM Gateway
This is the same pattern as Cisco ISE + pxGrid, Duo, Rapid Threat Containment. QControl produces context. Existing enforcement infrastructure consumes it.
DEPLOYMENT
One Binary. Two Delivery Models.
qcontrol CLI
Single static binary. ~8MB. No dependencies.
USAGE
$ qcontrol discover Found 3 agents on this endpoint: claude-code v1.0.33 pid:4821 user:mark cursor v0.52.1 pid:3102 user:mark codex-cli v0.1.4 pid:5590 user:sarah $ qcontrol attach 4821 Attached to claude-code (pid:4821) Loading plugins: destination-allowlist, secret-redactor Streaming events to stdout... $ qcontrol stream --format=json | tee events.jsonl
libqcontrol.h
Stable C ABI. Link from C/C++/Rust/Go/Python (FFI).
API SURFACE
// Initialize the QControl engine qc_handle_t *h = qc_init(NULL); // Discover agents on this endpoint qc_agent_t *agents = qc_discover(h); // Attach to a specific agent process qc_attach(h, agents[0].pid); // Register a plugin (compiled .so/.dylib) qc_register_plugin(h, "./plugins/secret-redactor.so"); // Stream events with callback qc_stream_events(h, event_callback, NULL);
TRUST ANCHOR
Heartbeat Model
Cryptographically signed against attested key. Absence of heartbeat = untrusted.
// Start cryptographic heartbeat
qc_heartbeat_start(h);
// Heartbeat payload (signed, attested)
// { endpoint_id, agent_count, last_event_ts,
// plugins_loaded, attestation_sig }
// Perimeter behavior:
// Heartbeat present -> managed, trusted
// Heartbeat absent -> untrusted, AI traffic constrainedPresent
Managed, trusted
Absent
Untrusted, constrained
Build With Us
Plugin SDK. Event stream. Stable ABI. Start integrating today.