@cclabsnz/sf-audit 1.17.0 → 1.18.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (83) hide show
  1. package/CHANGELOG.md +71 -0
  2. package/PERMISSIONS.md +139 -0
  3. package/README.md +8 -10
  4. package/docs/permissionset/SF_Audit_ReadOnly.permissionset-meta.xml +54 -0
  5. package/lib/chains/ChainEngine.js +11 -1
  6. package/lib/chains/namedChains.js +42 -24
  7. package/lib/checks/CheckEngine.js +55 -24
  8. package/lib/checks/impl/AgentUserPrivilegeCheck.js +5 -4
  9. package/lib/checks/impl/AnonymousApexAuditCheck.js +41 -8
  10. package/lib/checks/impl/ApexSharingCheck.js +3 -1
  11. package/lib/checks/impl/ApiClientPermissionCheck.js +21 -5
  12. package/lib/checks/impl/AuditTrailCheck.js +23 -8
  13. package/lib/checks/impl/CertificateExpiryCheck.js +2 -1
  14. package/lib/checks/impl/ConnectedAppScopeCheck.js +61 -5
  15. package/lib/checks/impl/ConnectedAppsCheck.js +13 -4
  16. package/lib/checks/impl/ContentLinksCheck.js +33 -9
  17. package/lib/checks/impl/CorsAllowlistCheck.js +3 -2
  18. package/lib/checks/impl/DataClassificationCheck.js +15 -13
  19. package/lib/checks/impl/DebugLogAccessCheck.js +4 -4
  20. package/lib/checks/impl/DelegatedAdministrationGroupsCheck.js +3 -2
  21. package/lib/checks/impl/DelegatedAuthenticationExposureCheck.js +8 -1
  22. package/lib/checks/impl/DeploymentIdentityCheck.js +32 -5
  23. package/lib/checks/impl/EmailSecurityCheck.d.ts +1 -1
  24. package/lib/checks/impl/EmailSecurityCheck.js +14 -34
  25. package/lib/checks/impl/EncryptionCoverageCheck.js +21 -15
  26. package/lib/checks/impl/EnhancedDomainsCheck.js +17 -2
  27. package/lib/checks/impl/EscalationPermsCheck.d.ts +2 -0
  28. package/lib/checks/impl/EscalationPermsCheck.js +88 -21
  29. package/lib/checks/impl/ExperienceCloudSiteCheck.js +56 -5
  30. package/lib/checks/impl/ExternalAccountHierarchyExposureCheck.js +7 -15
  31. package/lib/checks/impl/ExternalCredentialsCheck.js +6 -3
  32. package/lib/checks/impl/FailedLoginCheck.js +36 -9
  33. package/lib/checks/impl/FieldHistoryTrackingCheck.js +14 -11
  34. package/lib/checks/impl/FlowHttpCalloutCredentialBypassCheck.js +2 -2
  35. package/lib/checks/impl/GuestRecordAccessPolicyCheck.js +52 -11
  36. package/lib/checks/impl/HealthCheckCheck.js +1 -0
  37. package/lib/checks/impl/HighAssuranceSessionCheck.js +16 -11
  38. package/lib/checks/impl/InactiveUsersCheck.js +1 -1
  39. package/lib/checks/impl/InboundEmailHandlerExposureCheck.js +5 -5
  40. package/lib/checks/impl/IntegrationLeastPrivilegeCheck.js +7 -6
  41. package/lib/checks/impl/InternalUserMfaCheck.js +26 -8
  42. package/lib/checks/impl/IpRestrictionsCheck.js +35 -16
  43. package/lib/checks/impl/LoginAccessPolicyCheck.js +5 -4
  44. package/lib/checks/impl/LoginAnomalyCheck.js +10 -7
  45. package/lib/checks/impl/LoginSessionCheck.js +2 -0
  46. package/lib/checks/impl/MfaEnforcementCheck.js +23 -6
  47. package/lib/checks/impl/MfaMethodStrengthCheck.js +18 -3
  48. package/lib/checks/impl/MfaRegistrationCheck.js +4 -3
  49. package/lib/checks/impl/MyDomainLoginPolicyCheck.js +23 -10
  50. package/lib/checks/impl/OutboundMessagesCheck.js +48 -6
  51. package/lib/checks/impl/PlatformEventSubscriberContextCheck.js +5 -1
  52. package/lib/checks/impl/PrivilegedAccessCheck.js +12 -5
  53. package/lib/checks/impl/ReleaseUpdatesCheck.js +18 -3
  54. package/lib/checks/impl/RemoteSitesCheck.js +4 -4
  55. package/lib/checks/impl/RestrictionRulesIntegrityCheck.js +3 -3
  56. package/lib/checks/impl/SeparationOfDutiesCheck.js +14 -3
  57. package/lib/checks/impl/SoapLoginApiAuthCheck.js +20 -8
  58. package/lib/checks/impl/SsoEnforcementCheck.js +16 -5
  59. package/lib/checks/impl/TransactionSecurityPolicyCheck.js +5 -5
  60. package/lib/checks/impl/TrustedIPRangesCheck.js +18 -9
  61. package/lib/checks/impl/UsersAndAdminsCheck.js +24 -4
  62. package/lib/checks/permCatalog.js +1 -1
  63. package/lib/checks/support/missingObject.js +3 -1
  64. package/lib/checks/support/schema.d.ts +17 -0
  65. package/lib/checks/support/schema.js +41 -0
  66. package/lib/commands/audit/apps.js +3 -1
  67. package/lib/commands/audit/events/pull.js +3 -1
  68. package/lib/commands/audit/incident/collect.js +3 -1
  69. package/lib/commands/audit/security.js +9 -3
  70. package/lib/findings/AuditResult.d.ts +2 -0
  71. package/lib/findings/coverage.d.ts +6 -0
  72. package/lib/findings/coverage.js +12 -0
  73. package/lib/findings/scoring.js +51 -9
  74. package/lib/preflight/permissionMap.d.ts +2 -20
  75. package/lib/preflight/permissionMap.js +2 -43
  76. package/lib/preflight/permissions.d.ts +25 -0
  77. package/lib/preflight/permissions.js +50 -0
  78. package/lib/renderers/ClientReportRenderer.js +4 -4
  79. package/lib/renderers/HtmlRenderer.js +15 -4
  80. package/lib/renderers/MarkdownRenderer.js +6 -3
  81. package/lib/report/RemediationRoadmap.d.ts +5 -1
  82. package/lib/report/RemediationRoadmap.js +6 -2
  83. package/package.json +4 -2
package/CHANGELOG.md CHANGED
@@ -9,6 +9,77 @@ published note and carries the signed provenance attestation and CycloneDX SBOM
9
9
 
10
10
  ## [Unreleased]
11
11
 
12
+ ## [v1.18.1](https://github.com/cclabsnz/sf-audit-plugin/releases/tag/v1.18.1) — 2026-10-22
13
+
14
+ The HTML report's dashboard now agrees with the score and the executive report.
15
+
16
+ ### Fixed
17
+
18
+ - The HTML report's dashboard counted passed and inconclusive findings, so it showed 66 LOW where
19
+ the executive report showed 2. The donut and severity cards now count open findings only, and
20
+ the executive report's severity chips no longer count waived findings.
21
+ - The grade reason and coverage note in the HTML report were squeezed into a narrow column beside
22
+ the score gauge. They now sit below it.
23
+
24
+ ### Changed
25
+
26
+ - Unattended installs use `sf plugins trust allowlist add` (sf CLI 2.135.0 or later) in place of
27
+ the `jq` script.
28
+
29
+ ## [v1.18.0](https://github.com/cclabsnz/sf-audit-plugin/releases/tag/v1.18.0) — 2026-10-21
30
+
31
+ Evidence coverage on a live org rises from about 58% to 96–97%, and grades and attack chains now
32
+ mean what they say. Found by running the audit against a Developer Edition org and two sandboxes.
33
+
34
+ ### Fixed
35
+
36
+ - `engines.node` now says `>=22.0.0`, not `>=18.0.0`. `@salesforce/core` 9 and
37
+ `@salesforce/sf-plugins-core` 13 already require Node 22, so the plugin never ran on 18 or 20.
38
+ The README's requirements say Node.js 22+ to match.
39
+ - About 40 checks sent queries the org rejected, then reported "insufficient permissions":
40
+ - fields that do not exist (`LoginHistory.Username`, `ContentDistribution.PasswordEnabled`,
41
+ `Organization.MyDomain`, `RestrictionRule.Active`, the wrong MFA permission field, and others)
42
+ - objects sent to the wrong API (`TraceFlag`, `DelegateGroup`, `ExternalCredential`,
43
+ `NetworkAccess` and `CorsWhitelistEntry`)
44
+ - filters on fields Salesforce will not filter (`SetupAuditTrail.Section`, `LoginHistory.Status`)
45
+ - invalid syntax: the reserved alias `expr0`, and `COUNT(Id)` on `FieldDefinition`
46
+ - Commands pinned API 62.0 and could not see newer fields. They now use the org's own version.
47
+ - A rejected query is reported as "query rejected by the org" and quotes Salesforce's error.
48
+ "Insufficient permissions" is kept for real access errors, and it names the needed permission.
49
+ - Permission fields that only some editions carry are checked by describe before they are queried.
50
+ If one is absent, the check says the feature is not available in this org; that never counts as
51
+ a pass.
52
+ - `MALFORMED_QUERY` was treated as "object not present", so a broken query read as clean.
53
+ - Inconclusive checks no longer raise the health score.
54
+
55
+ ### Changed
56
+
57
+ - Every output gives the reason for the grade, for example `F: 2 CRITICAL findings (D allows none)`.
58
+ - Only open findings and named attack chains count towards the grade. Potential chains do not.
59
+ - CRITICAL is kept for breach-grade exposure:
60
+ - The super-admin finding and Modify All Data are rated by how many hold them (more than 5 is
61
+ CRITICAL, more than 3 is HIGH).
62
+ - Modify All Data and separation-of-duties leave out users the super-admin finding already
63
+ covers, so the same admins are not counted three times.
64
+ - In a sandbox, admin-count findings are capped at HIGH.
65
+ - An expiring certificate is HIGH.
66
+ - Externally callable Apex is CRITICAL only when a class declares `without sharing`.
67
+ - "Unauthenticated bulk exfiltration" needs a confirmed guest exposure. "Standard user to org
68
+ takeover" needs a low-trust way in and an escalation a non-admin can use. A guest user merely
69
+ existing no longer opens either chain, or any potential chain.
70
+ - The remediation roadmap lists only work: INFO inventories and checks that gathered no evidence
71
+ are left out. Healthy lowest-band results (few failed logins, a Health Check score of 85 or
72
+ more, a small number of View/Modify All Data holders) are reported as passed.
73
+ - Reports with unassessed checks point to `sf audit preflight` and PERMISSIONS.md.
74
+ `PERMISSIONS.md` and the read-only permission set now ship in the npm package.
75
+
76
+ ### Added
77
+
78
+ - `scripts/capture-schema.mjs` and a captured Developer Edition schema
79
+ (`test/fixtures/schema/developer-edition.json`, standard fields only). A test runs every
80
+ check against it and fails on any query the org would reject.
81
+ ||||||| a23c86e
82
+
12
83
  ## [v1.17.0](https://github.com/cclabsnz/sf-audit-plugin/releases/tag/v1.17.0) — 2026-10-17
13
84
 
14
85
  109 checks (up from 95) and 19 attack chains (up from 17).
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
@@ -38,19 +38,15 @@ third-party plugin can satisfy it. Answer `y`.
38
38
 
39
39
  ### Unattended installs (CI/CD)
40
40
 
41
- To install in CI/CD without the interactive prompt, add the plugin to the CLI allowlist first (the merge step needs `jq`):
41
+ To install in CI/CD without the interactive prompt, allowlist the plugin first (sf CLI 2.135.0 or later):
42
42
 
43
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
-
44
+ sf plugins trust allowlist add --name @cclabsnz/sf-audit
51
45
  sf plugins install @cclabsnz/sf-audit
52
46
  ```
53
47
 
48
+ Older CLIs have no `allowlist` command; [docs/INSTALL.md](docs/INSTALL.md) shows the file to write instead.
49
+
54
50
  ### Verifying provenance
55
51
 
56
52
  Every release is published from GitHub Actions with a signed npm provenance attestation that
@@ -234,7 +230,9 @@ confirm each: **[docs/TRUST.md](docs/TRUST.md)**. Least-privilege access is in
234
230
 
235
231
  Each finding carries a risk weight (CRITICAL 10, HIGH 7, MEDIUM 4, LOW 1, INFO 0). The health score is
236
232
  `100 - (total weight / max possible weight) * 100`, capped at 0, and maps to an A–F grade — A needs
237
- ≥ 85 with no HIGH findings; any CRITICAL is an F.
233
+ ≥ 85 with no HIGH findings; any open CRITICAL finding or named CRITICAL attack chain is an F. Every report says
234
+ which condition set the grade. Inconclusive checks count towards neither the penalty nor the maximum,
235
+ so they never improve the score. See [docs/SCORING.md](docs/SCORING.md).
238
236
 
239
237
  Every report also states its **evidence coverage**: how many checks gathered evidence, out of how
240
238
  many ran. A check the audit user could not run (missing permission, or an error) is listed by id
@@ -307,7 +305,7 @@ sensitive data.
307
305
 
308
306
  ## Requirements
309
307
 
310
- - Node.js 18+
308
+ - Node.js 22+
311
309
  - Salesforce CLI (`sf`) v2+
312
310
  - 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)).
313
311
 
@@ -0,0 +1,54 @@
1
+ <?xml version="1.0" encoding="UTF-8"?>
2
+ <!--
3
+ SF Audit (Read-Only) permission set — least-privilege access for `sf audit security`.
4
+ Grants only the read permissions needed for a complete audit. See ../../PERMISSIONS.md.
5
+
6
+ Deploy:
7
+ sf project deploy start -m PermissionSet:SF_Audit_ReadOnly -o <orgAlias>
8
+ then assign:
9
+ sf org assign permset -n SF_Audit_ReadOnly -o <orgAlias>
10
+
11
+ NOTE: user-permission API names occasionally vary by API version. If a deploy
12
+ fails on a specific <name>, confirm it against your org's API version
13
+ (Setup → Permission Sets → System Permissions) and adjust. The most likely to
14
+ differ are ViewHealthCheckScreen, ViewEventLogFiles, and ViewRoles.
15
+ -->
16
+ <PermissionSet xmlns="http://soap.sforce.com/2006/04/metadata">
17
+ <label>SF Audit (Read-Only)</label>
18
+ <description>Least-privilege, read-only access for the @cclabsnz/sf-audit security audit plugin. No DML, no metadata writes, no View All Data.</description>
19
+ <hasActivationRequired>false</hasActivationRequired>
20
+
21
+ <!-- Required -->
22
+ <userPermissions>
23
+ <enabled>true</enabled>
24
+ <name>ApiEnabled</name>
25
+ </userPermissions>
26
+ <userPermissions>
27
+ <enabled>true</enabled>
28
+ <name>ViewSetup</name>
29
+ </userPermissions>
30
+ <userPermissions>
31
+ <enabled>true</enabled>
32
+ <name>ViewAllUsers</name>
33
+ </userPermissions>
34
+ <userPermissions>
35
+ <enabled>true</enabled>
36
+ <name>ViewHealthCheckScreen</name>
37
+ </userPermissions>
38
+ <userPermissions>
39
+ <!-- Read-only: only gate that exposes ApexClass.Body via Tooling. Omit to skip the 9 code-security checks. -->
40
+ <enabled>true</enabled>
41
+ <name>AuthorApex</name>
42
+ </userPermissions>
43
+ <userPermissions>
44
+ <!-- Requires Event Monitoring / Shield licensed in the org. -->
45
+ <enabled>true</enabled>
46
+ <name>ViewEventLogFiles</name>
47
+ </userPermissions>
48
+
49
+ <!-- Recommended (completeness) -->
50
+ <userPermissions>
51
+ <enabled>true</enabled>
52
+ <name>ViewRoles</name>
53
+ </userPermissions>
54
+ </PermissionSet>
@@ -12,9 +12,16 @@ const SINK_SEVERITY = {
12
12
  'credential-theft': 'MEDIUM',
13
13
  };
14
14
  const MAX_STEPS = 4;
15
+ // Population findings reported as passed at a healthy count (RULE-074) still name people who hold
16
+ // the power, so they keep their place in correlation while they list any holder.
17
+ const CHAIN_EVIDENCE_WHEN_PASSED = new Set(['users-modify-all-data', 'users-view-all-data']);
18
+ // Findings that only show a surface exists (a guest user, a live classic site). Every org with a
19
+ // site has them, so they never supply the entry point of a potential path on their own. RULE-071.
20
+ const SURFACE_ONLY = new Set(['guest-user-baseline', 'classic-sites-active']);
15
21
  export class ChainEngine {
16
22
  correlate(findings) {
17
- const active = findings.filter((f) => !f.passed && !f.inconclusive);
23
+ const active = findings.filter((f) => !f.inconclusive &&
24
+ (!f.passed || (CHAIN_EVIDENCE_WHEN_PASSED.has(f.id) && (f.affectedItems?.length ?? 0) > 0)));
18
25
  // Build present capability set + per-finding grants.
19
26
  const present = new Set();
20
27
  const grantsByFinding = new Map();
@@ -98,6 +105,9 @@ export class ChainEngine {
98
105
  for (const src of SOURCE_CAPS) {
99
106
  if (!present.has(src))
100
107
  continue;
108
+ const hasRealSource = active.some((f) => !SURFACE_ONLY.has(f.id) && (grantsByFinding.get(f) ?? []).includes(src));
109
+ if (!hasRealSource)
110
+ continue;
101
111
  for (const sink of HIGH_IMPACT_SINKS) {
102
112
  if (!present.has(sink))
103
113
  continue;
@@ -5,6 +5,33 @@ const byIds = (active, ids) => active.filter((f) => ids.includes(f.id));
5
5
  // The AI & Agents findings carry dynamic id suffixes (userId, agent dev name, channel slug,
6
6
  // domain), so their chain ingredients are matched by id prefix rather than exact id.
7
7
  const byPrefixes = (active, prefixes) => active.filter((f) => prefixes.some((p) => f.id === p || f.id.startsWith(p)));
8
+ // Findings that show an unauthenticated visitor can actually read, write or run something. A guest
9
+ // user existing (`guest-user-baseline`) or a site being live (`classic-sites-active`) is a surface,
10
+ // not an exposure: every org with a site has one. RULE-071.
11
+ const GUEST_EXPOSURE = [
12
+ 'guest-user-read-access', 'guest-user-write-access', 'guest-user-sharing-exposure',
13
+ 'guest-executable-apex-unprotected', 'guest-executable-apex-exposed', 'guest-executable-apex-system-mode',
14
+ 'guest-object-exposure-public-owd', 'guest-object-exposure-guest-owned',
15
+ 'guest-api-access-enabled', 'guest-api-hard-delete',
16
+ 'guest-user-visibility-view-all-users', 'guest-user-visibility-owd', 'guest-user-visibility-object-read',
17
+ 'guest-record-access-policy-not-enforced',
18
+ 'inbound-email-handler-unauthenticated-execution',
19
+ ];
20
+ // Ways in for a low-trust principal: external users with public sharing, social sign-on,
21
+ // self-registration, or a confirmed guest exposure. RULE-072.
22
+ const LOW_TRUST_ENTRY = [
23
+ 'sharing-model-external-read', 'sharing-model-external-write',
24
+ 'auth-providers-social', 'experience-cloud-site-self-registration',
25
+ ...GUEST_EXPOSURE,
26
+ ];
27
+ // Escalations a non-admin can use. Admins holding admin permissions (`users-super-admin-combo`,
28
+ // `users-author-apex`) are not an escalation: they already have the access. RULE-072.
29
+ const NON_ADMIN_ESCALATION = [
30
+ 'escalation-perms-found', 'privileged-access-shadow-admins',
31
+ 'separation-of-duties-self-escalation', 'separation-of-duties-identity-takeover', 'separation-of-duties-grant-self-data',
32
+ 'login-access-policy-delegated-admins',
33
+ 'integration-least-privilege-escalation-permissions',
34
+ ];
8
35
  export const NAMED_CHAINS = [
9
36
  {
10
37
  id: 'unauth-bulk-exfil',
@@ -27,6 +54,10 @@ export const NAMED_CHAINS = [
27
54
  return null;
28
55
  if (!hasAny(present, 'code-exec', 'data-read-bulk', 'data-write'))
29
56
  return null;
57
+ // A surface and internal weaknesses are not a path: an unauthenticated visitor must be shown
58
+ // to reach something.
59
+ if (byIds(active, GUEST_EXPOSURE).length === 0)
60
+ return null;
30
61
  const steps = byIds(active, [
31
62
  'guest-user-read-access', 'guest-user-write-access', 'guest-user-sharing-exposure', 'guest-user-baseline',
32
63
  'guest-executable-apex-unprotected', 'guest-executable-apex-exposed', 'guest-executable-apex-system-mode',
@@ -85,33 +116,20 @@ export const NAMED_CHAINS = [
85
116
  narrative: 'A low-trust authenticated user combines with a privilege-escalation permission ' +
86
117
  '(assign permission sets, manage users, author apex, modify metadata) to reach full org control.',
87
118
  remediation: 'Remove escalation permissions from non-admin profiles/permission sets and review who holds them.',
88
- match(present, active) {
89
- if (!hasAny(present, 'low-trust-authenticated', 'unauth-foothold'))
90
- return null;
91
- if (!hasAny(present, 'priv-esc', 'org-takeover'))
92
- return null;
93
- const steps = byIds(active, [
94
- 'sharing-model-external-read', 'sharing-model-external-write', 'guest-user-baseline',
95
- 'escalation-perms-found', 'users-author-apex', 'users-super-admin-combo',
96
- 'login-access-policy-delegated-admins', 'login-access-policy-login-as-enabled',
97
- // Admin-equivalent users off the System Administrator profile, and the toxic combinations
98
- // that let one user grant themselves access, are escalation steps in their own right.
99
- 'privileged-access-shadow-admins',
100
- 'separation-of-duties-self-escalation', 'separation-of-duties-identity-takeover',
101
- 'separation-of-duties-grant-self-data',
102
- // An integration account holding Author Apex, Customize Application or user-management
103
- // permissions it does not use has the same escalation reach as users-author-apex above.
104
- 'integration-least-privilege-escalation-permissions',
105
- // Grants unauth-foothold, so it must appear whenever it is what opened the gate.
106
- 'inbound-email-handler-unauthenticated-execution',
107
- ]);
108
- if (steps.length < 2)
119
+ match(_present, active) {
120
+ // Both ends must be present: a way in for a low-trust principal, and an escalation that
121
+ // principal could use. Admin-held power and a guest user merely existing join only as evidence.
122
+ const entry = byIds(active, LOW_TRUST_ENTRY);
123
+ const escalation = byIds(active, NON_ADMIN_ESCALATION);
124
+ if (entry.length === 0 || escalation.length === 0)
109
125
  return null;
110
- // Further escalation paths. They join as evidence but never count toward the floor, so two of
111
- // them alone, with no low-trust step, cannot claim a standard-user path to takeover.
112
126
  return [
113
- ...steps,
127
+ ...entry,
128
+ ...escalation,
114
129
  ...byIds(active, [
130
+ // Admin powers: they widen what a takeover reaches but are not themselves the escalation.
131
+ 'users-super-admin-combo', 'users-author-apex', 'guest-user-baseline', 'login-access-policy-login-as-enabled',
132
+ 'separation-of-duties-code-and-data',
115
133
  'delegated-administration-groups-active',
116
134
  'auth-provider-registration-handler-admin-exec', 'auth-provider-registration-handler-unverified-email-linking',
117
135
  'delegated-authentication-admin-assigned', 'platform-event-subscriber-escalation',
@@ -2,41 +2,72 @@ import { buildAuditResult } from '../findings/scoring.js';
2
2
  import { getComplianceTags } from '../compliance/resolve.js';
3
3
  import { ChainEngine } from '../chains/ChainEngine.js';
4
4
  import { applyWaivers } from '../waivers/applyWaivers.js';
5
- const PERMISSION_ERROR_CODES = new Set([
5
+ import { permissionLabelsFor } from '../preflight/permissions.js';
6
+ const ACCESS_ERROR_CODES = new Set([
6
7
  'INSUFFICIENT_ACCESS_RIGHTS',
8
+ 'INSUFFICIENT_ACCESS_OR_READONLY',
7
9
  'INVALID_CROSS_REFERENCE_KEY',
8
10
  'ENTITY_IS_INACCESSIBLE',
9
- 'INVALID_FIELD',
10
- 'INVALID_TYPE',
11
11
  ]);
12
- function isPermissionError(err) {
12
+ const REJECTION_ERROR_CODES = new Set(['INVALID_FIELD', 'INVALID_TYPE', 'MALFORMED_QUERY']);
13
+ const PERMISSIONS_DOC = 'https://github.com/cclabsnz/sf-audit-plugin/blob/main/PERMISSIONS.md';
14
+ /**
15
+ * Why a check threw. A query the org rejects (unknown field or object, an unfilterable field,
16
+ * bad syntax) is not an access problem, even though a field hidden by field-level security is
17
+ * also reported as an unknown column: telling an admin to grant access sends them the wrong way.
18
+ */
19
+ function classifyError(err) {
13
20
  if (!(err instanceof Error))
14
- return false;
21
+ return 'failed';
15
22
  const code = err.errorCode ?? '';
16
23
  const msg = err.message ?? '';
17
- return (PERMISSION_ERROR_CODES.has(code) ||
18
- msg.includes('INSUFFICIENT_ACCESS') ||
19
- msg.includes('insufficient access') ||
20
- msg.includes('INVALID_FIELD') ||
21
- msg.includes('entity type cannot be queried'));
24
+ if (ACCESS_ERROR_CODES.has(code) || /INSUFFICIENT_ACCESS|insufficient access|entity type cannot be queried/i.test(msg)) {
25
+ return 'access';
26
+ }
27
+ if (REJECTION_ERROR_CODES.has(code) ||
28
+ /INVALID_FIELD|INVALID_TYPE|MALFORMED_QUERY|No such column|is not supported|can not be filtered|alias is reserved/i.test(msg)) {
29
+ return 'rejected';
30
+ }
31
+ return 'failed';
32
+ }
33
+ function accessRemediation(check) {
34
+ const labels = permissionLabelsFor(check);
35
+ const named = labels.length > 0 ? `This check needs ${labels.join(' and ')}. ` : '';
36
+ return (`${named}Run \`sf audit preflight\` to see which permissions the audit user is missing, and ` +
37
+ `assign the read-only permission set described in PERMISSIONS.md (${PERMISSIONS_DOC}), then re-run the audit.`);
22
38
  }
23
39
  function buildErrorFinding(check, err) {
24
40
  const msg = err instanceof Error ? err.message : String(err);
25
- const inconclusive = isPermissionError(err);
41
+ const kind = classifyError(err);
42
+ const base = { id: `${check.id}-error`, checkId: check.id, category: check.category, riskLevel: 'INFO' };
43
+ // A check that threw gathered no evidence, whatever the cause.
44
+ if (kind === 'access') {
45
+ return {
46
+ ...base,
47
+ title: `${check.name}: insufficient permissions`,
48
+ detail: `This check could not gather evidence because the org denied the audit user access: ${msg}`,
49
+ remediation: accessRemediation(check),
50
+ inconclusive: true,
51
+ notAssessed: true,
52
+ };
53
+ }
54
+ if (kind === 'rejected') {
55
+ return {
56
+ ...base,
57
+ title: `${check.name}: query rejected by the org`,
58
+ detail: `The org rejected this check's query, so it gathered no evidence. Salesforce said: ${msg}. ` +
59
+ 'The object or field may not exist in this edition or API version, or field-level security may hide it from the audit user.',
60
+ remediation: 'If the audit user is a System Administrator, this is a defect in the check: please report it at ' +
61
+ 'https://github.com/cclabsnz/sf-audit-plugin/issues with the error above. The area this check covers is unassessed, not clean.',
62
+ inconclusive: true,
63
+ notAssessed: true,
64
+ };
65
+ }
26
66
  return {
27
- id: `${check.id}-error`,
28
- checkId: check.id,
29
- category: check.category,
30
- riskLevel: 'INFO',
31
- title: `${check.name}: ${inconclusive ? 'insufficient permissions' : 'check failed'}`,
32
- detail: inconclusive
33
- ? `This check could not gather evidence because the running user lacks the required permissions: ${msg}`
34
- : `This check encountered an error and could not complete: ${msg}`,
35
- remediation: inconclusive
36
- ? 'Grant the audit user the permissions listed in the tool documentation, then re-run the audit.'
37
- : 'Review the error message and verify the running user has the required permissions.',
38
- inconclusive: inconclusive || undefined,
39
- // A check that threw gathered no evidence, whatever the cause.
67
+ ...base,
68
+ title: `${check.name}: check failed`,
69
+ detail: `This check encountered an error and could not complete: ${msg}`,
70
+ remediation: 'Review the error message and re-run the audit. The area this check covers is unassessed, not clean.',
40
71
  notAssessed: true,
41
72
  };
42
73
  }
@@ -188,12 +188,13 @@ export class AgentUserPrivilegeCheck {
188
188
  return new Set();
189
189
  const objList = readableObjects.map((o) => `'${o}'`).join(', ');
190
190
  try {
191
- const rows = await ctx.tooling.query(`SELECT EntityDefinition.QualifiedApiName objectName, COUNT(Id) classifiedCount
191
+ // FieldDefinition supports no aggregates (its Id is not aggregatable): list the classified
192
+ // fields and take their objects.
193
+ const rows = await ctx.tooling.query(`SELECT EntityDefinition.QualifiedApiName, QualifiedApiName
192
194
  FROM FieldDefinition
193
195
  WHERE EntityDefinition.QualifiedApiName IN (${objList})
194
- AND ComplianceGroup != null
195
- GROUP BY EntityDefinition.QualifiedApiName`);
196
- return new Set(rows.filter((r) => (r.classifiedCount ?? 0) > 0).map((r) => r.objectName));
196
+ AND ComplianceGroup != null`);
197
+ return new Set(rows.map((r) => r.EntityDefinition?.QualifiedApiName).filter((o) => Boolean(o)));
197
198
  }
198
199
  catch {
199
200
  // No classification feature / no Tooling access: skip the sub-signal silently.
@@ -1,3 +1,11 @@
1
+ // SetupAuditTrail.Section cannot be filtered in SOQL, so the 90-day trail is read (bounded) and
2
+ // matched here.
3
+ const DEV_TOOL_SECTIONS = new Set(['Developer Console', 'Developer Tools', 'IDE', 'Development', 'Workbench']);
4
+ const ANON_ACTION = /anon|runAs|executeCode/i;
5
+ const MAX_TRAIL_ROWS = 10000;
6
+ function isAnonymousExecution(r) {
7
+ return DEV_TOOL_SECTIONS.has(r.Section) || ANON_ACTION.test(r.Action ?? '');
8
+ }
1
9
  function isAdminProfile(profileName) {
2
10
  const lower = profileName.toLowerCase();
3
11
  return lower.includes('admin') || lower.includes('system administrator');
@@ -12,31 +20,43 @@ export class AnonymousApexAuditCheck {
12
20
  const baseUrl = ctx.orgInfo.instanceUrl;
13
21
  const auditTrailUrl = `${baseUrl}/lightning/setup/AuditTrail/home`;
14
22
  let records = [];
23
+ let truncated = false;
15
24
  try {
16
- records = await ctx.soql.queryAll(`SELECT CreatedDate, CreatedBy.Id, CreatedBy.Username, CreatedBy.Profile.Name,
25
+ const trail = await ctx.soql.queryAll(`SELECT CreatedDate, CreatedBy.Id, CreatedBy.Username, CreatedBy.Profile.Name,
17
26
  Section, Action, Display
18
27
  FROM SetupAuditTrail
19
28
  WHERE CreatedDate > LAST_N_DAYS:90
20
- AND (Section IN ('Developer Console', 'Developer Tools', 'IDE', 'Development', 'Workbench')
21
- OR Action LIKE '%anon%'
22
- OR Action LIKE '%runAs%'
23
- OR Action LIKE '%executeCode%')
24
29
  ORDER BY CreatedDate DESC
25
- LIMIT 200`);
30
+ LIMIT ${MAX_TRAIL_ROWS}`);
31
+ truncated = trail.length >= MAX_TRAIL_ROWS;
32
+ records = trail.filter(isAnonymousExecution);
26
33
  }
27
- catch {
34
+ catch (err) {
28
35
  findings.push({
29
36
  id: 'anonymous-apex-inaccessible',
30
37
  category: this.category,
31
38
  riskLevel: 'INFO',
32
39
  inconclusive: true,
33
40
  title: 'SetupAuditTrail could not be queried: anonymous Apex execution cannot be verified',
34
- detail: 'The SetupAuditTrail object was not accessible. This may indicate insufficient permissions to view the org audit trail.',
41
+ detail: `The SetupAuditTrail query failed: ${err instanceof Error ? err.message : String(err)}. If the org denied access, the audit user may lack "View Setup and Configuration".`,
35
42
  remediation: 'Grant "View Setup and Configuration" permission to the audit user. Review anonymous Apex execution manually in Setup → Audit Trail.',
36
43
  affectedItems: [{ label: 'Setup Audit Trail', url: auditTrailUrl }],
37
44
  });
38
45
  return { findings };
39
46
  }
47
+ if (records.length === 0 && truncated) {
48
+ findings.push({
49
+ id: 'anonymous-apex-partial',
50
+ category: this.category,
51
+ riskLevel: 'INFO',
52
+ inconclusive: true,
53
+ title: `No anonymous Apex execution in the latest ${MAX_TRAIL_ROWS} audit-trail entries; older entries were not read`,
54
+ detail: `The 90-day Setup Audit Trail holds more than ${MAX_TRAIL_ROWS} entries, so only the most recent were checked. None of them record anonymous Apex execution, but older ones in the window may.`,
55
+ remediation: 'Review anonymous Apex execution in Setup → Audit Trail, or export the full trail for review.',
56
+ affectedItems: [{ label: 'Setup Audit Trail', url: auditTrailUrl }],
57
+ });
58
+ return { findings };
59
+ }
40
60
  if (records.length === 0) {
41
61
  findings.push({
42
62
  id: 'anonymous-apex-none',
@@ -49,6 +69,19 @@ export class AnonymousApexAuditCheck {
49
69
  });
50
70
  return { findings };
51
71
  }
72
+ if (truncated) {
73
+ // Matches were found, but older entries in the window were not read: the list may be short.
74
+ findings.push({
75
+ id: 'anonymous-apex-partial',
76
+ category: this.category,
77
+ riskLevel: 'INFO',
78
+ inconclusive: true,
79
+ title: `Anonymous Apex executions listed may be incomplete: only the latest ${MAX_TRAIL_ROWS} audit-trail entries were read`,
80
+ detail: `The 90-day Setup Audit Trail holds more than ${MAX_TRAIL_ROWS} entries. The executions reported here come from the most recent ones; older executions in the window, and the users behind them, may be missing.`,
81
+ remediation: 'Review anonymous Apex execution in Setup → Audit Trail, or export the full trail for review.',
82
+ affectedItems: [{ label: 'Setup Audit Trail', url: auditTrailUrl }],
83
+ });
84
+ }
52
85
  const userMap = new Map();
53
86
  for (const r of records) {
54
87
  const userId = r.CreatedBy.Id;