@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
@@ -1,4 +1,4 @@
1
- import type { AuditContext } from '../../context/AuditContext.js';
1
+ import type { AuditContext } from '@cclabsnz/sf-core';
2
2
  import type { SecurityCheck, CheckResult } from '../SecurityCheck.js';
3
3
  /**
4
4
  * Verifies that Threat Detection event storage (especially Guest User Anomaly) is
@@ -1,4 +1,4 @@
1
- import type { AuditContext } from '../../context/AuditContext.js';
1
+ import type { AuditContext } from '@cclabsnz/sf-core';
2
2
  import type { SecurityCheck, CheckResult } from '../SecurityCheck.js';
3
3
  export declare class TransactionSecurityPolicyCheck implements SecurityCheck {
4
4
  readonly id = "transaction-security-policy";
@@ -1,4 +1,4 @@
1
- import type { AuditContext } from '../../context/AuditContext.js';
1
+ import type { AuditContext } from '@cclabsnz/sf-core';
2
2
  import type { SecurityCheck, CheckResult } from '../SecurityCheck.js';
3
3
  export declare class TrustedIPRangesCheck implements SecurityCheck {
4
4
  readonly id = "trusted-ip-ranges";
@@ -1,4 +1,4 @@
1
- import type { AuditContext } from '../../context/AuditContext.js';
1
+ import type { AuditContext } from '@cclabsnz/sf-core';
2
2
  import type { SecurityCheck, CheckResult } from '../SecurityCheck.js';
3
3
  export declare class TrustedUrlHygieneCheck implements SecurityCheck {
4
4
  readonly id = "trusted-url-hygiene";
@@ -1,4 +1,4 @@
1
- import type { AuditContext } from '../../context/AuditContext.js';
1
+ import type { AuditContext } from '@cclabsnz/sf-core';
2
2
  import type { SecurityCheck, CheckResult } from '../SecurityCheck.js';
3
3
  export declare class UsersAndAdminsCheck implements SecurityCheck {
4
4
  readonly id = "users-and-admins";
@@ -1,4 +1,4 @@
1
- import type { AuditContext } from '../../context/AuditContext.js';
1
+ import type { AuditContext } from '@cclabsnz/sf-core';
2
2
  import type { SecurityCheck, CheckResult } from '../SecurityCheck.js';
3
3
  export declare class VisualforceXssCheck implements SecurityCheck {
4
4
  readonly id = "visualforce-xss";
@@ -1,5 +1,5 @@
1
1
  import { SfCommand } from '@salesforce/sf-plugins-core';
2
- import { type EventsPullResult } from '../../../events/pullEventLogs.js';
2
+ import { type EventsPullResult } from '@cclabsnz/sf-core';
3
3
  export default class AuditEventsPullCommand extends SfCommand<EventsPullResult> {
4
4
  static summary: string;
5
5
  static description: string;
@@ -1,9 +1,9 @@
1
1
  // src/commands/audit/events/pull.ts
2
2
  import { SfCommand, Flags } from '@salesforce/sf-plugins-core';
3
3
  import { buildAuditContext, resolveOrgInfo } from '../../../lib/wire.js';
4
- import { EventBaselineStore } from '../../../events/EventBaselineStore.js';
5
- import { pullEventLogs } from '../../../events/pullEventLogs.js';
6
- import { sanitizeTypes } from '../../../events/eventLogQuery.js';
4
+ import { EventBaselineStore } from '@cclabsnz/sf-core';
5
+ import { pullEventLogs } from '@cclabsnz/sf-core';
6
+ import { sanitizeTypes } from '@cclabsnz/sf-core';
7
7
  export default class AuditEventsPullCommand extends SfCommand {
8
8
  static summary = 'Capture free EventLogFile daily logs to local disk';
9
9
  static description = 'Downloads the org\'s free (Daily-interval) EventLogFile CSV logs to ~/.sf/event-baseline/{orgId} so they ' +
@@ -7,7 +7,7 @@ import { JsonRenderer } from '../../renderers/JsonRenderer.js';
7
7
  import { HtmlRenderer } from '../../renderers/HtmlRenderer.js';
8
8
  import { MarkdownRenderer } from '../../renderers/MarkdownRenderer.js';
9
9
  import { ClientReportRenderer } from '../../renderers/ClientReportRenderer.js';
10
- import { resolveBranding } from '../../report/branding.js';
10
+ import { resolveBranding } from '@cclabsnz/sf-core';
11
11
  import { resolveFrameworks } from '../../compliance/resolve.js';
12
12
  import { buildAuditContext, resolveOrgInfo } from '../../lib/wire.js';
13
13
  import { loadScoringConfig } from '../../findings/loadScoringConfig.js';
@@ -107,6 +107,8 @@ export default class SecurityAuditCommand extends SfCommand {
107
107
  store.archive(result);
108
108
  this.log('');
109
109
  this.printSummary(result);
110
+ this.log('');
111
+ this.log(' Deep dives: https://softwareinsights.dev · Remediation help: https://cloudcounsel.co.nz');
110
112
  if (flags['fail-on']) {
111
113
  this.handleFailOn(result, flags['fail-on']);
112
114
  }
@@ -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
@@ -1,5 +1,5 @@
1
1
  import type { Finding } from './Finding.js';
2
- import type { OrgMetrics } from '../context/OrgMetrics.js';
2
+ import type { OrgMetrics } from '@cclabsnz/sf-core';
3
3
  import type { AttackChain } from '../chains/AttackChain.js';
4
4
  export interface AuditResult {
5
5
  generatedAt: Date;
@@ -1,4 +1,4 @@
1
- import type { RiskLevel } from './RiskLevel.js';
1
+ import type { RiskLevel } from '@cclabsnz/sf-core';
2
2
  import type { Capability } from '../chains/Capability.js';
3
3
  export interface AffectedItem {
4
4
  label: string;
@@ -1,27 +1,13 @@
1
1
  import { z } from 'zod';
2
- import type { RiskLevel } from './RiskLevel.js';
2
+ import type { RiskLevel } from '@cclabsnz/sf-core';
3
3
  export declare const scoringConfigSchema: z.ZodObject<{
4
- /** When provided, ALL five risk levels (CRITICAL, HIGH, MEDIUM, LOW, INFO) must be present.
5
- * The entire object is replaced atomically during merge, not key-by-key. */
6
4
  riskScores: z.ZodOptional<z.ZodObject<{
7
5
  CRITICAL: z.ZodNumber;
8
6
  HIGH: z.ZodNumber;
9
7
  MEDIUM: z.ZodNumber;
10
8
  LOW: z.ZodNumber;
11
9
  INFO: z.ZodNumber;
12
- }, "strip", z.ZodTypeAny, {
13
- CRITICAL: number;
14
- HIGH: number;
15
- MEDIUM: number;
16
- LOW: number;
17
- INFO: number;
18
- }, {
19
- CRITICAL: number;
20
- HIGH: number;
21
- MEDIUM: number;
22
- LOW: number;
23
- INFO: number;
24
- }>>;
10
+ }, z.core.$strip>>;
25
11
  checkWeights: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
26
12
  gradeThresholds: z.ZodOptional<z.ZodObject<{
27
13
  A: z.ZodOptional<z.ZodObject<{
@@ -29,227 +15,33 @@ export declare const scoringConfigSchema: z.ZodObject<{
29
15
  maxCritical: z.ZodOptional<z.ZodNumber>;
30
16
  maxHigh: z.ZodOptional<z.ZodNumber>;
31
17
  maxMedium: z.ZodOptional<z.ZodNumber>;
32
- }, "strip", z.ZodTypeAny, {
33
- minScore?: number | undefined;
34
- maxCritical?: number | undefined;
35
- maxHigh?: number | undefined;
36
- maxMedium?: number | undefined;
37
- }, {
38
- minScore?: number | undefined;
39
- maxCritical?: number | undefined;
40
- maxHigh?: number | undefined;
41
- maxMedium?: number | undefined;
42
- }>>;
18
+ }, z.core.$strip>>;
43
19
  B: z.ZodOptional<z.ZodObject<{
44
20
  minScore: z.ZodOptional<z.ZodNumber>;
45
21
  maxCritical: z.ZodOptional<z.ZodNumber>;
46
22
  maxHigh: z.ZodOptional<z.ZodNumber>;
47
23
  maxMedium: z.ZodOptional<z.ZodNumber>;
48
- }, "strip", z.ZodTypeAny, {
49
- minScore?: number | undefined;
50
- maxCritical?: number | undefined;
51
- maxHigh?: number | undefined;
52
- maxMedium?: number | undefined;
53
- }, {
54
- minScore?: number | undefined;
55
- maxCritical?: number | undefined;
56
- maxHigh?: number | undefined;
57
- maxMedium?: number | undefined;
58
- }>>;
24
+ }, z.core.$strip>>;
59
25
  C: z.ZodOptional<z.ZodObject<{
60
26
  minScore: z.ZodOptional<z.ZodNumber>;
61
27
  maxCritical: z.ZodOptional<z.ZodNumber>;
62
28
  maxHigh: z.ZodOptional<z.ZodNumber>;
63
29
  maxMedium: z.ZodOptional<z.ZodNumber>;
64
- }, "strip", z.ZodTypeAny, {
65
- minScore?: number | undefined;
66
- maxCritical?: number | undefined;
67
- maxHigh?: number | undefined;
68
- maxMedium?: number | undefined;
69
- }, {
70
- minScore?: number | undefined;
71
- maxCritical?: number | undefined;
72
- maxHigh?: number | undefined;
73
- maxMedium?: number | undefined;
74
- }>>;
30
+ }, z.core.$strip>>;
75
31
  D: z.ZodOptional<z.ZodObject<{
76
32
  minScore: z.ZodOptional<z.ZodNumber>;
77
33
  maxCritical: z.ZodOptional<z.ZodNumber>;
78
34
  maxHigh: z.ZodOptional<z.ZodNumber>;
79
35
  maxMedium: z.ZodOptional<z.ZodNumber>;
80
- }, "strip", z.ZodTypeAny, {
81
- minScore?: number | undefined;
82
- maxCritical?: number | undefined;
83
- maxHigh?: number | undefined;
84
- maxMedium?: number | undefined;
85
- }, {
86
- minScore?: number | undefined;
87
- maxCritical?: number | undefined;
88
- maxHigh?: number | undefined;
89
- maxMedium?: number | undefined;
90
- }>>;
36
+ }, z.core.$strip>>;
91
37
  F: z.ZodOptional<z.ZodObject<{
92
38
  minScore: z.ZodOptional<z.ZodNumber>;
93
39
  maxCritical: z.ZodOptional<z.ZodNumber>;
94
40
  maxHigh: z.ZodOptional<z.ZodNumber>;
95
41
  maxMedium: z.ZodOptional<z.ZodNumber>;
96
- }, "strip", z.ZodTypeAny, {
97
- minScore?: number | undefined;
98
- maxCritical?: number | undefined;
99
- maxHigh?: number | undefined;
100
- maxMedium?: number | undefined;
101
- }, {
102
- minScore?: number | undefined;
103
- maxCritical?: number | undefined;
104
- maxHigh?: number | undefined;
105
- maxMedium?: number | undefined;
106
- }>>;
107
- }, "strip", z.ZodTypeAny, {
108
- A?: {
109
- minScore?: number | undefined;
110
- maxCritical?: number | undefined;
111
- maxHigh?: number | undefined;
112
- maxMedium?: number | undefined;
113
- } | undefined;
114
- B?: {
115
- minScore?: number | undefined;
116
- maxCritical?: number | undefined;
117
- maxHigh?: number | undefined;
118
- maxMedium?: number | undefined;
119
- } | undefined;
120
- C?: {
121
- minScore?: number | undefined;
122
- maxCritical?: number | undefined;
123
- maxHigh?: number | undefined;
124
- maxMedium?: number | undefined;
125
- } | undefined;
126
- D?: {
127
- minScore?: number | undefined;
128
- maxCritical?: number | undefined;
129
- maxHigh?: number | undefined;
130
- maxMedium?: number | undefined;
131
- } | undefined;
132
- F?: {
133
- minScore?: number | undefined;
134
- maxCritical?: number | undefined;
135
- maxHigh?: number | undefined;
136
- maxMedium?: number | undefined;
137
- } | undefined;
138
- }, {
139
- A?: {
140
- minScore?: number | undefined;
141
- maxCritical?: number | undefined;
142
- maxHigh?: number | undefined;
143
- maxMedium?: number | undefined;
144
- } | undefined;
145
- B?: {
146
- minScore?: number | undefined;
147
- maxCritical?: number | undefined;
148
- maxHigh?: number | undefined;
149
- maxMedium?: number | undefined;
150
- } | undefined;
151
- C?: {
152
- minScore?: number | undefined;
153
- maxCritical?: number | undefined;
154
- maxHigh?: number | undefined;
155
- maxMedium?: number | undefined;
156
- } | undefined;
157
- D?: {
158
- minScore?: number | undefined;
159
- maxCritical?: number | undefined;
160
- maxHigh?: number | undefined;
161
- maxMedium?: number | undefined;
162
- } | undefined;
163
- F?: {
164
- minScore?: number | undefined;
165
- maxCritical?: number | undefined;
166
- maxHigh?: number | undefined;
167
- maxMedium?: number | undefined;
168
- } | undefined;
169
- }>>;
170
- }, "strip", z.ZodTypeAny, {
171
- riskScores?: {
172
- CRITICAL: number;
173
- HIGH: number;
174
- MEDIUM: number;
175
- LOW: number;
176
- INFO: number;
177
- } | undefined;
178
- checkWeights?: Record<string, number> | undefined;
179
- gradeThresholds?: {
180
- A?: {
181
- minScore?: number | undefined;
182
- maxCritical?: number | undefined;
183
- maxHigh?: number | undefined;
184
- maxMedium?: number | undefined;
185
- } | undefined;
186
- B?: {
187
- minScore?: number | undefined;
188
- maxCritical?: number | undefined;
189
- maxHigh?: number | undefined;
190
- maxMedium?: number | undefined;
191
- } | undefined;
192
- C?: {
193
- minScore?: number | undefined;
194
- maxCritical?: number | undefined;
195
- maxHigh?: number | undefined;
196
- maxMedium?: number | undefined;
197
- } | undefined;
198
- D?: {
199
- minScore?: number | undefined;
200
- maxCritical?: number | undefined;
201
- maxHigh?: number | undefined;
202
- maxMedium?: number | undefined;
203
- } | undefined;
204
- F?: {
205
- minScore?: number | undefined;
206
- maxCritical?: number | undefined;
207
- maxHigh?: number | undefined;
208
- maxMedium?: number | undefined;
209
- } | undefined;
210
- } | undefined;
211
- }, {
212
- riskScores?: {
213
- CRITICAL: number;
214
- HIGH: number;
215
- MEDIUM: number;
216
- LOW: number;
217
- INFO: number;
218
- } | undefined;
219
- checkWeights?: Record<string, number> | undefined;
220
- gradeThresholds?: {
221
- A?: {
222
- minScore?: number | undefined;
223
- maxCritical?: number | undefined;
224
- maxHigh?: number | undefined;
225
- maxMedium?: number | undefined;
226
- } | undefined;
227
- B?: {
228
- minScore?: number | undefined;
229
- maxCritical?: number | undefined;
230
- maxHigh?: number | undefined;
231
- maxMedium?: number | undefined;
232
- } | undefined;
233
- C?: {
234
- minScore?: number | undefined;
235
- maxCritical?: number | undefined;
236
- maxHigh?: number | undefined;
237
- maxMedium?: number | undefined;
238
- } | undefined;
239
- D?: {
240
- minScore?: number | undefined;
241
- maxCritical?: number | undefined;
242
- maxHigh?: number | undefined;
243
- maxMedium?: number | undefined;
244
- } | undefined;
245
- F?: {
246
- minScore?: number | undefined;
247
- maxCritical?: number | undefined;
248
- maxHigh?: number | undefined;
249
- maxMedium?: number | undefined;
250
- } | undefined;
251
- } | undefined;
252
- }>;
42
+ }, z.core.$strip>>;
43
+ }, z.core.$strip>>;
44
+ }, z.core.$strip>;
253
45
  export type ScoringConfigInput = z.infer<typeof scoringConfigSchema>;
254
46
  export interface GradeConditions {
255
47
  minScore?: number;
@@ -1,7 +1,7 @@
1
1
  import type { Finding } from './Finding.js';
2
- import type { OrgMetrics } from '../context/OrgMetrics.js';
2
+ import type { OrgMetrics } from '@cclabsnz/sf-core';
3
3
  import type { AuditResult } from './AuditResult.js';
4
- import type { AuditContext } from '../context/AuditContext.js';
4
+ import type { AuditContext } from '@cclabsnz/sf-core';
5
5
  import type { ScoringConfig } from './ScoringConfig.js';
6
6
  import type { AttackChain } from '../chains/AttackChain.js';
7
7
  export declare function buildAuditResult(ctx: AuditContext, findings: Finding[], metrics: Partial<OrgMetrics>, config?: ScoringConfig, attackChains?: AttackChain[]): AuditResult;
@@ -1,4 +1,4 @@
1
- import { EMPTY_METRICS } from '../context/OrgMetrics.js';
1
+ import { EMPTY_METRICS } from '@cclabsnz/sf-core';
2
2
  import { DEFAULT_SCORING_CONFIG } from './ScoringConfig.js';
3
3
  function meetsConditions(conditions, healthScore, criticalCount, highCount, mediumCount) {
4
4
  if (conditions.minScore !== undefined && healthScore < conditions.minScore)
@@ -1,5 +1,5 @@
1
1
  import type { Finding } from '../findings/Finding.js';
2
- import type { OrgMetrics } from '../context/OrgMetrics.js';
2
+ import type { OrgMetrics } from '@cclabsnz/sf-core';
3
3
  import type { AuditResult } from '../findings/AuditResult.js';
4
4
  export type FindingChangeType = 'new' | 'resolved' | 'severity-changed' | 'detail-changed' | 'unchanged';
5
5
  export interface FindingChange {
@@ -1,4 +1,4 @@
1
- import type { OrgMetrics } from '../context/OrgMetrics.js';
1
+ import type { OrgMetrics } from '@cclabsnz/sf-core';
2
2
  export interface MetricMeta {
3
3
  label: string;
4
4
  /** Which direction means "getting better"? */
package/lib/index.d.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  export type { AuditResult } from './findings/AuditResult.js';
2
2
  export type { Finding } from './findings/Finding.js';
3
- export type { RiskLevel } from './findings/RiskLevel.js';
4
- export type { OrgMetrics } from './context/OrgMetrics.js';
3
+ export type { RiskLevel } from '@cclabsnz/sf-core';
4
+ export type { OrgMetrics } from '@cclabsnz/sf-core';
5
5
  export type { AuditDiff, FindingChange, FindingChangeType, MetricDelta } from './history/AuditDiff.js';
6
6
  export { HistoryStore } from './history/HistoryStore.js';
7
7
  export { computeDiff } from './history/DiffEngine.js';
@@ -0,0 +1,2 @@
1
+ export declare function referencesCallout(source: string, name: string): boolean;
2
+ //# sourceMappingURL=apexRefs.d.ts.map