@cclabsnz/sf-audit 1.16.0 → 1.18.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 (170) hide show
  1. package/CHANGELOG.md +172 -1
  2. package/PERMISSIONS.md +139 -0
  3. package/README.md +98 -26
  4. package/config/scoring.sample.json +104 -5
  5. package/docs/permissionset/SF_Audit_ReadOnly.permissionset-meta.xml +54 -0
  6. package/lib/apps/analyzeApps.d.ts +8 -2
  7. package/lib/apps/analyzeApps.js +7 -2
  8. package/lib/apps/apiLogSource.d.ts +39 -0
  9. package/lib/apps/apiLogSource.js +75 -0
  10. package/lib/apps/appResolver.js +30 -4
  11. package/lib/apps/grantedAccess.js +16 -3
  12. package/lib/apps/leastPrivilege.d.ts +3 -1
  13. package/lib/apps/leastPrivilege.js +7 -3
  14. package/lib/apps/permissionSetGenerator.d.ts +22 -0
  15. package/lib/apps/permissionSetGenerator.js +100 -0
  16. package/lib/apps/types.d.ts +6 -0
  17. package/lib/apps/usageCollector.d.ts +7 -1
  18. package/lib/apps/usageCollector.js +57 -26
  19. package/lib/chains/CapabilityRegistry.js +26 -0
  20. package/lib/chains/ChainEngine.js +11 -1
  21. package/lib/chains/namedChains.js +130 -24
  22. package/lib/checks/CheckEngine.d.ts +3 -1
  23. package/lib/checks/CheckEngine.js +65 -26
  24. package/lib/checks/impl/AgentUserPrivilegeCheck.js +5 -4
  25. package/lib/checks/impl/AnonymousApexAuditCheck.js +41 -8
  26. package/lib/checks/impl/ApexCrudFLSCheck.js +45 -10
  27. package/lib/checks/impl/ApexSharingCheck.js +19 -26
  28. package/lib/checks/impl/ApiClientPermissionCheck.js +21 -5
  29. package/lib/checks/impl/AuditTrailCheck.js +23 -8
  30. package/lib/checks/impl/AuthProviderRegistrationHandlerCheck.d.ts +10 -0
  31. package/lib/checks/impl/AuthProviderRegistrationHandlerCheck.js +131 -0
  32. package/lib/checks/impl/CertificateExpiryCheck.js +2 -1
  33. package/lib/checks/impl/ConnectedAppScopeCheck.js +61 -5
  34. package/lib/checks/impl/ConnectedAppsCheck.js +60 -5
  35. package/lib/checks/impl/ContentLinksCheck.js +33 -9
  36. package/lib/checks/impl/CorsAllowlistCheck.js +3 -2
  37. package/lib/checks/impl/DataClassificationCheck.js +15 -13
  38. package/lib/checks/impl/DataCloudDataSpaceIsolationCheck.d.ts +10 -0
  39. package/lib/checks/impl/DataCloudDataSpaceIsolationCheck.js +116 -0
  40. package/lib/checks/impl/DebugLogAccessCheck.js +4 -4
  41. package/lib/checks/impl/DelegatedAdministrationGroupsCheck.d.ts +10 -0
  42. package/lib/checks/impl/DelegatedAdministrationGroupsCheck.js +76 -0
  43. package/lib/checks/impl/DelegatedAuthenticationExposureCheck.d.ts +10 -0
  44. package/lib/checks/impl/DelegatedAuthenticationExposureCheck.js +105 -0
  45. package/lib/checks/impl/DeploymentIdentityCheck.js +32 -5
  46. package/lib/checks/impl/EmailSecurityCheck.d.ts +1 -1
  47. package/lib/checks/impl/EmailSecurityCheck.js +14 -34
  48. package/lib/checks/impl/EncryptionCoverageCheck.js +21 -15
  49. package/lib/checks/impl/EnhancedDomainsCheck.js +17 -2
  50. package/lib/checks/impl/EscalationPermsCheck.d.ts +2 -0
  51. package/lib/checks/impl/EscalationPermsCheck.js +88 -21
  52. package/lib/checks/impl/ExperienceCloudSiteCheck.js +56 -5
  53. package/lib/checks/impl/ExternalAccountHierarchyExposureCheck.d.ts +10 -0
  54. package/lib/checks/impl/ExternalAccountHierarchyExposureCheck.js +65 -0
  55. package/lib/checks/impl/ExternalCredentialsCheck.js +6 -3
  56. package/lib/checks/impl/FailedLoginCheck.js +36 -9
  57. package/lib/checks/impl/FieldHistoryTrackingCheck.js +14 -11
  58. package/lib/checks/impl/FlowHttpCalloutCredentialBypassCheck.d.ts +10 -0
  59. package/lib/checks/impl/FlowHttpCalloutCredentialBypassCheck.js +115 -0
  60. package/lib/checks/impl/GenAiPromptTemplateGroundingCheck.d.ts +10 -0
  61. package/lib/checks/impl/GenAiPromptTemplateGroundingCheck.js +227 -0
  62. package/lib/checks/impl/GuestExecutableApexCheck.d.ts +1 -1
  63. package/lib/checks/impl/GuestExecutableApexCheck.js +105 -14
  64. package/lib/checks/impl/GuestRecordAccessPolicyCheck.js +52 -11
  65. package/lib/checks/impl/HardcodedCredentialsCheck.js +7 -2
  66. package/lib/checks/impl/HealthCheckCheck.js +1 -0
  67. package/lib/checks/impl/HighAssuranceSessionCheck.js +16 -11
  68. package/lib/checks/impl/InactiveUsersCheck.js +1 -1
  69. package/lib/checks/impl/InboundEmailHandlerExposureCheck.d.ts +10 -0
  70. package/lib/checks/impl/InboundEmailHandlerExposureCheck.js +136 -0
  71. package/lib/checks/impl/IntegrationLeastPrivilegeCheck.js +7 -6
  72. package/lib/checks/impl/InternalUserMfaCheck.js +26 -8
  73. package/lib/checks/impl/IpRestrictionsCheck.js +35 -16
  74. package/lib/checks/impl/LoginAccessPolicyCheck.js +5 -4
  75. package/lib/checks/impl/LoginAnomalyCheck.js +10 -7
  76. package/lib/checks/impl/LoginSessionCheck.js +2 -0
  77. package/lib/checks/impl/MfaEnforcementCheck.js +23 -6
  78. package/lib/checks/impl/MfaMethodStrengthCheck.js +18 -3
  79. package/lib/checks/impl/MfaRegistrationCheck.js +4 -3
  80. package/lib/checks/impl/MyDomainLoginPolicyCheck.js +23 -10
  81. package/lib/checks/impl/OauthDeviceAndAssetTokenFlowsCheck.d.ts +10 -0
  82. package/lib/checks/impl/OauthDeviceAndAssetTokenFlowsCheck.js +84 -0
  83. package/lib/checks/impl/OrgWideEmailSpoofingCheck.d.ts +10 -0
  84. package/lib/checks/impl/OrgWideEmailSpoofingCheck.js +106 -0
  85. package/lib/checks/impl/OutboundMessagesCheck.js +48 -6
  86. package/lib/checks/impl/PackagePostInstallSupplyChainCheck.d.ts +10 -0
  87. package/lib/checks/impl/PackagePostInstallSupplyChainCheck.js +89 -0
  88. package/lib/checks/impl/PlatformEventSubscriberContextCheck.d.ts +10 -0
  89. package/lib/checks/impl/PlatformEventSubscriberContextCheck.js +88 -0
  90. package/lib/checks/impl/PrivilegedAccessCheck.js +12 -5
  91. package/lib/checks/impl/ReleaseUpdatesCheck.js +18 -3
  92. package/lib/checks/impl/RemoteSitesCheck.js +4 -4
  93. package/lib/checks/impl/RestrictionRulesIntegrityCheck.d.ts +10 -0
  94. package/lib/checks/impl/RestrictionRulesIntegrityCheck.js +105 -0
  95. package/lib/checks/impl/SeparationOfDutiesCheck.js +14 -3
  96. package/lib/checks/impl/ShieldTenantSecretLifecycleCheck.d.ts +10 -0
  97. package/lib/checks/impl/ShieldTenantSecretLifecycleCheck.js +90 -0
  98. package/lib/checks/impl/SoapLoginApiAuthCheck.js +20 -8
  99. package/lib/checks/impl/SsoEnforcementCheck.js +16 -5
  100. package/lib/checks/impl/TransactionSecurityPolicyCheck.js +5 -5
  101. package/lib/checks/impl/TrustedIPRangesCheck.js +18 -9
  102. package/lib/checks/impl/UsersAndAdminsCheck.js +24 -4
  103. package/lib/checks/permCatalog.js +1 -1
  104. package/lib/checks/registry.js +30 -0
  105. package/lib/checks/support/apexAccess.d.ts +56 -0
  106. package/lib/checks/support/apexAccess.js +127 -0
  107. package/lib/checks/support/missingObject.d.ts +13 -0
  108. package/lib/checks/support/missingObject.js +37 -0
  109. package/lib/checks/support/schema.d.ts +17 -0
  110. package/lib/checks/support/schema.js +41 -0
  111. package/lib/commands/audit/apps.d.ts +1 -0
  112. package/lib/commands/audit/apps.js +86 -30
  113. package/lib/commands/audit/diff.js +2 -2
  114. package/lib/commands/audit/events/pull.js +3 -1
  115. package/lib/commands/audit/history.js +2 -2
  116. package/lib/commands/audit/incident/collect.js +3 -1
  117. package/lib/commands/audit/incident/report.js +2 -2
  118. package/lib/commands/audit/security.d.ts +3 -0
  119. package/lib/commands/audit/security.js +65 -10
  120. package/lib/commands/audit/timeline.js +2 -2
  121. package/lib/compliance/mapping.js +28 -7
  122. package/lib/findings/AuditResult.d.ts +10 -0
  123. package/lib/findings/CheckMeta.js +15 -0
  124. package/lib/findings/Finding.d.ts +4 -0
  125. package/lib/findings/ScoringConfig.d.ts +10 -8
  126. package/lib/findings/ScoringConfig.js +12 -5
  127. package/lib/findings/coverage.d.ts +34 -0
  128. package/lib/findings/coverage.js +42 -0
  129. package/lib/findings/exitCode.js +1 -1
  130. package/lib/findings/loadScoringConfig.js +51 -8
  131. package/lib/findings/scoring.js +61 -10
  132. package/lib/history/HistoryStore.js +9 -3
  133. package/lib/history/archivePolicy.d.ts +19 -0
  134. package/lib/history/archivePolicy.js +34 -0
  135. package/lib/incident/bundleIo.js +4 -3
  136. package/lib/incident/collect/collectBundle.d.ts +1 -1
  137. package/lib/incident/collect/collectBundle.js +4 -3
  138. package/lib/incident/collect/streamGuestLogs.d.ts +1 -1
  139. package/lib/incident/collect/streamGuestLogs.js +3 -2
  140. package/lib/incident/csv.js +4 -4
  141. package/lib/incident/render/evidence.js +3 -3
  142. package/lib/incident/render/html.js +2 -3
  143. package/lib/index.d.ts +2 -0
  144. package/lib/index.js +2 -0
  145. package/lib/lib/packageInfo.d.ts +6 -0
  146. package/lib/lib/packageInfo.js +19 -0
  147. package/lib/preflight/permissionMap.d.ts +2 -20
  148. package/lib/preflight/permissionMap.js +2 -43
  149. package/lib/preflight/permissions.d.ts +25 -0
  150. package/lib/preflight/permissions.js +50 -0
  151. package/lib/renderers/AttackChainDagRenderer.d.ts +7 -0
  152. package/lib/renderers/AttackChainDagRenderer.js +139 -0
  153. package/lib/renderers/ClientReportRenderer.d.ts +2 -0
  154. package/lib/renderers/ClientReportRenderer.js +34 -6
  155. package/lib/renderers/DiffHtmlRenderer.js +2 -7
  156. package/lib/renderers/HistoryRenderer.js +19 -11
  157. package/lib/renderers/HtmlRenderer.js +23 -6
  158. package/lib/renderers/MarkdownRenderer.js +11 -1
  159. package/lib/renderers/SarifRenderer.d.ts +43 -0
  160. package/lib/renderers/SarifRenderer.js +250 -0
  161. package/lib/report/ExecutivePriorities.js +1 -1
  162. package/lib/report/RemediationRoadmap.d.ts +5 -1
  163. package/lib/report/RemediationRoadmap.js +6 -2
  164. package/lib/waivers/WaiverLoader.d.ts +28 -0
  165. package/lib/waivers/WaiverLoader.js +103 -0
  166. package/lib/waivers/WaiverModel.d.ts +32 -0
  167. package/lib/waivers/WaiverModel.js +28 -0
  168. package/lib/waivers/applyWaivers.d.ts +22 -0
  169. package/lib/waivers/applyWaivers.js +85 -0
  170. package/package.json +6 -4
package/CHANGELOG.md CHANGED
@@ -9,7 +9,178 @@ published note and carries the signed provenance attestation and CycloneDX SBOM
9
9
 
10
10
  ## [Unreleased]
11
11
 
12
- Merged to `main`, not yet released.
12
+ ## [v1.18.0](https://github.com/cclabsnz/sf-audit-plugin/releases/tag/v1.18.0) — 2026-10-21
13
+
14
+ Evidence coverage on a live org rises from about 58% to 96–97%, and grades and attack chains now
15
+ mean what they say. Found by running the audit against a Developer Edition org and two sandboxes.
16
+
17
+ ### Fixed
18
+
19
+ - `engines.node` now says `>=22.0.0`, not `>=18.0.0`. `@salesforce/core` 9 and
20
+ `@salesforce/sf-plugins-core` 13 already require Node 22, so the plugin never ran on 18 or 20.
21
+ The README's requirements say Node.js 22+ to match.
22
+ - About 40 checks sent queries the org rejected, then reported "insufficient permissions":
23
+ - fields that do not exist (`LoginHistory.Username`, `ContentDistribution.PasswordEnabled`,
24
+ `Organization.MyDomain`, `RestrictionRule.Active`, the wrong MFA permission field, and others)
25
+ - objects sent to the wrong API (`TraceFlag`, `DelegateGroup`, `ExternalCredential`,
26
+ `NetworkAccess` and `CorsWhitelistEntry`)
27
+ - filters on fields Salesforce will not filter (`SetupAuditTrail.Section`, `LoginHistory.Status`)
28
+ - invalid syntax: the reserved alias `expr0`, and `COUNT(Id)` on `FieldDefinition`
29
+ - Commands pinned API 62.0 and could not see newer fields. They now use the org's own version.
30
+ - A rejected query is reported as "query rejected by the org" and quotes Salesforce's error.
31
+ "Insufficient permissions" is kept for real access errors, and it names the needed permission.
32
+ - Permission fields that only some editions carry are checked by describe before they are queried.
33
+ If one is absent, the check says the feature is not available in this org; that never counts as
34
+ a pass.
35
+ - `MALFORMED_QUERY` was treated as "object not present", so a broken query read as clean.
36
+ - Inconclusive checks no longer raise the health score.
37
+
38
+ ### Changed
39
+
40
+ - Every output gives the reason for the grade, for example `F: 2 CRITICAL findings (D allows none)`.
41
+ - Only open findings and named attack chains count towards the grade. Potential chains do not.
42
+ - CRITICAL is kept for breach-grade exposure:
43
+ - The super-admin finding and Modify All Data are rated by how many hold them (more than 5 is
44
+ CRITICAL, more than 3 is HIGH).
45
+ - Modify All Data and separation-of-duties leave out users the super-admin finding already
46
+ covers, so the same admins are not counted three times.
47
+ - In a sandbox, admin-count findings are capped at HIGH.
48
+ - An expiring certificate is HIGH.
49
+ - Externally callable Apex is CRITICAL only when a class declares `without sharing`.
50
+ - "Unauthenticated bulk exfiltration" needs a confirmed guest exposure. "Standard user to org
51
+ takeover" needs a low-trust way in and an escalation a non-admin can use. A guest user merely
52
+ existing no longer opens either chain, or any potential chain.
53
+ - The remediation roadmap lists only work: INFO inventories and checks that gathered no evidence
54
+ are left out. Healthy lowest-band results (few failed logins, a Health Check score of 85 or
55
+ more, a small number of View/Modify All Data holders) are reported as passed.
56
+ - Reports with unassessed checks point to `sf audit preflight` and PERMISSIONS.md.
57
+ `PERMISSIONS.md` and the read-only permission set now ship in the npm package.
58
+
59
+ ### Added
60
+
61
+ - `scripts/capture-schema.mjs` and a captured Developer Edition schema
62
+ (`test/fixtures/schema/developer-edition.json`, standard fields only). A test runs every
63
+ check against it and fails on any query the org would reject.
64
+ ||||||| a23c86e
65
+
66
+ ## [v1.17.0](https://github.com/cclabsnz/sf-audit-plugin/releases/tag/v1.17.0) — 2026-10-17
67
+
68
+ 109 checks (up from 95) and 19 attack chains (up from 17).
69
+
70
+ ### Added
71
+
72
+ - Fourteen checks for surfaces the audit did not reach before:
73
+ - `genai-prompt-template-grounding`: active Prompt Templates grounded on system-mode flows or
74
+ unshared Apex, or mixing untrusted external fields with sensitive CRM data.
75
+ - `data-cloud-data-space-isolation`: a default Data Space shared with integrations, partner or
76
+ agent users, and unconstrained Data Share Targets.
77
+ - `platform-event-subscriber-context`: Platform Event subscribers running in system context or
78
+ as an admin while low-trust or guest users can publish the event.
79
+ - `flow-http-callout-credential-bypass`: Flow HTTP callouts with embedded tokens, or that go
80
+ around Named Credentials.
81
+ - `oauth-device-and-asset-token-flows`: the OAuth Device Flow and Username-Password Flow
82
+ enabled in OAuth and OpenID Connect Settings. An unreadable setting is an advisory, never
83
+ "disabled".
84
+ - `delegated-authentication-exposure`: Delegated Authentication over unencrypted or non-mTLS
85
+ endpoints, or assigned to System Administrator profiles.
86
+ - `delegated-administration-groups`: delegated admin groups that can manage users, log in as
87
+ them or assign permission sets, which permission set queries do not show.
88
+ - `auth-provider-registration-handler`: a RegistrationHandler running as an admin that links
89
+ accounts by email, open to pre-auth account takeover.
90
+ - `inbound-email-handler-exposure`: email services that accept any sender and run Apex.
91
+ - `org-wide-email-spoofing`: Org-Wide Email Addresses open to all profiles without SPF/DKIM
92
+ alignment.
93
+ - `external-account-hierarchy-exposure`: Partner Super Users and External Account Hierarchies
94
+ that widen portal record reach past the external OWD.
95
+ - `restriction-rules-integrity`: inactive Restriction Rules leaving records exposed, and
96
+ conflicting active rules on one object.
97
+ - `package-post-install-supply-chain`: packaged Apex implementing `InstallHandler`, which runs
98
+ in system context on every install and push upgrade.
99
+ - `shield-tenant-secret-lifecycle`: Shield tenant secrets not rotated in 365 days.
100
+ - Two attack chains, both CRITICAL: **Unauthenticated inbound email to privileged code
101
+ execution** (`inbound-email-rce`) and **Guest or low-trust platform event publish to automated
102
+ process escalation** (`platform-event-priv-esc`).
103
+ - Every report states its evidence coverage: the share of checks that gathered evidence, and the
104
+ ids of those that could not. Below 90% a would-be A is capped at B, and the report says why.
105
+ `grade` stays a plain A–F letter; the detail is in the new `coverage` field of the JSON output.
106
+ - Accepted-risk waivers (`--waivers`, or `.sfaudit-waivers.json` in the working directory). A
107
+ waived finding leaves the score, `--fail-on` and the executive priorities and roadmap, and is
108
+ listed under Accepted Risks. Matching is exact, waivers run at most 365 days, and a CRITICAL
109
+ finding needs `acknowledgeCritical`. The loaded file's path is always printed.
110
+ - `sf audit security --no-history` skips the automatic archive to `~/.sf/audit-history`, and the
111
+ archive is now skipped by default in CI (`CI` set to a truthy value, `GITHUB_ACTIONS`, `TF_BUILD`
112
+ or `JENKINS_URL`), so ephemeral or shared runners don't keep org data. `--keep-history` archives
113
+ anyway and wins over `--no-history`.
114
+ - `sf audit security --format sarif` writes a SARIF 2.1.0 log for GitHub code scanning. Results
115
+ carry stable fingerprints so a recurring finding keeps one alert, the tool version comes from
116
+ the package, and checks that could not gather evidence are reported as tool notifications
117
+ rather than alerts.
118
+ - Attack chains now render as a diagram: each step is a card (severity, finding, capability
119
+ granted) joined by arrows, with the step whose fix breaks the chain marked as the cut-point.
120
+ It appears in the attack-path cards of the HTML report (dark) and in the Attack Scenarios of
121
+ the executive report (light). The diagram is self-contained inline SVG, so it works under the
122
+ executive report's no-script CSP and prints to PDF; long chains wrap onto rows of four.
123
+ - `sf audit apps --emit-permset <dir>` writes each app's suggested least-privilege permission set as
124
+ a local `.permissionset-meta.xml` for review. Nothing is deployed. Apps whose recommendation is
125
+ held back (soak window, many interactive users, incomplete logs) get no file, and generated names
126
+ are unique, valid metadata API names.
127
+ - `sf audit apps` now reads `BulkApi2`, `GraphQlQueryExecution` and `AuraRequest` logs as well as
128
+ `RestApi`, resolves External Client Apps, and counts profile object permissions as granted access.
129
+
130
+ ### Changed
131
+
132
+ - Apex findings now say which control is bypassed. `WITH SYSTEM_MODE` and
133
+ `AccessLevel.SYSTEM_MODE` switch off CRUD/FLS, not record sharing, so they are reported as
134
+ `apex-crud-fls-system-mode` (MEDIUM) and, for guest-callable classes, as the new
135
+ `guest-executable-apex-system-mode` (HIGH), never as a CRITICAL sharing bypass. `USER_MODE`
136
+ counts as CRUD/FLS enforcement.
137
+ - A guest-callable class that calls a helper declared `without sharing` is now CRITICAL
138
+ `guest-executable-apex-unprotected`, naming the helper. A guest-callable `inherited sharing`
139
+ class is no longer reported CRITICAL: at an entry point it runs with sharing.
140
+ - `@RestResource` classes without sharing are reported alongside `@AuraEnabled` and
141
+ `@RemoteAction` ones.
142
+ - A class's sharing keyword is read from its own declaration, ignoring comments, so a
143
+ `without sharing` class mentioning "with sharing" in a comment is no longer read as protected.
144
+ - `salesbleed-pattern` also fires when the way out is a CSP Trusted URL whose domain is parked
145
+ or no longer resolves: whoever registers it receives anything an agent puts in a link or image.
146
+ When the org shows where outsider text enters (an open email handler, guest write access), that
147
+ finding leads the chain as evidence.
148
+ - `--scoring-config` is now checked strictly. An unknown or misspelled key (`gradeTresholds`,
149
+ `minscore`) is an error instead of being silently ignored, `minScore` must be 0–100, and grade
150
+ thresholds must be ordered after merging with the defaults (A at least as strict as B, and so
151
+ on). Errors name the offending path. A JSON Schema for editors ships as
152
+ `schemas/scoring-config.schema.json`, and `config/scoring.sample.json` now lists every
153
+ registered check.
154
+ - The npm description states the current check count, and a test keeps it in step.
155
+ - README documents unattended CI installs and how to check a release's provenance.
156
+ - Requires `@cclabsnz/sf-core` 0.11.0.
157
+
158
+ ### Fixed
159
+
160
+ - Several of the fourteen new checks could not see their evidence, and some reported a pass
161
+ when their query failed; their tests passed because the mocks returned fields the real queries
162
+ never selected. They now read what the org actually returns, and a failed read is inconclusive,
163
+ never a pass.
164
+ - `genai-prompt-template-grounding` no longer builds a regular expression from a class name the
165
+ org returns; the declaration is found with literal patterns in one linear pass.
166
+ - `sf audit apps` no longer reports an empty, clean-looking result when `EventLogFile` cannot be
167
+ read: a failed listing is an error, and partly failed downloads mark the output incomplete and
168
+ suppress revoke recommendations.
169
+ - `connected-apps` lists External Client Apps for manual review of their OAuth policies. Their
170
+ policies are not evaluated automatically, so no External Client App is reported as
171
+ unrestricted or as passing. A failure to list them is reported as inconclusive, and the
172
+ connected-app results still stand.
173
+
174
+ ### Security
175
+
176
+ - Local stores that hold org data (`~/.sf/audit-history`, incident bundles, evidence CSVs,
177
+ guest-log staging) are now created owner-only: directories 0700, files 0600, through
178
+ `secureFs` from `@cclabsnz/sf-core`. An existing history root is tightened on first use.
179
+ Report files written to a user-chosen `--output` directory keep that directory's permissions.
180
+ - Every HTML report now carries a Content-Security-Policy that forbids all network requests:
181
+ the executive report allows no script at all, and the interactive reports allow inline script
182
+ only. Values in the history report that are read back from disk (grade, score, dates) are
183
+ escaped or coerced, so a tampered history file cannot inject markup or script.
13
184
 
14
185
  ## [v1.16.0](https://github.com/cclabsnz/sf-audit-plugin/releases/tag/v1.16.0) — 2026-10-09
15
186
 
package/PERMISSIONS.md ADDED
@@ -0,0 +1,139 @@
1
+ # Minimum Salesforce Permissions for `sf-audit`
2
+
3
+ `sf audit security` is **strictly read-only**. Every check issues
4
+ SOQL / Tooling / REST **GET** queries only: no DML, no Metadata API writes, no
5
+ record modification. The account running the audit needs only enough permission
6
+ to *read* security configuration, setup metadata, and audit/login data.
7
+
8
+ This document lists the **minimum** permission set required for a **complete**
9
+ audit, what each permission is for, and (importantly for a client security
10
+ team) what the tool explicitly does **not** need.
11
+
12
+ > **Key reassurance for the org owner:** the tool reads *configuration and
13
+ > metadata*, not your business record content. It checks Org-Wide Defaults via
14
+ > `EntityDefinition` (describe), not by reading Account/Contact/Opportunity
15
+ > data. It does **not** require `View All Data` to run.
16
+ >
17
+ > One check is a partial exception, and it is stated plainly rather than buried:
18
+ > **Integration Account Least Privilege** (`integration-least-privilege`) asks
19
+ > whether an integration account has ever written to an object it holds
20
+ > Create/Edit/Delete on. It does that with grouped **ownership aggregates** —
21
+ > `SELECT CreatedById, COUNT(Id) … GROUP BY CreatedById` — which return only
22
+ > owner ids and row counts. **No field value of any record is ever selected,
23
+ > read, or stored.** See ["Record visibility and the write-evidence
24
+ > probe"](#record-visibility-and-the-write-evidence-probe) below for what that
25
+ > probe can and cannot conclude without `View All Data`.
26
+
27
+ ## Recommended setup
28
+
29
+ Create a dedicated **permission set** (or integration profile) named e.g.
30
+ `SF Audit (Read-Only)`, assign it to a service/audit user with exactly the
31
+ permissions below, and nothing else. A starter permission-set definition is in
32
+ [`docs/permissionset/SF_Audit_ReadOnly.permissionset-meta.xml`](docs/permissionset/SF_Audit_ReadOnly.permissionset-meta.xml).
33
+
34
+ ## System (user) permissions: required
35
+
36
+ | Permission | API name | Why it's needed | If omitted |
37
+ |---|---|---|---|
38
+ | **API Enabled** | `ApiEnabled` | All access is via SOQL/Tooling/REST over the API | Audit cannot run at all |
39
+ | **View Setup and Configuration** | `ViewSetup` | Reads the bulk of the surface: `SetupAuditTrail`, `TraceFlag`, `ConnectedApplication`, `RemoteProxy`, `CorsWhitelistEntry`, `CspTrustedSite`, `NamedCredential`, `AuthConfig`, `CriticalUpdate`/release updates, `Network` (Experience sites), `ProfileLoginIpRange`, `NetworkAccess`, `Certificate`, `ExternalString` (Custom Labels), `OrgWideEmailAddress`, `EmailServicesFunction`/`EmailServicesAddress`, and Tooling metadata (`ApexClass`, `Flow`, `CustomObject`/`CustomField`, `EntityDefinition`, `FieldDefinition`, `FieldPermissions`, `ObjectPermissions`, `SetupEntityAccess`, `WorkflowOutboundMessage`, `StaticResource`) | Most setup/config checks return **inconclusive** |
40
+ | **Read `OauthToken`** | n/a (object read) | Standing OAuth authorisations per app, for `oauth-token-inventory`. Read separately from `ConnectedApplication`: a refresh token is exchanged without producing a login, so this is the only surface that shows an app which can still act | `oauth-token-inventory` returns **inconclusive** rather than reporting an org with no standing tokens |
41
+ | **View All Users** | `ViewAllUsers` | Enumerate every `User`, `UserLogin`, `PermissionSetAssignment`, and `TwoFactorInfo` record org-wide (not just role-hierarchy-visible users) | User/admin/MFA checks under-count and miss accounts |
42
+ | **View Health Check** | `ViewHealthCheckScreen` | Read `SecurityHealthCheck` and `SecurityHealthCheckRisks` (Tooling) | Health Check + Password/Session checks inconclusive |
43
+ | **Author Apex** | `AuthorApex` | **Read-only use:** the only standard gate that exposes `ApexClass`/`ApexTrigger`/`ApexPage` **`Body`** via the Tooling API. Used by the ~9 Apex/Visualforce code-security checks. Grants *no* ability to modify org data | The 9 code-security checks return **inconclusive**; rest of the audit is unaffected |
44
+ | **View Event Log Files** | `ViewEventLogFiles` | Read `EventLogFile` for the Event Monitoring check | Event Monitoring check inconclusive |
45
+
46
+ ### Recommended (improves completeness)
47
+
48
+ | Permission | API name | Why |
49
+ |---|---|---|
50
+ | **View Roles and Role Hierarchy** | `ViewRoles` | Complete visibility of role-based sharing context |
51
+
52
+ - **View Event Log Files**, **View Setup and Configuration**: required by `sf audit incident collect`.
53
+ - **Query All Files**: lets `incident collect` see files owned by guest users. Without it the report states the gap.
54
+
55
+ ## What the tool does **NOT** need
56
+
57
+ Grant **none** of these. They are unnecessary for a read-only audit and a client
58
+ security team is right to refuse them:
59
+
60
+ - **`View All Data`:** not required to run. Every check works without it, and no
61
+ check reads record content. The one thing it changes is completeness of a
62
+ single probe: without it, `integration-least-privilege` reports each object it
63
+ cannot conclude about as **unprobed** instead of reporting an unused write
64
+ grant (see below). Grant it only if you want that probe to be conclusive
65
+ - **`Modify All Data`** (`ModifyAllData`)
66
+ - **`Customize Application`** (`CustomizeApplication`)
67
+ - **`Manage Users`** / **`Manage Internal Users`**
68
+ - Any **Create / Edit / Delete (DML)** permission on any object
69
+ - **Metadata API** deploy/retrieve (`deployMetadata`, `modifyMetadata`)
70
+ - Password, MFA, or session **management** permissions (the tool *reads* MFA/session config, it does not change it)
71
+
72
+ ## Important caveats
73
+
74
+ - **`Author Apex` naming is misleading.** It sounds like a write/dev permission,
75
+ but for this tool it is used purely to *read* Apex source via Tooling. It does
76
+ not let the audit account modify data or deploy code. If your security policy
77
+ forbids it, omit it: the ~9 code-security checks will report **inconclusive**
78
+ and every other check runs normally.
79
+ - **Feature/licence-gated checks.** The Event Monitoring and SIEM checks require
80
+ **Event Monitoring / Shield** to be licensed in the org; the Shield
81
+ Platform Encryption portion of Data Classification likewise. Where a feature
82
+ isn't licensed, the relevant check reports **inconclusive** rather than failing.
83
+ - **Public `Document` visibility is folder-gated.** The Public Static Resources &
84
+ Documents check queries `Document WHERE IsPublic = true`. `Document` records are
85
+ visible per **folder** access rather than via `ViewSetup`, so an audit user with
86
+ no access to a folder will not see its public documents. Grant the audit user
87
+ read access to document folders (or assign a profile that can view all folders)
88
+ for complete coverage; otherwise that check reports **inconclusive** for what it
89
+ cannot read.
90
+ - **Inconclusive ≠ pass.** Any check the audit user cannot access is surfaced as
91
+ an explicit *inconclusive* finding (never silently treated as a pass) so an
92
+ under-permissioned run is visible in the report, not hidden.
93
+ - **`View Setup and Configuration` vs `View All Data`.** `ViewSetup` is the
94
+ narrowest standard permission that allows SOQL against setup objects. Some
95
+ strict org configurations may still require object-level Read FLS on the
96
+ setup/audit objects above; grant those rather than reaching for `View All Data`.
97
+
98
+ ### Record visibility and the write-evidence probe
99
+
100
+ `integration-least-privilege` is the only check that queries record data, and it
101
+ queries ownership rather than content: for each object an integration account
102
+ holds a write grant on, it runs a grouped count of records whose `CreatedById`
103
+ or `LastModifiedById` is that account. The result is a row count per owner id.
104
+ No field of any record is selected.
105
+
106
+ Like all SOQL, that aggregate runs **as the audit user with sharing enforced**.
107
+ An audit user that cannot see the records gets a successful query and zero rows
108
+ back, which is indistinguishable from "the integration has never written here" —
109
+ and reporting that as an unused grant would be a false accusation against a
110
+ working integration. So:
111
+
112
+ - The check first determines whether the audit user holds `View All Data` (or
113
+ `Modify All Data`). It identifies the running user through the Connect API
114
+ (`/chatter/users/me`, a read-only GET) and reads that user's own permission-set
115
+ assignments.
116
+ - **With** `View All Data`: the probe runs, and objects with no attributed
117
+ record are reported as write grants the integration has never exercised.
118
+ - **Without** it — or if the running user cannot be identified, e.g. Chatter is
119
+ disabled — **no object is probed at all.** Every object is listed as
120
+ *unprobed*, and the finding is marked **inconclusive**. The check never
121
+ reports an unused grant it could not establish.
122
+ - Every other part of that check (escalation-grade permissions, bulk-data
123
+ permissions, standing credentials, dormancy) is drawn from setup objects and
124
+ is unaffected.
125
+
126
+ This is a completeness trade, not a correctness one: refusing `View All Data`
127
+ costs you one probe's conclusions and is visible in the report as such.
128
+
129
+ ## Connected App (CI / automation)
130
+
131
+ To run the audit from CI (e.g. scheduled posture checks), authenticate with a
132
+ **Connected App** using least-privilege OAuth:
133
+
134
+ - OAuth scopes: `api`, `refresh_token`: **no** `full`, **no** `web`
135
+ - Apply IP restrictions to your CI runner's IP ranges if the org enforces them
136
+ - Store the credential (`sf org login sfdx-url` output) as a secret; rotate every
137
+ 90 days or on any suspected exposure
138
+ - Assign the `SF Audit (Read-Only)` permission set to the Connected App's
139
+ run-as / integration user
package/README.md CHANGED
@@ -15,13 +15,14 @@
15
15
 
16
16
  A Salesforce CLI (`sf`) plugin that runs a complete, **read-only** security audit against any Salesforce org, risk-scores it with an A–F grade, and turns the result into a report your security team (or your client's) can act on.
17
17
 
18
- - **95 read-only checks** across identity, access, data, code, integrations, monitoring, and Agentforce / GenAI
19
- - **Attack-chain correlation:** links individual findings into named, multi-step attack scenarios — seventeen modelled chains, plus an emergent pass for combinations nobody has named yet (see [Attack chains](#attack-chains))
20
- - **Compliance mapping:** every finding mapped to **source-verified** controls across 10 frameworks (OWASP, OWASP LLM Top 10, SOC 2, ISO/IEC 27001:2022, Security Benchmark for Salesforce, NZ Privacy Act, HISO 10029, NZISM, HIPAA Security Rule, GDPR)
18
+ - **109 read-only checks** across identity, access, data (including Data Cloud and Shield), code, integrations (including inbound email handlers and package install handlers), monitoring, and Agentforce / GenAI. Apex findings say which control a class bypasses: record sharing, or CRUD/FLS
19
+ - **Attack-chain correlation:** links individual findings into named, multi-step attack scenarios — nineteen modelled chains, plus an emergent pass for combinations nobody has named yet (see [Attack chains](#attack-chains))
20
+ - **Compliance mapping:** every finding mapped to **source-verified** controls across 10 frameworks: 8 general baseline frameworks (OWASP Top 10, OWASP LLM Top 10, SOC 2, ISO/IEC 27001:2022, Security Benchmark for Salesforce, NZ Privacy Act 2020, HISO 10029, NZISM) plus 2 specialized jurisdictional packs (HIPAA Security Rule, GDPR)
21
21
  - **Outputs:** a technical `html` / `md` / `json` report, or a branded, client-ready **executive report** (print-to-PDF) with priorities, remediation roadmap, and a compliance coverage matrix
22
- - **History & diff:** archives each run and shows security-posture drift over time
22
+ - **History & diff:** archives each run and shows security-posture drift over time (skipped by default on CI runners, so they keep no org data)
23
+ - **CI-ready:** `--format sarif` for GitHub code scanning, `--fail-on` to gate a pipeline, and [accepted-risk waivers](#accepting-a-risk) that expire
23
24
  - **Free event baseline:** `sf audit events pull` captures the org's free daily `EventLogFile` logs to local disk before the 1-day retention window drops them — no Event Monitoring / Shield add-on needed
24
- - **Connected-app least-privilege:** `sf audit apps` reads the `RestApi` EventLogFile to see which objects each connected app actually uses, compares that against what its run-as user is granted, and reports the over-grant per object and read/write bit — plus a suggested least-privilege permission set
25
+ - **Connected-app least-privilege:** `sf audit apps` reads the `RestApi`, `BulkApi2`, `GraphQlQueryExecution` and `AuraRequest` EventLogFiles to see which objects each connected app actually uses, compares that against what its run-as user is granted (permission sets and profile), and reports the over-grant per object and read/write bit — plus a suggested least-privilege permission set, which `--emit-permset <dir>` writes as local `.permissionset-meta.xml` files (never deployed)
25
26
  - **Guest User Anomaly investigation:** `sf audit incident collect` saves the guest user's evidence for each anomaly wave, and `sf audit incident report` analyses it offline into a cited verdict: who it was, whether content came back, and whether anyone logged in ([walkthrough](https://www.softwareinsights.dev/posts/salesforce-guest-user-anomaly-investigation-sf-audit-incident/))
26
27
  - Strictly read-only (SOQL/Tooling/REST GETs + Metadata API reads); see [PERMISSIONS.md](PERMISSIONS.md) for the least-privilege access it needs
27
28
 
@@ -33,8 +34,37 @@ sf plugins install @cclabsnz/sf-audit
33
34
 
34
35
  You will be warned that the plugin is not digitally signed. That is expected and says nothing about
35
36
  this plugin: Salesforce only accepts signing keys served from `developer.salesforce.com`, so no
36
- third-party plugin can satisfy it. Answer `y`. For unattended installs, allowlisting and local
37
- development setup are in **[docs/INSTALL.md](docs/INSTALL.md)**.
37
+ third-party plugin can satisfy it. Answer `y`.
38
+
39
+ ### Unattended installs (CI/CD)
40
+
41
+ To install in CI/CD without the interactive prompt, add the plugin to the CLI allowlist first (the merge step needs `jq`):
42
+
43
+ ```bash
44
+ mkdir -p ~/.config/sf
45
+ if [ -f ~/.config/sf/unsignedPluginAllowList.json ]; then
46
+ jq '. + ["@cclabsnz/sf-audit"] | unique' ~/.config/sf/unsignedPluginAllowList.json > ~/.config/sf/unsignedPluginAllowList.json.tmp && mv ~/.config/sf/unsignedPluginAllowList.json.tmp ~/.config/sf/unsignedPluginAllowList.json
47
+ else
48
+ echo '["@cclabsnz/sf-audit"]' > ~/.config/sf/unsignedPluginAllowList.json
49
+ fi
50
+
51
+ sf plugins install @cclabsnz/sf-audit
52
+ ```
53
+
54
+ ### Verifying provenance
55
+
56
+ Every release is published from GitHub Actions with a signed npm provenance attestation that
57
+ links the tarball to the commit and workflow run that built it. To check a version before
58
+ installing it:
59
+
60
+ ```bash
61
+ npm view @cclabsnz/sf-audit@<version> dist.attestations.provenance.predicateType
62
+ # https://slsa.dev/provenance/v1
63
+ ```
64
+
65
+ The package page on npmjs.com shows the same attestation, with a link to the build.
66
+
67
+ Detailed allowlisting and local development setup are in **[docs/INSTALL.md](docs/INSTALL.md)**.
38
68
 
39
69
  Since "trust us" is a poor answer from a tool that authenticates against your production org, the
40
70
  guarantees here are checkable rather than asserted — see [Trust & verification](#trust--verification).
@@ -45,17 +75,19 @@ guarantees here are checkable rather than asserted — see [Trust & verification
45
75
  sf audit security --target-org <orgAlias>
46
76
  ```
47
77
 
48
- Runs all 95 checks and writes an HTML report to the current directory. `sf audit list` prints every
78
+ Runs all 109 checks and writes an HTML report to the current directory. `sf audit list` prints every
49
79
  check id.
50
80
 
51
81
  | Flag | Default | |
52
82
  |------|---------|---|
53
- | `--format` / `-f` | `html` | `html`, `md`, `json`, `executive` — comma-separated |
83
+ | `--format` / `-f` | `html` | `html`, `md`, `json`, `executive`, `sarif` — comma-separated |
54
84
  | `--fail-on` | (none) | Exit 1 if any finding is at or above `CRITICAL`/`HIGH`/`MEDIUM`/`LOW`. For CI |
55
85
  | `--fail-on-inconclusive` | `false` | Exit 3 if any check could not gather evidence. For CI |
86
+ | `--waivers` | `.sfaudit-waivers.json` if present | Accepted-risk waivers. See [Accepting a risk](#accepting-a-risk) |
56
87
  | `--digest` | `false` | Compact result for programmatic callers — no passing checks, no prose, capped lists |
57
88
  | `--checks` | *(all)* | Run only these check ids |
58
89
  | `--frameworks` | `universal` | Compliance matrix scope for the executive report |
90
+ | `--no-history` / `--keep-history` | `false` | Skip, or force, the archive to `~/.sf/audit-history`. Skipped in CI (`CI` set, `GITHUB_ACTIONS`, `TF_BUILD`, `JENKINS_URL`) unless `--keep-history` |
59
91
 
60
92
  ```bash
61
93
  # Fail a pipeline on HIGH or worse
@@ -75,6 +107,9 @@ sf audit security --target-org myOrg --json
75
107
 
76
108
  # Compact result for an agent or script
77
109
  sf audit security --target-org myOrg --json --digest
110
+
111
+ # SARIF 2.1.0 for GitHub code scanning or any SARIF viewer
112
+ sf audit security --target-org myOrg --format sarif --output ./reports
78
113
  ```
79
114
 
80
115
  In GitHub Actions, [cclabsnz/sf-audit-action](https://github.com/cclabsnz/sf-audit-action) wraps this:
@@ -96,24 +131,24 @@ A definite finding outranks unknown coverage: when both apply you get `1`, and t
96
131
  inconclusive count is still in the report body. `3` exists so a pipeline can tell
97
132
  "this org is fine" apart from "the audit user could not see enough to judge".
98
133
 
99
- All twelve flags, more examples, and what the executive report contains:
134
+ Every flag, more examples, and what the executive report contains:
100
135
  **[docs/COMMANDS.md](docs/COMMANDS.md)**.
101
136
 
102
137
  ## What It Checks
103
138
 
104
- **95 read-only checks** across ten domains. Every finding is risk-rated CRITICAL → INFO, mapped to
139
+ **109 read-only checks** across ten domains. Every finding is risk-rated CRITICAL → INFO, mapped to
105
140
  compliance controls, and correlated into [attack chains](#attack-chains).
106
141
 
107
142
  | Domain | Checks |
108
143
  |--------|-------:|
109
- | Identity & Authentication | 13 |
110
- | Users, Permissions & Privilege | 13 |
111
- | Data Access & Sharing | 11 |
112
- | Guest & External-Facing Access | 12 |
113
- | Integrations, Connected Apps & Deployments | 11 |
144
+ | Identity & Authentication | 16 |
145
+ | Users, Permissions & Privilege | 14 |
146
+ | Data Access & Sharing | 14 |
147
+ | Guest & External-Facing Access | 13 |
148
+ | Integrations, Connected Apps & Deployments | 14 |
114
149
  | Monitoring & Threat Detection | 10 |
115
- | Apex & Code Security | 10 |
116
- | AI & Agents (Agentforce / GenAI) | 8 |
150
+ | Apex & Code Security | 12 |
151
+ | AI & Agents (Agentforce / GenAI) | 9 |
117
152
  | Org Health & Configuration | 5 |
118
153
  | Secrets & Credential Storage | 2 |
119
154
 
@@ -125,9 +160,9 @@ advisories are INFO and never inflate the health score.
125
160
 
126
161
  ## Compliance frameworks
127
162
 
128
- Findings map to controls across ten frameworks: OWASP Top 10, OWASP LLM Top 10, SOC 2, ISO/IEC
129
- 27001:2022, the Security Benchmark for Salesforce, the NZ Privacy Act, HISO 10029, NZISM, the HIPAA
130
- Security Rule, and GDPR.
163
+ Findings map to controls across 10 frameworks organized into 8 source-verified general baselines and 2 specialized jurisdictional packs:
164
+ - **8 General Baselines:** OWASP Top 10 (2021), OWASP LLM Top 10 (2025), SOC 2 (2017 TSC), ISO/IEC 27001:2022, Security Benchmark for Salesforce (SBS), New Zealand Privacy Act 2020, HISO 10029:2022, and NZISM (v3.8).
165
+ - **2 Jurisdictional Packs:** HIPAA Security Rule (45 CFR Part 164 Subpart C) and GDPR (Regulation (EU) 2016/679).
131
166
 
132
167
  The mapping is built on a **sourced catalog** — each control carries its framework, pinned version,
133
168
  official title and a citation — so a finding ties to an exact, defensible requirement rather than a
@@ -150,7 +185,7 @@ A list of findings is not a risk assessment. Three MEDIUM findings that combine
150
185
  unauthenticated path to bulk data matter more than a lone HIGH that leads nowhere, and reading a
151
186
  report severity-by-severity hides exactly that.
152
187
 
153
- So every audit correlates its findings into attack chains. **Seventeen named chains** are hand-modelled
188
+ So every audit correlates its findings into attack chains. **Nineteen named chains** are hand-modelled
154
189
  scenarios — each with its own narrative and remediation, several naming the concrete request path an
155
190
  attacker would use. Where no named chain explains a combination, an emergent pass reports the
156
191
  remaining entry-point → outcome pairs as lower-confidence "potential attack paths", so a novel
@@ -159,7 +194,7 @@ combination is still surfaced.
159
194
  Every chain lists the findings forming its steps, and remediating **any one step breaks the chain**.
160
195
  A chain is reported only when every ingredient is present: a clean org produces none.
161
196
 
162
- All seventeen with severities and trigger conditions: **[docs/ATTACK-CHAINS.md](docs/ATTACK-CHAINS.md)**.
197
+ All nineteen with severities and trigger conditions: **[docs/ATTACK-CHAINS.md](docs/ATTACK-CHAINS.md)**.
163
198
 
164
199
  ## Scope & Liability
165
200
 
@@ -199,7 +234,14 @@ confirm each: **[docs/TRUST.md](docs/TRUST.md)**. Least-privilege access is in
199
234
 
200
235
  Each finding carries a risk weight (CRITICAL 10, HIGH 7, MEDIUM 4, LOW 1, INFO 0). The health score is
201
236
  `100 - (total weight / max possible weight) * 100`, capped at 0, and maps to an A–F grade — A needs
202
- ≥ 85 with no HIGH findings; any CRITICAL is an F.
237
+ ≥ 85 with no HIGH findings; any open CRITICAL finding or named CRITICAL attack chain is an F. Every report says
238
+ which condition set the grade. Inconclusive checks count towards neither the penalty nor the maximum,
239
+ so they never improve the score. See [docs/SCORING.md](docs/SCORING.md).
240
+
241
+ Every report also states its **evidence coverage**: how many checks gathered evidence, out of how
242
+ many ran. A check the audit user could not run (missing permission, or an error) is listed by id
243
+ as not assessed. Its area is unknown, not clean. A run below 90% coverage cannot be graded A: it is
244
+ capped at B, and the report says so. Grades below A are never changed by coverage.
203
245
 
204
246
  All weights and grade thresholds are configurable without recompiling, via
205
247
  `--scoring-config ./my-scoring.json`. Start from [`config/scoring.sample.json`](config/scoring.sample.json),
@@ -208,6 +250,36 @@ only what you want to change.
208
250
 
209
251
  Grade bands, the full config shape and worked examples: **[docs/SCORING.md](docs/SCORING.md)**.
210
252
 
253
+ ### Accepting a risk
254
+
255
+ A finding you have reviewed and accepted can be waived, which takes it out of the score and out of
256
+ `--fail-on` until the waiver expires. Waivers live in a JSON file passed with `--waivers`, or in
257
+ `.sfaudit-waivers.json` in the working directory; the command always prints which file it loaded.
258
+
259
+ ```json
260
+ {
261
+ "$schema": "https://raw.githubusercontent.com/cclabsnz/sf-audit-plugin/main/schemas/waivers.schema.json",
262
+ "waivers": [
263
+ {
264
+ "checkId": "flows-without-sharing",
265
+ "entity": "Order_Processor",
266
+ "reason": "Integration runs without user context; refactor booked for Q3",
267
+ "approvedBy": "security-lead",
268
+ "expiresAt": "2027-03-31"
269
+ }
270
+ ]
271
+ }
272
+ ```
273
+
274
+ - `entity` must equal an affected item's label exactly (case-insensitive), or the finding id for a
275
+ finding with no affected items. There are no wildcards. A finding is waived only when every one
276
+ of its affected items is covered; otherwise the covered items are annotated and it stays active.
277
+ - `expiresAt` is an ISO 8601 date at most 365 days out. An expired waiver stops applying and the
278
+ finding counts again.
279
+ - A CRITICAL finding is waived only when the waiver also sets `"acknowledgeCritical": true`.
280
+ - Waived findings are listed under Accepted Risks in the executive report, and still take part in
281
+ attack-chain correlation: accepting one weakness does not accept the path it forms with others.
282
+
211
283
  ## Other commands
212
284
 
213
285
  Beyond the audit itself, the plugin ships five commands. Each is documented in
@@ -219,7 +291,7 @@ Beyond the audit itself, the plugin ships five commands. Each is documented in
219
291
  | `sf audit events pull` | Capture the org's **free** daily `EventLogFile` logs to local disk before the ~1-day retention window drops them — no Event Monitoring / Shield add-on needed. Idempotent, safe to cron |
220
292
  | `sf audit timeline` | Reconstruct one actor's activity across every captured event type, entirely offline. Refuses to expand a shared identity or join on a blank field, and always reports capture coverage first |
221
293
  | `sf audit preflight` | Read the running user's effective permissions in one query and report which checks will produce a verdict and which will return inconclusive — **before** an audit is run |
222
- | `sf audit apps` | Read the `RestApi` event log to compare what each connected app actually *uses* against what its run-as user is *granted*, and emit a suggested least-privilege permission set |
294
+ | `sf audit apps` | Read the API event logs to compare what each connected app actually *uses* against what its run-as user is *granted*, and suggest a least-privilege permission set. `--emit-permset <dir>` writes it as local `.permissionset-meta.xml` files for review; nothing is deployed |
223
295
 
224
296
  To triage captured logs for abuse patterns, pair `events pull` with the companion CLI
225
297
  **[sfelf-triage](https://github.com/cclabsnz/sfelf-triage)**, which reads this plugin's
@@ -237,7 +309,7 @@ sensitive data.
237
309
 
238
310
  ## Requirements
239
311
 
240
- - Node.js 18+
312
+ - Node.js 22+
241
313
  - Salesforce CLI (`sf`) v2+
242
314
  - A least-privilege, **read-only** org user. The audit performs no writes and does **not** require `View All Data` — without it one probe (integration write evidence) reports *inconclusive* rather than drawing a conclusion. See **[PERMISSIONS.md](PERMISSIONS.md)** for the exact minimum permission set, what each is for, what the tool does *not* need, and a ready-to-deploy `SF Audit (Read-Only)` permission set ([`docs/permissionset/`](docs/permissionset/SF_Audit_ReadOnly.permissionset-meta.xml)).
243
315