@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
package/README.md
CHANGED
|
@@ -29,6 +29,24 @@ A Salesforce CLI (`sf`) plugin that runs a complete, **read-only** security audi
|
|
|
29
29
|
sf plugins install @cclabsnz/sf-audit
|
|
30
30
|
```
|
|
31
31
|
|
|
32
|
+
**You will be warned that this plugin is not digitally signed.** That is expected, and it is not a judgement on this plugin. Salesforce's signature verification only accepts public keys served from `developer.salesforce.com`, so no third-party plugin can satisfy it: every community plugin in the ecosystem produces the same prompt. Answer `y` to continue.
|
|
33
|
+
|
|
34
|
+
Since "trust us" is a poor answer from a tool that authenticates against your production org, the guarantees this project offers are ones you can check yourself rather than take on faith. Releases carry signed npm provenance, so you can confirm the published tarball was built from the exact public commit, and the read-only promise is enforced by a test that fails the build if a single write path appears in the source:
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
npm audit signatures # reports "verified attestations" for @cclabsnz/sf-audit
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
See [Trust & verification](#trust--verification) for the full list, including the no-network-egress guard and the independent scans.
|
|
41
|
+
|
|
42
|
+
For CI or any unattended install, where an interactive prompt would hang the job, allowlist the package on the machine doing the installing:
|
|
43
|
+
|
|
44
|
+
```jsonc
|
|
45
|
+
// macOS and Linux: ~/.config/sf/unsignedPluginAllowList.json
|
|
46
|
+
// Windows: %LOCALAPPDATA%\sf\unsignedPluginAllowList.json
|
|
47
|
+
["@cclabsnz/sf-audit"]
|
|
48
|
+
```
|
|
49
|
+
|
|
32
50
|
Or, for local development:
|
|
33
51
|
|
|
34
52
|
```bash
|
|
@@ -586,6 +604,168 @@ sfelf-triage analyze ~/.sf/event-baseline/<orgId> # triage (companion)
|
|
|
586
604
|
|
|
587
605
|
See the [sfelf-triage README](https://github.com/cclabsnz/sfelf-triage#readme) for install and usage.
|
|
588
606
|
|
|
607
|
+
## Forensic timeline
|
|
608
|
+
|
|
609
|
+
Salesforce splits one actor's activity across many event types, and each carries a different
|
|
610
|
+
subset of identifying fields — so no single log answers *"what did this actor do"*. Filtering by
|
|
611
|
+
IP finds the requests but misses every SOQL execution, because the query log has no `CLIENT_IP`
|
|
612
|
+
column at all. Filtering by user finds everything the *guest* user did, which on a community is
|
|
613
|
+
everyone.
|
|
614
|
+
|
|
615
|
+
`sf audit timeline` correlates a seed across every captured event type and writes a defensible
|
|
616
|
+
timeline:
|
|
617
|
+
|
|
618
|
+
```bash
|
|
619
|
+
sf audit timeline --window 2026-08-02T04:00Z/PT1H --seed ip:203.0.113.50
|
|
620
|
+
```
|
|
621
|
+
|
|
622
|
+
It runs **entirely offline** against captures written by `sf audit events pull` — no org
|
|
623
|
+
connection is opened, so it still works long after the org's retention window has expired or its
|
|
624
|
+
credentials have been revoked. The org id is inferred from the capture directory when only one
|
|
625
|
+
org has been captured.
|
|
626
|
+
|
|
627
|
+
### What it will not do
|
|
628
|
+
|
|
629
|
+
Cross-event correlation is easy to get confidently wrong, and a wrong answer here reads as
|
|
630
|
+
evidence. Two rules are enforced and both are visible in the output:
|
|
631
|
+
|
|
632
|
+
- **A blank field is never a join key.** A blank `REQUEST_ID` used as a key stops identifying
|
|
633
|
+
anything and starts matching every other row whose value is also blank — quietly attributing
|
|
634
|
+
strangers' sessions to your actor.
|
|
635
|
+
- **A shared identity is not expanded.** A community guest user can stand for hundreds of
|
|
636
|
+
distinct visitors. Expanding through it would present the whole crowd's activity as one
|
|
637
|
+
actor's, so it is refused by default and the refusal is reported with its evidence:
|
|
638
|
+
|
|
639
|
+
```
|
|
640
|
+
Expansion refused: userId 005xx0000000000 is shared by 1371 distinct addresses
|
|
641
|
+
(threshold 8). Override with --allow-shared-identity.
|
|
642
|
+
```
|
|
643
|
+
|
|
644
|
+
Every output also leads with what was actually captured, because *"no rows matched"* means two
|
|
645
|
+
entirely different things — the actor did nothing, or nobody captured the hour they did it in:
|
|
646
|
+
|
|
647
|
+
```
|
|
648
|
+
Window — coverage INCOMPLETE
|
|
649
|
+
captured AuraRequest, ListViewEvent
|
|
650
|
+
MISSING LightningInteraction (not-in-core-set)
|
|
651
|
+
MISSING GuestUserAnomalyEventStore (storage-disabled)
|
|
652
|
+
|
|
653
|
+
No activity in captured sources. Coverage incomplete — 2 sources missing.
|
|
654
|
+
```
|
|
655
|
+
|
|
656
|
+
**Flags:**
|
|
657
|
+
|
|
658
|
+
| Flag | Description | Default |
|
|
659
|
+
|------|-------------|---------|
|
|
660
|
+
| `--window` | When to look — see below | required |
|
|
661
|
+
| `--seed` | Typed and repeatable: `ip:` `user:` `session:` `request:` `login:` `transaction:` `event:` | *(whole window)* |
|
|
662
|
+
| `--org-id` | Which captured org to read | *(inferred when unambiguous)* |
|
|
663
|
+
| `--input` | Capture base directory | `~/.sf/event-baseline` |
|
|
664
|
+
| `--allow-shared-identity` | Expand through identities shared by many actors | `false` |
|
|
665
|
+
| `--max-cardinality` | Distinct-actor ceiling above which a key is not expanded | `8` |
|
|
666
|
+
| `--format` | Comma-separated: `csv,json,md` | all three |
|
|
667
|
+
| `--output` | Directory to write into | `.` |
|
|
668
|
+
|
|
669
|
+
**Finding your way in.** Two things you do not have to know up front. Omit `--seed` and you get
|
|
670
|
+
the whole window, uncorrelated — which is where you look to find something worth seeding on.
|
|
671
|
+
Ask for a window that was never captured and the error lists the days that *were*:
|
|
672
|
+
|
|
673
|
+
```
|
|
674
|
+
No captures for 2026-07-01 under ~/.sf/event-baseline/00Dxx0000000000EAA.
|
|
675
|
+
|
|
676
|
+
Captured days for this org:
|
|
677
|
+
2026-08-01 11 event type(s), whole day
|
|
678
|
+
2026-08-02 14 event type(s), whole day
|
|
679
|
+
|
|
680
|
+
Try: --window 2026-08-02
|
|
681
|
+
```
|
|
682
|
+
|
|
683
|
+
**Saying when.** `--window` takes whichever form is nearest to hand — you should not have to
|
|
684
|
+
compose an ISO 8601 interval while an incident is running:
|
|
685
|
+
|
|
686
|
+
| You type | You get |
|
|
687
|
+
|---|---|
|
|
688
|
+
| `yesterday` | the whole of yesterday, UTC |
|
|
689
|
+
| `today` | midnight UTC until now |
|
|
690
|
+
| `2h` · `90m` | the last two hours; the last ninety minutes |
|
|
691
|
+
| `2026-08-02` | that whole day — the shape the free tier captures in |
|
|
692
|
+
| `2026-08-02T04:17Z` | the hour containing that instant, for a timestamp pasted from an alert |
|
|
693
|
+
| `2026-08-02T04:00Z/PT1H` | an exact interval, start and duration |
|
|
694
|
+
| `2026-08-02T04:00Z/2026-08-02T06:00Z` | an exact interval, start and end |
|
|
695
|
+
|
|
696
|
+
Times are UTC, because every capture is stored in UTC — a bare timestamp with no zone is read
|
|
697
|
+
that way rather than as local time. A window has to fall inside one UTC day; one that crosses
|
|
698
|
+
midnight is refused, and the error names the two runs that would cover it.
|
|
699
|
+
|
|
700
|
+
```bash
|
|
701
|
+
# Follow one address across every captured event type
|
|
702
|
+
sf audit timeline --window yesterday --seed ip:203.0.113.50
|
|
703
|
+
|
|
704
|
+
# Start from a request and walk outward, including its Apex cascade
|
|
705
|
+
sf audit timeline --window 2026-08-02T04:00Z/PT1H --seed request:abc123
|
|
706
|
+
|
|
707
|
+
# Several orgs captured — name the one to read
|
|
708
|
+
sf audit timeline --org-id 00Dxx0000000000EAA --window 2026-08-02T04:00Z/PT2H --seed user:005xx000000000
|
|
709
|
+
|
|
710
|
+
# Machine-readable only, into an evidence directory
|
|
711
|
+
sf audit timeline --window 2026-08-02T04:00Z/PT1H --seed ip:203.0.113.50 \
|
|
712
|
+
--format json --output ./evidence/incident-2026-08-02
|
|
713
|
+
```
|
|
714
|
+
|
|
715
|
+
**Outputs:**
|
|
716
|
+
|
|
717
|
+
| File | Contents |
|
|
718
|
+
|------|----------|
|
|
719
|
+
| `timeline.csv` | The correlated rows, one schema across all sources, chronological |
|
|
720
|
+
| `timeline.json` | The same rows plus the provenance — seeds, every key expanded through, and every refusal |
|
|
721
|
+
| `summary.md` | Narrative: coverage, per-type counts, what tied each row in, refusals, and whether records left |
|
|
722
|
+
|
|
723
|
+
Each row records **which join key tied it in**, so attribution is checkable rather than asserted.
|
|
724
|
+
The `rows_processed` and `records_returned` columns are populated only from Real-Time Event
|
|
725
|
+
objects — no `EventLogFile` type records them — and when none were captured the summary says the
|
|
726
|
+
question is unanswerable rather than going quiet, since silence there reads as *"nothing left"*.
|
|
727
|
+
|
|
728
|
+
### Checking a claim against its control group
|
|
729
|
+
|
|
730
|
+
When a seed's rows share an identity with many other people — a community guest user, a shared
|
|
731
|
+
integration account — *"this actor did X"* needs something to be checked against. Otherwise the
|
|
732
|
+
claim is unfalsifiable: nobody can tell your 15 rows from the other 600 behind the same user.
|
|
733
|
+
|
|
734
|
+
The refusal message already gives you the denominator:
|
|
735
|
+
|
|
736
|
+
```
|
|
737
|
+
Expansion refused: userId 005xx000000000 is shared by 1371 distinct addresses (threshold 8).
|
|
738
|
+
```
|
|
739
|
+
|
|
740
|
+
To see the peer set itself, run the command a second time seeded on that identity, with expansion
|
|
741
|
+
allowed:
|
|
742
|
+
|
|
743
|
+
```bash
|
|
744
|
+
# 1. The claim — narrow, seeded on something that identifies one actor
|
|
745
|
+
sf audit timeline --window 2026-08-02T04:00Z/PT1H --seed request:REQ000000 \
|
|
746
|
+
--output ./evidence/actor
|
|
747
|
+
|
|
748
|
+
# 2. The control — everyone behind the identity those rows share
|
|
749
|
+
sf audit timeline --window 2026-08-02T04:00Z/PT1H --seed user:005xx000000000 \
|
|
750
|
+
--allow-shared-identity --output ./evidence/peers
|
|
751
|
+
```
|
|
752
|
+
|
|
753
|
+
Both use the same schema, so they concatenate and diff directly:
|
|
754
|
+
|
|
755
|
+
```bash
|
|
756
|
+
# How much of the identity's activity is actually your actor?
|
|
757
|
+
# (tail -n +2 skips the header row, so these are data rows)
|
|
758
|
+
echo "actor: $(tail -n +2 ./evidence/actor/timeline.csv | wc -l)"
|
|
759
|
+
echo "control: $(tail -n +2 ./evidence/peers/timeline.csv | wc -l)"
|
|
760
|
+
```
|
|
761
|
+
|
|
762
|
+
An actor accounting for 15 of 603 rows — 2.5%, and separable by request id — is a different
|
|
763
|
+
finding from one accounting for 580 of 603. The second command is what lets a reviewer tell
|
|
764
|
+
which they are looking at, rather than taking the first on trust.
|
|
765
|
+
|
|
766
|
+
> `sf audit timeline` adds **no checks** and does not affect the security grade. It is an
|
|
767
|
+
> investigation command, not a `SecurityCheck`.
|
|
768
|
+
|
|
589
769
|
## Connected-app least-privilege
|
|
590
770
|
|
|
591
771
|
Connected-app over-privilege was at the centre of the 2025-2026 wave of Salesforce data-theft
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { ApexRepository } from '@cclabsnz/sf-core';
|
|
2
|
+
import { referencesCallout } from '../../lib/apexRefs.js';
|
|
2
3
|
export class NamedCredentialsCheck {
|
|
3
4
|
id = 'named-credentials';
|
|
4
5
|
name = 'Named Credentials';
|
|
@@ -54,9 +55,11 @@ export class NamedCredentialsCheck {
|
|
|
54
55
|
const combinedApexSource = apexBodies.map((c) => c.body).join('\n');
|
|
55
56
|
const unusedCredentials = records.filter((r) => {
|
|
56
57
|
// Named credentials are referenced as callout:DeveloperName or callout:MasterLabel
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
58
|
+
// Literal search, not a pattern built from the credential's own name: MasterLabel is free
|
|
59
|
+
// text from Setup, and a bracket in it used to crash the check while a quantifier quietly
|
|
60
|
+
// matched the wrong thing.
|
|
61
|
+
return (!referencesCallout(combinedApexSource, r.DeveloperName) &&
|
|
62
|
+
!referencesCallout(combinedApexSource, r.MasterLabel.replace(/\s+/g, '_')));
|
|
60
63
|
});
|
|
61
64
|
const usedCredentials = records.filter((r) => !unusedCredentials.includes(r));
|
|
62
65
|
// Inventory finding
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
import { SfCommand } from '@salesforce/sf-plugins-core';
|
|
2
|
+
export interface TimelineResult {
|
|
3
|
+
orgId: string;
|
|
4
|
+
window: string;
|
|
5
|
+
rows: number;
|
|
6
|
+
coverage: string;
|
|
7
|
+
refusals: number;
|
|
8
|
+
written: string[];
|
|
9
|
+
}
|
|
10
|
+
export default class AuditTimelineCommand extends SfCommand<TimelineResult> {
|
|
11
|
+
static summary: string;
|
|
12
|
+
static description: string;
|
|
13
|
+
static examples: string[];
|
|
14
|
+
static flags: {
|
|
15
|
+
'org-id': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
|
|
16
|
+
input: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
|
|
17
|
+
window: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
|
|
18
|
+
seed: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
|
|
19
|
+
'allow-shared-identity': import("@oclif/core/interfaces").BooleanFlag<boolean>;
|
|
20
|
+
'max-cardinality': import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
|
|
21
|
+
format: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
|
|
22
|
+
output: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
|
|
23
|
+
};
|
|
24
|
+
run(): Promise<TimelineResult>;
|
|
25
|
+
}
|
|
26
|
+
//# sourceMappingURL=timeline.d.ts.map
|
|
@@ -0,0 +1,189 @@
|
|
|
1
|
+
// src/commands/audit/timeline.ts
|
|
2
|
+
import * as fs from 'node:fs';
|
|
3
|
+
import * as path from 'node:path';
|
|
4
|
+
import { SfCommand, Flags } from '@salesforce/sf-plugins-core';
|
|
5
|
+
import { EventBaselineStore } from '@cclabsnz/sf-core';
|
|
6
|
+
import { parseWindow } from '../../timeline/parseWindow.js';
|
|
7
|
+
import { loadCaptures, resolveOrgId, describeCaptures } from '../../timeline/loadCaptures.js';
|
|
8
|
+
import { assessCoverage } from '../../timeline/CaptureIndex.js';
|
|
9
|
+
import { correlate, DEFAULT_MAX_CARDINALITY } from '../../timeline/CorrelationEngine.js';
|
|
10
|
+
import { normaliseRow } from '../../timeline/normalise.js';
|
|
11
|
+
import { renderCsv, renderJson, renderSummary } from '../../timeline/render.js';
|
|
12
|
+
/** `ip:1.2.3.4` — typed rather than inferred, so a value is never guessed at. */
|
|
13
|
+
const SEED_PREFIXES = {
|
|
14
|
+
ip: 'clientIp',
|
|
15
|
+
user: 'userId',
|
|
16
|
+
session: 'sessionKey',
|
|
17
|
+
request: 'requestId',
|
|
18
|
+
login: 'loginKey',
|
|
19
|
+
transaction: 'transactionId',
|
|
20
|
+
event: 'eventIdentifier',
|
|
21
|
+
};
|
|
22
|
+
function parseSeed(raw) {
|
|
23
|
+
const at = raw.indexOf(':');
|
|
24
|
+
const prefix = at === -1 ? '' : raw.slice(0, at);
|
|
25
|
+
const type = SEED_PREFIXES[prefix];
|
|
26
|
+
if (!type) {
|
|
27
|
+
throw new Error(`Unrecognised seed "${raw}". Use one of ${Object.keys(SEED_PREFIXES).map((p) => `${p}:`).join(' ')} — ` +
|
|
28
|
+
'for example ip:203.0.113.50. Types are explicit so a value is never guessed at.');
|
|
29
|
+
}
|
|
30
|
+
const value = raw.slice(at + 1).trim();
|
|
31
|
+
if (value === '')
|
|
32
|
+
throw new Error(`Seed "${raw}" has no value.`);
|
|
33
|
+
return { type, value };
|
|
34
|
+
}
|
|
35
|
+
export default class AuditTimelineCommand extends SfCommand {
|
|
36
|
+
static summary = 'Reconstruct one actor\'s activity across event types from local captures';
|
|
37
|
+
static description = 'Correlates a seed (an address, user, session, request or transaction) across every captured EventLogFile type ' +
|
|
38
|
+
'and Real-Time Event object, and writes a defensible timeline. Runs entirely offline against captures written ' +
|
|
39
|
+
'by `sf audit events pull` — it opens no org connection, so it still works long after the org\'s retention ' +
|
|
40
|
+
'window has expired or its credentials have been revoked. Attribution is recorded per row, expansion through ' +
|
|
41
|
+
'shared identities is refused by default, and every output states what was captured so an empty result is ' +
|
|
42
|
+
'never mistaken for a quiet one.';
|
|
43
|
+
static examples = [
|
|
44
|
+
'<%= config.bin %> <%= command.id %> --window yesterday --seed ip:203.0.113.50',
|
|
45
|
+
'<%= config.bin %> <%= command.id %> --window 2h --seed user:005xx000000000',
|
|
46
|
+
'<%= config.bin %> <%= command.id %> --window 2026-08-02 --seed request:REQ000000',
|
|
47
|
+
'<%= config.bin %> <%= command.id %> --window 2026-08-02T04:00Z/PT1H --seed ip:203.0.113.50',
|
|
48
|
+
'<%= config.bin %> <%= command.id %> --org-id 00Dxx0000000000EAA --window 2026-08-02T04:00Z/PT1H --seed ip:203.0.113.50',
|
|
49
|
+
'<%= config.bin %> <%= command.id %> --org-id 00Dxx0000000000EAA --window 2026-08-02T04:00Z/PT1H --seed user:005xx1 --allow-shared-identity',
|
|
50
|
+
'<%= config.bin %> <%= command.id %> --org-id 00Dxx0000000000EAA --window 2026-08-02T04:00Z/PT2H --seed request:abc --format json',
|
|
51
|
+
];
|
|
52
|
+
static flags = {
|
|
53
|
+
// Deliberately not requiredOrg(): this command reads disk and must not need, or take, a
|
|
54
|
+
// live connection. The org id names which capture directory to read, and is optional
|
|
55
|
+
// because the capture store is keyed by it — with one org captured there is nothing to
|
|
56
|
+
// disambiguate, and making someone retype an eighteen-character id they cannot check by
|
|
57
|
+
// eye only invites a typo that reads back as "no captures found".
|
|
58
|
+
'org-id': Flags.string({
|
|
59
|
+
summary: 'Org id whose captures to read. Inferred when only one org has captures. No org connection is opened.',
|
|
60
|
+
}),
|
|
61
|
+
input: Flags.string({
|
|
62
|
+
summary: 'Capture base directory. Defaults to the events-pull location.',
|
|
63
|
+
}),
|
|
64
|
+
window: Flags.string({
|
|
65
|
+
summary: 'When to look. yesterday | today | 2h | 90m | 2026-08-02 (whole day) | ' +
|
|
66
|
+
'2026-08-02T04:17Z (that hour) | 2026-08-02T04:00Z/PT1H (exact). UTC, within one day.',
|
|
67
|
+
required: true,
|
|
68
|
+
helpValue: 'yesterday',
|
|
69
|
+
}),
|
|
70
|
+
seed: Flags.string({
|
|
71
|
+
summary: 'Typed seed, repeatable: ip: user: session: request: transaction: event:',
|
|
72
|
+
multiple: true,
|
|
73
|
+
helpValue: 'ip:203.0.113.50',
|
|
74
|
+
}),
|
|
75
|
+
'allow-shared-identity': Flags.boolean({
|
|
76
|
+
summary: 'Expand through identities shared by many actors. Off by default.',
|
|
77
|
+
default: false,
|
|
78
|
+
}),
|
|
79
|
+
'max-cardinality': Flags.integer({
|
|
80
|
+
summary: 'Distinct-actor ceiling above which a key is not expanded.',
|
|
81
|
+
default: DEFAULT_MAX_CARDINALITY,
|
|
82
|
+
}),
|
|
83
|
+
format: Flags.string({
|
|
84
|
+
summary: 'Comma-separated: csv,json,md. All three by default.',
|
|
85
|
+
default: 'csv,json,md',
|
|
86
|
+
}),
|
|
87
|
+
output: Flags.string({
|
|
88
|
+
summary: 'Directory to write the timeline into.',
|
|
89
|
+
default: '.',
|
|
90
|
+
}),
|
|
91
|
+
};
|
|
92
|
+
async run() {
|
|
93
|
+
const { flags } = await this.parse(AuditTimelineCommand);
|
|
94
|
+
const window = parseWindow(flags.window);
|
|
95
|
+
const seeds = (flags.seed ?? []).map(parseSeed);
|
|
96
|
+
const base = flags.input ?? EventBaselineStore.defaultRoot();
|
|
97
|
+
const orgId = resolveOrgId(base, flags['org-id']);
|
|
98
|
+
const loaded = loadCaptures({
|
|
99
|
+
base, orgId, date: window.date, hours: window.hours,
|
|
100
|
+
startMs: window.startMs, endMs: window.endMs,
|
|
101
|
+
});
|
|
102
|
+
// Fail fast rather than reporting a confident emptiness. An operator who has not captured
|
|
103
|
+
// the window needs the command that captures it, not a clean bill of health — and, more
|
|
104
|
+
// usefully, the windows that *are* on disk, so they are not sent to re-pull data they
|
|
105
|
+
// already have under a date they guessed wrong.
|
|
106
|
+
if (!loaded.windowPresent) {
|
|
107
|
+
const available = describeCaptures(base, orgId);
|
|
108
|
+
const lines = [`No captures for ${flags.window} under ${path.join(base, orgId)}.`];
|
|
109
|
+
if (available.length === 0) {
|
|
110
|
+
lines.push('', 'Nothing is captured for this org yet:', ' sf audit events pull --target-org <alias>');
|
|
111
|
+
}
|
|
112
|
+
else {
|
|
113
|
+
lines.push('', 'Captured days for this org:');
|
|
114
|
+
for (const day of available) {
|
|
115
|
+
const hours = day.hours.length > 0 ? `hours ${day.hours.join(',')}` : 'whole day';
|
|
116
|
+
lines.push(` ${day.date} ${String(day.types).padStart(2)} event type(s), ${hours}`);
|
|
117
|
+
}
|
|
118
|
+
lines.push('', `Try: --window ${available[available.length - 1].date}`);
|
|
119
|
+
}
|
|
120
|
+
throw new Error(lines.join('\n'));
|
|
121
|
+
}
|
|
122
|
+
const coverage = assessCoverage({ coverage: loaded.coverage });
|
|
123
|
+
const result = correlate(loaded.rows, seeds, {
|
|
124
|
+
maxCardinality: flags['max-cardinality'],
|
|
125
|
+
allowSharedIdentity: flags['allow-shared-identity'],
|
|
126
|
+
});
|
|
127
|
+
const rows = result.rows.map((correlated, i) => normaliseRow(correlated.row, {
|
|
128
|
+
seq: i + 1,
|
|
129
|
+
attribution: correlated.attribution,
|
|
130
|
+
source: correlated.row.__source ?? 'EventLogFile',
|
|
131
|
+
}));
|
|
132
|
+
const output = {
|
|
133
|
+
window: flags.window,
|
|
134
|
+
seeds,
|
|
135
|
+
rows,
|
|
136
|
+
refusals: result.refusals,
|
|
137
|
+
expandedThrough: result.expandedThrough,
|
|
138
|
+
coverage,
|
|
139
|
+
};
|
|
140
|
+
const formats = new Set(flags.format.split(',').map((f) => f.trim().toLowerCase()).filter(Boolean));
|
|
141
|
+
fs.mkdirSync(flags.output, { recursive: true });
|
|
142
|
+
const written = [];
|
|
143
|
+
const write = (name, body) => {
|
|
144
|
+
const target = path.join(flags.output, name);
|
|
145
|
+
fs.writeFileSync(target, body, 'utf-8');
|
|
146
|
+
written.push(target);
|
|
147
|
+
};
|
|
148
|
+
if (formats.has('csv'))
|
|
149
|
+
write('timeline.csv', renderCsv(output));
|
|
150
|
+
if (formats.has('json'))
|
|
151
|
+
write('timeline.json', renderJson(output));
|
|
152
|
+
if (formats.has('md'))
|
|
153
|
+
write('summary.md', renderSummary(output));
|
|
154
|
+
// Coverage first on the console too, for the same reason it leads the file outputs.
|
|
155
|
+
if (!flags['org-id'])
|
|
156
|
+
this.log(`Org: ${orgId} (only org with captures under ${base})`);
|
|
157
|
+
if (seeds.length === 0) {
|
|
158
|
+
// Said plainly, because an uncorrelated window looks exactly like a correlated one in the
|
|
159
|
+
// output and the difference is the whole basis for trusting it.
|
|
160
|
+
this.log('No --seed given: showing the whole window, uncorrelated. Seed with ip: user: session: request: to follow one actor.');
|
|
161
|
+
}
|
|
162
|
+
this.log(coverage.banner());
|
|
163
|
+
this.log('');
|
|
164
|
+
this.log(coverage.statement(rows.length));
|
|
165
|
+
if (loaded.malformed > 0 || loaded.unreadable > 0) {
|
|
166
|
+
this.log(`Skipped ${loaded.malformed} unparseable line(s) and ${loaded.unreadable} unreadable file(s).`);
|
|
167
|
+
}
|
|
168
|
+
if (loaded.undated > 0) {
|
|
169
|
+
// Kept rather than dropped, and said out loud: these rows could not be placed in or out
|
|
170
|
+
// of the window, so a reader needs to know they are here on sufferance.
|
|
171
|
+
this.log(`${loaded.undated} row(s) had no readable timestamp and were kept regardless of the window.`);
|
|
172
|
+
}
|
|
173
|
+
for (const refusal of result.refusals) {
|
|
174
|
+
this.log(`Expansion refused: ${refusal.type} ${refusal.value} is shared by ${refusal.cardinality} ` +
|
|
175
|
+
`distinct addresses (threshold ${refusal.threshold}). Override with --allow-shared-identity.`);
|
|
176
|
+
}
|
|
177
|
+
for (const target of written)
|
|
178
|
+
this.log(`Written: ${target}`);
|
|
179
|
+
return {
|
|
180
|
+
orgId,
|
|
181
|
+
window: flags.window,
|
|
182
|
+
rows: rows.length,
|
|
183
|
+
coverage: coverage.state,
|
|
184
|
+
refusals: result.refusals.length,
|
|
185
|
+
written,
|
|
186
|
+
};
|
|
187
|
+
}
|
|
188
|
+
}
|
|
189
|
+
//# sourceMappingURL=timeline.js.map
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Does `source` reference `callout:<name>` as a whole token?
|
|
3
|
+
*
|
|
4
|
+
* Apex names a Named Credential as `callout:MyCredential`. Matching that used to interpolate the
|
|
5
|
+
* credential's name into a regular expression, which was the wrong tool twice over: MasterLabel
|
|
6
|
+
* is free text from Setup, so an unescaped bracket crashed the check and an unescaped quantifier
|
|
7
|
+
* quietly matched something other than the credential. Escaping fixed the behaviour but left a
|
|
8
|
+
* pattern compiled from customer data on every call.
|
|
9
|
+
*
|
|
10
|
+
* A literal search cannot misbehave whatever the label contains, and there is nothing here a
|
|
11
|
+
* regular expression was buying: the name is matched as text, and the trailing check is the same
|
|
12
|
+
* word boundary `\b` would have applied.
|
|
13
|
+
*/
|
|
14
|
+
const WORD = /[a-z0-9_]/;
|
|
15
|
+
export function referencesCallout(source, name) {
|
|
16
|
+
if (name.length === 0)
|
|
17
|
+
return false;
|
|
18
|
+
// Case-insensitive, matching Apex's own treatment of these references.
|
|
19
|
+
const haystack = source.toLowerCase();
|
|
20
|
+
const needle = `callout:${name}`.toLowerCase();
|
|
21
|
+
for (let i = haystack.indexOf(needle); i !== -1; i = haystack.indexOf(needle, i + 1)) {
|
|
22
|
+
const next = haystack[i + needle.length];
|
|
23
|
+
// End of source, or a non-word character, is a boundary — so `callout:Foo` does not count
|
|
24
|
+
// as a reference to a credential named `Fo`.
|
|
25
|
+
if (next === undefined || !WORD.test(next))
|
|
26
|
+
return true;
|
|
27
|
+
}
|
|
28
|
+
return false;
|
|
29
|
+
}
|
|
30
|
+
//# sourceMappingURL=apexRefs.js.map
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
import type { CaptureCoverage, SkipReason } from '@cclabsnz/sf-core';
|
|
2
|
+
export interface CoverageInput {
|
|
3
|
+
/** The manifest for the window, or `undefined` when none was found. */
|
|
4
|
+
coverage: CaptureCoverage | undefined;
|
|
5
|
+
}
|
|
6
|
+
/** A source that was asked for and is not in the data. */
|
|
7
|
+
export interface MissingSource {
|
|
8
|
+
source: string;
|
|
9
|
+
reason: SkipReason | string;
|
|
10
|
+
}
|
|
11
|
+
export type CoverageState = 'complete' | 'incomplete' | 'unknown';
|
|
12
|
+
export interface CoverageAssessment {
|
|
13
|
+
state: CoverageState;
|
|
14
|
+
missing: MissingSource[];
|
|
15
|
+
capturedSources: string[];
|
|
16
|
+
/** The sentence that qualifies a row count. Never composed by the caller. */
|
|
17
|
+
statement(rowCount: number): string;
|
|
18
|
+
/** The multi-line header every output leads with. */
|
|
19
|
+
banner(): string;
|
|
20
|
+
}
|
|
21
|
+
/**
|
|
22
|
+
* Decide what the capture actually covers, and say so in words the reader cannot misread.
|
|
23
|
+
*
|
|
24
|
+
* This is the most important behaviour in the command. Every other part can be wrong and look
|
|
25
|
+
* wrong; this one can be wrong and look like reassurance. "No rows matched" means either the
|
|
26
|
+
* actor did nothing or nobody captured the hour — and those are opposite conclusions in an
|
|
27
|
+
* investigation.
|
|
28
|
+
*
|
|
29
|
+
* The wording therefore belongs here, derived from state, rather than being left to whichever
|
|
30
|
+
* renderer happens to be printing. A caller cannot accidentally report an unqualified absence,
|
|
31
|
+
* because it never gets to phrase one.
|
|
32
|
+
*/
|
|
33
|
+
export declare function assessCoverage(input: CoverageInput): CoverageAssessment;
|
|
34
|
+
//# sourceMappingURL=CaptureIndex.d.ts.map
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A skip that means the data is present, not absent.
|
|
3
|
+
*
|
|
4
|
+
* Dedup on a re-run reports the type as skipped because it was already pulled — the rows are on
|
|
5
|
+
* disk from an earlier capture, so treating this as missing coverage would report a gap that
|
|
6
|
+
* does not exist and push an operator into re-pulling data they already have.
|
|
7
|
+
*/
|
|
8
|
+
const SKIP_MEANS_PRESENT = new Set(['already-captured']);
|
|
9
|
+
/**
|
|
10
|
+
* Decide what the capture actually covers, and say so in words the reader cannot misread.
|
|
11
|
+
*
|
|
12
|
+
* This is the most important behaviour in the command. Every other part can be wrong and look
|
|
13
|
+
* wrong; this one can be wrong and look like reassurance. "No rows matched" means either the
|
|
14
|
+
* actor did nothing or nobody captured the hour — and those are opposite conclusions in an
|
|
15
|
+
* investigation.
|
|
16
|
+
*
|
|
17
|
+
* The wording therefore belongs here, derived from state, rather than being left to whichever
|
|
18
|
+
* renderer happens to be printing. A caller cannot accidentally report an unqualified absence,
|
|
19
|
+
* because it never gets to phrase one.
|
|
20
|
+
*/
|
|
21
|
+
export function assessCoverage(input) {
|
|
22
|
+
const { coverage } = input;
|
|
23
|
+
if (!coverage) {
|
|
24
|
+
// Silence is not evidence of completeness. An absent manifest tells us less than an empty
|
|
25
|
+
// one, and must never read like "we looked and found nothing".
|
|
26
|
+
return {
|
|
27
|
+
state: 'unknown',
|
|
28
|
+
missing: [],
|
|
29
|
+
capturedSources: [],
|
|
30
|
+
statement: (rowCount) => `${rowCount === 0 ? 'No' : String(rowCount)} matching row${rowCount === 1 ? '' : 's'} — ` +
|
|
31
|
+
'coverage UNKNOWN (no manifest). Absence here is not evidence of absence.',
|
|
32
|
+
banner: () => 'Window — coverage UNKNOWN (no manifest)\n' +
|
|
33
|
+
' Nothing is known about which sources were captured for this window.',
|
|
34
|
+
};
|
|
35
|
+
}
|
|
36
|
+
const missing = [
|
|
37
|
+
...coverage.elf.skipped
|
|
38
|
+
.filter((s) => !SKIP_MEANS_PRESENT.has(s.reason))
|
|
39
|
+
.map((s) => ({ source: s.type, reason: s.reason })),
|
|
40
|
+
...coverage.elf.failed.map((f) => ({ source: f.type, reason: f.reason })),
|
|
41
|
+
...coverage.rte.unavailable.map((u) => ({ source: u.object, reason: u.reason })),
|
|
42
|
+
// A query that could not run is coverage loss under another name — the type was requested
|
|
43
|
+
// and produced nothing, and the reason it produced nothing is not "there was nothing".
|
|
44
|
+
...coverage.accessErrors.map((e) => ({ source: e.scope, reason: e.reason })),
|
|
45
|
+
];
|
|
46
|
+
const capturedSources = [
|
|
47
|
+
...new Set([
|
|
48
|
+
...coverage.elf.captured.map((c) => c.type),
|
|
49
|
+
...coverage.elf.skipped.filter((s) => SKIP_MEANS_PRESENT.has(s.reason)).map((s) => s.type),
|
|
50
|
+
...coverage.rte.captured.map((c) => c.object),
|
|
51
|
+
]),
|
|
52
|
+
].sort();
|
|
53
|
+
const state = missing.length === 0 ? 'complete' : 'incomplete';
|
|
54
|
+
return {
|
|
55
|
+
state,
|
|
56
|
+
missing,
|
|
57
|
+
capturedSources,
|
|
58
|
+
statement(rowCount) {
|
|
59
|
+
const n = missing.length;
|
|
60
|
+
if (state === 'complete') {
|
|
61
|
+
return rowCount === 0
|
|
62
|
+
? 'No activity from this seed. Coverage complete.'
|
|
63
|
+
: `${rowCount} matching row${rowCount === 1 ? '' : 's'}. Coverage complete.`;
|
|
64
|
+
}
|
|
65
|
+
const qualifier = `Coverage incomplete — ${n} source${n === 1 ? '' : 's'} missing.`;
|
|
66
|
+
return rowCount === 0
|
|
67
|
+
? `No activity in captured sources. ${qualifier}`
|
|
68
|
+
: `${rowCount} matching row${rowCount === 1 ? '' : 's'} in captured sources. ${qualifier}`;
|
|
69
|
+
},
|
|
70
|
+
banner() {
|
|
71
|
+
const lines = [`Window — coverage ${state.toUpperCase()}`];
|
|
72
|
+
if (capturedSources.length > 0) {
|
|
73
|
+
lines.push(` captured ${capturedSources.join(', ')}`);
|
|
74
|
+
}
|
|
75
|
+
for (const m of missing) {
|
|
76
|
+
lines.push(` MISSING ${m.source} (${m.reason})`);
|
|
77
|
+
}
|
|
78
|
+
return lines.join('\n');
|
|
79
|
+
},
|
|
80
|
+
};
|
|
81
|
+
}
|
|
82
|
+
//# sourceMappingURL=CaptureIndex.js.map
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
import { type JoinKeyType } from './JoinKeys.js';
|
|
2
|
+
export type { JoinKeyType };
|
|
3
|
+
export interface CardinalityIndex {
|
|
4
|
+
/**
|
|
5
|
+
* How many distinct actors share this key value in the window.
|
|
6
|
+
*
|
|
7
|
+
* Zero means the value was never seen, or was seen only on rows that carry no client address
|
|
8
|
+
* — either way there is no evidence that it identifies anybody.
|
|
9
|
+
*/
|
|
10
|
+
cardinality(type: JoinKeyType, value: string): number;
|
|
11
|
+
}
|
|
12
|
+
/**
|
|
13
|
+
* Count distinct actors behind each join-key value across a window.
|
|
14
|
+
*
|
|
15
|
+
* This is the evidence for Invariant 2. Some keys identify a person and some identify a crowd,
|
|
16
|
+
* and the difference is not knowable from the key's name: REQUEST_ID is reliably 1:1, while a
|
|
17
|
+
* community guest USER_ID was measured at 1:1371 in a single hour. Expanding through the second
|
|
18
|
+
* turns one actor's timeline into every anonymous visitor's, attributed to one actor.
|
|
19
|
+
*
|
|
20
|
+
* Actors are counted as distinct client IPs rather than rows on purpose. Rows measure how busy a
|
|
21
|
+
* key was; IPs measure how many people stand behind it. A single actor making ten thousand
|
|
22
|
+
* requests must stay expandable, and ten actors sharing one key must not.
|
|
23
|
+
*
|
|
24
|
+
* The index only measures. Refusing to expand, and recording why, belongs to the engine — a
|
|
25
|
+
* timeline that was quietly bounded is as misleading as one that was over-attributed.
|
|
26
|
+
*/
|
|
27
|
+
export declare function buildCardinalityIndex(rows: ReadonlyArray<Record<string, unknown>>): CardinalityIndex;
|
|
28
|
+
//# sourceMappingURL=CardinalityIndex.d.ts.map
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
import { joinKeysOf, JOIN_KEY_TYPES } from './JoinKeys.js';
|
|
2
|
+
/**
|
|
3
|
+
* Count distinct actors behind each join-key value across a window.
|
|
4
|
+
*
|
|
5
|
+
* This is the evidence for Invariant 2. Some keys identify a person and some identify a crowd,
|
|
6
|
+
* and the difference is not knowable from the key's name: REQUEST_ID is reliably 1:1, while a
|
|
7
|
+
* community guest USER_ID was measured at 1:1371 in a single hour. Expanding through the second
|
|
8
|
+
* turns one actor's timeline into every anonymous visitor's, attributed to one actor.
|
|
9
|
+
*
|
|
10
|
+
* Actors are counted as distinct client IPs rather than rows on purpose. Rows measure how busy a
|
|
11
|
+
* key was; IPs measure how many people stand behind it. A single actor making ten thousand
|
|
12
|
+
* requests must stay expandable, and ten actors sharing one key must not.
|
|
13
|
+
*
|
|
14
|
+
* The index only measures. Refusing to expand, and recording why, belongs to the engine — a
|
|
15
|
+
* timeline that was quietly bounded is as misleading as one that was over-attributed.
|
|
16
|
+
*/
|
|
17
|
+
export function buildCardinalityIndex(rows) {
|
|
18
|
+
// type -> value -> set of distinct actor addresses
|
|
19
|
+
const actors = new Map();
|
|
20
|
+
for (const type of JOIN_KEY_TYPES)
|
|
21
|
+
actors.set(type, new Map());
|
|
22
|
+
for (const row of rows) {
|
|
23
|
+
const keys = joinKeysOf(row);
|
|
24
|
+
// Blank values already came back undefined, so nothing blank can accumulate a count.
|
|
25
|
+
const actor = keys.clientIp;
|
|
26
|
+
for (const type of JOIN_KEY_TYPES) {
|
|
27
|
+
const value = keys[type];
|
|
28
|
+
if (value === undefined)
|
|
29
|
+
continue;
|
|
30
|
+
const byValue = actors.get(type);
|
|
31
|
+
let seen = byValue.get(value);
|
|
32
|
+
if (!seen)
|
|
33
|
+
byValue.set(value, (seen = new Set()));
|
|
34
|
+
// A row with no usable address still registers the key's existence but contributes no
|
|
35
|
+
// actor — UniqueQuery carries no CLIENT_IP column at all, and counting it as an actor
|
|
36
|
+
// would inflate every key it touches.
|
|
37
|
+
if (actor !== undefined)
|
|
38
|
+
seen.add(actor);
|
|
39
|
+
}
|
|
40
|
+
}
|
|
41
|
+
return {
|
|
42
|
+
cardinality(type, value) {
|
|
43
|
+
return actors.get(type)?.get(value)?.size ?? 0;
|
|
44
|
+
},
|
|
45
|
+
};
|
|
46
|
+
}
|
|
47
|
+
//# sourceMappingURL=CardinalityIndex.js.map
|