@cclabsnz/sf-audit 1.6.1 → 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.
Files changed (198) hide show
  1. package/README.md +258 -5
  2. package/lib/apps/analyzeApps.d.ts +1 -1
  3. package/lib/apps/appResolver.d.ts +1 -1
  4. package/lib/apps/grantedAccess.d.ts +1 -1
  5. package/lib/chains/AttackChain.d.ts +1 -1
  6. package/lib/chains/namedChains.d.ts +1 -1
  7. package/lib/checks/CheckEngine.d.ts +1 -1
  8. package/lib/checks/SecurityCheck.d.ts +3 -3
  9. package/lib/checks/impl/AgentActionSurfaceCheck.d.ts +1 -1
  10. package/lib/checks/impl/AgentActionSurfaceCheck.js +1 -1
  11. package/lib/checks/impl/AgentChannelExposureCheck.d.ts +1 -1
  12. package/lib/checks/impl/AgentInventoryCheck.d.ts +1 -1
  13. package/lib/checks/impl/AgentInventoryCheck.js +1 -1
  14. package/lib/checks/impl/AgentMonitoringCoverageCheck.d.ts +1 -1
  15. package/lib/checks/impl/AgentUserPrivilegeCheck.d.ts +1 -1
  16. package/lib/checks/impl/AnonymousApexAuditCheck.d.ts +1 -1
  17. package/lib/checks/impl/ApexCrudFLSCheck.d.ts +1 -1
  18. package/lib/checks/impl/ApexLoggingCheck.d.ts +1 -1
  19. package/lib/checks/impl/ApexRestEndpointCheck.d.ts +1 -1
  20. package/lib/checks/impl/ApexSharingCheck.d.ts +1 -1
  21. package/lib/checks/impl/ApexSharingCheck.js +3 -2
  22. package/lib/checks/impl/ApiClientPermissionCheck.d.ts +1 -1
  23. package/lib/checks/impl/ApiLimitsCheck.d.ts +1 -1
  24. package/lib/checks/impl/AuditTrailCheck.d.ts +1 -1
  25. package/lib/checks/impl/AuthProvidersCheck.d.ts +1 -1
  26. package/lib/checks/impl/CertificateExpiryCheck.d.ts +1 -1
  27. package/lib/checks/impl/ClassicSitesCheck.d.ts +1 -1
  28. package/lib/checks/impl/CodeSecurityCheck.d.ts +1 -1
  29. package/lib/checks/impl/CodeSecurityCheck.js +5 -5
  30. package/lib/checks/impl/ConnectedAppInactivityCheck.d.ts +1 -1
  31. package/lib/checks/impl/ConnectedAppScopeCheck.d.ts +1 -1
  32. package/lib/checks/impl/ConnectedAppsCheck.d.ts +1 -1
  33. package/lib/checks/impl/ContentLinksCheck.d.ts +1 -1
  34. package/lib/checks/impl/CorsAllowlistCheck.d.ts +1 -1
  35. package/lib/checks/impl/CspTrustedSitesCheck.d.ts +1 -1
  36. package/lib/checks/impl/CustomLabelsCredentialCheck.d.ts +1 -1
  37. package/lib/checks/impl/CustomSettingsCheck.d.ts +1 -1
  38. package/lib/checks/impl/DataClassificationCheck.d.ts +1 -1
  39. package/lib/checks/impl/DataExportAccessCheck.d.ts +1 -1
  40. package/lib/checks/impl/DebugLogAccessCheck.d.ts +1 -1
  41. package/lib/checks/impl/DeploymentIdentityCheck.d.ts +1 -1
  42. package/lib/checks/impl/EmailSecurityCheck.d.ts +1 -1
  43. package/lib/checks/impl/EncryptionCoverageCheck.d.ts +1 -1
  44. package/lib/checks/impl/EnhancedDomainsCheck.d.ts +1 -1
  45. package/lib/checks/impl/EnhancedDomainsCheck.js +2 -2
  46. package/lib/checks/impl/EscalationPermsCheck.d.ts +1 -1
  47. package/lib/checks/impl/EventMonitoringCheck.d.ts +1 -1
  48. package/lib/checks/impl/EventMonitoringCheck.js +1 -1
  49. package/lib/checks/impl/ExperienceCloudSiteCheck.d.ts +1 -1
  50. package/lib/checks/impl/ExperienceCspCheck.d.ts +1 -1
  51. package/lib/checks/impl/ExternalCredentialsCheck.d.ts +1 -1
  52. package/lib/checks/impl/FailedLoginCheck.d.ts +1 -1
  53. package/lib/checks/impl/FieldHistoryTrackingCheck.d.ts +1 -1
  54. package/lib/checks/impl/FieldLevelSecurityCheck.d.ts +1 -1
  55. package/lib/checks/impl/FlowsWithoutSharingCheck.d.ts +1 -1
  56. package/lib/checks/impl/FlowsWithoutSharingCheck.js +10 -9
  57. package/lib/checks/impl/GuestApiAccessCheck.d.ts +1 -1
  58. package/lib/checks/impl/GuestExecutableApexCheck.d.ts +1 -1
  59. package/lib/checks/impl/GuestExecutableApexCheck.js +4 -3
  60. package/lib/checks/impl/GuestObjectExposureCheck.d.ts +1 -1
  61. package/lib/checks/impl/GuestRecordAccessPolicyCheck.d.ts +1 -1
  62. package/lib/checks/impl/GuestSiteOptionsCheck.d.ts +1 -1
  63. package/lib/checks/impl/GuestTrafficAnomalyCheck.d.ts +1 -1
  64. package/lib/checks/impl/GuestTrafficAnomalyCheck.js +1 -1
  65. package/lib/checks/impl/GuestUserAccessCheck.d.ts +1 -1
  66. package/lib/checks/impl/HardcodedCredentialsCheck.d.ts +1 -1
  67. package/lib/checks/impl/HardcodedCredentialsCheck.js +8 -1
  68. package/lib/checks/impl/HealthCheckCheck.d.ts +1 -1
  69. package/lib/checks/impl/HighAssuranceSessionCheck.d.ts +1 -1
  70. package/lib/checks/impl/InactiveUsersCheck.d.ts +1 -1
  71. package/lib/checks/impl/InstalledPackagesCheck.d.ts +1 -1
  72. package/lib/checks/impl/IntegrationUsersCheck.d.ts +1 -1
  73. package/lib/checks/impl/InternalUserMfaCheck.d.ts +1 -1
  74. package/lib/checks/impl/IpRestrictionsCheck.d.ts +1 -1
  75. package/lib/checks/impl/LegacyApiVersionCheck.d.ts +1 -1
  76. package/lib/checks/impl/LoginAccessPolicyCheck.d.ts +1 -1
  77. package/lib/checks/impl/LoginAnomalyCheck.d.ts +1 -1
  78. package/lib/checks/impl/LoginSessionCheck.d.ts +1 -1
  79. package/lib/checks/impl/MfaEnforcementCheck.d.ts +1 -1
  80. package/lib/checks/impl/MfaMethodStrengthCheck.d.ts +1 -1
  81. package/lib/checks/impl/MfaRegistrationCheck.d.ts +1 -1
  82. package/lib/checks/impl/MyDomainLoginPolicyCheck.d.ts +1 -1
  83. package/lib/checks/impl/NamedCredentialsCheck.d.ts +1 -1
  84. package/lib/checks/impl/NamedCredentialsCheck.js +13 -9
  85. package/lib/checks/impl/OutboundMessagesCheck.d.ts +1 -1
  86. package/lib/checks/impl/PasswordSessionPolicyCheck.d.ts +2 -2
  87. package/lib/checks/impl/PermissionsCheck.d.ts +1 -1
  88. package/lib/checks/impl/PrivilegedAccessCheck.d.ts +1 -1
  89. package/lib/checks/impl/PublicContentExposureCheck.d.ts +1 -1
  90. package/lib/checks/impl/PublicGroupSharingCheck.d.ts +1 -1
  91. package/lib/checks/impl/ReleaseUpdatesCheck.d.ts +1 -1
  92. package/lib/checks/impl/RemoteSitesCheck.d.ts +1 -1
  93. package/lib/checks/impl/ReportFolderAccessCheck.d.ts +1 -1
  94. package/lib/checks/impl/SandboxDataMaskingCheck.d.ts +1 -1
  95. package/lib/checks/impl/ScheduledApexCheck.d.ts +1 -1
  96. package/lib/checks/impl/SeparationOfDutiesCheck.d.ts +1 -1
  97. package/lib/checks/impl/SessionHardeningCheck.d.ts +1 -1
  98. package/lib/checks/impl/SharingModelCheck.d.ts +1 -1
  99. package/lib/checks/impl/SiemIntegrationCheck.d.ts +1 -1
  100. package/lib/checks/impl/SsoEnforcementCheck.d.ts +1 -1
  101. package/lib/checks/impl/StandardProfilesCheck.d.ts +1 -1
  102. package/lib/checks/impl/ThreatDetectionCheck.d.ts +1 -1
  103. package/lib/checks/impl/TransactionSecurityPolicyCheck.d.ts +1 -1
  104. package/lib/checks/impl/TrustedIPRangesCheck.d.ts +1 -1
  105. package/lib/checks/impl/TrustedUrlHygieneCheck.d.ts +1 -1
  106. package/lib/checks/impl/UsersAndAdminsCheck.d.ts +1 -1
  107. package/lib/checks/impl/VisualforceXssCheck.d.ts +1 -1
  108. package/lib/commands/audit/events/pull.d.ts +1 -1
  109. package/lib/commands/audit/events/pull.js +3 -3
  110. package/lib/commands/audit/security.js +3 -1
  111. package/lib/commands/audit/timeline.d.ts +26 -0
  112. package/lib/commands/audit/timeline.js +189 -0
  113. package/lib/findings/AuditResult.d.ts +1 -1
  114. package/lib/findings/Finding.d.ts +1 -1
  115. package/lib/findings/ScoringConfig.d.ts +9 -217
  116. package/lib/findings/scoring.d.ts +2 -2
  117. package/lib/findings/scoring.js +1 -1
  118. package/lib/history/AuditDiff.d.ts +1 -1
  119. package/lib/history/metricMeta.d.ts +1 -1
  120. package/lib/index.d.ts +2 -2
  121. package/lib/lib/apexRefs.d.ts +2 -0
  122. package/lib/lib/apexRefs.js +30 -0
  123. package/lib/lib/wire.d.ts +6 -6
  124. package/lib/lib/wire.js +4 -4
  125. package/lib/renderers/ClientReportRenderer.d.ts +1 -1
  126. package/lib/renderers/ClientReportRenderer.js +6 -3
  127. package/lib/renderers/HistoryRenderer.js +2 -1
  128. package/lib/renderers/HtmlRenderer.js +3 -4
  129. package/lib/renderers/MarkdownRenderer.js +1 -1
  130. package/lib/renderers/chartAsset.d.ts +12 -0
  131. package/lib/renderers/chartAsset.js +25 -0
  132. package/lib/timeline/CaptureIndex.d.ts +34 -0
  133. package/lib/timeline/CaptureIndex.js +82 -0
  134. package/lib/timeline/CardinalityIndex.d.ts +28 -0
  135. package/lib/timeline/CardinalityIndex.js +47 -0
  136. package/lib/timeline/CorrelationEngine.d.ts +65 -0
  137. package/lib/timeline/CorrelationEngine.js +0 -0
  138. package/lib/timeline/EventRow.d.ts +69 -0
  139. package/lib/timeline/EventRow.js +14 -0
  140. package/lib/timeline/JoinKeys.d.ts +50 -0
  141. package/lib/timeline/JoinKeys.js +63 -0
  142. package/lib/timeline/loadCaptures.d.ts +87 -0
  143. package/lib/timeline/loadCaptures.js +424 -0
  144. package/lib/timeline/normalise.d.ts +26 -0
  145. package/lib/timeline/normalise.js +161 -0
  146. package/lib/timeline/parseWindow.d.ts +29 -0
  147. package/lib/timeline/parseWindow.js +133 -0
  148. package/lib/timeline/render.d.ts +33 -0
  149. package/lib/timeline/render.js +120 -0
  150. package/package.json +22 -20
  151. package/lib/api/ApiError.d.ts +0 -6
  152. package/lib/api/ApiError.js +0 -6
  153. package/lib/api/MetadataClient.d.ts +0 -4
  154. package/lib/api/MetadataClient.js +0 -2
  155. package/lib/api/MetadataClientImpl.d.ts +0 -8
  156. package/lib/api/MetadataClientImpl.js +0 -22
  157. package/lib/api/RestClient.d.ts +0 -6
  158. package/lib/api/RestClient.js +0 -2
  159. package/lib/api/RestClientImpl.d.ts +0 -10
  160. package/lib/api/RestClientImpl.js +0 -45
  161. package/lib/api/SoqlClient.d.ts +0 -10
  162. package/lib/api/SoqlClient.js +0 -2
  163. package/lib/api/SoqlClientImpl.d.ts +0 -9
  164. package/lib/api/SoqlClientImpl.js +0 -19
  165. package/lib/api/ToolingClient.d.ts +0 -5
  166. package/lib/api/ToolingClient.js +0 -2
  167. package/lib/api/ToolingClientImpl.d.ts +0 -10
  168. package/lib/api/ToolingClientImpl.js +0 -29
  169. package/lib/api/index.d.ts +0 -9
  170. package/lib/api/index.js +0 -5
  171. package/lib/checks/eventLogAccess.d.ts +0 -14
  172. package/lib/checks/eventLogAccess.js +0 -33
  173. package/lib/context/AuditCache.d.ts +0 -78
  174. package/lib/context/AuditCache.js +0 -2
  175. package/lib/context/AuditContext.d.ts +0 -19
  176. package/lib/context/AuditContext.js +0 -2
  177. package/lib/context/OrgInfo.d.ts +0 -9
  178. package/lib/context/OrgInfo.js +0 -2
  179. package/lib/context/OrgMetrics.d.ts +0 -20
  180. package/lib/context/OrgMetrics.js +0 -20
  181. package/lib/events/EventBaselineStore.d.ts +0 -16
  182. package/lib/events/EventBaselineStore.js +0 -55
  183. package/lib/events/eventLogQuery.d.ts +0 -21
  184. package/lib/events/eventLogQuery.js +0 -34
  185. package/lib/events/pullEventLogs.d.ts +0 -51
  186. package/lib/events/pullEventLogs.js +0 -79
  187. package/lib/findings/RiskLevel.d.ts +0 -3
  188. package/lib/findings/RiskLevel.js +0 -2
  189. package/lib/renderers/html-utils.d.ts +0 -2
  190. package/lib/renderers/html-utils.js +0 -8
  191. package/lib/report/branding.d.ts +0 -18
  192. package/lib/report/branding.js +0 -19
  193. package/lib/report/fonts.d.ts +0 -2
  194. package/lib/report/fonts.js +0 -22
  195. package/src/assets/fonts/dm-sans-italic-latin.woff2 +0 -0
  196. package/src/assets/fonts/dm-sans-normal-latin.woff2 +0 -0
  197. package/src/assets/fonts/dm-serif-display-italic-latin.woff2 +0 -0
  198. package/src/assets/fonts/dm-serif-display-normal-latin.woff2 +0 -0
@@ -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
@@ -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