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.

13.0 KB
Raw Blame
"""An identity, a scope and an expiry for each of AiSOC's own agents.

Depth plan wave 2, Phase 7.3 — parity 6.7's first half: "Give each internal
agent its own identity, with short-lived credentials and least-privilege
tool scopes, visible in the audit log."

Why this exists
---------------
``ToolRegistry.execute(name, args)`` ran any registered tool for any caller.
There was no identity, no scope and no audit row, which meant three things:

* a triage agent steered by injected text into asking for a containment
  tool would have it run, because nothing compared the request against what
  that agent is allowed to hold;
* the question an incident asks of an agent — *what did it do* — had no
  answer in the ledger, because no row named the caller;
* and the platform that flags "no person is linked, nobody is accountable"
  on a customer's AI estate was running its own agents with exactly that
  property.

What "short-lived" means here, and what it does not
----------------------------------------------------
A credential bound to one investigation run with a wall-clock expiry. It is
deliberately **not** a bearer token to another service: these agents call
Python functions inside their own process, so a network credential would be
ceremony rather than a control, and this repository has shipped enough of
those to be wary of one more.

What the control has to survive is the in-process threat — a model steered
into requesting a tool outside its grant — and the only place that can be
stopped is the one chokepoint every tool call passes through. The expiry
earns its place separately: a run that stalls and resumes hours later must
re-issue rather than continue on a credential nobody has re-authorised.

Why the scopes are a table and not a decorator
-----------------------------------------------
Because the interesting operation is reading them side by side. "Which
agents can run a containment tool" is a question a reviewer asks of the
whole system, and a table answers it in one screen; decorators scattered
across twelve modules do not. The table is also what makes
``test_the_scopes_are_least_privilege_and_not_all_the_same`` possible: if
every agent held every tool the scope would be a comment, and that is
checkable here and nowhere else.

Unknown agents are refused rather than defaulted
-------------------------------------------------
Defaulting an undeclared agent to "everything" makes the control
decorative. Defaulting it to "nothing" breaks that agent silently at run
time, in production, on whatever path first reached for a tool. Refusing to
mint an identity at all fails at the point a human can still see it.
"""

from __future__ import annotations

import time
import uuid
from dataclasses import dataclass, field

#: Default credential lifetime. Long enough for a deep investigation,
#: short enough that a stalled run re-issues rather than continuing on a
#: grant nobody re-authorised.
DEFAULT_TTL_SECONDS = 1800

#: Which tools each of AiSOC's own agents may call.
#:
#: Read as a privilege boundary, not as a dependency list: these are the
#: tools an agent is *permitted* to reach, and the set is deliberately
#: unequal across agents. The triage and investigation agents read; only
#: the response agent reaches anything that changes an estate, and it does
#: so through the governed action path, which applies its own capability
#: contract and approval tier on top of this.
#:
#: A tool absent from every set here is reachable by nobody, which is the
#: correct default for a tool nobody has thought about.
#: Every tool name AiSOC's own registries actually register.
#:
#: Written out rather than imported, because importing the registries here
#: would make this module depend on the investigator, the sandbox client and
#: the MITRE corpus just to answer "what is a valid tool name". The cost of
#: writing them out is drift, and that is paid for by
#: `test_every_scoped_tool_name_is_a_tool_something_registers`, which walks
#: the registries and fails if a name here is not among them.
#:
#: This mattered: the first draft of the table below listed `search_logs`,
#: `query_lake` and `graph_blast_radius`, none of which any registry
#: registers. A scope naming tools that do not exist grants nothing and
#: refuses everything real — the same class of mistake as a detection rule
#: clausing on a field no connector emits, and just as invisible, because a
#: scope full of plausible names reads as careful.
KNOWN_TOOLS: frozenset[str] = frozenset(
    {
        # default_registry
        "lookup_file_hash",
        "extract_iocs",
        "map_to_mitre",
        "lookup_technique",
        "enrich_ioc",
        # investigator customer tools (typed, lake-backed pivots)
        "process_activity",
        "historical_execution",
        "network_connections",
        "authentication_events",
        "fleet_ioc_hunt",
        "entity_timeline",
        "technique_activity",
        "process_tree",
        "mailbox_activity",
        "oauth_grants",
        "persistence_mechanisms",
        # Wave-2 1.1 and 1.5, registered unconditionally in
        # `default_registry`: what this identity could do at the moment it
        # acted, and what changed shortly before it did. Read-only, and
        # both answer "unknown, and here is why" rather than a silent zero
        # when no snapshot covers the question.
        "identity_effective_permissions",
        "changes_before_alert",
        # Customer-estate read tools (`app/tools/customer_tools.py`). These
        # reach the customer's own vendors through the governed read path
        # rather than AiSOC's lake, which is why the investigator holds
        # them and nothing else does.
        "siem_indicator_search",
        "cloud_audit_lookup",
        "edr_host_details",
        "edr_host_detections",
        "endpoint_telemetry_sightings",
        "identity_user_activity",
    }
)

#: Which tools each of AiSOC's own agents may call.
#:
#: Read as a privilege boundary, not as a dependency list. The sets are
#: deliberately unequal: triage is the agent most exposed to
#: attacker-controlled text and holds the least, while the investigator
#: holds the deep pivots because that is its job.
#:
#: Note what is *not* here: nothing in this table changes an estate. AiSOC's
#: own agents propose; execution goes through `services/actions`, which
#: applies a capability contract and an approval tier of its own. Putting a
#: containment verb in this table would create a second, weaker door to the
#: same operation.
#:
#: A tool in `KNOWN_TOOLS` and in no scope here is reachable by nobody,
#: which is the correct default for a tool nobody has thought about.
AGENT_TOOL_SCOPES: dict[str, frozenset[str]] = {
    # Reads alert context, extracts indicators, looks up techniques. Holds
    # no pivot that reaches customer telemetry, because this is the agent
    # an injected alert talks to first.
    "triage": frozenset({"extract_iocs", "map_to_mitre", "lookup_technique", "enrich_ioc"}),
    # The recursive investigator: everything triage holds, plus the typed
    # lake-backed pivots and the sandbox lookup.
    "investigation": frozenset(
        {
            "extract_iocs",
            "map_to_mitre",
            "lookup_technique",
            "enrich_ioc",
            "lookup_file_hash",
            "process_activity",
            "historical_execution",
            "network_connections",
            "authentication_events",
            "fleet_ioc_hunt",
            "entity_timeline",
            "technique_activity",
            "process_tree",
            "mailbox_activity",
            "oauth_grants",
            "persistence_mechanisms",
            # The two halves of "what could this identity do, and what
            # changed before it did". The investigator rather than triage:
            # both take typed entity fields, but the scope table keeps the
            # agent most exposed to attacker-controlled text at its minimum.
            "identity_effective_permissions",
            "changes_before_alert",
            "siem_indicator_search",
            "cloud_audit_lookup",
            "edr_host_details",
            "edr_host_detections",
            "endpoint_telemetry_sightings",
            "identity_user_activity",
        }
    ),
    # Hunting sweeps the fleet and reads timelines; it does not enrich
    # against third parties, which is a per-tenant opt-in with its own key.
    "hunt": frozenset(
        {
            "extract_iocs",
            "lookup_technique",
            "fleet_ioc_hunt",
            "entity_timeline",
            "technique_activity",
            "historical_execution",
            "siem_indicator_search",
        }
    ),
    # Proposes a disposition and a containment plan. Reads what it needs to
    # justify one; executes nothing here.
    "respond": frozenset({"lookup_technique", "entity_timeline", "process_tree", "network_connections"}),
    # Detection engineering drafts rules from technique coverage.
    "detect": frozenset({"map_to_mitre", "lookup_technique", "technique_activity", "historical_execution"}),
}


class ScopeDenied(RuntimeError):
    """A tool was requested outside the caller's scope, or after expiry.

    An exception rather than a sentinel because a direct caller must not be
    able to mistake a denial for a result. ``ToolRegistry`` converts it into
    the structured ``{"error": ...}`` its loop contract requires, which is a
    conversion at one place rather than every caller parsing a string.
    """


@dataclass(frozen=True)
class AgentIdentity:
    """One agent, one run, one expiry, one scope."""

    agent: str
    run_id: str
    expires_at: float
    scopes: frozenset[str]
    #: Distinguishes two concurrent runs of the same agent in the audit log.
    credential_id: str = field(default_factory=lambda: uuid.uuid4().hex)

    def expired(self, *, now: float | None = None) -> bool:
        return (now if now is not None else time.time()) >= self.expires_at

    def may(self, tool: str) -> bool:
        return not self.expired() and tool in self.scopes

    def require(self, tool: str, *, now: float | None = None) -> None:
        """Raise unless this identity may call ``tool`` right now."""
        if self.expired(now=now):
            raise ScopeDenied(
                f"the credential for agent {self.agent!r} on run {self.run_id!r} has expired; re-issue it rather than extending it"
            )
        if tool not in self.scopes:
            raise ScopeDenied(f"tool {tool!r} is outside the scope of agent {self.agent!r}")

    def with_granted_tools(self, tools: frozenset[str] | set[str] | list[str]) -> AgentIdentity:
        """A copy of this identity extended with tools another control approved.

        The one legitimate way the scope grows, and it exists for MCP: a
        tenant's MCP servers are discovered at run time, so their tool names
        cannot be in a static table. They are not ungoverned — `app/mcp/
        policy.py` classifies each one and refuses the destructive ones
        before this is ever called — so this is one control handing its
        verdict to the other rather than a hole in either.

        The expiry and the credential id are carried over deliberately: a
        grant must not silently extend the credential's life, and the audit
        rows for the granted tools must join to the same run.
        """
        return _granted(self, frozenset(str(t) for t in tools))

    def audit_row(self, tool: str, *, allowed: bool, reason: str | None = None) -> dict[str, object]:
        """One row for the audit log. Never the tool's arguments.

        Arguments carry alert content — hostnames, account names, raw text
        lifted from a vendor payload. An audit log is read by more people
        than an alert is, so a tool-call log that copied the arguments
        would become a second, wider copy of the evidence.
        """
        row: dict[str, object] = {
            "agent": self.agent,
            "run_id": self.run_id,
            "credential_id": self.credential_id,
            "tool": tool,
            "allowed": allowed,
            "at": time.time(),
        }
        if reason:
            row["reason"] = reason
        return row


def _granted(identity: AgentIdentity, tools: frozenset[str]) -> AgentIdentity:
    return AgentIdentity(
        agent=identity.agent,
        run_id=identity.run_id,
        expires_at=identity.expires_at,
        scopes=identity.scopes | tools,
        credential_id=identity.credential_id,
    )


def issue_identity(agent: str, *, run_id: str, ttl_seconds: int | None = None) -> AgentIdentity:
    """Mint a short-lived identity for one of AiSOC's own agents.

    Refuses an agent with no declared scope. See the module docstring for
    why that is a refusal and not a default in either direction.
    """
    scopes = AGENT_TOOL_SCOPES.get(agent)
    if scopes is None:
        raise ValueError(
            f"unknown agent {agent!r}: declare its tool scope in AGENT_TOOL_SCOPES. Known agents: {', '.join(sorted(AGENT_TOOL_SCOPES))}."
        )
    ttl = DEFAULT_TTL_SECONDS if ttl_seconds is None else ttl_seconds
    return AgentIdentity(agent=agent, run_id=run_id, expires_at=time.time() + ttl, scopes=scopes)