@cclabsnz/sf-audit 1.7.0 → 1.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +162 -0
- package/lib/checks/impl/NamedCredentialsCheck.js +6 -3
- package/lib/commands/audit/timeline.d.ts +26 -0
- package/lib/commands/audit/timeline.js +189 -0
- package/lib/lib/apexRefs.d.ts +2 -0
- package/lib/lib/apexRefs.js +30 -0
- package/lib/timeline/CaptureIndex.d.ts +34 -0
- package/lib/timeline/CaptureIndex.js +82 -0
- package/lib/timeline/CardinalityIndex.d.ts +28 -0
- package/lib/timeline/CardinalityIndex.js +47 -0
- package/lib/timeline/CorrelationEngine.d.ts +65 -0
- package/lib/timeline/CorrelationEngine.js +0 -0
- package/lib/timeline/EventRow.d.ts +69 -0
- package/lib/timeline/EventRow.js +14 -0
- package/lib/timeline/JoinKeys.d.ts +50 -0
- package/lib/timeline/JoinKeys.js +63 -0
- package/lib/timeline/loadCaptures.d.ts +87 -0
- package/lib/timeline/loadCaptures.js +424 -0
- package/lib/timeline/normalise.d.ts +26 -0
- package/lib/timeline/normalise.js +161 -0
- package/lib/timeline/parseWindow.d.ts +29 -0
- package/lib/timeline/parseWindow.js +133 -0
- package/lib/timeline/render.d.ts +33 -0
- package/lib/timeline/render.js +120 -0
- package/package.json +4 -4
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
import { type JoinKeyType } from './JoinKeys.js';
|
|
2
|
+
/** Where a seed value enters the search. */
|
|
3
|
+
export interface Seed {
|
|
4
|
+
type: JoinKeyType;
|
|
5
|
+
value: string;
|
|
6
|
+
}
|
|
7
|
+
/**
|
|
8
|
+
* Why a row is in the timeline: the seed matched it, a key tied it in, or no seed was given and
|
|
9
|
+
* the whole window was returned.
|
|
10
|
+
*/
|
|
11
|
+
export type Attribution = 'seed' | 'window' | JoinKeyType;
|
|
12
|
+
export interface CorrelatedRow {
|
|
13
|
+
row: Record<string, unknown>;
|
|
14
|
+
attribution: Attribution;
|
|
15
|
+
}
|
|
16
|
+
/** An expansion the engine declined, and the evidence for declining it. */
|
|
17
|
+
export interface Refusal {
|
|
18
|
+
type: JoinKeyType;
|
|
19
|
+
value: string;
|
|
20
|
+
cardinality: number;
|
|
21
|
+
threshold: number;
|
|
22
|
+
}
|
|
23
|
+
export interface CorrelateOptions {
|
|
24
|
+
/** Distinct-actor ceiling above which a key is not expanded. Default 8. */
|
|
25
|
+
maxCardinality?: number;
|
|
26
|
+
/** Expand regardless of cardinality. Off by default; the result reports the consequence. */
|
|
27
|
+
allowSharedIdentity?: boolean;
|
|
28
|
+
}
|
|
29
|
+
export interface CorrelationResult {
|
|
30
|
+
rows: CorrelatedRow[];
|
|
31
|
+
refusals: Refusal[];
|
|
32
|
+
/** Key values actually expanded through, in visit order — the provenance of the result. */
|
|
33
|
+
expandedThrough: Array<{
|
|
34
|
+
type: JoinKeyType;
|
|
35
|
+
value: string;
|
|
36
|
+
}>;
|
|
37
|
+
}
|
|
38
|
+
/**
|
|
39
|
+
* A judgement call from one incident, recorded rather than buried: a request id was 1:1, and a
|
|
40
|
+
* shared community identity was 1:1371. Eight sits far above the former and far below the
|
|
41
|
+
* latter. Worth revisiting against a second dataset.
|
|
42
|
+
*/
|
|
43
|
+
export declare const DEFAULT_MAX_CARDINALITY = 8;
|
|
44
|
+
/**
|
|
45
|
+
* Expand from seed values to every row belonging to the same actor.
|
|
46
|
+
*
|
|
47
|
+
* Salesforce splits one actor's activity across event types that share no common identifier.
|
|
48
|
+
* Some carry a client address, some carry only a request id, and one carries the address column
|
|
49
|
+
* but leaves it empty. Filtering on any single field finds a fraction of the activity, so the
|
|
50
|
+
* search has to walk between keys — and walking between keys is exactly where correlation
|
|
51
|
+
* invents relationships that are not there.
|
|
52
|
+
*
|
|
53
|
+
* Two guards keep it honest, and neither lives here by accident:
|
|
54
|
+
*
|
|
55
|
+
* Blank values cannot reach the frontier because {@link joinKeysOf} never yields one. A blank
|
|
56
|
+
* admitted as a key matches every other row whose value is also blank, which is how a two-row
|
|
57
|
+
* answer became a twenty-five-row one during the original hand reconstruction.
|
|
58
|
+
*
|
|
59
|
+
* Shared identities are refused by cardinality. A key standing for many actors is not an
|
|
60
|
+
* identifier, and expanding through it presents a crowd's activity as one actor's. Refusals are
|
|
61
|
+
* returned rather than applied quietly: a bounded timeline that does not say it was bounded is
|
|
62
|
+
* as misleading as an over-attributed one.
|
|
63
|
+
*/
|
|
64
|
+
export declare function correlate(rows: ReadonlyArray<Record<string, unknown>>, seeds: ReadonlyArray<Seed>, options: CorrelateOptions): CorrelationResult;
|
|
65
|
+
//# sourceMappingURL=CorrelationEngine.d.ts.map
|
|
Binary file
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
import type { Attribution } from './CorrelationEngine.js';
|
|
2
|
+
/** Which capture the row came out of. */
|
|
3
|
+
export type EventSource = 'EventLogFile' | 'RealTimeEventMonitoring';
|
|
4
|
+
/**
|
|
5
|
+
* One row of the timeline, in the shape every source is mapped into.
|
|
6
|
+
*
|
|
7
|
+
* Ordered identity → attribution → causation → timing → payload → source-specific, so a reader
|
|
8
|
+
* scanning left to right meets "who and why is this here" before "what did it do".
|
|
9
|
+
*
|
|
10
|
+
* Everything is optional except the few fields every source can supply. A blank column is
|
|
11
|
+
* informative in itself: `rows_processed` is empty for every EventLogFile row because no ELF
|
|
12
|
+
* type records it, and that absence is exactly why the real-time objects matter.
|
|
13
|
+
*/
|
|
14
|
+
export interface EventRow {
|
|
15
|
+
seq: number;
|
|
16
|
+
timestamp_utc: string;
|
|
17
|
+
event_type: string;
|
|
18
|
+
source: EventSource;
|
|
19
|
+
attribution: Attribution;
|
|
20
|
+
client_ip?: string;
|
|
21
|
+
request_id?: string;
|
|
22
|
+
session_key?: string;
|
|
23
|
+
login_key?: string;
|
|
24
|
+
user_id?: string;
|
|
25
|
+
user_type?: string;
|
|
26
|
+
is_guest?: boolean;
|
|
27
|
+
/** The save transaction this row belongs to — a cascade shares one. */
|
|
28
|
+
transaction_id?: string;
|
|
29
|
+
/** This row's own event identity, which later events point back at. */
|
|
30
|
+
event_identifier?: string;
|
|
31
|
+
/** The event that caused this one. */
|
|
32
|
+
related_event_identifier?: string;
|
|
33
|
+
/** Object the row acted on, where the source names one. */
|
|
34
|
+
entity_name?: string;
|
|
35
|
+
/** Records the row touched, where the source names them. */
|
|
36
|
+
record_ids?: string;
|
|
37
|
+
/** The page this request came from — chains navigation into a path. */
|
|
38
|
+
referrer_uri?: string;
|
|
39
|
+
/** Actor fingerprint. Weak alone, but it survives an address change. */
|
|
40
|
+
user_agent?: string;
|
|
41
|
+
/** Apex execution context: trigger, batch, anonymous, and so on. */
|
|
42
|
+
quiddity?: string;
|
|
43
|
+
run_time_ms?: number;
|
|
44
|
+
response_bytes?: number;
|
|
45
|
+
page_name?: string;
|
|
46
|
+
http_method?: string;
|
|
47
|
+
is_error?: boolean;
|
|
48
|
+
uri?: string;
|
|
49
|
+
entry_point?: string;
|
|
50
|
+
query_type?: string;
|
|
51
|
+
sql_id?: string;
|
|
52
|
+
rows_processed?: number;
|
|
53
|
+
queried_entities?: string;
|
|
54
|
+
records_returned?: string;
|
|
55
|
+
list_view_name?: string;
|
|
56
|
+
list_view_scope?: string;
|
|
57
|
+
filter_criteria?: string;
|
|
58
|
+
graphql_operation?: string;
|
|
59
|
+
graphql_query?: string;
|
|
60
|
+
graphql_exception?: string;
|
|
61
|
+
/** Batched actions collapsed to one readable line. */
|
|
62
|
+
aura_action_summary?: string;
|
|
63
|
+
/** The raw message, kept so the collapse is never the only record. */
|
|
64
|
+
aura_action_message?: string;
|
|
65
|
+
source_file?: string;
|
|
66
|
+
}
|
|
67
|
+
/** Column order for tabular output. The single source of truth for CSV headers. */
|
|
68
|
+
export declare const EVENT_ROW_COLUMNS: ReadonlyArray<keyof EventRow>;
|
|
69
|
+
//# sourceMappingURL=EventRow.d.ts.map
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
/** Column order for tabular output. The single source of truth for CSV headers. */
|
|
2
|
+
export const EVENT_ROW_COLUMNS = [
|
|
3
|
+
'seq', 'timestamp_utc', 'event_type', 'source', 'attribution',
|
|
4
|
+
'client_ip', 'request_id', 'session_key', 'login_key', 'user_id', 'user_type', 'is_guest',
|
|
5
|
+
'transaction_id', 'event_identifier', 'related_event_identifier',
|
|
6
|
+
'entity_name', 'record_ids', 'referrer_uri', 'user_agent', 'quiddity',
|
|
7
|
+
'run_time_ms', 'response_bytes', 'page_name', 'http_method', 'is_error', 'uri', 'entry_point',
|
|
8
|
+
'query_type', 'sql_id',
|
|
9
|
+
'rows_processed', 'queried_entities', 'records_returned', 'list_view_name', 'list_view_scope',
|
|
10
|
+
'filter_criteria',
|
|
11
|
+
'graphql_operation', 'graphql_query', 'graphql_exception',
|
|
12
|
+
'aura_action_summary', 'aura_action_message', 'source_file',
|
|
13
|
+
];
|
|
14
|
+
//# sourceMappingURL=EventRow.js.map
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The values that tie one actor's rows together across event types.
|
|
3
|
+
*
|
|
4
|
+
* Every field is optional by construction, and that is the point. A key is present only when it
|
|
5
|
+
* carries something usable; anything blank comes back `undefined` and can never reach the
|
|
6
|
+
* correlation frontier.
|
|
7
|
+
*/
|
|
8
|
+
export interface JoinKeys {
|
|
9
|
+
requestId?: string;
|
|
10
|
+
clientIp?: string;
|
|
11
|
+
sessionKey?: string;
|
|
12
|
+
loginKey?: string;
|
|
13
|
+
userId?: string;
|
|
14
|
+
/**
|
|
15
|
+
* One Salesforce transaction — a save and everything it cascaded into. The strongest causal
|
|
16
|
+
* link available: rows sharing it did not merely happen near each other, they happened
|
|
17
|
+
* *because* of each other.
|
|
18
|
+
*/
|
|
19
|
+
transactionId?: string;
|
|
20
|
+
/** A real-time event's own identity, which other events point at. */
|
|
21
|
+
eventIdentifier?: string;
|
|
22
|
+
/**
|
|
23
|
+
* The event this one was caused by. Points at another row's {@link eventIdentifier}, so
|
|
24
|
+
* following it walks from an action to its consequences rather than to its neighbours.
|
|
25
|
+
*/
|
|
26
|
+
relatedEventIdentifier?: string;
|
|
27
|
+
}
|
|
28
|
+
/**
|
|
29
|
+
* Every key type, in one place.
|
|
30
|
+
*
|
|
31
|
+
* The cardinality index and the correlation engine both walk this list. Kept here so adding a
|
|
32
|
+
* key cannot reach one of them and miss the other — a key the engine expands through but the
|
|
33
|
+
* index does not measure would bypass the cardinality gate entirely.
|
|
34
|
+
*/
|
|
35
|
+
export declare const JOIN_KEY_TYPES: readonly ["requestId", "clientIp", "sessionKey", "loginKey", "userId", "transactionId", "eventIdentifier", "relatedEventIdentifier"];
|
|
36
|
+
export type JoinKeyType = (typeof JOIN_KEY_TYPES)[number];
|
|
37
|
+
/**
|
|
38
|
+
* Extract the join keys from a raw ELF or Real-Time Event row.
|
|
39
|
+
*
|
|
40
|
+
* This function is the whole of Invariant 1. A blank value never becomes a key, so the
|
|
41
|
+
* correlation engine cannot expand through one — it has no opportunity to get this wrong, and
|
|
42
|
+
* no obligation to remember the rule.
|
|
43
|
+
*
|
|
44
|
+
* The failure this prevents is specific and was observed: a blank REQUEST_ID admitted to the
|
|
45
|
+
* join set stops behaving like an identifier and starts behaving like a wildcard, matching every
|
|
46
|
+
* other row whose REQUEST_ID is also blank. During the 2026-08-02 reconstruction that turned
|
|
47
|
+
* 2 genuinely related rows into 25, most of them other people's sessions.
|
|
48
|
+
*/
|
|
49
|
+
export declare function joinKeysOf(row: Record<string, unknown>): JoinKeys;
|
|
50
|
+
//# sourceMappingURL=JoinKeys.d.ts.map
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Every key type, in one place.
|
|
3
|
+
*
|
|
4
|
+
* The cardinality index and the correlation engine both walk this list. Kept here so adding a
|
|
5
|
+
* key cannot reach one of them and miss the other — a key the engine expands through but the
|
|
6
|
+
* index does not measure would bypass the cardinality gate entirely.
|
|
7
|
+
*/
|
|
8
|
+
export const JOIN_KEY_TYPES = [
|
|
9
|
+
'requestId',
|
|
10
|
+
'clientIp',
|
|
11
|
+
'sessionKey',
|
|
12
|
+
'loginKey',
|
|
13
|
+
'userId',
|
|
14
|
+
'transactionId',
|
|
15
|
+
'eventIdentifier',
|
|
16
|
+
'relatedEventIdentifier',
|
|
17
|
+
];
|
|
18
|
+
/**
|
|
19
|
+
* Read a key from a raw event row, or `undefined` if it is unusable.
|
|
20
|
+
*
|
|
21
|
+
* Unusable means absent, null, or whitespace — not merely falsy. `'0'` is a legitimate
|
|
22
|
+
* identifier and a truthiness check would silently drop it.
|
|
23
|
+
*
|
|
24
|
+
* Trimming matters as much as rejecting: `' req-1 '` and `'req-1'` are the same request, and
|
|
25
|
+
* treating them as two keys would split one actor's rows across two frontier values and
|
|
26
|
+
* under-report rather than over-report.
|
|
27
|
+
*/
|
|
28
|
+
function usable(value) {
|
|
29
|
+
if (typeof value !== 'string')
|
|
30
|
+
return undefined;
|
|
31
|
+
const trimmed = value.trim();
|
|
32
|
+
return trimmed.length > 0 ? trimmed : undefined;
|
|
33
|
+
}
|
|
34
|
+
/**
|
|
35
|
+
* Extract the join keys from a raw ELF or Real-Time Event row.
|
|
36
|
+
*
|
|
37
|
+
* This function is the whole of Invariant 1. A blank value never becomes a key, so the
|
|
38
|
+
* correlation engine cannot expand through one — it has no opportunity to get this wrong, and
|
|
39
|
+
* no obligation to remember the rule.
|
|
40
|
+
*
|
|
41
|
+
* The failure this prevents is specific and was observed: a blank REQUEST_ID admitted to the
|
|
42
|
+
* join set stops behaving like an identifier and starts behaving like a wildcard, matching every
|
|
43
|
+
* other row whose REQUEST_ID is also blank. During the 2026-08-02 reconstruction that turned
|
|
44
|
+
* 2 genuinely related rows into 25, most of them other people's sessions.
|
|
45
|
+
*/
|
|
46
|
+
export function joinKeysOf(row) {
|
|
47
|
+
return {
|
|
48
|
+
requestId: usable(row.REQUEST_ID),
|
|
49
|
+
// ELF spells it CLIENT_IP, Real-Time Events spell it SourceIp. ApexExecution carries
|
|
50
|
+
// CLIENT_IP as a column but leaves it empty in practice, so an unusable value must fall
|
|
51
|
+
// through rather than shadow a SourceIp that would have identified the row.
|
|
52
|
+
clientIp: usable(row.CLIENT_IP) ?? usable(row.SourceIp),
|
|
53
|
+
// RTE spells these without underscores; accept both so one row type does not silently
|
|
54
|
+
// drop out of the join graph because of a naming convention.
|
|
55
|
+
sessionKey: usable(row.SESSION_KEY) ?? usable(row.SessionKey),
|
|
56
|
+
loginKey: usable(row.LOGIN_KEY) ?? usable(row.LoginKey),
|
|
57
|
+
userId: usable(row.USER_ID) ?? usable(row.UserId),
|
|
58
|
+
transactionId: usable(row.TRANSACTION_ID) ?? usable(row.TransactionId),
|
|
59
|
+
eventIdentifier: usable(row.EVENT_IDENTIFIER) ?? usable(row.EventIdentifier),
|
|
60
|
+
relatedEventIdentifier: usable(row.RELATED_EVENT_IDENTIFIER) ?? usable(row.RelatedEventIdentifier),
|
|
61
|
+
};
|
|
62
|
+
}
|
|
63
|
+
//# sourceMappingURL=JoinKeys.js.map
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
import { type CaptureCoverage } from '@cclabsnz/sf-core';
|
|
2
|
+
export interface LoadRequest {
|
|
3
|
+
/** Capture base directory. */
|
|
4
|
+
base: string;
|
|
5
|
+
orgId: string;
|
|
6
|
+
/** Window date, YYYY-MM-DD. */
|
|
7
|
+
date: string;
|
|
8
|
+
/** Hours within that date, two digits. */
|
|
9
|
+
hours: ReadonlyArray<string>;
|
|
10
|
+
/** Window start, inclusive. Omit to keep every row in the selected files. */
|
|
11
|
+
startMs?: number;
|
|
12
|
+
/** Window end, exclusive. */
|
|
13
|
+
endMs?: number;
|
|
14
|
+
}
|
|
15
|
+
export interface LoadedCaptures {
|
|
16
|
+
rows: Array<Record<string, unknown>>;
|
|
17
|
+
coverage: CaptureCoverage | undefined;
|
|
18
|
+
/** True when any capture file existed for the window at all. */
|
|
19
|
+
windowPresent: boolean;
|
|
20
|
+
/** Lines that could not be parsed. Reported, never fatal. */
|
|
21
|
+
malformed: number;
|
|
22
|
+
/** Files that could not be read. Reported, never fatal. */
|
|
23
|
+
unreadable: number;
|
|
24
|
+
/** Rows kept despite an unreadable timestamp — they could not be placed in or out of the window. */
|
|
25
|
+
undated: number;
|
|
26
|
+
}
|
|
27
|
+
/**
|
|
28
|
+
* Which orgs have captures under this base directory.
|
|
29
|
+
*
|
|
30
|
+
* The store is keyed by org id, so the directory names already hold the answer. Reading them
|
|
31
|
+
* keeps the command offline: resolving an alias would mean asking Salesforce, and this command
|
|
32
|
+
* exists to work when the org is unreachable or its credentials are gone.
|
|
33
|
+
*
|
|
34
|
+
* Filtered by shape because the base directory belongs to the operator and may hold anything —
|
|
35
|
+
* notes, exports, an unrelated folder.
|
|
36
|
+
*/
|
|
37
|
+
export declare function discoverCapturedOrgs(base: string): string[];
|
|
38
|
+
/**
|
|
39
|
+
* Settle on the org to read, or explain why that is not possible.
|
|
40
|
+
*
|
|
41
|
+
* Inferring the only captured org removes a step that exists for no reason; an operator with one
|
|
42
|
+
* capture directory should not have to retype an eighteen-character identifier they cannot check
|
|
43
|
+
* by eye. Where the answer is genuinely ambiguous the command asks rather than picks: choosing
|
|
44
|
+
* one of several would analyse the wrong org and produce output that looks entirely correct.
|
|
45
|
+
*/
|
|
46
|
+
export declare function resolveOrgId(base: string, explicit: string | undefined): string;
|
|
47
|
+
/** One captured day, and how much of it there is. */
|
|
48
|
+
export interface CapturedDay {
|
|
49
|
+
date: string;
|
|
50
|
+
/** How many event types have a capture for that date. */
|
|
51
|
+
types: number;
|
|
52
|
+
/** Hours captured in the hourly layout. Empty for a daily capture, which covers the day. */
|
|
53
|
+
hours: string[];
|
|
54
|
+
}
|
|
55
|
+
/**
|
|
56
|
+
* Which days have captures, read off the store's own layout.
|
|
57
|
+
*
|
|
58
|
+
* "No captures for that window" is only half an answer. The operator's next question is which
|
|
59
|
+
* windows do exist, and without it they go and re-pull data that may already be on disk under a
|
|
60
|
+
* date they guessed wrong. The store is keyed by date, so it already knows.
|
|
61
|
+
*
|
|
62
|
+
* An empty file does not count, matching what counts as captured everywhere else — a partial
|
|
63
|
+
* write is not a capture, and offering it as an available window would send somebody to
|
|
64
|
+
* investigate an hour that holds nothing.
|
|
65
|
+
*/
|
|
66
|
+
export declare function describeCaptures(base: string, orgId: string): CapturedDay[];
|
|
67
|
+
/**
|
|
68
|
+
* A real CSV reader.
|
|
69
|
+
*
|
|
70
|
+
* Splitting on commas and newlines is wrong for this data specifically, not merely in principle:
|
|
71
|
+
* event log columns carry GraphQL queries, URIs and Aura messages, and a quoted newline in any of
|
|
72
|
+
* them splits one record into two while shifting every later field left. The result still parses,
|
|
73
|
+
* still looks like rows, and is wrong — which is the worst failure mode available to a forensic
|
|
74
|
+
* importer.
|
|
75
|
+
*/
|
|
76
|
+
export declare function parseCsv(text: string): Array<Record<string, string>>;
|
|
77
|
+
/**
|
|
78
|
+
* Load every captured row for a window.
|
|
79
|
+
*
|
|
80
|
+
* Fault-tolerant by design, matching the capture side: a parse failure on one file must never
|
|
81
|
+
* lose the rest of the window. An investigation frequently runs against the one hour that also
|
|
82
|
+
* happens to contain a truncated download, and losing the other fifty files to it would be
|
|
83
|
+
* self-defeating. Failures are counted and returned so the caller can report them rather than
|
|
84
|
+
* discover them by their absence.
|
|
85
|
+
*/
|
|
86
|
+
export declare function loadCaptures(request: LoadRequest): LoadedCaptures;
|
|
87
|
+
//# sourceMappingURL=loadCaptures.d.ts.map
|