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.
Python agentic-aiai-securityalert-triageblue-teamcybersecuritydetection-engineeringincident-responselanggraphllm-agentsmcpmitre-attackmodel-context-protocolpurple-teamsecurity-operationsself-hostedsiemsoarsocthreat-detectionthreat-intelligence
feat(2.4): Session nodes and the assumed-role chain in the graph
Beenu Arora19ea830d53d2
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 84f8a2a4a..17a28469d 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -735,6 +735,15 @@ jobs:run: python3 scripts/check_activity_projection.py --self-test- name: Activity projection drift gaterun: python3 scripts/check_activity_projection.py+ # ADR-0010 accepted writing sessions to Postgres *and* to the graph on+ # the stated condition that one producer derives the key and the other+ # three only read it. A second deriver would agree today and disagree+ # after the next vendor-schema change, and the symptom is a session+ # count that drifts rather than anything failing.+ - name: Session projection gate — self-test+ run: python3 scripts/check_session_projection.py --self-test+ - name: Session projection gate+ run: python3 scripts/check_session_projection.py# The same shape one layer over: an inbox template that ships has to be# mintable, and a mintable id has to have a template to apply. Both# directions, because only one of them was ever checked informally anddiff --git a/services/api/clickhouse/001_init.sql b/services/api/clickhouse/001_init.sqlindex c55c7bda9..205dd8c90 100644--- a/services/api/clickhouse/001_init.sql+++ b/services/api/clickhouse/001_init.sql@@ -81,6 +81,19 @@ CREATE TABLE IF NOT EXISTS aisoc.raw_events (-- itself the finding.client_raw String DEFAULT '',outcome LowCardinality(String) DEFAULT '',++ -- Sessions per principal (depth plan 2.4). `session_id` is the same+ -- deterministic uuid the Postgres `sessions` row and the Neo4j Session+ -- node carry, so a hunt joins the three without any of them having+ -- coordinated at write time. `session_key_kind` is a column rather than a+ -- derivable detail: a query counting events per session means something+ -- different for a vendor session than for a grouping this product+ -- derived, and a hunter who cannot see which they have will mix them.+ session_id String DEFAULT '',+ session_key String DEFAULT '',+ session_key_kind LowCardinality(String) DEFAULT '',+ session_originating_human String DEFAULT '',+-- Data-skipping (bloom-filter) indexes so hunts over high-cardinality-- needles (file hash, user, host, IOCs) skip granules instead of scanning-- the whole ZSTD blob. GRANULARITY 4 = one index block per 4 * 8192 rows.@@ -90,7 +103,10 @@ CREATE TABLE IF NOT EXISTS aisoc.raw_events (INDEX idx_iocs iocs TYPE bloom_filter(0.01) GRANULARITY 4,INDEX idx_techniques mitre_techniques TYPE bloom_filter(0.01) GRANULARITY 4,INDEX idx_action action TYPE bloom_filter(0.01) GRANULARITY 4,- INDEX idx_resource_id resource_id TYPE bloom_filter(0.01) GRANULARITY 4+ INDEX idx_resource_id resource_id TYPE bloom_filter(0.01) GRANULARITY 4,+ -- The id is what a join uses; the key is high-cardinality free text+ -- read only after the id has already narrowed the scan.+ INDEX idx_session_id session_id TYPE bloom_filter(0.01) GRANULARITY 4)-- ReplacingMergeTree collapses rows sharing the ORDER BY key, keeping the row-- with the greatest ingest_time. Ingest now stamps a replay-stable event_iddiff --git a/services/ingest/internal/graph/extractor.go b/services/ingest/internal/graph/extractor.goindex 29ea51e97..0054c86f8 100644--- a/services/ingest/internal/graph/extractor.go+++ b/services/ingest/internal/graph/extractor.go@@ -91,6 +91,11 @@ func ExtractFromOCSF(eventID, tenantID, connectorType string, ocsf map[string]in// for one source.applyActivityProperties(ev, ocsf)+ // The session this event belongs to, and the assumed-role chain when the+ // event issued one. A post-pass for the same reason as the line above:+ // the session is a property of the event, not of the connector.+ applySessionGraph(ev, ocsf)+if len(ev.Nodes) == 0 && len(ev.Edges) == 0 {return nil}diff --git a/services/ingest/internal/graph/session.go b/services/ingest/internal/graph/session.gonew file mode 100644index 000000000..da7e47b8d--- /dev/null+++ b/services/ingest/internal/graph/session.go@@ -0,0 +1,185 @@+package graph++import (+ "strings"+ "time"+)++// The graph half of depth plan 2.4.+//+// Why this is a post-pass and not a line in each extractor+// ---------------------------------------------------------+// Same reason `applyActivityProperties` is: the session is a property of the+// event, not of the connector. Put it inside the five extractors and the+// sixth one somebody writes ships without it, and nobody notices until a+// traversal comes back missing sessions for one source.+//+// Why the graph is not the authority+// -----------------------------------+// ADR-0010. Neo4j measured 696.8 MiB resident for 20,000 sessions, which is+// 42.2% of what the CORE profile has left at the moment it is triaging an+// alert, so the authoritative session row is in Postgres and the graph keeps+// the nodes for `full`, where traversal is the point. The id below is the+// *same* deterministic uuid the Postgres row carries, computed from the same+// three parts by the fusion consumer and stamped onto the event before this+// runs — so the two stores agree without either waiting on the other.+//+// An event that reaches the graph without that stamp (a replay, or a+// deployment with the alert sink off) still gets a node keyed on the vendor's+// own value. That node is correct and joins to nothing, which is the honest+// outcome: the grouping is known and the row it would join to does not exist.++// applySessionGraph adds the Session node and its edges for one event.+//+// It reads `activity.session` and derives nothing. `session.go` in the+// activity package is the only producer of a session key; this is one of its+// three consumers, and `scripts/check_session_projection.py` fails the build+// if a second site starts deriving one.+func applySessionGraph(ev *Event, ocsf map[string]interface{}) {+ act, ok := ocsf["activity"].(map[string]interface{})+ if !ok {+ // The projection is a struct on the normalizer's own path and a map+ // once it has been through JSON. Both reach here depending on+ // whether the graph writer runs in-process or off the topic.+ act = structToMap(ocsf["activity"])+ if act == nil {+ return+ }+ }+ session := childMap(act, "session")+ if session == nil {+ return+ }++ key := strings.TrimSpace(asString(session["key"]))+ kind := strings.TrimSpace(asString(session["key_kind"]))+ if key == "" || kind == "" {+ // No vendor key and no derived one. An event with no session is a+ // real answer; inventing a node of one here would make "what else+ // did this session touch" answerable with a number that means+ // nothing.+ return+ }++ // The natural key is the vendor's own value namespaced by source, because+ // an Okta session id and a GitHub token hash share no namespace. The+ // Postgres uuid rides as a property rather than as the key: it is absent+ // on a replayed event, and a MERGE on an empty key would collapse every+ // such event onto one node.+ source := sessionSource(ocsf)+ natural := source + "|" + key++ props := map[string]interface{}{+ "session_key": key,+ "key_kind": kind,+ "source": source,+ // Written even when empty, for the same reason `actor_kind` is: a+ // Cypher `IS NULL` cannot tell "this deployment does not stamp ids"+ // from "this session has no row".+ "id": strings.TrimSpace(asString(session["id"])),+ "last_seen_at": ev.TS.UTC().Format(time.RFC3339),+ }+ if v := strings.TrimSpace(asString(session["key_source"])); v != "" {+ props["key_source"] = v+ }+ if v := strings.TrimSpace(asString(session["principal"])); v != "" {+ props["principal"] = v+ }+ if v := strings.TrimSpace(asString(session["originating_human"])); v != "" {+ props["originating_human"] = v+ }++ ev.Nodes = append(ev.Nodes, Node{+ Label: NodeSession,+ NaturalKey: natural,+ TenantID: ev.TenantID,+ Properties: props,+ })++ // Identity -> Session. Attached to whichever principal node the+ // extractors already produced rather than to a new one, so the session+ // hangs off the same account every other edge in this event does.+ for _, node := range ev.Nodes {+ if node.Label != NodeUser && node.Label != NodeServiceAccount && node.Label != NodeIdentity {+ continue+ }+ ev.Edges = append(ev.Edges, Edge{+ Type: RelOpenedSession,+ FromLabel: node.Label, FromKey: node.NaturalKey,+ ToLabel: NodeSession, ToKey: natural,+ Properties: map[string]interface{}{+ "ts": ev.TS.UTC().Format(time.RFC3339),+ "source_event_id": ev.EventID,+ "snapshot_id": ev.SnapshotID,+ },+ })+ break+ }++ // Session -> Session, the assumed-role chain. The edge exists on the+ // issuing STS call and nowhere else: the child's own events name only the+ // role it assumed, so once this record ages out of the lake the person+ // behind the second hop is unrecoverable. `link_source` records which+ // field established it, because a chain built from a caller-chosen+ // roleSessionName is weaker evidence than one built from sourceIdentity.+ issued := childMap(session, "issued")+ if issued == nil {+ return+ }+ childKey := strings.TrimSpace(asString(issued["key"]))+ if childKey == "" || childKey == key {+ return+ }+ childNatural := source + "|" + childKey++ childProps := map[string]interface{}{+ "session_key": childKey,+ // An issued credential is always the credential-that-is-the-session+ // kind; nothing else is handed out by an STS call.+ "key_kind": "vendor_credential",+ "source": source,+ }+ if v := strings.TrimSpace(asString(issued["key_source"])); v != "" {+ childProps["key_source"] = v+ }+ if v := strings.TrimSpace(asString(issued["principal"])); v != "" {+ childProps["principal"] = v+ }+ if v := strings.TrimSpace(asString(issued["originating_human"])); v != "" {+ childProps["originating_human"] = v+ }+ ev.Nodes = append(ev.Nodes, Node{+ Label: NodeSession,+ NaturalKey: childNatural,+ TenantID: ev.TenantID,+ Properties: childProps,+ })+ ev.Edges = append(ev.Edges, Edge{+ Type: RelIssuedSession,+ FromLabel: NodeSession, FromKey: natural,+ ToLabel: NodeSession, ToKey: childNatural,+ Properties: map[string]interface{}{+ "ts": ev.TS.UTC().Format(time.RFC3339),+ "source_event_id": ev.EventID,+ "snapshot_id": ev.SnapshotID,+ "link_source": strings.TrimSpace(asString(issued["originating_human_source"])),+ },+ })+}++// sessionSource names the product the session belongs to, matching what the+// fusion store uses so the two agree on the namespace half of the key.+func sessionSource(ocsf map[string]interface{}) string {+ if v := getString(ocsf, "metadata.product.name"); v != "" {+ return v+ }+ if v := getString(ocsf, "connector_type"); v != "" {+ return v+ }+ return "unknown"+}++func asString(value interface{}) string {+ s, _ := value.(string)+ return s+}diff --git a/services/ingest/internal/graph/session_test.go b/services/ingest/internal/graph/session_test.gonew file mode 100644index 000000000..6d24a7bdf--- /dev/null+++ b/services/ingest/internal/graph/session_test.go@@ -0,0 +1,195 @@+package graph++import "testing"++func ocsfWithSession(session map[string]interface{}, extra map[string]interface{}) map[string]interface{} {+ activity := map[string]interface{}{+ "actor": map[string]interface{}{"kind": "human", "id": "[email protected]"},+ }+ if session != nil {+ activity["session"] = session+ }+ ocsf := map[string]interface{}{+ "time": "2026-03-04T05:06:07Z",+ "metadata": map[string]interface{}{"product": map[string]interface{}{"name": "aws_cloudtrail"}},+ "activity": activity,+ }+ for k, v := range extra {+ ocsf[k] = v+ }+ return ocsf+}++func sessionNodes(ev *Event) []Node {+ var out []Node+ for _, n := range ev.Nodes {+ if n.Label == NodeSession {+ out = append(out, n)+ }+ }+ return out+}++func edgesOfType(ev *Event, t RelType) []Edge {+ var out []Edge+ for _, e := range ev.Edges {+ if e.Type == t {+ out = append(out, e)+ }+ }+ return out+}++func TestTheSessionNodeCarriesTheVendorsKeyAndItsStrength(t *testing.T) {+ ev := ExtractFromOCSF("evt-1", "tenant-1", "okta_system_log", ocsfWithSession(map[string]interface{}{+ "key": "102bFs0Aq6VQ1qjqVqk",+ "key_kind": "vendor_session",+ "key_source": "authenticationContext.externalSessionId",+ "id": "9ad0f0a1-0000-5000-8000-000000000001",+ "principal": "[email protected]",+ }, nil))+ if ev == nil {+ t.Fatal("no projection")+ }++ nodes := sessionNodes(ev)+ if len(nodes) != 1 {+ t.Fatalf("got %d session nodes, want 1", len(nodes))+ }+ node := nodes[0]+ if node.Properties["session_key"] != "102bFs0Aq6VQ1qjqVqk" {+ t.Fatalf("session_key: %v", node.Properties["session_key"])+ }+ if node.Properties["key_kind"] != "vendor_session" {+ t.Fatalf("key_kind must travel with the node, got %v", node.Properties["key_kind"])+ }+ if node.Properties["id"] != "9ad0f0a1-0000-5000-8000-000000000001" {+ t.Fatalf("the Postgres id must ride along so the two stores join: %v", node.Properties["id"])+ }+ if node.TenantID != "tenant-1" {+ t.Fatalf("tenant: %q", node.TenantID)+ }+}++// An event whose source names no session must produce no node. A session of+// one invented for every unattributable event makes "what else did this+// session touch" answerable with a number that means nothing.+func TestNoSessionBlockMeansNoSessionNode(t *testing.T) {+ ev := ExtractFromOCSF("evt-2", "tenant-1", "okta_system_log", ocsfWithSession(nil, nil))+ if ev != nil && len(sessionNodes(ev)) != 0 {+ t.Fatalf("invented %d session nodes from an event that has none", len(sessionNodes(ev)))+ }+}++func TestAnEmptyKeyIsNotMergedOntoOneNode(t *testing.T) {+ ev := ExtractFromOCSF("evt-3", "tenant-1", "okta_system_log", ocsfWithSession(map[string]interface{}{+ "key": "", "key_kind": "vendor_session",+ }, nil))+ if ev != nil && len(sessionNodes(ev)) != 0 {+ t.Fatal("an empty key produced a node; every such event would MERGE onto it")+ }+}++// The chain is the reason the session projection reaches into the AssumeRole+// response at all.+func TestTheIssuedSessionGetsItsOwnNodeAndTheChainEdge(t *testing.T) {+ ev := ExtractFromOCSF("evt-4", "tenant-1", "aws_security_hub", ocsfWithSession(map[string]interface{}{+ "key": "AKIAPARENT0000000EXM",+ "key_kind": "vendor_credential",+ "issued": map[string]interface{}{+ "key": "ASIACHILD0000000EXMP",+ "key_source": "responseElements.credentials.accessKeyId",+ "principal": "arn:aws:sts::1:assumed-role/Deploy/build-471",+ "originating_human": "[email protected]",+ "originating_human_source": "requestParameters.sourceIdentity",+ },+ }, nil))+ if ev == nil {+ t.Fatal("no projection")+ }++ if n := len(sessionNodes(ev)); n != 2 {+ t.Fatalf("got %d session nodes, want the caller's and the one it issued", n)+ }+ edges := edgesOfType(ev, RelIssuedSession)+ if len(edges) != 1 {+ t.Fatalf("got %d chain edges, want 1", len(edges))+ }+ if edges[0].FromKey != "aws_cloudtrail|AKIAPARENT0000000EXM" {+ t.Fatalf("chain starts at %q", edges[0].FromKey)+ }+ if edges[0].ToKey != "aws_cloudtrail|ASIACHILD0000000EXMP" {+ t.Fatalf("chain ends at %q", edges[0].ToKey)+ }+ // A chain built from a caller-chosen roleSessionName is weaker evidence+ // than one built from sourceIdentity, and the edge has to say which.+ if edges[0].Properties["link_source"] != "requestParameters.sourceIdentity" {+ t.Fatalf("link_source: %v", edges[0].Properties["link_source"])+ }++ var child Node+ for _, n := range sessionNodes(ev) {+ if n.NaturalKey == "aws_cloudtrail|ASIACHILD0000000EXMP" {+ child = n+ }+ }+ if child.Properties["originating_human"] != "[email protected]" {+ t.Fatalf("the person must land on the child, which is the only place it is knowable: %v", child.Properties)+ }+}++func TestACallThatIssuedItsOwnCredentialIsNotItsOwnParent(t *testing.T) {+ ev := ExtractFromOCSF("evt-5", "tenant-1", "aws_security_hub", ocsfWithSession(map[string]interface{}{+ "key": "ASIASAME00000000EXMP", "key_kind": "vendor_credential",+ "issued": map[string]interface{}{"key": "ASIASAME00000000EXMP"},+ }, nil))+ if ev == nil {+ t.Fatal("no projection")+ }+ if n := len(edgesOfType(ev, RelIssuedSession)); n != 0 {+ t.Fatalf("got %d self-edges, want 0", n)+ }+}++// The key is namespaced by source because an Okta session id and a GitHub+// token hash share no namespace, and a bare MERGE on the value alone would+// collide them.+func TestTheNaturalKeyIsNamespacedBySource(t *testing.T) {+ okta := ExtractFromOCSF("evt-6", "t", "okta_system_log", map[string]interface{}{+ "time": "2026-03-04T05:06:07Z",+ "metadata": map[string]interface{}{"product": map[string]interface{}{"name": "okta"}},+ "activity": map[string]interface{}{"session": map[string]interface{}{"key": "shared", "key_kind": "vendor_session"}},+ })+ github := ExtractFromOCSF("evt-7", "t", "github_audit", map[string]interface{}{+ "time": "2026-03-04T05:06:07Z",+ "metadata": map[string]interface{}{"product": map[string]interface{}{"name": "github"}},+ "activity": map[string]interface{}{"session": map[string]interface{}{"key": "shared", "key_kind": "vendor_credential"}},+ })+ if okta == nil || github == nil {+ t.Fatal("no projection")+ }+ if sessionNodes(okta)[0].NaturalKey == sessionNodes(github)[0].NaturalKey {+ t.Fatal("two sources sharing one identifier collided onto one node")+ }+}++// Every label and relationship this file emits has to be in the published+// vocabulary, or the schema-drift gate and the live database disagree.+func TestTheSessionVocabularyIsPublished(t *testing.T) {+ labels := map[NodeLabel]bool{}+ for _, l := range AllNodeLabels {+ labels[l] = true+ }+ if !labels[NodeSession] {+ t.Fatal("Session is not in AllNodeLabels")+ }+ rels := map[RelType]bool{}+ for _, r := range AllRelTypes {+ rels[r] = true+ }+ for _, r := range []RelType{RelOpenedSession, RelIssuedSession, RelSessionRaised} {+ if !rels[r] {+ t.Fatalf("%s is not in AllRelTypes", r)+ }+ }+}