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.

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.yml
index 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 gate
run: 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 and
diff --git a/services/api/clickhouse/001_init.sql b/services/api/clickhouse/001_init.sql
index 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_id
diff --git a/services/ingest/internal/graph/extractor.go b/services/ingest/internal/graph/extractor.go
index 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.go
new file mode 100644
index 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.go
new file mode 100644
index 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)
+ }
+ }
+}