@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.
- package/README.md +258 -5
- package/lib/apps/analyzeApps.d.ts +1 -1
- package/lib/apps/appResolver.d.ts +1 -1
- package/lib/apps/grantedAccess.d.ts +1 -1
- package/lib/chains/AttackChain.d.ts +1 -1
- package/lib/chains/namedChains.d.ts +1 -1
- package/lib/checks/CheckEngine.d.ts +1 -1
- package/lib/checks/SecurityCheck.d.ts +3 -3
- package/lib/checks/impl/AgentActionSurfaceCheck.d.ts +1 -1
- package/lib/checks/impl/AgentActionSurfaceCheck.js +1 -1
- package/lib/checks/impl/AgentChannelExposureCheck.d.ts +1 -1
- package/lib/checks/impl/AgentInventoryCheck.d.ts +1 -1
- package/lib/checks/impl/AgentInventoryCheck.js +1 -1
- package/lib/checks/impl/AgentMonitoringCoverageCheck.d.ts +1 -1
- package/lib/checks/impl/AgentUserPrivilegeCheck.d.ts +1 -1
- package/lib/checks/impl/AnonymousApexAuditCheck.d.ts +1 -1
- package/lib/checks/impl/ApexCrudFLSCheck.d.ts +1 -1
- package/lib/checks/impl/ApexLoggingCheck.d.ts +1 -1
- package/lib/checks/impl/ApexRestEndpointCheck.d.ts +1 -1
- package/lib/checks/impl/ApexSharingCheck.d.ts +1 -1
- package/lib/checks/impl/ApexSharingCheck.js +3 -2
- package/lib/checks/impl/ApiClientPermissionCheck.d.ts +1 -1
- package/lib/checks/impl/ApiLimitsCheck.d.ts +1 -1
- package/lib/checks/impl/AuditTrailCheck.d.ts +1 -1
- package/lib/checks/impl/AuthProvidersCheck.d.ts +1 -1
- package/lib/checks/impl/CertificateExpiryCheck.d.ts +1 -1
- package/lib/checks/impl/ClassicSitesCheck.d.ts +1 -1
- package/lib/checks/impl/CodeSecurityCheck.d.ts +1 -1
- package/lib/checks/impl/CodeSecurityCheck.js +5 -5
- package/lib/checks/impl/ConnectedAppInactivityCheck.d.ts +1 -1
- package/lib/checks/impl/ConnectedAppScopeCheck.d.ts +1 -1
- package/lib/checks/impl/ConnectedAppsCheck.d.ts +1 -1
- package/lib/checks/impl/ContentLinksCheck.d.ts +1 -1
- package/lib/checks/impl/CorsAllowlistCheck.d.ts +1 -1
- package/lib/checks/impl/CspTrustedSitesCheck.d.ts +1 -1
- package/lib/checks/impl/CustomLabelsCredentialCheck.d.ts +1 -1
- package/lib/checks/impl/CustomSettingsCheck.d.ts +1 -1
- package/lib/checks/impl/DataClassificationCheck.d.ts +1 -1
- package/lib/checks/impl/DataExportAccessCheck.d.ts +1 -1
- package/lib/checks/impl/DebugLogAccessCheck.d.ts +1 -1
- package/lib/checks/impl/DeploymentIdentityCheck.d.ts +1 -1
- package/lib/checks/impl/EmailSecurityCheck.d.ts +1 -1
- package/lib/checks/impl/EncryptionCoverageCheck.d.ts +1 -1
- package/lib/checks/impl/EnhancedDomainsCheck.d.ts +1 -1
- package/lib/checks/impl/EnhancedDomainsCheck.js +2 -2
- package/lib/checks/impl/EscalationPermsCheck.d.ts +1 -1
- package/lib/checks/impl/EventMonitoringCheck.d.ts +1 -1
- package/lib/checks/impl/EventMonitoringCheck.js +1 -1
- package/lib/checks/impl/ExperienceCloudSiteCheck.d.ts +1 -1
- package/lib/checks/impl/ExperienceCspCheck.d.ts +1 -1
- package/lib/checks/impl/ExternalCredentialsCheck.d.ts +1 -1
- package/lib/checks/impl/FailedLoginCheck.d.ts +1 -1
- package/lib/checks/impl/FieldHistoryTrackingCheck.d.ts +1 -1
- package/lib/checks/impl/FieldLevelSecurityCheck.d.ts +1 -1
- package/lib/checks/impl/FlowsWithoutSharingCheck.d.ts +1 -1
- package/lib/checks/impl/FlowsWithoutSharingCheck.js +10 -9
- package/lib/checks/impl/GuestApiAccessCheck.d.ts +1 -1
- package/lib/checks/impl/GuestExecutableApexCheck.d.ts +1 -1
- package/lib/checks/impl/GuestExecutableApexCheck.js +4 -3
- package/lib/checks/impl/GuestObjectExposureCheck.d.ts +1 -1
- package/lib/checks/impl/GuestRecordAccessPolicyCheck.d.ts +1 -1
- package/lib/checks/impl/GuestSiteOptionsCheck.d.ts +1 -1
- package/lib/checks/impl/GuestTrafficAnomalyCheck.d.ts +1 -1
- package/lib/checks/impl/GuestTrafficAnomalyCheck.js +1 -1
- package/lib/checks/impl/GuestUserAccessCheck.d.ts +1 -1
- package/lib/checks/impl/HardcodedCredentialsCheck.d.ts +1 -1
- package/lib/checks/impl/HardcodedCredentialsCheck.js +8 -1
- package/lib/checks/impl/HealthCheckCheck.d.ts +1 -1
- package/lib/checks/impl/HighAssuranceSessionCheck.d.ts +1 -1
- package/lib/checks/impl/InactiveUsersCheck.d.ts +1 -1
- package/lib/checks/impl/InstalledPackagesCheck.d.ts +1 -1
- package/lib/checks/impl/IntegrationUsersCheck.d.ts +1 -1
- package/lib/checks/impl/InternalUserMfaCheck.d.ts +1 -1
- package/lib/checks/impl/IpRestrictionsCheck.d.ts +1 -1
- package/lib/checks/impl/LegacyApiVersionCheck.d.ts +1 -1
- package/lib/checks/impl/LoginAccessPolicyCheck.d.ts +1 -1
- package/lib/checks/impl/LoginAnomalyCheck.d.ts +1 -1
- package/lib/checks/impl/LoginSessionCheck.d.ts +1 -1
- package/lib/checks/impl/MfaEnforcementCheck.d.ts +1 -1
- package/lib/checks/impl/MfaMethodStrengthCheck.d.ts +1 -1
- package/lib/checks/impl/MfaRegistrationCheck.d.ts +1 -1
- package/lib/checks/impl/MyDomainLoginPolicyCheck.d.ts +1 -1
- package/lib/checks/impl/NamedCredentialsCheck.d.ts +1 -1
- package/lib/checks/impl/NamedCredentialsCheck.js +13 -9
- package/lib/checks/impl/OutboundMessagesCheck.d.ts +1 -1
- package/lib/checks/impl/PasswordSessionPolicyCheck.d.ts +2 -2
- package/lib/checks/impl/PermissionsCheck.d.ts +1 -1
- package/lib/checks/impl/PrivilegedAccessCheck.d.ts +1 -1
- package/lib/checks/impl/PublicContentExposureCheck.d.ts +1 -1
- package/lib/checks/impl/PublicGroupSharingCheck.d.ts +1 -1
- package/lib/checks/impl/ReleaseUpdatesCheck.d.ts +1 -1
- package/lib/checks/impl/RemoteSitesCheck.d.ts +1 -1
- package/lib/checks/impl/ReportFolderAccessCheck.d.ts +1 -1
- package/lib/checks/impl/SandboxDataMaskingCheck.d.ts +1 -1
- package/lib/checks/impl/ScheduledApexCheck.d.ts +1 -1
- package/lib/checks/impl/SeparationOfDutiesCheck.d.ts +1 -1
- package/lib/checks/impl/SessionHardeningCheck.d.ts +1 -1
- package/lib/checks/impl/SharingModelCheck.d.ts +1 -1
- package/lib/checks/impl/SiemIntegrationCheck.d.ts +1 -1
- package/lib/checks/impl/SsoEnforcementCheck.d.ts +1 -1
- package/lib/checks/impl/StandardProfilesCheck.d.ts +1 -1
- package/lib/checks/impl/ThreatDetectionCheck.d.ts +1 -1
- package/lib/checks/impl/TransactionSecurityPolicyCheck.d.ts +1 -1
- package/lib/checks/impl/TrustedIPRangesCheck.d.ts +1 -1
- package/lib/checks/impl/TrustedUrlHygieneCheck.d.ts +1 -1
- package/lib/checks/impl/UsersAndAdminsCheck.d.ts +1 -1
- package/lib/checks/impl/VisualforceXssCheck.d.ts +1 -1
- package/lib/commands/audit/events/pull.d.ts +1 -1
- package/lib/commands/audit/events/pull.js +3 -3
- package/lib/commands/audit/security.js +3 -1
- package/lib/commands/audit/timeline.d.ts +26 -0
- package/lib/commands/audit/timeline.js +189 -0
- package/lib/findings/AuditResult.d.ts +1 -1
- package/lib/findings/Finding.d.ts +1 -1
- package/lib/findings/ScoringConfig.d.ts +9 -217
- package/lib/findings/scoring.d.ts +2 -2
- package/lib/findings/scoring.js +1 -1
- package/lib/history/AuditDiff.d.ts +1 -1
- package/lib/history/metricMeta.d.ts +1 -1
- package/lib/index.d.ts +2 -2
- package/lib/lib/apexRefs.d.ts +2 -0
- package/lib/lib/apexRefs.js +30 -0
- package/lib/lib/wire.d.ts +6 -6
- package/lib/lib/wire.js +4 -4
- package/lib/renderers/ClientReportRenderer.d.ts +1 -1
- package/lib/renderers/ClientReportRenderer.js +6 -3
- package/lib/renderers/HistoryRenderer.js +2 -1
- package/lib/renderers/HtmlRenderer.js +3 -4
- package/lib/renderers/MarkdownRenderer.js +1 -1
- package/lib/renderers/chartAsset.d.ts +12 -0
- package/lib/renderers/chartAsset.js +25 -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 +22 -20
- package/lib/api/ApiError.d.ts +0 -6
- package/lib/api/ApiError.js +0 -6
- package/lib/api/MetadataClient.d.ts +0 -4
- package/lib/api/MetadataClient.js +0 -2
- package/lib/api/MetadataClientImpl.d.ts +0 -8
- package/lib/api/MetadataClientImpl.js +0 -22
- package/lib/api/RestClient.d.ts +0 -6
- package/lib/api/RestClient.js +0 -2
- package/lib/api/RestClientImpl.d.ts +0 -10
- package/lib/api/RestClientImpl.js +0 -45
- package/lib/api/SoqlClient.d.ts +0 -10
- package/lib/api/SoqlClient.js +0 -2
- package/lib/api/SoqlClientImpl.d.ts +0 -9
- package/lib/api/SoqlClientImpl.js +0 -19
- package/lib/api/ToolingClient.d.ts +0 -5
- package/lib/api/ToolingClient.js +0 -2
- package/lib/api/ToolingClientImpl.d.ts +0 -10
- package/lib/api/ToolingClientImpl.js +0 -29
- package/lib/api/index.d.ts +0 -9
- package/lib/api/index.js +0 -5
- package/lib/checks/eventLogAccess.d.ts +0 -14
- package/lib/checks/eventLogAccess.js +0 -33
- package/lib/context/AuditCache.d.ts +0 -78
- package/lib/context/AuditCache.js +0 -2
- package/lib/context/AuditContext.d.ts +0 -19
- package/lib/context/AuditContext.js +0 -2
- package/lib/context/OrgInfo.d.ts +0 -9
- package/lib/context/OrgInfo.js +0 -2
- package/lib/context/OrgMetrics.d.ts +0 -20
- package/lib/context/OrgMetrics.js +0 -20
- package/lib/events/EventBaselineStore.d.ts +0 -16
- package/lib/events/EventBaselineStore.js +0 -55
- package/lib/events/eventLogQuery.d.ts +0 -21
- package/lib/events/eventLogQuery.js +0 -34
- package/lib/events/pullEventLogs.d.ts +0 -51
- package/lib/events/pullEventLogs.js +0 -79
- package/lib/findings/RiskLevel.d.ts +0 -3
- package/lib/findings/RiskLevel.js +0 -2
- package/lib/renderers/html-utils.d.ts +0 -2
- package/lib/renderers/html-utils.js +0 -8
- package/lib/report/branding.d.ts +0 -18
- package/lib/report/branding.js +0 -19
- package/lib/report/fonts.d.ts +0 -2
- package/lib/report/fonts.js +0 -22
- package/src/assets/fonts/dm-sans-italic-latin.woff2 +0 -0
- package/src/assets/fonts/dm-sans-normal-latin.woff2 +0 -0
- package/src/assets/fonts/dm-serif-display-italic-latin.woff2 +0 -0
- package/src/assets/fonts/dm-serif-display-normal-latin.woff2 +0 -0
|
@@ -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
|
package/lib/lib/wire.d.ts
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
import type { Connection } from '@salesforce/core';
|
|
2
|
-
import { SoqlClientImpl } from '
|
|
3
|
-
import { ToolingClientImpl } from '
|
|
4
|
-
import { RestClientImpl } from '
|
|
5
|
-
import { MetadataClientImpl } from '
|
|
6
|
-
import type { AuditContext, AuditOptions } from '
|
|
7
|
-
import type { OrgInfo } from '
|
|
2
|
+
import { SoqlClientImpl } from '@cclabsnz/sf-core';
|
|
3
|
+
import { ToolingClientImpl } from '@cclabsnz/sf-core';
|
|
4
|
+
import { RestClientImpl } from '@cclabsnz/sf-core';
|
|
5
|
+
import { MetadataClientImpl } from '@cclabsnz/sf-core';
|
|
6
|
+
import type { AuditContext, AuditOptions } from '@cclabsnz/sf-core';
|
|
7
|
+
import type { OrgInfo } from '@cclabsnz/sf-core';
|
|
8
8
|
export declare function buildApiClients(conn: Connection): {
|
|
9
9
|
soql: SoqlClientImpl;
|
|
10
10
|
tooling: ToolingClientImpl;
|
package/lib/lib/wire.js
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
|
-
import { SoqlClientImpl } from '
|
|
2
|
-
import { ToolingClientImpl } from '
|
|
3
|
-
import { RestClientImpl } from '
|
|
4
|
-
import { MetadataClientImpl } from '
|
|
1
|
+
import { SoqlClientImpl } from '@cclabsnz/sf-core';
|
|
2
|
+
import { ToolingClientImpl } from '@cclabsnz/sf-core';
|
|
3
|
+
import { RestClientImpl } from '@cclabsnz/sf-core';
|
|
4
|
+
import { MetadataClientImpl } from '@cclabsnz/sf-core';
|
|
5
5
|
export function buildApiClients(conn) {
|
|
6
6
|
return {
|
|
7
7
|
soql: new SoqlClientImpl(conn),
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import type { AuditResult } from '../findings/AuditResult.js';
|
|
2
2
|
import type { AuditRenderer } from './AuditRenderer.js';
|
|
3
|
-
import type { Branding } from '
|
|
3
|
+
import type { Branding } from '@cclabsnz/sf-core';
|
|
4
4
|
import type { Framework } from '../compliance/types.js';
|
|
5
5
|
export interface ClientReportOptions {
|
|
6
6
|
branding: Branding;
|
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
import { esc } from '
|
|
2
|
-
import { fontFaceCss } from '
|
|
1
|
+
import { esc } from '@cclabsnz/sf-core';
|
|
2
|
+
import { fontFaceCss } from '@cclabsnz/sf-core';
|
|
3
3
|
import { getCheckMeta } from '../findings/CheckMeta.js';
|
|
4
4
|
import { selectPriorities } from '../report/ExecutivePriorities.js';
|
|
5
5
|
import { buildRoadmap } from '../report/RemediationRoadmap.js';
|
|
@@ -198,8 +198,11 @@ ${tier('Projects', 'weeks', roadmap.project)}`;
|
|
|
198
198
|
return `${this.sectionHead(numStr, 'All Findings')}${rows}`;
|
|
199
199
|
}
|
|
200
200
|
footer(b) {
|
|
201
|
+
const site = b.website
|
|
202
|
+
? ` · <a href="https://${esc(b.website.replace(/^https?:\/\//, ''))}">${esc(b.website.replace(/^https?:\/\//, ''))}</a>`
|
|
203
|
+
: '';
|
|
201
204
|
return `<footer><span class="label">Scope & Liability</span>
|
|
202
|
-
Read-only, point-in-time configuration review: not a penetration test, not a code audit. The grade is a prioritisation aid, not a certification. Validate findings before remediation. © ${new Date().getFullYear()} ${esc(b.firmName)} · ${esc(b.contact)}</footer>`;
|
|
205
|
+
Read-only, point-in-time configuration review: not a penetration test, not a code audit. The grade is a prioritisation aid, not a certification. Validate findings before remediation. © ${new Date().getFullYear()} ${esc(b.firmName)} · ${esc(b.contact)}${site}</footer>`;
|
|
203
206
|
}
|
|
204
207
|
}
|
|
205
208
|
//# sourceMappingURL=ClientReportRenderer.js.map
|
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import { chartJsScript } from './chartAsset.js';
|
|
1
2
|
function fmtDate(d) {
|
|
2
3
|
return d.toISOString().replace('T', ' ').substring(0, 16);
|
|
3
4
|
}
|
|
@@ -65,7 +66,7 @@ export class HistoryRenderer {
|
|
|
65
66
|
<meta charset="UTF-8">
|
|
66
67
|
<meta name="viewport" content="width=device-width,initial-scale=1">
|
|
67
68
|
<title>SF Audit History: ${orgName}</title>
|
|
68
|
-
<script
|
|
69
|
+
<script>${chartJsScript()}</script>
|
|
69
70
|
<style>
|
|
70
71
|
*, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
|
|
71
72
|
body { font-family: system-ui, -apple-system, 'Segoe UI', sans-serif; background: #0d1117; color: #c9d1d9; max-width: 1100px; margin: 2rem auto; padding: 0 1.25rem 4rem; line-height: 1.6; }
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { esc } from '
|
|
1
|
+
import { esc, firaFontFaceCss } from '@cclabsnz/sf-core';
|
|
2
2
|
const RISK_COLORS = {
|
|
3
3
|
CRITICAL: '#dc2626',
|
|
4
4
|
HIGH: '#ea580c',
|
|
@@ -242,9 +242,8 @@ export class HtmlRenderer {
|
|
|
242
242
|
<meta charset="UTF-8">
|
|
243
243
|
<meta name="viewport" content="width=device-width,initial-scale=1">
|
|
244
244
|
<title>SF Security Audit: ${esc(result.orgName)}</title>
|
|
245
|
-
<link rel="preconnect" href="https://fonts.googleapis.com">
|
|
246
|
-
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Fira+Code:wght@400;500;700&family=Fira+Sans:wght@300;400;500;600;700&display=swap">
|
|
247
245
|
<style>
|
|
246
|
+
${firaFontFaceCss()}
|
|
248
247
|
*, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
|
|
249
248
|
body {
|
|
250
249
|
font-family: 'Fira Sans', system-ui, -apple-system, 'Segoe UI', sans-serif;
|
|
@@ -563,7 +562,7 @@ export class HtmlRenderer {
|
|
|
563
562
|
});
|
|
564
563
|
</script>
|
|
565
564
|
<div class="offline-footer">
|
|
566
|
-
<strong>Offline-first audit:</strong> all analysis performed locally; no data is transmitted outside your Salesforce org. Generated by
|
|
565
|
+
<strong>Offline-first audit:</strong> all analysis performed locally; no data is transmitted outside your Salesforce org. Generated by <a href="https://github.com/cclabsnz/sf-audit-plugin" style="color:inherit">sf-audit</a>, built by <a href="https://cloudcounsel.co.nz" style="color:inherit">CloudCounsel</a>.
|
|
567
566
|
</div>
|
|
568
567
|
</body>
|
|
569
568
|
</html>`;
|
|
@@ -79,7 +79,7 @@ export class MarkdownRenderer {
|
|
|
79
79
|
lines.push('');
|
|
80
80
|
lines.push('---');
|
|
81
81
|
lines.push('');
|
|
82
|
-
lines.push('> **Offline-first audit:** all analysis is performed locally; no data is transmitted outside your Salesforce org. Generated by
|
|
82
|
+
lines.push('> **Offline-first audit:** all analysis is performed locally; no data is transmitted outside your Salesforce org. Generated by [sf-audit](https://github.com/cclabsnz/sf-audit-plugin), built by [CloudCounsel](https://cloudcounsel.co.nz).');
|
|
83
83
|
lines.push('');
|
|
84
84
|
return lines.join('\n');
|
|
85
85
|
}
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The Chart.js UMD bundle, read from the pinned `chart.js` dependency so it can be inlined
|
|
3
|
+
* into a generated report. An audit deliverable must never fetch script from a third-party
|
|
4
|
+
* CDN: the report carries sensitive org findings, is often opened on locked-down machines,
|
|
5
|
+
* and a compromised CDN would otherwise execute arbitrary JS in that page.
|
|
6
|
+
*
|
|
7
|
+
* Resolved from the dependency rather than vendored as a committed blob so the version stays
|
|
8
|
+
* visible to `pnpm audit`/dependabot. The UMD file itself is not in chart.js's `exports` map,
|
|
9
|
+
* so it is located relative to the resolved main entry.
|
|
10
|
+
*/
|
|
11
|
+
export declare function chartJsScript(): string;
|
|
12
|
+
//# sourceMappingURL=chartAsset.d.ts.map
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
import { readFileSync } from 'node:fs';
|
|
2
|
+
import { createRequire } from 'node:module';
|
|
3
|
+
import { dirname, join } from 'node:path';
|
|
4
|
+
const requireFrom = createRequire(import.meta.url);
|
|
5
|
+
let cached = null;
|
|
6
|
+
/**
|
|
7
|
+
* The Chart.js UMD bundle, read from the pinned `chart.js` dependency so it can be inlined
|
|
8
|
+
* into a generated report. An audit deliverable must never fetch script from a third-party
|
|
9
|
+
* CDN: the report carries sensitive org findings, is often opened on locked-down machines,
|
|
10
|
+
* and a compromised CDN would otherwise execute arbitrary JS in that page.
|
|
11
|
+
*
|
|
12
|
+
* Resolved from the dependency rather than vendored as a committed blob so the version stays
|
|
13
|
+
* visible to `pnpm audit`/dependabot. The UMD file itself is not in chart.js's `exports` map,
|
|
14
|
+
* so it is located relative to the resolved main entry.
|
|
15
|
+
*/
|
|
16
|
+
export function chartJsScript() {
|
|
17
|
+
if (cached !== null)
|
|
18
|
+
return cached;
|
|
19
|
+
const umd = join(dirname(requireFrom.resolve('chart.js')), 'chart.umd.min.js');
|
|
20
|
+
// A literal `</script` in the bundle would close the tag early. Chart.js has none today;
|
|
21
|
+
// escape defensively so a future version cannot silently break the report.
|
|
22
|
+
cached = readFileSync(umd, 'utf8').replace(/<\/script/gi, '<\\/script');
|
|
23
|
+
return cached;
|
|
24
|
+
}
|
|
25
|
+
//# sourceMappingURL=chartAsset.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
|
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
import { type JoinKeyType } from './JoinKeys.js';
|
|
2
|
+
/** Where a seed value enters the search. */
|
|
3
|
+
export interface Seed {
|
|
4
|
+
type: JoinKeyType;
|
|
5
|
+
value: string;
|
|
6
|
+
}
|
|
7
|
+
/**
|
|
8
|
+
* Why a row is in the timeline: the seed matched it, a key tied it in, or no seed was given and
|
|
9
|
+
* the whole window was returned.
|
|
10
|
+
*/
|
|
11
|
+
export type Attribution = 'seed' | 'window' | JoinKeyType;
|
|
12
|
+
export interface CorrelatedRow {
|
|
13
|
+
row: Record<string, unknown>;
|
|
14
|
+
attribution: Attribution;
|
|
15
|
+
}
|
|
16
|
+
/** An expansion the engine declined, and the evidence for declining it. */
|
|
17
|
+
export interface Refusal {
|
|
18
|
+
type: JoinKeyType;
|
|
19
|
+
value: string;
|
|
20
|
+
cardinality: number;
|
|
21
|
+
threshold: number;
|
|
22
|
+
}
|
|
23
|
+
export interface CorrelateOptions {
|
|
24
|
+
/** Distinct-actor ceiling above which a key is not expanded. Default 8. */
|
|
25
|
+
maxCardinality?: number;
|
|
26
|
+
/** Expand regardless of cardinality. Off by default; the result reports the consequence. */
|
|
27
|
+
allowSharedIdentity?: boolean;
|
|
28
|
+
}
|
|
29
|
+
export interface CorrelationResult {
|
|
30
|
+
rows: CorrelatedRow[];
|
|
31
|
+
refusals: Refusal[];
|
|
32
|
+
/** Key values actually expanded through, in visit order — the provenance of the result. */
|
|
33
|
+
expandedThrough: Array<{
|
|
34
|
+
type: JoinKeyType;
|
|
35
|
+
value: string;
|
|
36
|
+
}>;
|
|
37
|
+
}
|
|
38
|
+
/**
|
|
39
|
+
* A judgement call from one incident, recorded rather than buried: a request id was 1:1, and a
|
|
40
|
+
* shared community identity was 1:1371. Eight sits far above the former and far below the
|
|
41
|
+
* latter. Worth revisiting against a second dataset.
|
|
42
|
+
*/
|
|
43
|
+
export declare const DEFAULT_MAX_CARDINALITY = 8;
|
|
44
|
+
/**
|
|
45
|
+
* Expand from seed values to every row belonging to the same actor.
|
|
46
|
+
*
|
|
47
|
+
* Salesforce splits one actor's activity across event types that share no common identifier.
|
|
48
|
+
* Some carry a client address, some carry only a request id, and one carries the address column
|
|
49
|
+
* but leaves it empty. Filtering on any single field finds a fraction of the activity, so the
|
|
50
|
+
* search has to walk between keys — and walking between keys is exactly where correlation
|
|
51
|
+
* invents relationships that are not there.
|
|
52
|
+
*
|
|
53
|
+
* Two guards keep it honest, and neither lives here by accident:
|
|
54
|
+
*
|
|
55
|
+
* Blank values cannot reach the frontier because {@link joinKeysOf} never yields one. A blank
|
|
56
|
+
* admitted as a key matches every other row whose value is also blank, which is how a two-row
|
|
57
|
+
* answer became a twenty-five-row one during the original hand reconstruction.
|
|
58
|
+
*
|
|
59
|
+
* Shared identities are refused by cardinality. A key standing for many actors is not an
|
|
60
|
+
* identifier, and expanding through it presents a crowd's activity as one actor's. Refusals are
|
|
61
|
+
* returned rather than applied quietly: a bounded timeline that does not say it was bounded is
|
|
62
|
+
* as misleading as an over-attributed one.
|
|
63
|
+
*/
|
|
64
|
+
export declare function correlate(rows: ReadonlyArray<Record<string, unknown>>, seeds: ReadonlyArray<Seed>, options: CorrelateOptions): CorrelationResult;
|
|
65
|
+
//# sourceMappingURL=CorrelationEngine.d.ts.map
|
|
Binary file
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
import type { Attribution } from './CorrelationEngine.js';
|
|
2
|
+
/** Which capture the row came out of. */
|
|
3
|
+
export type EventSource = 'EventLogFile' | 'RealTimeEventMonitoring';
|
|
4
|
+
/**
|
|
5
|
+
* One row of the timeline, in the shape every source is mapped into.
|
|
6
|
+
*
|
|
7
|
+
* Ordered identity → attribution → causation → timing → payload → source-specific, so a reader
|
|
8
|
+
* scanning left to right meets "who and why is this here" before "what did it do".
|
|
9
|
+
*
|
|
10
|
+
* Everything is optional except the few fields every source can supply. A blank column is
|
|
11
|
+
* informative in itself: `rows_processed` is empty for every EventLogFile row because no ELF
|
|
12
|
+
* type records it, and that absence is exactly why the real-time objects matter.
|
|
13
|
+
*/
|
|
14
|
+
export interface EventRow {
|
|
15
|
+
seq: number;
|
|
16
|
+
timestamp_utc: string;
|
|
17
|
+
event_type: string;
|
|
18
|
+
source: EventSource;
|
|
19
|
+
attribution: Attribution;
|
|
20
|
+
client_ip?: string;
|
|
21
|
+
request_id?: string;
|
|
22
|
+
session_key?: string;
|
|
23
|
+
login_key?: string;
|
|
24
|
+
user_id?: string;
|
|
25
|
+
user_type?: string;
|
|
26
|
+
is_guest?: boolean;
|
|
27
|
+
/** The save transaction this row belongs to — a cascade shares one. */
|
|
28
|
+
transaction_id?: string;
|
|
29
|
+
/** This row's own event identity, which later events point back at. */
|
|
30
|
+
event_identifier?: string;
|
|
31
|
+
/** The event that caused this one. */
|
|
32
|
+
related_event_identifier?: string;
|
|
33
|
+
/** Object the row acted on, where the source names one. */
|
|
34
|
+
entity_name?: string;
|
|
35
|
+
/** Records the row touched, where the source names them. */
|
|
36
|
+
record_ids?: string;
|
|
37
|
+
/** The page this request came from — chains navigation into a path. */
|
|
38
|
+
referrer_uri?: string;
|
|
39
|
+
/** Actor fingerprint. Weak alone, but it survives an address change. */
|
|
40
|
+
user_agent?: string;
|
|
41
|
+
/** Apex execution context: trigger, batch, anonymous, and so on. */
|
|
42
|
+
quiddity?: string;
|
|
43
|
+
run_time_ms?: number;
|
|
44
|
+
response_bytes?: number;
|
|
45
|
+
page_name?: string;
|
|
46
|
+
http_method?: string;
|
|
47
|
+
is_error?: boolean;
|
|
48
|
+
uri?: string;
|
|
49
|
+
entry_point?: string;
|
|
50
|
+
query_type?: string;
|
|
51
|
+
sql_id?: string;
|
|
52
|
+
rows_processed?: number;
|
|
53
|
+
queried_entities?: string;
|
|
54
|
+
records_returned?: string;
|
|
55
|
+
list_view_name?: string;
|
|
56
|
+
list_view_scope?: string;
|
|
57
|
+
filter_criteria?: string;
|
|
58
|
+
graphql_operation?: string;
|
|
59
|
+
graphql_query?: string;
|
|
60
|
+
graphql_exception?: string;
|
|
61
|
+
/** Batched actions collapsed to one readable line. */
|
|
62
|
+
aura_action_summary?: string;
|
|
63
|
+
/** The raw message, kept so the collapse is never the only record. */
|
|
64
|
+
aura_action_message?: string;
|
|
65
|
+
source_file?: string;
|
|
66
|
+
}
|
|
67
|
+
/** Column order for tabular output. The single source of truth for CSV headers. */
|
|
68
|
+
export declare const EVENT_ROW_COLUMNS: ReadonlyArray<keyof EventRow>;
|
|
69
|
+
//# sourceMappingURL=EventRow.d.ts.map
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
/** Column order for tabular output. The single source of truth for CSV headers. */
|
|
2
|
+
export const EVENT_ROW_COLUMNS = [
|
|
3
|
+
'seq', 'timestamp_utc', 'event_type', 'source', 'attribution',
|
|
4
|
+
'client_ip', 'request_id', 'session_key', 'login_key', 'user_id', 'user_type', 'is_guest',
|
|
5
|
+
'transaction_id', 'event_identifier', 'related_event_identifier',
|
|
6
|
+
'entity_name', 'record_ids', 'referrer_uri', 'user_agent', 'quiddity',
|
|
7
|
+
'run_time_ms', 'response_bytes', 'page_name', 'http_method', 'is_error', 'uri', 'entry_point',
|
|
8
|
+
'query_type', 'sql_id',
|
|
9
|
+
'rows_processed', 'queried_entities', 'records_returned', 'list_view_name', 'list_view_scope',
|
|
10
|
+
'filter_criteria',
|
|
11
|
+
'graphql_operation', 'graphql_query', 'graphql_exception',
|
|
12
|
+
'aura_action_summary', 'aura_action_message', 'source_file',
|
|
13
|
+
];
|
|
14
|
+
//# sourceMappingURL=EventRow.js.map
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The values that tie one actor's rows together across event types.
|
|
3
|
+
*
|
|
4
|
+
* Every field is optional by construction, and that is the point. A key is present only when it
|
|
5
|
+
* carries something usable; anything blank comes back `undefined` and can never reach the
|
|
6
|
+
* correlation frontier.
|
|
7
|
+
*/
|
|
8
|
+
export interface JoinKeys {
|
|
9
|
+
requestId?: string;
|
|
10
|
+
clientIp?: string;
|
|
11
|
+
sessionKey?: string;
|
|
12
|
+
loginKey?: string;
|
|
13
|
+
userId?: string;
|
|
14
|
+
/**
|
|
15
|
+
* One Salesforce transaction — a save and everything it cascaded into. The strongest causal
|
|
16
|
+
* link available: rows sharing it did not merely happen near each other, they happened
|
|
17
|
+
* *because* of each other.
|
|
18
|
+
*/
|
|
19
|
+
transactionId?: string;
|
|
20
|
+
/** A real-time event's own identity, which other events point at. */
|
|
21
|
+
eventIdentifier?: string;
|
|
22
|
+
/**
|
|
23
|
+
* The event this one was caused by. Points at another row's {@link eventIdentifier}, so
|
|
24
|
+
* following it walks from an action to its consequences rather than to its neighbours.
|
|
25
|
+
*/
|
|
26
|
+
relatedEventIdentifier?: string;
|
|
27
|
+
}
|
|
28
|
+
/**
|
|
29
|
+
* Every key type, in one place.
|
|
30
|
+
*
|
|
31
|
+
* The cardinality index and the correlation engine both walk this list. Kept here so adding a
|
|
32
|
+
* key cannot reach one of them and miss the other — a key the engine expands through but the
|
|
33
|
+
* index does not measure would bypass the cardinality gate entirely.
|
|
34
|
+
*/
|
|
35
|
+
export declare const JOIN_KEY_TYPES: readonly ["requestId", "clientIp", "sessionKey", "loginKey", "userId", "transactionId", "eventIdentifier", "relatedEventIdentifier"];
|
|
36
|
+
export type JoinKeyType = (typeof JOIN_KEY_TYPES)[number];
|
|
37
|
+
/**
|
|
38
|
+
* Extract the join keys from a raw ELF or Real-Time Event row.
|
|
39
|
+
*
|
|
40
|
+
* This function is the whole of Invariant 1. A blank value never becomes a key, so the
|
|
41
|
+
* correlation engine cannot expand through one — it has no opportunity to get this wrong, and
|
|
42
|
+
* no obligation to remember the rule.
|
|
43
|
+
*
|
|
44
|
+
* The failure this prevents is specific and was observed: a blank REQUEST_ID admitted to the
|
|
45
|
+
* join set stops behaving like an identifier and starts behaving like a wildcard, matching every
|
|
46
|
+
* other row whose REQUEST_ID is also blank. During the 2026-08-02 reconstruction that turned
|
|
47
|
+
* 2 genuinely related rows into 25, most of them other people's sessions.
|
|
48
|
+
*/
|
|
49
|
+
export declare function joinKeysOf(row: Record<string, unknown>): JoinKeys;
|
|
50
|
+
//# sourceMappingURL=JoinKeys.d.ts.map
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Every key type, in one place.
|
|
3
|
+
*
|
|
4
|
+
* The cardinality index and the correlation engine both walk this list. Kept here so adding a
|
|
5
|
+
* key cannot reach one of them and miss the other — a key the engine expands through but the
|
|
6
|
+
* index does not measure would bypass the cardinality gate entirely.
|
|
7
|
+
*/
|
|
8
|
+
export const JOIN_KEY_TYPES = [
|
|
9
|
+
'requestId',
|
|
10
|
+
'clientIp',
|
|
11
|
+
'sessionKey',
|
|
12
|
+
'loginKey',
|
|
13
|
+
'userId',
|
|
14
|
+
'transactionId',
|
|
15
|
+
'eventIdentifier',
|
|
16
|
+
'relatedEventIdentifier',
|
|
17
|
+
];
|
|
18
|
+
/**
|
|
19
|
+
* Read a key from a raw event row, or `undefined` if it is unusable.
|
|
20
|
+
*
|
|
21
|
+
* Unusable means absent, null, or whitespace — not merely falsy. `'0'` is a legitimate
|
|
22
|
+
* identifier and a truthiness check would silently drop it.
|
|
23
|
+
*
|
|
24
|
+
* Trimming matters as much as rejecting: `' req-1 '` and `'req-1'` are the same request, and
|
|
25
|
+
* treating them as two keys would split one actor's rows across two frontier values and
|
|
26
|
+
* under-report rather than over-report.
|
|
27
|
+
*/
|
|
28
|
+
function usable(value) {
|
|
29
|
+
if (typeof value !== 'string')
|
|
30
|
+
return undefined;
|
|
31
|
+
const trimmed = value.trim();
|
|
32
|
+
return trimmed.length > 0 ? trimmed : undefined;
|
|
33
|
+
}
|
|
34
|
+
/**
|
|
35
|
+
* Extract the join keys from a raw ELF or Real-Time Event row.
|
|
36
|
+
*
|
|
37
|
+
* This function is the whole of Invariant 1. A blank value never becomes a key, so the
|
|
38
|
+
* correlation engine cannot expand through one — it has no opportunity to get this wrong, and
|
|
39
|
+
* no obligation to remember the rule.
|
|
40
|
+
*
|
|
41
|
+
* The failure this prevents is specific and was observed: a blank REQUEST_ID admitted to the
|
|
42
|
+
* join set stops behaving like an identifier and starts behaving like a wildcard, matching every
|
|
43
|
+
* other row whose REQUEST_ID is also blank. During the 2026-08-02 reconstruction that turned
|
|
44
|
+
* 2 genuinely related rows into 25, most of them other people's sessions.
|
|
45
|
+
*/
|
|
46
|
+
export function joinKeysOf(row) {
|
|
47
|
+
return {
|
|
48
|
+
requestId: usable(row.REQUEST_ID),
|
|
49
|
+
// ELF spells it CLIENT_IP, Real-Time Events spell it SourceIp. ApexExecution carries
|
|
50
|
+
// CLIENT_IP as a column but leaves it empty in practice, so an unusable value must fall
|
|
51
|
+
// through rather than shadow a SourceIp that would have identified the row.
|
|
52
|
+
clientIp: usable(row.CLIENT_IP) ?? usable(row.SourceIp),
|
|
53
|
+
// RTE spells these without underscores; accept both so one row type does not silently
|
|
54
|
+
// drop out of the join graph because of a naming convention.
|
|
55
|
+
sessionKey: usable(row.SESSION_KEY) ?? usable(row.SessionKey),
|
|
56
|
+
loginKey: usable(row.LOGIN_KEY) ?? usable(row.LoginKey),
|
|
57
|
+
userId: usable(row.USER_ID) ?? usable(row.UserId),
|
|
58
|
+
transactionId: usable(row.TRANSACTION_ID) ?? usable(row.TransactionId),
|
|
59
|
+
eventIdentifier: usable(row.EVENT_IDENTIFIER) ?? usable(row.EventIdentifier),
|
|
60
|
+
relatedEventIdentifier: usable(row.RELATED_EVENT_IDENTIFIER) ?? usable(row.RelatedEventIdentifier),
|
|
61
|
+
};
|
|
62
|
+
}
|
|
63
|
+
//# sourceMappingURL=JoinKeys.js.map
|