@cclabsnz/sf-audit 1.7.0 → 1.8.1
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 +180 -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 +28 -5
|
@@ -0,0 +1,424 @@
|
|
|
1
|
+
import * as fs from 'node:fs';
|
|
2
|
+
import * as path from 'node:path';
|
|
3
|
+
import { readCoverageManifest } from '@cclabsnz/sf-core';
|
|
4
|
+
/** Salesforce org ids are 15 or 18 characters and start 00D. */
|
|
5
|
+
const ORG_ID = /^00D[A-Za-z0-9]{12}([A-Za-z0-9]{3})?$/;
|
|
6
|
+
/**
|
|
7
|
+
* Which orgs have captures under this base directory.
|
|
8
|
+
*
|
|
9
|
+
* The store is keyed by org id, so the directory names already hold the answer. Reading them
|
|
10
|
+
* keeps the command offline: resolving an alias would mean asking Salesforce, and this command
|
|
11
|
+
* exists to work when the org is unreachable or its credentials are gone.
|
|
12
|
+
*
|
|
13
|
+
* Filtered by shape because the base directory belongs to the operator and may hold anything —
|
|
14
|
+
* notes, exports, an unrelated folder.
|
|
15
|
+
*/
|
|
16
|
+
export function discoverCapturedOrgs(base) {
|
|
17
|
+
try {
|
|
18
|
+
return fs
|
|
19
|
+
.readdirSync(base, { withFileTypes: true })
|
|
20
|
+
.filter((e) => e.isDirectory() && ORG_ID.test(e.name))
|
|
21
|
+
.map((e) => e.name)
|
|
22
|
+
.sort();
|
|
23
|
+
}
|
|
24
|
+
catch {
|
|
25
|
+
return [];
|
|
26
|
+
}
|
|
27
|
+
}
|
|
28
|
+
/**
|
|
29
|
+
* Settle on the org to read, or explain why that is not possible.
|
|
30
|
+
*
|
|
31
|
+
* Inferring the only captured org removes a step that exists for no reason; an operator with one
|
|
32
|
+
* capture directory should not have to retype an eighteen-character identifier they cannot check
|
|
33
|
+
* by eye. Where the answer is genuinely ambiguous the command asks rather than picks: choosing
|
|
34
|
+
* one of several would analyse the wrong org and produce output that looks entirely correct.
|
|
35
|
+
*/
|
|
36
|
+
export function resolveOrgId(base, explicit) {
|
|
37
|
+
const captured = discoverCapturedOrgs(base);
|
|
38
|
+
if (explicit) {
|
|
39
|
+
if (captured.length > 0 && !captured.includes(explicit)) {
|
|
40
|
+
throw new Error(`No captures for ${explicit} under ${base}.\n` +
|
|
41
|
+
`Captured here: ${captured.join(', ')}\n` +
|
|
42
|
+
'If that id is right, capture the org first: sf audit events pull --target-org <alias>');
|
|
43
|
+
}
|
|
44
|
+
return explicit;
|
|
45
|
+
}
|
|
46
|
+
if (captured.length === 1)
|
|
47
|
+
return captured[0];
|
|
48
|
+
if (captured.length === 0) {
|
|
49
|
+
throw new Error(`No captures found under ${base}.\n` +
|
|
50
|
+
'Capture an org first: sf audit events pull --target-org <alias>');
|
|
51
|
+
}
|
|
52
|
+
throw new Error(`Several orgs are captured under ${base}; name the one to read with --org-id.\n` +
|
|
53
|
+
captured.map((id) => ` ${id}`).join('\n'));
|
|
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 function describeCaptures(base, orgId) {
|
|
67
|
+
const orgDir = path.join(base, orgId);
|
|
68
|
+
const days = new Map();
|
|
69
|
+
const note = (date, type, hour) => {
|
|
70
|
+
let day = days.get(date);
|
|
71
|
+
if (!day)
|
|
72
|
+
days.set(date, (day = { types: new Set(), hours: new Set() }));
|
|
73
|
+
day.types.add(type);
|
|
74
|
+
if (hour)
|
|
75
|
+
day.hours.add(hour);
|
|
76
|
+
};
|
|
77
|
+
let entries;
|
|
78
|
+
try {
|
|
79
|
+
entries = fs.readdirSync(orgDir);
|
|
80
|
+
}
|
|
81
|
+
catch {
|
|
82
|
+
return [];
|
|
83
|
+
}
|
|
84
|
+
for (const entry of entries) {
|
|
85
|
+
if (entry === '_manifests')
|
|
86
|
+
continue;
|
|
87
|
+
const entryPath = path.join(orgDir, entry);
|
|
88
|
+
if (entry === '_realtime') {
|
|
89
|
+
for (const object of safeList(entryPath)) {
|
|
90
|
+
for (const date of safeList(path.join(entryPath, object))) {
|
|
91
|
+
for (const file of safeList(path.join(entryPath, object, date))) {
|
|
92
|
+
if (file.endsWith('.ndjson') && nonEmpty(path.join(entryPath, object, date, file))) {
|
|
93
|
+
note(date, object, file.slice(0, 2));
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
continue;
|
|
99
|
+
}
|
|
100
|
+
for (const child of safeList(entryPath)) {
|
|
101
|
+
const full = path.join(entryPath, child);
|
|
102
|
+
// Daily: {date}-{id}.csv
|
|
103
|
+
const daily = /^(\d{4}-\d{2}-\d{2})-.*\.csv$/.exec(child);
|
|
104
|
+
if (daily && nonEmpty(full)) {
|
|
105
|
+
note(daily[1], entry);
|
|
106
|
+
continue;
|
|
107
|
+
}
|
|
108
|
+
// Hourly: a directory named for the date.
|
|
109
|
+
if (/^\d{4}-\d{2}-\d{2}$/.test(child)) {
|
|
110
|
+
for (const file of safeList(full)) {
|
|
111
|
+
if (file.endsWith('.csv') && nonEmpty(path.join(full, file)))
|
|
112
|
+
note(child, entry, file.slice(0, 2));
|
|
113
|
+
}
|
|
114
|
+
}
|
|
115
|
+
}
|
|
116
|
+
}
|
|
117
|
+
return [...days]
|
|
118
|
+
.map(([date, d]) => ({ date, types: d.types.size, hours: [...d.hours].sort() }))
|
|
119
|
+
.sort((a, b) => a.date.localeCompare(b.date));
|
|
120
|
+
}
|
|
121
|
+
function safeList(dir) {
|
|
122
|
+
try {
|
|
123
|
+
return fs.readdirSync(dir);
|
|
124
|
+
}
|
|
125
|
+
catch {
|
|
126
|
+
return [];
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
/**
|
|
130
|
+
* A real CSV reader.
|
|
131
|
+
*
|
|
132
|
+
* Splitting on commas and newlines is wrong for this data specifically, not merely in principle:
|
|
133
|
+
* event log columns carry GraphQL queries, URIs and Aura messages, and a quoted newline in any of
|
|
134
|
+
* them splits one record into two while shifting every later field left. The result still parses,
|
|
135
|
+
* still looks like rows, and is wrong — which is the worst failure mode available to a forensic
|
|
136
|
+
* importer.
|
|
137
|
+
*/
|
|
138
|
+
export function parseCsv(text) {
|
|
139
|
+
const rows = [];
|
|
140
|
+
let row = [];
|
|
141
|
+
let cell = '';
|
|
142
|
+
let quoted = false;
|
|
143
|
+
for (let i = 0; i < text.length; i++) {
|
|
144
|
+
const ch = text[i];
|
|
145
|
+
if (quoted) {
|
|
146
|
+
if (ch === '"') {
|
|
147
|
+
// A doubled quote inside a quoted field is one literal quote.
|
|
148
|
+
if (text[i + 1] === '"') {
|
|
149
|
+
cell += '"';
|
|
150
|
+
i++;
|
|
151
|
+
}
|
|
152
|
+
else
|
|
153
|
+
quoted = false;
|
|
154
|
+
}
|
|
155
|
+
else
|
|
156
|
+
cell += ch;
|
|
157
|
+
continue;
|
|
158
|
+
}
|
|
159
|
+
if (ch === '"') {
|
|
160
|
+
quoted = true;
|
|
161
|
+
continue;
|
|
162
|
+
}
|
|
163
|
+
if (ch === ',') {
|
|
164
|
+
row.push(cell);
|
|
165
|
+
cell = '';
|
|
166
|
+
continue;
|
|
167
|
+
}
|
|
168
|
+
if (ch === '\r')
|
|
169
|
+
continue;
|
|
170
|
+
if (ch === '\n') {
|
|
171
|
+
row.push(cell);
|
|
172
|
+
rows.push(row);
|
|
173
|
+
row = [];
|
|
174
|
+
cell = '';
|
|
175
|
+
continue;
|
|
176
|
+
}
|
|
177
|
+
cell += ch;
|
|
178
|
+
}
|
|
179
|
+
if (cell.length > 0 || row.length > 0) {
|
|
180
|
+
row.push(cell);
|
|
181
|
+
rows.push(row);
|
|
182
|
+
}
|
|
183
|
+
const [header, ...body] = rows;
|
|
184
|
+
if (!header)
|
|
185
|
+
return [];
|
|
186
|
+
return body
|
|
187
|
+
// A trailing newline yields a single empty cell, which is not a record.
|
|
188
|
+
.filter((cells) => !(cells.length === 1 && cells[0] === ''))
|
|
189
|
+
.map((cells) => {
|
|
190
|
+
const record = {};
|
|
191
|
+
// Header-driven, so a short row yields empty columns and a long one drops its extras
|
|
192
|
+
// rather than either corrupting the named columns.
|
|
193
|
+
header.forEach((name, idx) => { record[name] = cells[idx] ?? ''; });
|
|
194
|
+
return record;
|
|
195
|
+
});
|
|
196
|
+
}
|
|
197
|
+
/**
|
|
198
|
+
* Load every captured row for a window.
|
|
199
|
+
*
|
|
200
|
+
* Fault-tolerant by design, matching the capture side: a parse failure on one file must never
|
|
201
|
+
* lose the rest of the window. An investigation frequently runs against the one hour that also
|
|
202
|
+
* happens to contain a truncated download, and losing the other fifty files to it would be
|
|
203
|
+
* self-defeating. Failures are counted and returned so the caller can report them rather than
|
|
204
|
+
* discover them by their absence.
|
|
205
|
+
*/
|
|
206
|
+
export function loadCaptures(request) {
|
|
207
|
+
const orgDir = path.join(request.base, request.orgId);
|
|
208
|
+
const out = { rows: [], coverage: undefined, windowPresent: false, malformed: 0, unreadable: 0, undated: 0 };
|
|
209
|
+
if (!fs.existsSync(orgDir))
|
|
210
|
+
return out;
|
|
211
|
+
for (const entry of safeReadDir(orgDir, out)) {
|
|
212
|
+
if (entry === '_manifests')
|
|
213
|
+
continue;
|
|
214
|
+
if (entry === '_realtime') {
|
|
215
|
+
loadRealtime(path.join(orgDir, entry), request, out);
|
|
216
|
+
continue;
|
|
217
|
+
}
|
|
218
|
+
loadElf(path.join(orgDir, entry), request, out);
|
|
219
|
+
}
|
|
220
|
+
out.coverage = newestCoverage(path.join(orgDir, '_manifests'));
|
|
221
|
+
return out;
|
|
222
|
+
}
|
|
223
|
+
/**
|
|
224
|
+
* When did this row happen?
|
|
225
|
+
*
|
|
226
|
+
* EventLogFile carries both an ISO timestamp and Salesforce's own compact form; real-time
|
|
227
|
+
* objects carry EventDate. Any one of them will do, and the compact form has to be assembled
|
|
228
|
+
* because it does not parse as a date on its own.
|
|
229
|
+
*/
|
|
230
|
+
function rowTimeMs(row) {
|
|
231
|
+
for (const key of ['TIMESTAMP_DERIVED', 'EventDate', 'CreatedDate']) {
|
|
232
|
+
const value = row[key];
|
|
233
|
+
if (typeof value === 'string' && value.trim() !== '') {
|
|
234
|
+
const parsed = Date.parse(value);
|
|
235
|
+
if (!Number.isNaN(parsed))
|
|
236
|
+
return parsed;
|
|
237
|
+
}
|
|
238
|
+
}
|
|
239
|
+
// 20260802043000.000 — year month day hour minute second, no separators.
|
|
240
|
+
const compact = row.TIMESTAMP;
|
|
241
|
+
if (typeof compact === 'string') {
|
|
242
|
+
const m = /^(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})(?:\.(\d+))?$/.exec(compact.trim());
|
|
243
|
+
if (m) {
|
|
244
|
+
return Date.UTC(+m[1], +m[2] - 1, +m[3], +m[4], +m[5], +m[6], m[7] ? +m[7].slice(0, 3) : 0);
|
|
245
|
+
}
|
|
246
|
+
}
|
|
247
|
+
return undefined;
|
|
248
|
+
}
|
|
249
|
+
/**
|
|
250
|
+
* Keep a row if it falls in the window — or if its time cannot be read at all.
|
|
251
|
+
*
|
|
252
|
+
* A daily capture file spans twenty-four hours, so selecting the file is not selecting the
|
|
253
|
+
* window; without this, asking for one hour returns the day. The window is half-open so two
|
|
254
|
+
* consecutive windows partition their rows instead of both claiming the boundary.
|
|
255
|
+
*
|
|
256
|
+
* A row whose timestamp will not parse is kept rather than dropped. It cannot be placed in or
|
|
257
|
+
* out of the window, and dropping it would lose evidence with no trace; kept, it appears in the
|
|
258
|
+
* output with an empty timestamp where a reviewer can see it and judge.
|
|
259
|
+
*/
|
|
260
|
+
function inWindow(row, request, out) {
|
|
261
|
+
if (request.startMs === undefined || request.endMs === undefined)
|
|
262
|
+
return true;
|
|
263
|
+
const at = rowTimeMs(row);
|
|
264
|
+
if (at === undefined) {
|
|
265
|
+
out.undated++;
|
|
266
|
+
return true;
|
|
267
|
+
}
|
|
268
|
+
return at >= request.startMs && at < request.endMs;
|
|
269
|
+
}
|
|
270
|
+
/**
|
|
271
|
+
* A file that exists but holds nothing is not a capture.
|
|
272
|
+
*
|
|
273
|
+
* sf-core 0.3.0 made presence on disk mean complete: the capture writes atomically and treats a
|
|
274
|
+
* zero-byte file as absent, because a run killed between create and write leaves one behind and
|
|
275
|
+
* counting it as captured retires that hour permanently. The reader has to agree, or a gap the
|
|
276
|
+
* capture side now refuses to hide reappears here as a window reported captured with no data in
|
|
277
|
+
* it — which is precisely the ambiguity this command exists to remove.
|
|
278
|
+
*/
|
|
279
|
+
function nonEmpty(filePath) {
|
|
280
|
+
try {
|
|
281
|
+
return fs.statSync(filePath).size > 0;
|
|
282
|
+
}
|
|
283
|
+
catch {
|
|
284
|
+
return false;
|
|
285
|
+
}
|
|
286
|
+
}
|
|
287
|
+
function safeReadDir(dir, out) {
|
|
288
|
+
try {
|
|
289
|
+
return fs.readdirSync(dir);
|
|
290
|
+
}
|
|
291
|
+
catch {
|
|
292
|
+
out.unreadable++;
|
|
293
|
+
return [];
|
|
294
|
+
}
|
|
295
|
+
}
|
|
296
|
+
/**
|
|
297
|
+
* Both EventLogFile layouts.
|
|
298
|
+
*
|
|
299
|
+
* `{EventType}/{date}-{id}.csv` daily — what the free tier serves, and what
|
|
300
|
+
* `sf audit events pull` writes by default
|
|
301
|
+
* `{EventType}/{date}/{HH}-{id}.csv` hourly
|
|
302
|
+
*
|
|
303
|
+
* Reading only the hourly form would make this command blind to the captures it exists to read.
|
|
304
|
+
* A day can hold both at once, so both are read and the rows are filtered to the window
|
|
305
|
+
* afterwards.
|
|
306
|
+
*/
|
|
307
|
+
function loadElf(typeDir, request, out) {
|
|
308
|
+
const readFile = (full) => {
|
|
309
|
+
if (!nonEmpty(full))
|
|
310
|
+
return;
|
|
311
|
+
out.windowPresent = true;
|
|
312
|
+
let text;
|
|
313
|
+
try {
|
|
314
|
+
text = fs.readFileSync(full, 'utf-8');
|
|
315
|
+
}
|
|
316
|
+
catch {
|
|
317
|
+
out.unreadable++;
|
|
318
|
+
return;
|
|
319
|
+
}
|
|
320
|
+
for (const row of parseCsv(text)) {
|
|
321
|
+
const record = { ...row, __sourceFile: full, __source: 'EventLogFile' };
|
|
322
|
+
if (inWindow(record, request, out))
|
|
323
|
+
out.rows.push(record);
|
|
324
|
+
}
|
|
325
|
+
};
|
|
326
|
+
// Daily: a file named for the date, directly under the event type.
|
|
327
|
+
for (const entry of safeReadDir(typeDir, out)) {
|
|
328
|
+
if (entry.startsWith(`${request.date}-`) && entry.endsWith('.csv')) {
|
|
329
|
+
readFile(path.join(typeDir, entry));
|
|
330
|
+
}
|
|
331
|
+
}
|
|
332
|
+
// Hourly: a directory named for the date, holding a file per hour.
|
|
333
|
+
const dayDir = path.join(typeDir, request.date);
|
|
334
|
+
if (!fs.existsSync(dayDir) || !fs.statSync(dayDir).isDirectory())
|
|
335
|
+
return;
|
|
336
|
+
for (const file of safeReadDir(dayDir, out)) {
|
|
337
|
+
const hour = file.slice(0, 2);
|
|
338
|
+
if (!request.hours.includes(hour) || !file.endsWith('.csv'))
|
|
339
|
+
continue;
|
|
340
|
+
readFile(path.join(dayDir, file));
|
|
341
|
+
}
|
|
342
|
+
}
|
|
343
|
+
/** `_realtime/{ObjectName}/{date}/{HH}.ndjson` */
|
|
344
|
+
function loadRealtime(realtimeDir, request, out) {
|
|
345
|
+
for (const object of safeReadDir(realtimeDir, out)) {
|
|
346
|
+
const dayDir = path.join(realtimeDir, object, request.date);
|
|
347
|
+
if (!fs.existsSync(dayDir))
|
|
348
|
+
continue;
|
|
349
|
+
for (const file of safeReadDir(dayDir, out)) {
|
|
350
|
+
const hour = file.slice(0, 2);
|
|
351
|
+
if (!request.hours.includes(hour) || !file.endsWith('.ndjson'))
|
|
352
|
+
continue;
|
|
353
|
+
const full = path.join(dayDir, file);
|
|
354
|
+
if (!nonEmpty(full))
|
|
355
|
+
continue;
|
|
356
|
+
out.windowPresent = true;
|
|
357
|
+
let text;
|
|
358
|
+
try {
|
|
359
|
+
text = fs.readFileSync(full, 'utf-8');
|
|
360
|
+
}
|
|
361
|
+
catch {
|
|
362
|
+
out.unreadable++;
|
|
363
|
+
continue;
|
|
364
|
+
}
|
|
365
|
+
for (const line of text.split('\n')) {
|
|
366
|
+
if (line.trim() === '')
|
|
367
|
+
continue;
|
|
368
|
+
try {
|
|
369
|
+
const parsed = JSON.parse(line);
|
|
370
|
+
if (parsed && typeof parsed === 'object') {
|
|
371
|
+
const record = {
|
|
372
|
+
...parsed,
|
|
373
|
+
EVENT_TYPE: parsed.EVENT_TYPE ?? object,
|
|
374
|
+
__sourceFile: full,
|
|
375
|
+
__source: 'RealTimeEventMonitoring',
|
|
376
|
+
};
|
|
377
|
+
if (inWindow(record, request, out))
|
|
378
|
+
out.rows.push(record);
|
|
379
|
+
}
|
|
380
|
+
else
|
|
381
|
+
out.malformed++;
|
|
382
|
+
}
|
|
383
|
+
catch {
|
|
384
|
+
// One bad line loses one row, not the file.
|
|
385
|
+
out.malformed++;
|
|
386
|
+
}
|
|
387
|
+
}
|
|
388
|
+
}
|
|
389
|
+
}
|
|
390
|
+
}
|
|
391
|
+
/**
|
|
392
|
+
* The newest manifest wins.
|
|
393
|
+
*
|
|
394
|
+
* A window can be pulled more than once — a later run adding real-time objects to an earlier
|
|
395
|
+
* ELF-only capture, say — and the most recent record is the one that describes what is actually
|
|
396
|
+
* on disk now.
|
|
397
|
+
*/
|
|
398
|
+
function newestCoverage(manifestDir) {
|
|
399
|
+
if (!fs.existsSync(manifestDir))
|
|
400
|
+
return undefined;
|
|
401
|
+
let files;
|
|
402
|
+
try {
|
|
403
|
+
files = fs.readdirSync(manifestDir).filter((f) => f.startsWith('coverage-') && f.endsWith('.json'));
|
|
404
|
+
}
|
|
405
|
+
catch {
|
|
406
|
+
return undefined;
|
|
407
|
+
}
|
|
408
|
+
// Named coverage-{epochMs}-{rand}.json, so lexical order on the timestamp is chronological
|
|
409
|
+
// for any run this decade; compare numerically anyway rather than relying on that.
|
|
410
|
+
const sorted = files.sort((a, b) => stamp(b) - stamp(a));
|
|
411
|
+
for (const file of sorted) {
|
|
412
|
+
const parsed = readCoverageManifest(path.join(manifestDir, file));
|
|
413
|
+
// A manifest that will not parse is skipped rather than failing the load; the next one
|
|
414
|
+
// down may still describe the window.
|
|
415
|
+
if (parsed)
|
|
416
|
+
return parsed;
|
|
417
|
+
}
|
|
418
|
+
return undefined;
|
|
419
|
+
}
|
|
420
|
+
function stamp(fileName) {
|
|
421
|
+
const parsed = Number(fileName.split('-')[1]);
|
|
422
|
+
return Number.isFinite(parsed) ? parsed : 0;
|
|
423
|
+
}
|
|
424
|
+
//# sourceMappingURL=loadCaptures.js.map
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
import { type EventRow, type EventSource } from './EventRow.js';
|
|
2
|
+
import type { Attribution } from './CorrelationEngine.js';
|
|
3
|
+
export interface NormaliseContext {
|
|
4
|
+
seq: number;
|
|
5
|
+
attribution: Attribution;
|
|
6
|
+
source: EventSource;
|
|
7
|
+
}
|
|
8
|
+
/**
|
|
9
|
+
* Collapse a batch of Aura actions into one readable line.
|
|
10
|
+
*
|
|
11
|
+
* A single request can carry hundreds of action invocations, and printed raw they bury the
|
|
12
|
+
* timeline. The count alone would not do: the min–max range is the finding. A batch that is
|
|
13
|
+
* uniformly 0ms is fail-fast permission denial — the actor was refused. A batch spread across
|
|
14
|
+
* hundreds of milliseconds is the database being queried, which is the actor getting data.
|
|
15
|
+
* Collapsing to a count would erase the difference between an attempt and a success.
|
|
16
|
+
*/
|
|
17
|
+
export declare function collapseAuraActions(message: string | undefined): string | undefined;
|
|
18
|
+
/**
|
|
19
|
+
* Map one raw row into the unified shape.
|
|
20
|
+
*
|
|
21
|
+
* Every declared column is present on the result, set to `undefined` where the source had
|
|
22
|
+
* nothing. That keeps the CSV header and the row in lockstep — a column that only materialises
|
|
23
|
+
* when populated shifts every value to its left the moment a source omits it.
|
|
24
|
+
*/
|
|
25
|
+
export declare function normaliseRow(raw: Record<string, unknown>, ctx: NormaliseContext): EventRow;
|
|
26
|
+
//# sourceMappingURL=normalise.d.ts.map
|
|
@@ -0,0 +1,161 @@
|
|
|
1
|
+
import { EVENT_ROW_COLUMNS } from './EventRow.js';
|
|
2
|
+
import { joinKeysOf } from './JoinKeys.js';
|
|
3
|
+
/** Blank is absent. An empty string in a column means the source had nothing, not that it said "". */
|
|
4
|
+
function text(...candidates) {
|
|
5
|
+
for (const value of candidates) {
|
|
6
|
+
if (typeof value !== 'string')
|
|
7
|
+
continue;
|
|
8
|
+
const trimmed = value.trim();
|
|
9
|
+
if (trimmed.length > 0)
|
|
10
|
+
return trimmed;
|
|
11
|
+
}
|
|
12
|
+
return undefined;
|
|
13
|
+
}
|
|
14
|
+
/** A number, or nothing. Never a guess: an unparseable value is absent, not zero. */
|
|
15
|
+
function num(...candidates) {
|
|
16
|
+
for (const value of candidates) {
|
|
17
|
+
if (typeof value === 'number' && Number.isFinite(value))
|
|
18
|
+
return value;
|
|
19
|
+
if (typeof value === 'string' && value.trim() !== '') {
|
|
20
|
+
const parsed = Number(value);
|
|
21
|
+
if (Number.isFinite(parsed))
|
|
22
|
+
return parsed;
|
|
23
|
+
}
|
|
24
|
+
}
|
|
25
|
+
return undefined;
|
|
26
|
+
}
|
|
27
|
+
/**
|
|
28
|
+
* Field aliases, one table rather than a branch per event type.
|
|
29
|
+
*
|
|
30
|
+
* There are more than sixty event types and Salesforce keeps adding them. A switch would need a
|
|
31
|
+
* case for each, and the type it does not have a case for would vanish — which for a forensic
|
|
32
|
+
* tool is the worst outcome, because the absence looks like evidence. Every row is mapped
|
|
33
|
+
* through the same table, so an unrecognised type still yields its common fields and simply
|
|
34
|
+
* leaves the specific ones blank.
|
|
35
|
+
*
|
|
36
|
+
* Each entry lists the spellings a value appears under, in preference order. EventLogFile uses
|
|
37
|
+
* SHOUTING_SNAKE and real-time objects use PascalCase, often for the same concept.
|
|
38
|
+
*/
|
|
39
|
+
const TEXT_FIELDS = {
|
|
40
|
+
event_type: ['EVENT_TYPE', 'EventType'],
|
|
41
|
+
timestamp_utc: ['TIMESTAMP_DERIVED', 'TIMESTAMP', 'EventDate', 'CreatedDate'],
|
|
42
|
+
user_type: ['USER_TYPE', 'UserType'],
|
|
43
|
+
entity_name: ['ENTITY_NAME', 'EntityName', 'QueriedEntities'],
|
|
44
|
+
record_ids: ['RECORD_ID', 'RecordIds', 'RecordId'],
|
|
45
|
+
referrer_uri: ['REFERRER_URI', 'REFERRER'],
|
|
46
|
+
user_agent: ['USER_AGENT', 'UserAgent', 'Browser'],
|
|
47
|
+
quiddity: ['QUIDDITY', 'Quiddity'],
|
|
48
|
+
page_name: ['PAGE_NAME', 'PAGE_APP_NAME', 'Page'],
|
|
49
|
+
http_method: ['METHOD', 'HTTP_METHOD', 'RequestType'],
|
|
50
|
+
uri: ['URI', 'Uri', 'URL'],
|
|
51
|
+
entry_point: ['ENTRY_POINT', 'EntryPoint'],
|
|
52
|
+
query_type: ['QUERY_TYPE', 'QueryType', 'Operation'],
|
|
53
|
+
sql_id: ['SQL_ID', 'QueryId'],
|
|
54
|
+
queried_entities: ['QueriedEntities', 'QUERIED_ENTITIES'],
|
|
55
|
+
records_returned: ['RecordIds', 'RECORDS_RETURNED', 'Records'],
|
|
56
|
+
list_view_name: ['Name', 'LIST_VIEW_NAME', 'ListViewName'],
|
|
57
|
+
list_view_scope: ['Scope', 'LIST_VIEW_SCOPE'],
|
|
58
|
+
filter_criteria: ['FilterCriteria', 'FILTER_CRITERIA', 'Filter'],
|
|
59
|
+
graphql_operation: ['OPERATION_NAME', 'GraphQLOperation'],
|
|
60
|
+
graphql_query: ['QUERY', 'GraphQLQuery'],
|
|
61
|
+
graphql_exception: ['EXCEPTION_MESSAGE', 'GraphQLException'],
|
|
62
|
+
aura_action_message: ['ACTION_MESSAGE'],
|
|
63
|
+
source_file: ['SOURCE_FILE', '__sourceFile'],
|
|
64
|
+
};
|
|
65
|
+
const NUMBER_FIELDS = {
|
|
66
|
+
run_time_ms: ['RUN_TIME', 'RunTime', 'EXEC_TIME'],
|
|
67
|
+
response_bytes: ['RESPONSE_SIZE', 'ResponseSize', 'BYTES'],
|
|
68
|
+
rows_processed: ['RowsProcessed', 'ROWS_PROCESSED', 'NUMBER_OF_RECORDS'],
|
|
69
|
+
};
|
|
70
|
+
/** Real-time objects supply the record-count fields; no EventLogFile type records them. */
|
|
71
|
+
const RTE_ONLY = [
|
|
72
|
+
'rows_processed', 'records_returned', 'list_view_name', 'list_view_scope', 'filter_criteria',
|
|
73
|
+
];
|
|
74
|
+
/**
|
|
75
|
+
* Collapse a batch of Aura actions into one readable line.
|
|
76
|
+
*
|
|
77
|
+
* A single request can carry hundreds of action invocations, and printed raw they bury the
|
|
78
|
+
* timeline. The count alone would not do: the min–max range is the finding. A batch that is
|
|
79
|
+
* uniformly 0ms is fail-fast permission denial — the actor was refused. A batch spread across
|
|
80
|
+
* hundreds of milliseconds is the database being queried, which is the actor getting data.
|
|
81
|
+
* Collapsing to a count would erase the difference between an attempt and a success.
|
|
82
|
+
*/
|
|
83
|
+
export function collapseAuraActions(message) {
|
|
84
|
+
if (!message)
|
|
85
|
+
return undefined;
|
|
86
|
+
const timings = new Map();
|
|
87
|
+
for (const [, descriptor, ms] of message.matchAll(/([A-Za-z0-9_$./-]+)\s*=\s*(\d+)/g)) {
|
|
88
|
+
const value = Number(ms);
|
|
89
|
+
const seen = timings.get(descriptor);
|
|
90
|
+
if (seen) {
|
|
91
|
+
seen.count++;
|
|
92
|
+
seen.min = Math.min(seen.min, value);
|
|
93
|
+
seen.max = Math.max(seen.max, value);
|
|
94
|
+
}
|
|
95
|
+
else {
|
|
96
|
+
timings.set(descriptor, { count: 1, min: value, max: value });
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
if (timings.size === 0)
|
|
100
|
+
return undefined;
|
|
101
|
+
return [...timings]
|
|
102
|
+
.map(([descriptor, t]) => `${descriptor} x${t.count} [${t.min}-${t.max}ms]`)
|
|
103
|
+
.join('; ');
|
|
104
|
+
}
|
|
105
|
+
/**
|
|
106
|
+
* Map one raw row into the unified shape.
|
|
107
|
+
*
|
|
108
|
+
* Every declared column is present on the result, set to `undefined` where the source had
|
|
109
|
+
* nothing. That keeps the CSV header and the row in lockstep — a column that only materialises
|
|
110
|
+
* when populated shifts every value to its left the moment a source omits it.
|
|
111
|
+
*/
|
|
112
|
+
export function normaliseRow(raw, ctx) {
|
|
113
|
+
const keys = joinKeysOf(raw);
|
|
114
|
+
const isRte = ctx.source === 'RealTimeEventMonitoring';
|
|
115
|
+
const row = {};
|
|
116
|
+
for (const column of EVENT_ROW_COLUMNS)
|
|
117
|
+
row[column] = undefined;
|
|
118
|
+
row.seq = ctx.seq;
|
|
119
|
+
row.attribution = ctx.attribution;
|
|
120
|
+
row.source = ctx.source;
|
|
121
|
+
for (const [column, aliases] of Object.entries(TEXT_FIELDS)) {
|
|
122
|
+
if (!isRte && RTE_ONLY.includes(column))
|
|
123
|
+
continue;
|
|
124
|
+
row[column] = text(...aliases.map((a) => raw[a]));
|
|
125
|
+
}
|
|
126
|
+
for (const [column, aliases] of Object.entries(NUMBER_FIELDS)) {
|
|
127
|
+
if (!isRte && RTE_ONLY.includes(column))
|
|
128
|
+
continue;
|
|
129
|
+
row[column] = num(...aliases.map((a) => raw[a]));
|
|
130
|
+
}
|
|
131
|
+
// Join keys come from the one place that already applies the blank rule, so the timeline's
|
|
132
|
+
// columns and the correlation that produced them cannot disagree about what a row's keys are.
|
|
133
|
+
row.client_ip = keys.clientIp;
|
|
134
|
+
row.request_id = keys.requestId;
|
|
135
|
+
row.session_key = keys.sessionKey;
|
|
136
|
+
row.login_key = keys.loginKey;
|
|
137
|
+
row.user_id = keys.userId;
|
|
138
|
+
row.transaction_id = keys.transactionId;
|
|
139
|
+
row.event_identifier = keys.eventIdentifier;
|
|
140
|
+
row.related_event_identifier = keys.relatedEventIdentifier;
|
|
141
|
+
row.event_type = row.event_type ?? 'Unknown';
|
|
142
|
+
row.timestamp_utc = row.timestamp_utc ?? '';
|
|
143
|
+
row.is_guest = row.user_type === undefined ? undefined : /guest/i.test(String(row.user_type));
|
|
144
|
+
row.is_error = errorFlag(raw);
|
|
145
|
+
row.aura_action_summary = collapseAuraActions(row.aura_action_message);
|
|
146
|
+
return row;
|
|
147
|
+
}
|
|
148
|
+
/** Several types spell failure differently; none of them spell it consistently. */
|
|
149
|
+
function errorFlag(raw) {
|
|
150
|
+
const status = text(raw.STATUS_CODE, raw.HTTP_STATUS_CODE, raw.StatusCode);
|
|
151
|
+
if (status !== undefined) {
|
|
152
|
+
const code = Number(status);
|
|
153
|
+
if (Number.isFinite(code))
|
|
154
|
+
return code >= 400;
|
|
155
|
+
}
|
|
156
|
+
const explicit = text(raw.IS_ERROR, raw.EXCEPTION_MESSAGE, raw.GraphQLException);
|
|
157
|
+
if (explicit === undefined)
|
|
158
|
+
return undefined;
|
|
159
|
+
return explicit.toLowerCase() !== 'false' && explicit !== '0';
|
|
160
|
+
}
|
|
161
|
+
//# sourceMappingURL=normalise.js.map
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
export interface Window {
|
|
2
|
+
/** UTC date, YYYY-MM-DD. */
|
|
3
|
+
date: string;
|
|
4
|
+
/** Two-digit UTC hours to read, ascending. */
|
|
5
|
+
hours: string[];
|
|
6
|
+
/** Window start, inclusive. */
|
|
7
|
+
startMs: number;
|
|
8
|
+
/** Window end, exclusive — so consecutive windows partition rows rather than sharing a boundary. */
|
|
9
|
+
endMs: number;
|
|
10
|
+
}
|
|
11
|
+
/**
|
|
12
|
+
* Resolve a window to the hour files that hold it.
|
|
13
|
+
*
|
|
14
|
+
* Several spellings, one meaning. The exact ISO interval is precise and nobody composes one
|
|
15
|
+
* under pressure; an investigator knows "yesterday", "the last two hours", or has a timestamp
|
|
16
|
+
* pasted from an alert. Translating that by hand is a step where the timezone or the duration
|
|
17
|
+
* syntax goes wrong, and the resulting empty timeline reads as an absence of evidence rather
|
|
18
|
+
* than as a mistyped window.
|
|
19
|
+
*
|
|
20
|
+
* Resolution errs toward reading more rather than less: a window starting at 04:45 still reads
|
|
21
|
+
* hour 04, because the evidence between 04:45 and 05:00 lives in that file. Over-reading costs a
|
|
22
|
+
* few rows the correlation ignores; under-reading reports an absence the capture would have
|
|
23
|
+
* contradicted.
|
|
24
|
+
*
|
|
25
|
+
* `now` is a parameter rather than read from the clock, so the relative forms are testable and a
|
|
26
|
+
* run can be reproduced.
|
|
27
|
+
*/
|
|
28
|
+
export declare function parseWindow(interval: string, now?: number): Window;
|
|
29
|
+
//# sourceMappingURL=parseWindow.d.ts.map
|