Threat Detection Agent — Engineering Guide

InfinitySDLC Engineering Guides · 09/12

The Threat Detection Agent is a bounded analyst that enriches and correlates detections. It should increase signal quality and investigation speed without giving a language model unrestricted powers to disable users, block networks or delete workloads.

The production objective is not “an AI SOC analyst that decides what happened.” It is a reproducible investigation package: normalized entities, source-linked evidence, explicit uncertainty, competing explanations and a containment proposal whose authority is evaluated outside the model.

Reference engineering design, not a report of a completed client deployment. Sections 9.1–9.4 and the implementation blueprint preserve the source handbook. Sections 9.5–9.12 add production recommendations. Example alert IDs, confidence values, aliases and timelines are illustrative.

A detection is evidence that a rule or analytic matched. It is not permission to contain an identity, host or workload.

The Header diagram places detection inside a wider security-operations loop. Preventive controls, detection, response and post-incident learning have different authorities. Open the diagram at full size.

9.1 Inputs

• SIEM alerts and normalized event schemas.
• EDR findings and process trees.
• Cloud audit logs and IAM events.
• Identity-provider sign-in and risk events.
• Network, DNS and proxy telemetry.
• Asset inventory, vulnerability state and ownership.
• Recent deployments and configuration changes from the release system.
• Threat-intelligence feeds accessed through curated tools.

Normalize enough structure for cross-source reasoning while retaining the original vendor event identifier and source reference. OCSF is one vendor-neutral schema option; its core model defines categories, event classes, objects and attributes for security-event normalization. See the Open Cybersecurity Schema Framework. A normalized field must not erase information needed to reproduce the source event.

9.2 Detection triage workflow

1. Parse the alert into entities: actor, host or workload, IP or domain, process, cloud resource and time.
2. Resolve those observations against canonical entities using deterministic identity and asset services.
3. Enrich each entity through bounded tools with explicit time windows and access scopes.
4. Build a source-linked timeline. Preserve event time, ingestion time and the detector that produced each finding.
5. Compare suspicious behavior with known-good deployment, administrative and maintenance events.
6. Map observed behavior to the organization’s detection taxonomy and, where useful, MITRE ATT&CK detection strategies.
7. Produce multiple disposition options with supporting evidence, contradicting evidence and missing observations.
8. For containment, emit a versioned proposal. High-impact actions require the independently enforced approval policy.

# Illustrative source-handbook example
triage:
  alert_id: SIEM-99182
  entities: [user:u1042, host:wks-044, domain:example.invalid]
  disposition: suspicious
  confidence: 0.86
  evidence:
    - edr_process_tree: ...
    - idp_signin: impossible_travel=false
    - dns_first_seen: 12m
  recommended_next:
    - collect_edr_package
    - revoke_session   # approval required
  destructive_actions: none_executed

The value 0.86 and the evidence above are illustrative. Unless a confidence value has been calibrated against a defined replay population, do not interpret it as an 86% probability that an incident is malicious.

9.3 Retrieval strategy

RAG should hold versioned runbooks, asset criticality, approved administrative tooling, past incident patterns and exception knowledge. Threat telemetry itself should be queried live from the SIEM or data lake with strict entity and time filters. Use local inference for high-volume summarization where policy prohibits external processing, but keep the same authorization and evidence contracts.

Retrieval of a historical incident can inform a hypothesis; it cannot silently convert yesterday’s resolution into today’s containment action. Retrieve the approved runbook revision and applicability metadata, then check current entity state and current policy before proposing an effect.

9.4 Evaluation on replay datasets

• Replay known incidents and benign operational events.
• Measure false-positive reduction together with true-positive preservation; never optimize one by hiding the other.
• Score timeline correctness and entity-resolution accuracy.
• Test against poisoned log fields, malicious ticket text and adversarial threat-intelligence descriptions.
• Track whether the agent requests dangerous containment without sufficient evidence or correct authorization.

Split evaluation by underlying incident or campaign, not by individual alert. Otherwise near-duplicate alerts from one incident can appear in both development and evaluation sets and inflate apparent performance.

9.5 Build a canonical entity graph outside the model

The blueprint’s most important deterministic service is entity resolution. A username, cloud role, GitHub identity, workload service account and IP address may all appear in the same investigation, but they do not have the same identity semantics. Canonicalization should happen before the model correlates behavior.

Represent identity assertions as versioned relationships, not permanent aliases. A cloud role can be assumed by many humans; an IP can be shared through NAT; a container identifier can disappear and be reused at another layer. Record the source that asserted an alias, when it was observed and whether it denotes a principal, a credential, a session, a device or merely a network observable.

# Proposed production extension
canonical_entity: principal:8d21
entity_type: human_principal
aliases:
  - value: idp:user:alice@example.com
    source: idp-directory
    observed_at: 2026-09-15T00:22:00Z
  - value: github:user:alice
    source: scm-directory
    observed_at: 2026-09-15T00:22:14Z
relationships:
  - type: assumed_role
    target: cloud_role:ops-admin
    valid_from: 2026-09-15T00:03:11Z
    valid_until: 2026-09-15T01:03:11Z
risk_context:
  privileged: true
  owner_team: platform

Do not allow a free-form model conclusion such as “these aliases are probably the same person” to mutate the canonical graph. The agent can request a new deterministic join or mark an unresolved identity hypothesis; identity services own authoritative links.

9.6 Preserve detection provenance from rule to raw event

Every finding should retain the detector, rule or analytic identifier, rule version, execution backend, execution time, query or compiled-rule digest, data sources searched and the exact source-event references that caused the match. A translated rule and its source representation are different artifacts and should be versioned accordingly.

Sigma provides a vendor-agnostic format for describing log detections. In an enterprise pipeline, the meaningful audit question is not only “which Sigma rule?” but “which version was converted by which backend against which data, and which normalized events matched?”

DetectionFinding {
  finding_id,
  detector, rule_id, rule_version,
  backend, compiled_query_hash,
  executed_at,
  coverage: {sources, window, completeness},
  matched_event_refs[],
  canonical_entities[],
  technique_mappings[],
  disposition_state
}

MITRE ATT&CK’s current Detection Strategies organize analytics for detecting adversary techniques. Use ATT&CK mappings as a shared analytic vocabulary and coverage aid, not as proof that a specific adversary or root cause has been established. A technique mapping explains observed behavior; attribution requires separate evidence.

9.7 Model time explicitly: event time is not arrival time

Security correlation fails when a timeline assumes that SIEM arrival order equals real execution order. Store at least the producer’s event time, ingestion time and the collector or source clock context. Record observed lag and late-arriving events. For high-impact conclusions, show when ordering is certain, inferred or unknown.

An identity event received two minutes after an endpoint event may have happened earlier. A cloud control-plane record can arrive after a detector has already opened a case. Recompute affected hypotheses when late evidence crosses a defined watermark instead of quietly appending it to a finished narrative.

CISA’s joint guidance on living-off-the-land activity recommends aggregated logs and SIEM baselines across account behavior, administrative tools and network activity, with sufficient retention for extended dwell periods. See Identifying and Mitigating Living Off the Land Techniques. The implication for an agent is operational: a baseline must state its time window and data completeness before it can support “unusual” or “first seen” claims.

9.8 Treat missing evidence as a first-class state

“No evidence of compromise” is only meaningful when the relevant evidence source was available, searched and retained for the required interval. Return explicit observation states rather than one empty result.

Track telemetry-health signals alongside detection health: last successfully ingested event, expected event rate or heartbeat where appropriate, parser errors and schema-drift alarms. The model may explain a coverage gap, but it should not convert a broken sensor into a reassuring “no alerts” statement.

9.9 Threat intelligence needs validity and sharing boundaries

Do not treat every IOC as permanently malicious. Store the producer, indicator type, observable or pattern, validity interval, confidence semantics, handling restrictions and the exact intelligence object version. OASIS STIX 2.1 defines valid_from and optional valid_until properties for Indicator objects; this is a useful model for preventing stale indicators from silently driving current containment.

Preserve sharing restrictions when CTI crosses tools or model boundaries. FIRST TLP 2.0 defines TLP:RED, TLP:AMBER, TLP:GREEN and TLP:CLEAR as sharing-boundary labels. TLP is not an authorization system for your infrastructure: use it to constrain redistribution, then apply the enterprise data policy to retrieval, model routing, exports and case attachments.

Threat-intelligence text is untrusted input. A report containing “block this domain immediately” is evidence to assess, not an instruction channel. An IOC can increase investigation priority or satisfy a pre-approved exact-match rule only if the deterministic policy explicitly permits that path.

9.10 Bind containment to an exact proposal and current state

Containment is a separate business operation from investigation. The agent should emit a proposal with exact targets, action class, evidence, expected effect, expiry or rollback conditions and required approval. A separately authenticated enforcement service re-resolves the target immediately before execution.

containment_proposal:
  id: CP-2041
  finding_revision: SIEM-99182-r4
  target:
    canonical_entity: principal:8d21
    current_session: session:7ab3
  action: revoke_session
  scope: current_session_only
  evidence: [edr:pkg-91, idp:event-447, dns:q-81]
  expected_effect: terminate_current_authentication_session
  approval:
    policy: soc-high-impact-v5
    state: pending
  expires_at: 2026-09-15T03:40:00Z

Approval applies to this proposal, not to a later expanded action. If the canonical entity, target session, action scope or evidence revision changes materially, invalidate the approval. If execution acknowledgement is lost, reconcile the original operation before issuing another containment call.

The important boundary is architectural: the model proposes, policy decides, enforcement executes and independent readback verifies. This prevents a malicious alert field from directly becoming a firewall or identity command.

9.11 Security telemetry is hostile content, not trusted instruction

Logs, EDR command lines, email subjects, ticket descriptions, threat-intelligence reports and analyst comments can contain attacker-controlled text. Treat every such field as data. Preserve source and encoding, apply output-size limits, and present the model with structured fields whose role is explicit.

OWASP’s Prompt Injection Prevention Cheat Sheet describes indirect injection through external content. For a SOC agent, the strongest boundary is not a prompt that says “ignore malicious instructions”; it is that reading telemetry cannot grant new tools, expand scopes or satisfy an approval requirement.

Apply the same rule to MCP integrations. The current MCP authorization design binds access tokens to intended resources and explicitly rejects token passthrough. See the MCP authorization specification. Threat-intelligence and SIEM content may influence a proposed query, but enterprise identity and downstream service authorization determine whether that query or action is allowed.

Render analyst-facing Markdown or HTML safely. Never make attacker-controlled links or images an implicit exfiltration channel. Keep raw evidence in the security system of record and pass compact, redacted references to the model where full content is unnecessary.

9.12 Evaluate correlation, abstention and containment discipline

A useful replay suite contains malicious incidents, benign administrative activity, sensor failures and deliberately ambiguous cases. The agent should be rewarded for preserving a true positive and asking for missing evidence, not for forcing every case into “malicious” or “benign.”

Report entity-resolution precision and recall on labeled joins, timeline-order accuracy, evidence completeness, true-positive preservation, false-positive reduction at a declared recall level, analyst correction rate and inappropriate-containment proposal rate. Break results down by data-source availability and incident class.

For handoff to Incident Response, persist the alert revision, canonical entities, timeline with source references, open hypotheses, missing evidence, proposed actions and approvals. A new model session should be able to reproduce why the case is in its current state without relying on a hidden chat transcript.

Implementation Blueprint: Correlation Without Unbounded Containment

Deterministic entity-resolution service

Canonicalize human principals, service identities, cloud principals, hosts, containers, sessions, IPs and applications outside the model. Store relationship type, source and validity instead of flattening every alias into one permanent identity.

canonical_entity: principal:8d21
aliases:
  - idp:user:alice@example.com
  - github:user:alice
risk_context:
  privileged: true
  owner_team: platform
  last_role_change: 2026-09-02
# Illustrative blueprint data.

Recommended bounded tool surface

Containment policy from the handbook

Automatic evidence collection and bounded telemetry expansion can be useful low-risk automation. Blocking an IOC, revoking a session, disabling a user or isolating a host require progressively stronger controls. Resource deletion is deliberately absent from the agent’s containment primitives. The reference defaults must still be adapted to organizational policy and legal constraints before production use.

Operating invariants

• One alert or correlation result cannot expand tool authority.
• Canonical entity resolution is deterministic and auditable; the model cannot silently rewrite identity.
• Every material claim points to a query, finding or evidence reference plus its observation state.
• Threat-intelligence validity and sharing restrictions survive retrieval and model routing.
• High-impact containment is proposal → approval → separately authenticated execution → authoritative readback.
• A broken sensor or inaccessible log source produces an evidence gap, not a benign conclusion.
• Replay evaluations include poisoned content, late events, stale intelligence and ambiguous execution outcomes.

Sources and shared prerequisites

Adapted from Article 9 and Blueprint 9 of the September 2026 Enterprise AI Agent Mesh handbook. The added production sections are engineering recommendations, not claims of completed client work. Vendor and standards behavior is linked to the corresponding primary documentation.

The Enterprise Agent Platform Foundation provides shared identity, policy, retrieval, audit and execution boundaries. The Observability Agent supplies bounded telemetry queries; Security Prevention supplies preventive context; consequential coordination belongs to Incident Response.

Explore the series

Previous: Security Prevention Agent

Next: Risk & Reliability Agent