Skip to content

armgit / AiSOC

Public Imported from GitHub
0

Open-source AI Security Operations Center: alert fusion, LLM-agent triage, MITRE ATT&CK investigation, and a replayable decision ledger for every agent step. Self-hostable, runs with no API keys, MIT licensed. Ships an MCP server for Claude, Cursor and Continue.

12.9 KB
Raw Blame
"""
Agent state models for LangGraph workflows.
"""

from __future__ import annotations

import hashlib
import json
from datetime import datetime
from enum import Enum
from typing import Any
from uuid import UUID, uuid4

from pydantic import BaseModel, Field

#: Ceiling on the literal prompt / response kept beside a hash. Matches
#: `InvestigatorState`'s, so the two paths truncate at the same point.
_LLM_LITERAL_LIMIT = 8000


def _stable_hash(value: str) -> str:
    return hashlib.sha256(value.encode("utf-8")).hexdigest()


class AgentTask(str, Enum):
    TRIAGE = "triage"
    INVESTIGATION = "investigation"
    THREAT_HUNT = "threat_hunt"
    CONTAINMENT = "containment"
    ENRICHMENT = "enrichment"
    REPORTING = "reporting"


class AgentStatus(str, Enum):
    PENDING = "pending"
    RUNNING = "running"
    WAITING_APPROVAL = "waiting_approval"
    COMPLETED = "completed"
    FAILED = "failed"
    CANCELLED = "cancelled"


class ActionRisk(str, Enum):
    LOW = "low"
    MEDIUM = "medium"
    HIGH = "high"
    CRITICAL = "critical"


class ProposedAction(BaseModel):
    """An action the agent wants to take, subject to approval gating."""

    id: UUID = Field(default_factory=uuid4)
    action_type: str
    description: str
    risk_level: ActionRisk
    target: str
    parameters: dict[str, Any] = Field(default_factory=dict)
    requires_approval: bool = False
    rationale: str = ""


class InvestigationState(BaseModel):
    """Full state object passed through the LangGraph workflow."""

    #: Set when the run stopped on its token or model-call budget rather
    #: than finishing. Carried on the state so the console and the ledger
    #: can say "this did not conclude" rather than presenting a partial
    #: run's last verdict as the answer.
    budget_exhausted: bool = False
    budget_exhausted_reason: str | None = None

    #: The model that actually answered this triage, set from the call rather
    #: than from the pin.
    #:
    #: `fused_alert_consumer` stamps a shadow decision with
    #: `getattr(state, "model_used", None)`. The field did not exist, so that
    #: default was the only branch that ever ran and **every shadow decision
    #: recorded a null model** -- which makes per-model agreement, the reason
    #: the column exists, empty on every deployment.
    #:
    #: `None` means "no model answered", which is the honest value on the
    #: deterministic path. It is deliberately not defaulted to a pin name: a
    #: non-null column that nobody wrote is worse than an empty one, because
    #: it reads as a measurement.
    model_used: str | None = None

    # Identifiers
    run_id: UUID = Field(default_factory=uuid4)
    incident_id: UUID
    tenant_id: UUID
    task: AgentTask = AgentTask.INVESTIGATION
    status: AgentStatus = AgentStatus.PENDING

    # Input
    alert_summary: str = ""
    raw_alert: dict[str, Any] = Field(default_factory=dict)

    # Durable statements compiled from repeated analyst disagreement for this
    # tenant (services/api analyst_feedback). Carried on the state rather than
    # fetched inside the agent so the network read happens once per alert on
    # the worker's own timeline, and so a test can set it directly.
    organisation_memory: list[dict[str, Any]] = Field(default_factory=list)

    # The tenant skill that matched this alert, if any, and the version of it.
    # Carried for the same reason organisation memory is, plus one more: this
    # is the provenance a disputed verdict is explained from months later, so
    # it travels with the verdict rather than being recoverable only by
    # re-running the resolver against a store that has since changed.
    # `{"skill_id": ..., "version": N, "ref": "id@vN", "owner": ...}`.
    tenant_skill: dict[str, Any] | None = None

    # What the tenant's business-context rules did to this alert before triage
    # (services/agents workers/business_context). Carried on the state so the
    # prompt can tell the model a mutation happened and the verdict can cite
    # the rule ids that caused it — a `set_severity` the model cannot see is a
    # provenance hole in every downstream explanation.
    # `{"matched_rule_ids": [...], "severity_before": ..., "severity_after": ...}`.
    business_context: dict[str, Any] | None = None

    # The verdict's business-impact element, kept only when every citation it
    # carries resolves to supplied context (rule ids, identity accounts). An
    # uncited impact statement is dropped, not rendered — same discipline as
    # knowledge-base citations. `{"statement": str, "citations": [...]}`.
    business_impact: dict[str, Any] | None = None

    #: The claim-support review behind the verdict, as structure rather than
    #: only as basis strings: which decisive claims the evidence supported,
    #: which it did not, and which it contradicted
    #: (``ClaimSupportResult.as_dict()``). ``None`` on paths that never score
    #: claims — the deterministic tier, memory suppression — which is a
    #: different fact from "scored and found nothing".
    claim_review: dict[str, Any] | None = None

    # Knowledge-base runbook chunks retrieved for this alert, as
    # `app.context.knowledge_base.RunbookRetrieval.as_state()` renders them:
    # the chunks, the markers a citation resolves through, and what the
    # retrieval refused. Carried for the same reasons as the two above.
    #
    # A dict rather than the dataclass because this module sits below
    # `app.context`, whose package import reaches back here through
    # `bundle.py`. A type annotation is not worth an import cycle.
    knowledge_base: dict[str, Any] | None = None

    #: True when the prompt-injection guard refused any evidence retrieved
    #: for this alert. Carried onto the per-signature outcome prior, so a
    #: benign disposition reached through attacker-reachable text can never
    #: auto-close a later alert with the same signature.
    #:
    #: A field rather than a lookup at suppression time: by then the
    #: retrieval is gone, and recomputing it would mean re-running the guard
    #: over text the triage no longer holds.
    injection_suspected: bool = False

    # The last few analyst decisions on alerts of this shape, as
    # `app.context.dispositions.RecentDispositions.as_state()` renders them,
    # and the directory record for the principals this alert names, as
    # `app.context.identity.IdentityContext.as_state()` renders it. Dicts
    # rather than the dataclasses for the same import-cycle reason as above.
    recent_dispositions: dict[str, Any] | None = None
    identity_context: dict[str, Any] | None = None

    # Phase 4.5. What the vendors that raised or observe this alert said when
    # asked, just before triage reasoned over it. Carried as the
    # `VendorEvidence` dataclass rather than as a dict, because the guard on
    # fabricated tool claims reads `executed_capabilities` off it — the list
    # of verbs a vendor really answered, which is not recoverable from a
    # rendered block. `Any` for the same import-cycle reason as above, and
    # excluded from the serialised state for the same reason the retrieval
    # dicts are shaped the way they are.
    vendor_evidence: Any = None
    # What those principals could do *at the alert's event time*, as
    # `app.context.privilege.PrivilegeContext.as_state()` renders it (depth
    # plan wave 2, 1.1). Distinct from `identity_context`, which says who
    # holds the account: a service account no directory knows about still
    # has effective permissions, and that is usually the interesting case.
    privilege_context: dict[str, Any] | None = None

    # Findings accumulated during investigation
    findings: list[str] = Field(default_factory=list)
    ioc_enrichments: dict[str, Any] = Field(default_factory=dict)
    threat_intel: dict[str, Any] = Field(default_factory=dict)
    mitre_mappings: list[str] = Field(default_factory=list)

    # Actions
    proposed_actions: list[ProposedAction] = Field(default_factory=list)
    executed_actions: list[dict[str, Any]] = Field(default_factory=list)

    # LLM messages (for LangGraph)
    messages: list[dict[str, Any]] = Field(default_factory=list)

    # Calibrated confidence on the agent's verdict (0.0–1.0). Calibrated via
    # the Brier-score gate in the eval harness — see services/agents/app/confidence
    # and tests/test_confidence_calibration.py.
    confidence: float = 0.0
    confidence_basis: list[str] = Field(default_factory=list)
    verdict: str | None = None

    # Pre-fetched investigation context (graph neighbourhood, blast radius,
    # historical verdicts, UEBA baselines, TI matches). Built on the escalation
    # path so an auto-escalated alert is investigated with the same context an
    # analyst-initiated investigation of the same alert would have had.
    context_bundle: dict[str, Any] | None = None

    # Fraction of the concrete indicators cited in the reasoning that actually
    # appear in the evidence (see app/confidence/groundedness.py). None means
    # the verdict was not scored. Recorded alongside the verdict so an
    # ungrounded auto-closure is visible after the fact, not just at the time.
    groundedness: float | None = None

    # What the recursive investigation actually did: which strategy was
    # selected, how many distinct pivots it took, whether it hit its
    # iteration cap or time budget, and which data classes it could not
    # check. Recorded rather than inferred, because a narrative is not
    # evidence that anything was looked at — an investigation that called
    # one tool and wrote three paragraphs reads identically to one that
    # pivoted five times. This is what the depth gate grades.
    investigation_depth: dict[str, Any] | None = None

    # The literal model calls this run made, in order (issue #1276).
    #
    # The auto-triage ledger recorded a verdict and nothing a reader could
    # check it against: no prompt, and `input_hash`/`output_hash` null on
    # every step. A verdict with no recorded prompt cannot be replayed, and
    # replay is what `aisoc_explain_step` is documented to provide.
    #
    # The convention is the manual path's, not a second one: the hash is
    # over the full text and is always present, while the literal copy is
    # truncated, because these payloads carry customer data. Written by
    # `record_llm_exchange`; read by `ledger.persist_auto_triage`.
    llm_exchanges: list[dict[str, Any]] = Field(default_factory=list)

    # Metadata
    iteration_count: int = 0
    max_iterations: int = 10
    error: str | None = None

    started_at: datetime = Field(default_factory=datetime.utcnow)
    completed_at: datetime | None = None

    def add_finding(self, finding: str) -> None:
        self.findings.append(finding)

    def record_llm_exchange(
        self,
        *,
        agent: str,
        purpose: str,
        model: str | None,
        prompt: str | list[dict[str, Any]],
        response: str,
        duration_ms: int,
        serving_model: str | None = None,
        serving_attribution: str | None = None,
        system_fingerprint: str | None = None,
    ) -> dict[str, Any]:
        """Record one model call so the verdict it produced can be replayed.

        Mirrors ``InvestigatorState.log_llm_prompt`` /
        ``log_llm_response`` on the manual path: a SHA-256 over the full
        text always, a truncated literal for a human reader. The two
        differ only in shape — the manual path appends two audit entries,
        this one records a single call with both of its hashes, because
        the ledger row it becomes carries ``input_hash`` and
        ``output_hash`` on the same event.
        """
        prompt_text = prompt if isinstance(prompt, str) else json.dumps(prompt, sort_keys=True, default=str)
        exchange = {
            "agent": agent,
            "purpose": purpose,
            "model": model,
            # The serving identity, kept apart from the requested one above.
            # `model` is what was asked for; `serving_model` is what some
            # party said answered, `serving_attribution` is who said it
            # (gateway_header / response_body), and None means nobody did —
            # never a copy of the request. `system_fingerprint` is the
            # backend's own configuration digest when it published one.
            "serving_model": serving_model,
            "serving_attribution": serving_attribution,
            "system_fingerprint": system_fingerprint,
            "prompt": prompt_text[:_LLM_LITERAL_LIMIT],
            "prompt_truncated": len(prompt_text) > _LLM_LITERAL_LIMIT,
            "response": response[:_LLM_LITERAL_LIMIT],
            "response_truncated": len(response) > _LLM_LITERAL_LIMIT,
            "input_hash": _stable_hash(prompt_text),
            "output_hash": _stable_hash(response),
            "duration_ms": int(duration_ms),
            "timestamp": datetime.utcnow().isoformat(),
        }
        self.llm_exchanges.append(exchange)
        return exchange

    def to_dict(self) -> dict:
        return self.model_dump(mode="json")