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): 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.go
index 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.go
new file mode 100644
index 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.go
new file mode 100644
index 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)
+ }
+}