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): derive a session key per event in the activity projection
Beenu Arora6031749dc2e6
diff --git a/services/ingest/internal/activity/activity.go b/services/ingest/internal/activity/activity.goindex b776ef752..abcf06966 100644--- a/services/ingest/internal/activity/activity.go+++ b/services/ingest/internal/activity/activity.go@@ -127,6 +127,11 @@ type Activity struct {Resource Resource `json:"resource,omitempty"`Location Location `json:"location,omitempty"`Outcome Outcome `json:"outcome"`+ // Session is which session this event belongs to and how strongly that+ // is known. See session.go: the grouping itself is stateful and happens+ // in fusion, but the key can only be read here, while the vendor record+ // still exists.+ Session Session `json:"session,omitempty"`}// Project builds the projection for one normalized event.@@ -150,6 +155,10 @@ func Project(connectorType string, payload, ocsf map[string]any) Activity {Outcome: deriveOutcome(payload, vendor, ocsf),}act.Location = deriveLocation(payload, vendor, ocsf)+ // Last: the derived session key falls back to the principal, the address+ // and the parsed client, so it needs the actor and the location already+ // filled.+ act.Session = deriveSession(connectorType, payload, vendor, &act)return act}diff --git a/services/ingest/internal/activity/session.go b/services/ingest/internal/activity/session.gonew file mode 100644index 000000000..3e7df41b3--- /dev/null+++ b/services/ingest/internal/activity/session.go@@ -0,0 +1,415 @@+package activity++import (+ "strings"+)++// Session identity, derived per event from the strongest key the source offers.+//+// What this file does and does not do+// -----------------------------------+// A session is a *stateful* object: it has a start, an end, a duration and a+// set of events. None of that can be decided while looking at one event, so+// none of it is decided here. This file answers the one question that is+// answerable per event and that no later stage can recover once the vendor+// record is gone: **which session does this event belong to, and how do we+// know**. Grouping, duration, idle expiry and the walk up an assumed-role+// chain are stateful and live in `services/fusion/app/services/sessions.py`.+//+// The key, not a guess+// --------------------+// Same rule as `actor.go`: read a field whose documented meaning is "the+// session (or the credential that is the session)" and report nothing+// otherwise. A session id invented from a user plus a timestamp would group+// events that have nothing to do with each other, and every surface that+// later says "what else did this session do" would be lying with a precise+// number.+//+// `KeyKind` is how strong the answer is, and it is carried to every consumer+// rather than flattened away:+//+// vendor_session the vendor names a session and this is its id+// vendor_credential the vendor names the credential, which *is* the session+// (an AWS temporary access key, a GitHub token hash)+// vendor_flow the vendor groups one sign-in flow but not a durable+// session, so events outside that flow will not join+// derived no vendor key: principal + address + client, which+// fusion closes on an idle gap+//+// References, each read before the derivation below was written:+//+// AWS CloudTrail userIdentity (accessKeyId, sessionContext, sourceIdentity)+// https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference-user-identity.html+// AWS STS AssumeRoleWithSAML / AssumeRoleWithWebIdentity response elements+// https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html+// https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html+// Okta System Log authenticationContext.externalSessionId+// https://developer.okta.com/docs/reference/api/system-log/+// Office 365 Management Activity API common schema, AppAccessContext+// https://learn.microsoft.com/en-us/office/office-365-management-api/office-365-management-activity-api-schema+// Microsoft Entra signIn resource (correlationId)+// https://learn.microsoft.com/en-us/graph/api/resources/signin+// Google Workspace Reports API activities (token application parameters)+// https://developers.google.com/workspace/admin/reports/v1/appendix/activity/token+// GitHub audit log hashed_token+// https://docs.github.com/en/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization++// SessionKeyKind is the closed set describing how a session key was obtained.+type SessionKeyKind string++const (+ // SessionVendorSession — the vendor's own session identifier.+ SessionVendorSession SessionKeyKind = "vendor_session"+ // SessionVendorCredential — the credential is the session. An AWS+ // temporary access key exists for exactly one assumed-role session, so+ // it identifies that session as precisely as a session id would.+ SessionVendorCredential SessionKeyKind = "vendor_credential"+ // SessionVendorFlow — the vendor correlates one sign-in flow and+ // nothing wider. Grouping on it is correct for the events of that flow+ // and will not pick up what the resulting session went on to do.+ SessionVendorFlow SessionKeyKind = "vendor_flow"+ // SessionDerived — no vendor key at all. Fusion closes these on an+ // idle gap; they are the weakest and are labelled so a surface can say+ // so rather than presenting them as the vendor's own grouping.+ SessionDerived SessionKeyKind = "derived"+)++// SessionKeyKinds is the closed set in strength order, strongest first. The+// gate and the lake enum read this rather than a second list.+var SessionKeyKinds = []SessionKeyKind{+ SessionVendorSession, SessionVendorCredential, SessionVendorFlow, SessionDerived,+}++// IssuedSession is a session this event *created*, as opposed to the one it+// belongs to.+//+// Only credential-issuing calls populate it, and today that means AWS STS.+// It is what makes an assumed-role chain reconstructable: the AssumeRole call+// is logged against the *calling* session and carries the new session's+// access key in its response, so this is the only place the edge between the+// two exists. Without it a chained session's originating human is+// unrecoverable, because the second hop's own events name only the role.+type IssuedSession struct {+ Key string `json:"key"`+ KeySource string `json:"key_source"`+ // Principal is the identity the new session acts as (the role ARN).+ Principal string `json:"principal,omitempty"`+ // OriginatingHuman is the person the new session is for, where the+ // issuing call named one. Empty is the honest answer when it did not.+ OriginatingHuman string `json:"originating_human,omitempty"`+ OriginatingHumanSource string `json:"originating_human_source,omitempty"`+}++// Session is the per-event session projection.+type Session struct {+ // Key is the raw value as the vendor spells it, not a hash. Fusion+ // namespaces it by tenant and source when it mints a session id; keeping+ // the vendor's own value here is what lets an analyst paste it into the+ // vendor's console.+ Key string `json:"key,omitempty"`+ KeyKind SessionKeyKind `json:"key_kind,omitempty"`+ // KeySource names the vendor field the key was read from, so a reviewer+ // can check the derivation against the vendor's documentation without+ // re-reading this package.+ KeySource string `json:"key_source,omitempty"`+ // Principal is the identity the session acts as.+ Principal string `json:"principal,omitempty"`+ // OriginatingHuman is the person behind the session when *this event*+ // names one. A chained session names nobody on its own events; fusion+ // resolves those by walking Issued edges.+ OriginatingHuman string `json:"originating_human,omitempty"`+ OriginatingHumanSource string `json:"originating_human_source,omitempty"`+ // Issued is set only on a credential-issuing call. See IssuedSession.+ Issued *IssuedSession `json:"issued,omitempty"`+}++// deriveSession fills the session block for one event.+func deriveSession(connectorType string, payload, vendor map[string]any, act *Activity) Session {+ var s Session+ switch connectorType {+ case "aws_cloudtrail", "aws_cloudtrail_s3":+ s = cloudTrailSession(vendor)+ case "okta", "okta_system_log":+ s = oktaSession(vendor)+ case "m365_audit":+ s = m365Session(vendor)+ case "azure_entra":+ s = entraSession(vendor)+ case "google_workspace":+ s = workspaceSession(vendor)+ case "github":+ s = githubSession(vendor)+ }++ if s.Principal == "" {+ s.Principal = firstNonEmpty(act.Actor.ID, act.Actor.Email, act.Actor.Name)+ }+ if s.OriginatingHuman == "" && act.Actor.OnBehalfOf != "" {+ s.OriginatingHuman = act.Actor.OnBehalfOf+ s.OriginatingHumanSource = "activity.actor.on_behalf_of"+ }+ // An actor the source called a person is their own originating human.+ // Stated rather than left empty so a human session and an unattributed+ // one are different rows rather than both being blank.+ if s.OriginatingHuman == "" && act.Actor.Kind == ActorHuman && s.Principal != "" {+ s.OriginatingHuman = s.Principal+ s.OriginatingHumanSource = "activity.actor.kind=human"+ }++ if s.Key == "" {+ s.Key, s.KeySource = derivedSessionKey(s.Principal, act)+ if s.Key != "" {+ s.KeyKind = SessionDerived+ }+ }+ return s+}++// cloudTrailSession reads the temporary access key, which identifies exactly+// one assumed-role session, and the STS response elements that name the+// session this call issued.+//+// A long-lived IAM user key (AKIA…) is also returned: it is still the+// credential the request was signed with, and grouping an IAM user's calls by+// the key they used is the question an analyst asks after a key leaks. What+// it is *not* is a login session, which is why the kind is `vendor_credential`+// and not `vendor_session`.+// The issued session is read *before* the caller's own identity and+// independently of it. The federated AssumeRole calls — `AssumeRoleWithSAML`+// and `AssumeRoleWithWebIdentity` — carry no `userIdentity` at all, because+// the caller is not yet an AWS principal when they make the request. An early+// return on a missing identity therefore drops the chain edge on exactly the+// two calls where the person is named and nowhere else, leaving every+// subsequent event of that session attributable only to a role.+func cloudTrailSession(vendor map[string]any) Session {+ var s Session+ if issued := cloudTrailIssued(vendor); issued != nil {+ s.Issued = issued+ }++ identity, _ := nested(vendor, "userIdentity").(map[string]any)+ if identity == nil {+ return s+ }+ s.Principal = firstStr(identity, []string{"arn"}, []string{"principalId"})+ if key := str(identity, "accessKeyId"); key != "" {+ s.Key, s.KeyKind, s.KeySource = key, SessionVendorCredential, "userIdentity.accessKeyId"+ }++ // sourceIdentity is AWS's documented mechanism for carrying the+ // originating principal across a role assumption, and it is the only+ // CloudTrail field that means that. It is set on the identity itself and,+ // on some event versions, inside sessionContext.+ if who := firstStr(identity,+ []string{"sourceIdentity"},+ []string{"sessionContext", "sourceIdentity"},+ ); who != "" {+ s.OriginatingHuman = who+ s.OriginatingHumanSource = "userIdentity.sourceIdentity"+ }+ return s+}++// cloudTrailIssued reads the session an STS call created.+//+// The `credentials.accessKeyId` under responseElements is the new session's+// key. The originating human comes from whichever of the three documented+// federation shapes the call used, and from `sourceIdentity` when the caller+// set one — never from the role name, which names the role and not a person.+func cloudTrailIssued(vendor map[string]any) *IssuedSession {+ eventName := str(vendor, "eventName")+ if !strings.HasPrefix(eventName, "AssumeRole") && eventName != "GetFederationToken" && eventName != "GetSessionToken" {+ return nil+ }+ resp, _ := nested(vendor, "responseElements").(map[string]any)+ if resp == nil {+ return nil+ }+ key := firstStr(resp,+ []string{"credentials", "accessKeyId"},+ []string{"Credentials", "AccessKeyId"},+ )+ if key == "" {+ return nil+ }+ issued := &IssuedSession{+ Key: key,+ KeySource: "responseElements.credentials.accessKeyId",+ Principal: firstStr(resp,+ []string{"assumedRoleUser", "arn"},+ []string{"federatedUser", "arn"},+ ),+ }++ req, _ := nested(vendor, "requestParameters").(map[string]any)+ if req == nil {+ req = map[string]any{}+ }+ switch {+ case str(req, "sourceIdentity") != "":+ // Explicitly set by the caller and carried by AWS on every+ // subsequent event of the new session.+ issued.OriginatingHuman = str(req, "sourceIdentity")+ issued.OriginatingHumanSource = "requestParameters.sourceIdentity"+ case str(resp, "subject") != "":+ // AssumeRoleWithSAML: the SAML NameID, which is the person the+ // identity provider authenticated.+ issued.OriginatingHuman = str(resp, "subject")+ issued.OriginatingHumanSource = "responseElements.subject"+ case str(resp, "subjectFromWebIdentityToken") != "":+ issued.OriginatingHuman = str(resp, "subjectFromWebIdentityToken")+ issued.OriginatingHumanSource = "responseElements.subjectFromWebIdentityToken"+ case str(req, "roleSessionName") != "":+ // Weakest of the four and labelled as what it is. The session name+ // is caller-chosen free text; in an IAM Identity Center estate it is+ // reliably the signed-in user's name, and elsewhere it can be+ // anything. Carried because an analyst reading it knows which it is,+ // and dropped into its own source string so nothing downstream can+ // mistake it for an authenticated identity.+ issued.OriginatingHuman = str(req, "roleSessionName")+ issued.OriginatingHumanSource = "requestParameters.roleSessionName"+ }+ return issued+}++// oktaSession reads `authenticationContext.externalSessionId`.+//+// Okta writes the literal string "unknown" on events with no session rather+// than omitting the field, so that value is treated as absent. Reading it as+// a key would collapse every session-less event in the tenant into one+// enormous session called "unknown".+func oktaSession(vendor map[string]any) Session {+ s := Session{Principal: firstStr(vendor,+ []string{"actor", "alternateId"},+ []string{"actor", "id"},+ )}+ id := str(vendor, "authenticationContext", "externalSessionId")+ if id != "" && id != "unknown" {+ s.Key, s.KeyKind, s.KeySource = id, SessionVendorSession, "authenticationContext.externalSessionId"+ }+ return s+}++// m365Session reads `AppAccessContext.AADSessionId`, the Entra session the+// token was issued for, and falls back to a record-level `SessionId` on the+// schemas that carry one.+func m365Session(vendor map[string]any) Session {+ s := Session{Principal: str(vendor, "UserId")}+ if id := str(vendor, "AppAccessContext", "AADSessionId"); id != "" {+ s.Key, s.KeyKind, s.KeySource = id, SessionVendorSession, "AppAccessContext.AADSessionId"+ return s+ }+ if id := str(vendor, "SessionId"); id != "" {+ s.Key, s.KeyKind, s.KeySource = id, SessionVendorSession, "SessionId"+ }+ return s+}++// entraSession reads `correlationId`.+//+// This is deliberately `vendor_flow` and not `vendor_session`. Microsoft+// documents correlationId as the identifier sent by the client when a sign-in+// is initiated; it groups the operations of one sign-in flow and says nothing+// about the session that flow produced. The v1.0 signIn resource exposes no+// session identifier at all, so there is no stronger field to read, and+// labelling this as a session would promise a grouping Entra does not give.+// M365 audit records *do* carry the Entra session id (AADSessionId above),+// which is where a durable Entra session is reconstructable from.+func entraSession(vendor map[string]any) Session {+ s := Session{Principal: firstStr(vendor,+ []string{"userPrincipalName"},+ []string{"initiatedBy", "user", "userPrincipalName"},+ []string{"userId"},+ )}+ if id := str(vendor, "correlationId"); id != "" {+ s.Key, s.KeyKind, s.KeySource = id, SessionVendorFlow, "correlationId"+ }+ return s+}++// workspaceSession reads the OAuth client id from a token-application+// activity.+//+// The Reports API publishes no session identifier on any application. What it+// does publish, on the `token` application, is the `client_id` of the+// application acting — which is the "token id" half of the plan's wording and+// the thing worth grouping on, because an OAuth app's reads are one campaign+// whoever authorised them. Everything else on Workspace falls to the derived+// key, which is the honest answer rather than a fabricated one.+func workspaceSession(vendor map[string]any) Session {+ s := Session{Principal: str(vendor, "actor", "email")}+ if id := workspaceParam(vendor, "client_id"); id != "" {+ s.Key, s.KeyKind, s.KeySource = id, SessionVendorCredential, "events[].parameters[client_id]"+ }+ return s+}++// workspaceParam reads a named parameter out of the Reports API's+// `events[].parameters[]` list of `{name, value}` objects.+func workspaceParam(vendor map[string]any, name string) string {+ events, ok := nested(vendor, "events").([]any)+ if !ok {+ return ""+ }+ for _, raw := range events {+ event, ok := raw.(map[string]any)+ if !ok {+ continue+ }+ params, ok := event["parameters"].([]any)+ if !ok {+ continue+ }+ for _, rawParam := range params {+ param, ok := rawParam.(map[string]any)+ if !ok {+ continue+ }+ if str(param, "name") == name {+ if v := str(param, "value"); v != "" {+ return v+ }+ }+ }+ }+ return ""+}++// githubSession reads `hashed_token`, the SHA-256 of the credential the call+// was made with. GitHub audit entries carry no session identifier; the token+// hash is the credential and groups one token's activity, which is the+// question asked after a token leaks.+func githubSession(vendor map[string]any) Session {+ s := Session{Principal: str(vendor, "actor")}+ if id := str(vendor, "hashed_token"); id != "" {+ s.Key, s.KeyKind, s.KeySource = id, SessionVendorCredential, "hashed_token"+ }+ return s+}++// derivedSessionKey is the fallback the plan names: principal plus address+// plus client, which fusion then closes on an idle gap.+//+// All three parts are required. Two events share a derived session only when+// the same principal acted from the same address with the same client, which+// is the weakest grouping that is still a grouping — principal plus address+// alone would merge a browser session and a CLI run from one office, and+// address alone would merge every user behind one NAT gateway into a single+// session.+func derivedSessionKey(principal string, act *Activity) (string, string) {+ ip := act.Location.IP+ client := act.Location.Client.Raw+ if principal == "" || ip == "" || client == "" {+ return "", ""+ }+ return strings.Join([]string{principal, ip, client}, "|"), "principal+ip+user_agent"+}++func firstNonEmpty(values ...string) string {+ for _, v := range values {+ if v = strings.TrimSpace(v); v != "" {+ return v+ }+ }+ return ""+}diff --git a/services/ingest/internal/activity/session_test.go b/services/ingest/internal/activity/session_test.gonew file mode 100644index 000000000..19a0655b5--- /dev/null+++ b/services/ingest/internal/activity/session_test.go@@ -0,0 +1,385 @@+package activity++import (+ "strings"+ "testing"+)++// Same rule as activity_test.go: every fixture is a transcription of the+// documented vendor schema named in session.go, not an invention. A fixture+// that put `externalSessionId` somewhere Okta does not would make this suite+// agree with itself forever while the derivation read nothing in production.++func TestSessionKeyComesFromTheVendorsOwnField(t *testing.T) {+ cases := []struct {+ name string+ connector string+ vendor map[string]any+ wantKey string+ wantKind SessionKeyKind+ wantSource string+ }{+ {+ name: "CloudTrail temporary credentials are the session",+ connector: "aws_cloudtrail",+ vendor: map[string]any{+ "eventName": "GetObject",+ "userIdentity": map[string]any{+ "type": "AssumedRole",+ "arn": "arn:aws:sts::123456789012:assumed-role/Deploy/i-0abc",+ "accessKeyId": "ASIAIOSFODNN7EXAMPLE",+ },+ },+ wantKey: "ASIAIOSFODNN7EXAMPLE",+ wantKind: SessionVendorCredential,+ wantSource: "userIdentity.accessKeyId",+ },+ {+ name: "Okta names a session",+ connector: "okta",+ vendor: map[string]any{+ "actor": map[string]any{"alternateId": "[email protected]", "type": "User"},+ "authenticationContext": map[string]any{"externalSessionId": "102bFs0Aq6VQ1qjqVqk"},+ },+ wantKey: "102bFs0Aq6VQ1qjqVqk",+ wantKind: SessionVendorSession,+ wantSource: "authenticationContext.externalSessionId",+ },+ {+ name: "M365 carries the Entra session the token was issued for",+ connector: "m365_audit",+ vendor: map[string]any{+ "UserId": "[email protected]",+ "AppAccessContext": map[string]any{"AADSessionId": "c0ffee00-1111-2222-3333-444455556666"},+ },+ wantKey: "c0ffee00-1111-2222-3333-444455556666",+ wantKind: SessionVendorSession,+ wantSource: "AppAccessContext.AADSessionId",+ },+ {+ name: "Entra correlates a sign-in flow, which is not a session",+ connector: "azure_entra",+ vendor: map[string]any{+ "userPrincipalName": "[email protected]",+ "correlationId": "9f8e7d6c-5b4a-3210-fedc-ba9876543210",+ },+ wantKey: "9f8e7d6c-5b4a-3210-fedc-ba9876543210",+ wantKind: SessionVendorFlow,+ wantSource: "correlationId",+ },+ {+ name: "Workspace groups an OAuth application's activity by its client id",+ connector: "google_workspace",+ vendor: map[string]any{+ "actor": map[string]any{"email": "[email protected]"},+ "events": []any{map[string]any{+ "type": "token",+ "name": "authorize",+ "parameters": []any{+ map[string]any{"name": "app_name", "value": "Some App"},+ map[string]any{"name": "client_id", "value": "1234567890.apps.googleusercontent.com"},+ },+ }},+ },+ wantKey: "1234567890.apps.googleusercontent.com",+ wantKind: SessionVendorCredential,+ wantSource: "events[].parameters[client_id]",+ },+ {+ name: "GitHub has no session, so the token is the grouping",+ connector: "github",+ vendor: map[string]any{+ "actor": "alice",+ "action": "repo.destroy",+ "hashed_token": "ZWFzdGVyLWVnZw==",+ },+ wantKey: "ZWFzdGVyLWVnZw==",+ wantKind: SessionVendorCredential,+ wantSource: "hashed_token",+ },+ }++ for _, tc := range cases {+ t.Run(tc.name, func(t *testing.T) {+ got := Project(tc.connector, canonical(tc.connector, tc.vendor), nil).Session+ if got.Key != tc.wantKey {+ t.Fatalf("key: got %q, want %q", got.Key, tc.wantKey)+ }+ if got.KeyKind != tc.wantKind {+ t.Fatalf("kind: got %q, want %q", got.KeyKind, tc.wantKind)+ }+ if got.KeySource != tc.wantSource {+ t.Fatalf("source: got %q, want %q", got.KeySource, tc.wantSource)+ }+ })+ }+}++// The negative control for the whole file. Each case removes exactly the+// field the matching positive case above reads, and asserts the derivation+// reports no vendor key rather than inventing one.+func TestNoVendorFieldMeansNoVendorKey(t *testing.T) {+ cases := []struct {+ name string+ connector string+ vendor map[string]any+ }{+ {+ name: "CloudTrail without an access key",+ connector: "aws_cloudtrail",+ vendor: map[string]any{+ "eventName": "GetObject",+ "userIdentity": map[string]any{"type": "AssumedRole", "arn": "arn:aws:sts::1:assumed-role/R/s"},+ },+ },+ {+ // Okta writes the literal "unknown" rather than omitting the+ // field. Reading it would collapse every session-less event in+ // the tenant into one enormous session called "unknown".+ name: "Okta writes the literal unknown",+ connector: "okta",+ vendor: map[string]any{+ "actor": map[string]any{"alternateId": "[email protected]"},+ "authenticationContext": map[string]any{"externalSessionId": "unknown"},+ },+ },+ {+ name: "M365 without an app access context",+ connector: "m365_audit",+ vendor: map[string]any{"UserId": "[email protected]", "Operation": "FileAccessed"},+ },+ {+ name: "Entra without a correlation id",+ connector: "azure_entra",+ vendor: map[string]any{"userPrincipalName": "[email protected]"},+ },+ {+ name: "Workspace activity that is not a token application",+ connector: "google_workspace",+ vendor: map[string]any{+ "actor": map[string]any{"email": "[email protected]"},+ "events": []any{map[string]any{+ "type": "login",+ "name": "login_success",+ "parameters": []any{map[string]any{"name": "login_type", "value": "google_password"}},+ }},+ },+ },+ {+ name: "GitHub without a hashed token",+ connector: "github",+ vendor: map[string]any{"actor": "alice", "action": "repo.destroy"},+ },+ }++ for _, tc := range cases {+ t.Run(tc.name, func(t *testing.T) {+ got := Project(tc.connector, canonical(tc.connector, tc.vendor), nil).Session+ if got.KeyKind != "" && got.KeyKind != SessionDerived {+ t.Fatalf("invented a %s key %q from a record that carries none", got.KeyKind, got.Key)+ }+ })+ }+}++// The chain is the reason this projection exists. A second-hop session's own+// events name only the role it assumed; the edge back to the person lives on+// the AssumeRole call alone, and is unrecoverable once that record is gone.+func TestAssumeRoleRecordsTheSessionItIssued(t *testing.T) {+ cases := []struct {+ name string+ vendor map[string]any+ wantKey string+ wantWho string+ wantSource string+ }{+ {+ name: "sourceIdentity is the strongest, and AWS carries it onward itself",+ vendor: map[string]any{+ "eventName": "AssumeRole",+ "userIdentity": map[string]any{"arn": "arn:aws:iam::123456789012:user/ci"},+ "requestParameters": map[string]any{"roleSessionName": "build-471", "sourceIdentity": "[email protected]"},+ "responseElements": map[string]any{+ "credentials": map[string]any{"accessKeyId": "ASIACHILD0000000EXMP"},+ "assumedRoleUser": map[string]any{"arn": "arn:aws:sts::123456789012:assumed-role/Deploy/build-471"},+ },+ },+ wantKey: "ASIACHILD0000000EXMP",+ wantWho: "[email protected]",+ wantSource: "requestParameters.sourceIdentity",+ },+ {+ name: "AssumeRoleWithSAML names the person the IdP authenticated",+ vendor: map[string]any{+ "eventName": "AssumeRoleWithSAML",+ "requestParameters": map[string]any{"roleSessionName": "alice"},+ "responseElements": map[string]any{+ "credentials": map[string]any{"accessKeyId": "ASIASAML00000000EXMP"},+ "subject": "[email protected]",+ "assumedRoleUser": map[string]any{"arn": "arn:aws:sts::1:assumed-role/Admin/alice"},+ },+ },+ wantKey: "ASIASAML00000000EXMP",+ wantWho: "[email protected]",+ wantSource: "responseElements.subject",+ },+ {+ name: "AssumeRoleWithWebIdentity names the token subject",+ vendor: map[string]any{+ "eventName": "AssumeRoleWithWebIdentity",+ "responseElements": map[string]any{+ "credentials": map[string]any{"accessKeyId": "ASIAOIDC00000000EXMP"},+ "subjectFromWebIdentityToken": "repo:acme/app:ref:refs/heads/main",+ },+ },+ wantKey: "ASIAOIDC00000000EXMP",+ wantWho: "repo:acme/app:ref:refs/heads/main",+ wantSource: "responseElements.subjectFromWebIdentityToken",+ },+ {+ // Caller-chosen free text. Carried because an analyst reading it+ // knows which estate they are in, and kept in its own source+ // string so nothing downstream mistakes it for an authenticated+ // identity.+ name: "roleSessionName is the weakest and says so",+ vendor: map[string]any{+ "eventName": "AssumeRole",+ "requestParameters": map[string]any{"roleSessionName": "[email protected]"},+ "responseElements": map[string]any{+ "credentials": map[string]any{"accessKeyId": "ASIANAME00000000EXMP"},+ },+ },+ wantKey: "ASIANAME00000000EXMP",+ wantWho: "[email protected]",+ wantSource: "requestParameters.roleSessionName",+ },+ }++ for _, tc := range cases {+ t.Run(tc.name, func(t *testing.T) {+ got := Project("aws_cloudtrail", canonical("aws_cloudtrail", tc.vendor), nil).Session+ if got.Issued == nil {+ t.Fatal("no issued session recorded, so the chain to the person is lost")+ }+ if got.Issued.Key != tc.wantKey {+ t.Fatalf("issued key: got %q, want %q", got.Issued.Key, tc.wantKey)+ }+ if got.Issued.OriginatingHuman != tc.wantWho {+ t.Fatalf("originating human: got %q, want %q", got.Issued.OriginatingHuman, tc.wantWho)+ }+ if got.Issued.OriginatingHumanSource != tc.wantSource {+ t.Fatalf("source: got %q, want %q", got.Issued.OriginatingHumanSource, tc.wantSource)+ }+ })+ }+}++// A call that issues no credential must record no issued session, or every+// consumer walking the chain gains an edge that does not exist.+func TestOnlyCredentialIssuingCallsRecordAnIssuedSession(t *testing.T) {+ for _, eventName := range []string{"GetObject", "ConsoleLogin", "DeleteBucket", "GetCallerIdentity"} {+ t.Run(eventName, func(t *testing.T) {+ got := Project("aws_cloudtrail", canonical("aws_cloudtrail", map[string]any{+ "eventName": eventName,+ "userIdentity": map[string]any{"arn": "arn:aws:iam::1:user/alice", "accessKeyId": "AKIA0000000000000EXM"},+ "responseElements": map[string]any{"credentials": map[string]any{"accessKeyId": "ASIANOTREAL00000EXMP"}},+ }), nil).Session+ if got.Issued != nil {+ t.Fatalf("%s is not a credential-issuing call but recorded an issued session", eventName)+ }+ })+ }+}++// An AssumeRole whose caller set nothing identifying must leave the person+// empty. The role name is a role, not a human, and reading it as one would+// attribute a machine's actions to an invented person.+func TestAnAnonymousAssumeRoleNamesNobody(t *testing.T) {+ got := Project("aws_cloudtrail", canonical("aws_cloudtrail", map[string]any{+ "eventName": "AssumeRole",+ "responseElements": map[string]any{+ "credentials": map[string]any{"accessKeyId": "ASIAANON00000000EXMP"},+ "assumedRoleUser": map[string]any{"arn": "arn:aws:sts::1:assumed-role/Batch/nightly"},+ },+ }), nil).Session+ if got.Issued == nil {+ t.Fatal("the issued session itself should still be recorded")+ }+ if got.Issued.OriginatingHuman != "" {+ t.Fatalf("named %q as the originating human from a record that names nobody", got.Issued.OriginatingHuman)+ }+}++// The plan's fallback: principal plus address plus client. All three are+// required, because two of them is a grouping that merges unrelated work.+func TestTheDerivedKeyNeedsAllThreeParts(t *testing.T) {+ // The address reaches the projection through the OCSF event rather than+ // the vendor record, because the normalizer's identity aliases have+ // already resolved the four spellings these sources use.+ ocsf := map[string]any{"src_endpoint": map[string]any{"ip": "203.0.113.10"}}+ full := map[string]any{+ "actor": map[string]any{"alternateId": "[email protected]", "type": "User"},+ "client": map[string]any{"userAgent": map[string]any{"rawUserAgent": "Mozilla/5.0"}},+ "outcome": map[string]any{"result": "SUCCESS"},+ "eventType": "policy.lifecycle.update",+ "displayMessage": "Update policy",+ }+ got := Project("okta", canonical("okta", full), ocsf).Session+ if got.KeyKind != SessionDerived {+ t.Fatalf("kind: got %q, want %q", got.KeyKind, SessionDerived)+ }+ if n := len(strings.Split(got.Key, "|")); n != 3 {+ t.Fatalf("derived key %q has %d parts, want 3", got.Key, n)+ }+ if got.KeySource != "principal+ip+user_agent" {+ t.Fatalf("source: got %q", got.KeySource)+ }++ // Negative control: drop the user agent and the key must disappear+ // entirely rather than degrade to principal+ip, which would merge a+ // browser session and a CLI run from one office.+ withoutClient := map[string]any{+ "actor": map[string]any{"alternateId": "[email protected]", "type": "User"},+ "outcome": map[string]any{"result": "SUCCESS"},+ }+ if got := Project("okta", canonical("okta", withoutClient), ocsf).Session; got.Key != "" {+ t.Fatalf("derived a key %q from two parts", got.Key)+ }+}++// Every kind a derivation can emit has to be in the closed set, or the lake+// enum and the gate are describing a vocabulary the producer does not use.+func TestEverySessionKindIsInTheClosedSet(t *testing.T) {+ allowed := map[SessionKeyKind]bool{}+ for _, k := range SessionKeyKinds {+ allowed[k] = true+ }+ vendors := map[string]map[string]any{+ "aws_cloudtrail": {"userIdentity": map[string]any{"accessKeyId": "ASIA0000000000000EXM"}},+ "okta": {"authenticationContext": map[string]any{"externalSessionId": "s1"}},+ "m365_audit": {"AppAccessContext": map[string]any{"AADSessionId": "s2"}},+ "azure_entra": {"correlationId": "s3"},+ "google_workspace": {"events": []any{map[string]any{"parameters": []any{map[string]any{"name": "client_id", "value": "s4"}}}}},+ "github": {"hashed_token": "s5"},+ }+ for connector, vendor := range vendors {+ got := Project(connector, canonical(connector, vendor), nil).Session+ if got.KeyKind != "" && !allowed[got.KeyKind] {+ t.Fatalf("%s emitted kind %q, which is outside the closed set", connector, got.KeyKind)+ }+ }+}++// The key is kept as the vendor spells it so an analyst can paste it into+// the vendor's own console. A hash here would be a value that exists nowhere+// else and cannot be looked up anywhere.+func TestTheKeyIsTheVendorsOwnValue(t *testing.T) {+ const raw = "102bFs0Aq6VQ1qjqVqk"+ got := Project("okta", canonical("okta", map[string]any{+ "actor": map[string]any{"alternateId": "[email protected]"},+ "authenticationContext": map[string]any{"externalSessionId": raw},+ }), nil).Session+ if got.Key != raw {+ t.Fatalf("key %q is not the vendor's own value %q", got.Key, raw)+ }+}