@cclabsnz/sf-audit 1.8.2 → 1.10.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 (53) hide show
  1. package/CHANGELOG.md +221 -0
  2. package/README.md +144 -756
  3. package/lib/chains/CapabilityRegistry.d.ts +6 -2
  4. package/lib/chains/CapabilityRegistry.js +48 -2
  5. package/lib/chains/namedChains.js +140 -7
  6. package/lib/checks/impl/AgentChannelExposureCheck.js +52 -10
  7. package/lib/checks/impl/ApexCrudFLSCheck.js +3 -3
  8. package/lib/checks/impl/ApexRestEndpointCheck.js +0 -3
  9. package/lib/checks/impl/CustomLabelsCredentialCheck.js +1 -1
  10. package/lib/checks/impl/DataClassificationCheck.js +15 -1
  11. package/lib/checks/impl/FailedLoginCheck.js +16 -1
  12. package/lib/checks/impl/FieldLevelSecurityCheck.js +29 -16
  13. package/lib/checks/impl/GuestUserVisibilityCheck.d.ts +35 -0
  14. package/lib/checks/impl/GuestUserVisibilityCheck.js +168 -0
  15. package/lib/checks/impl/HardcodedCredentialsCheck.js +0 -1
  16. package/lib/checks/impl/HealthCheckCheck.js +1 -3
  17. package/lib/checks/impl/IntegrationLeastPrivilegeCheck.d.ts +42 -0
  18. package/lib/checks/impl/IntegrationLeastPrivilegeCheck.js +467 -0
  19. package/lib/checks/impl/IntegrationUsersCheck.js +48 -52
  20. package/lib/checks/impl/InternalUserMfaCheck.js +0 -1
  21. package/lib/checks/impl/IpRestrictionsCheck.js +39 -5
  22. package/lib/checks/impl/PublicGroupSharingCheck.js +21 -2
  23. package/lib/checks/impl/ScheduledApexCheck.js +0 -1
  24. package/lib/checks/impl/SoapLoginApiAuthCheck.d.ts +10 -0
  25. package/lib/checks/impl/SoapLoginApiAuthCheck.js +151 -0
  26. package/lib/checks/impl/SsoEnforcementCheck.js +0 -1
  27. package/lib/checks/impl/TrustedUrlHygieneCheck.js +3 -1
  28. package/lib/checks/registry.js +4 -0
  29. package/lib/checks/support/integrationAccounts.d.ts +35 -0
  30. package/lib/checks/support/integrationAccounts.js +209 -0
  31. package/lib/commands/audit/preflight.d.ts +13 -0
  32. package/lib/commands/audit/preflight.js +56 -0
  33. package/lib/commands/audit/security.d.ts +16 -3
  34. package/lib/commands/audit/security.js +40 -10
  35. package/lib/compliance/catalogs/gdpr.d.ts +3 -0
  36. package/lib/compliance/catalogs/gdpr.js +54 -0
  37. package/lib/compliance/catalogs/hipaa.d.ts +3 -0
  38. package/lib/compliance/catalogs/hipaa.js +97 -0
  39. package/lib/compliance/catalogs/index.js +4 -0
  40. package/lib/compliance/mapping.js +111 -36
  41. package/lib/findings/CheckMeta.js +2 -0
  42. package/lib/findings/digest.d.ts +50 -0
  43. package/lib/findings/digest.js +56 -0
  44. package/lib/findings/exitCode.d.ts +28 -0
  45. package/lib/findings/exitCode.js +46 -0
  46. package/lib/findings/loadScoringConfig.js +5 -5
  47. package/lib/preflight/permissionMap.d.ts +47 -0
  48. package/lib/preflight/permissionMap.js +84 -0
  49. package/lib/preflight/readPermissions.d.ts +11 -0
  50. package/lib/preflight/readPermissions.js +20 -0
  51. package/lib/renderers/HtmlRenderer.js +1 -1
  52. package/messages/audit.security.md +6 -0
  53. package/package.json +5 -3
package/CHANGELOG.md ADDED
@@ -0,0 +1,221 @@
1
+ # Changelog
2
+
3
+ All notable changes to `@cclabsnz/sf-audit` are recorded here. The format follows
4
+ [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) loosely, and the project uses
5
+ [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
6
+
7
+ Each entry mirrors the [GitHub Release](https://github.com/cclabsnz/sf-audit-plugin/releases) for that tag, which is the canonical
8
+ published note and carries the signed provenance attestation and CycloneDX SBOM for the build.
9
+
10
+ ## [Unreleased]
11
+
12
+ Merged to `main`, not yet released.
13
+
14
+ ## [v1.10.0](https://github.com/cclabsnz/sf-audit-plugin/releases/tag/v1.10.0) — 2026-09-07
15
+
16
+ Two additions for callers that drive this plugin programmatically: find out what the audit
17
+ user can actually see *before* spending a run, and get the result back without paying for
18
+ the half of it that is passing checks and prose.
19
+
20
+ ### Added
21
+
22
+ - **`sf audit preflight`** — reports what this audit user will and will not be able to
23
+ establish, before a run is spent. Reads the caller's effective permissions from
24
+ `UserPermissionAccess` in a single query and names the checks that will return
25
+ inconclusive, with the grants that would fix them. The audit itself can only report a
26
+ permission gap *after* it has come back blind; this asks the same question up front.
27
+ The affected-check lists are derived from the registry's declared cache wiring rather
28
+ than hand-maintained, so a check added later is covered without editing the map.
29
+
30
+ - **`--digest`** on `sf audit security` — a compact result for programmatic callers.
31
+ Passing checks are counted but not listed, `detail` prose gives way to `remediation`,
32
+ and affected-item lists — unbounded, and the bulk of a large org's report — collapse to
33
+ a count plus a three-item sample. Attack chains survive intact. Composes with `--json`,
34
+ so an agent gets one command and compact stdout.
35
+
36
+ ## [v1.9.0](https://github.com/cclabsnz/sf-audit-plugin/releases/tag/v1.9.0) — 2026-09-07
37
+
38
+ Two compliance catalogs, three attack chains, and a restructured documentation set — but
39
+ the reason to upgrade is the `--fail-on` fix. That flag never worked: any pipeline using it
40
+ exited 1 on every run, whatever the org looked like. If you gate CI on this plugin, this is
41
+ the release that makes the gate mean something.
42
+
43
+ ### Fixed
44
+
45
+ - **`--fail-on` fired on every audit.** The threshold comparison ranked findings with
46
+ `ORDER.indexOf(level) <= threshold`, and `INFO` is absent from that order, so it
47
+ scored `-1` — more severe than `CRITICAL` at every threshold. Because passing and
48
+ inconclusive checks both carry `INFO`, and every audit produces passes, any pipeline
49
+ using `--fail-on` exited 1 regardless of what was actually found. Gateable severities
50
+ are now matched explicitly, and passed/inconclusive findings can never be violations.
51
+
52
+ ### Added
53
+
54
+ - **`--fail-on-inconclusive`** — exit 3 when a check could not gather evidence, so CI can
55
+ tell a clean org apart from an audit user that could not see enough to judge. Off by
56
+ default. A finding at or above `--fail-on` still takes precedence and exits 1.
57
+
58
+ - **HIPAA Security Rule and GDPR compliance catalogs** — 26 source-verified controls, taking the
59
+ catalog from 93 to 119. HIPAA pins the operative 2013 Omnibus rule (the 2025 NPRM remains
60
+ proposed) and preserves each implementation specification's Required/Addressable designation;
61
+ GDPR is mapped at paragraph level. Reachable via `--frameworks hipaa`, `gdpr` or `all`, which
62
+ previously rendered nothing for either. (#75)
63
+ - **Three attack chains** — `sandbox-pii-exposure`, `insider-bulk-exfil` and
64
+ `undetected-compromise` — plus capability grants for 14 previously unmodelled findings, lifting
65
+ chain coverage from roughly 30 to 43 of the 88 checks. Guest chains now name the concrete
66
+ request path an attacker uses. (#75)
67
+
68
+ ### Fixed
69
+
70
+ - **`MessagingChannel` was never readable.** The Agentforce channel check selected a
71
+ non-existent `ChannelType` field; the resulting `INVALID_FIELD` error was swallowed by a
72
+ defensive catch, so every org reported zero messaging channels. The field is `MessageType`.
73
+ Channels of type `EmbeddedMessaging` or `WebChat` are now surfaced as public channel
74
+ candidates. (#75)
75
+
76
+ ### Changed
77
+
78
+ - **Publish workflow** installs the pinned npm with `--ignore-scripts` and asserts the resulting
79
+ version, so a lifecycle script cannot run beside the OIDC publish credential and a failed
80
+ upgrade cannot reach `npm publish`. (#76)
81
+ - **Documentation restructured.** The README is an overview (935 to 226 lines); the full check
82
+ inventory, attack chains, compliance detail, command reference and trust material moved to
83
+ `docs/`. Drift guards follow the tables they protect. (#75, #77)
84
+ - Dead code removed and unused declarations are now a compile error. (#79)
85
+
86
+ ### Removed
87
+
88
+ - `ts-node`, which was unused — Jest 30 parses `jest.config.ts` natively. (#75)
89
+
90
+ ## [v1.8.2](https://github.com/cclabsnz/sf-audit-plugin/releases/tag/v1.8.2) — 2026-08-10
91
+
92
+ Maintenance release. No user-facing behaviour changed — the check set, flags and report formats are identical to v1.8.1.
93
+
94
+ ### Security
95
+
96
+ - **js-yaml** override raised to `^3.15.1`, closing Dependabot alert #27 (high — GHSA-5p4m-2wfm-xmqj, quadratic CPU consumption in `!!omap` resolution). Development-scope transitive dependency; not in the shipped runtime. (#64)
97
+
98
+ ### Toolchain
99
+
100
+ - **TypeScript 5.9.3 → 7.0.2.** TS7 is the native compiler and no longer exposes the JavaScript compiler API ts-jest is built on, and no TS7-compatible ts-jest exists, so transforms moved to `@swc/jest`. Because swc only strips types, an explicit `pnpm run typecheck` step was added and runs ahead of jest. This also fixed a `tsconfig.test.json` config bug that had been leaving every file under `test/` out of the type-check program. (#62)
101
+ - **Pinned actions:** codeql-action v4.37.4, upload-artifact v7.0.1, action-gh-release v3.0.2. (#61)
102
+ - **@oclif/core** 4.13.0 → 4.13.2. (#54)
103
+
104
+ ### Docs
105
+
106
+ - README blog links point at the canonical `www` host. (#63)
107
+
108
+ ---
109
+
110
+ Build clean, 85 suites / 629 tests passing (including the read-only and network-egress invariants), `pnpm audit --prod --audit-level high` clean, 0 open Dependabot alerts.
111
+
112
+ ## [v1.8.1](https://github.com/cclabsnz/sf-audit-plugin/releases/tag/v1.8.1) — 2026-08-05
113
+
114
+ Metadata and documentation only. No functional change to any check, and no change to what the tool does against your org.
115
+
116
+ **npm discoverability.** The package carried no keywords at all, which made it effectively invisible to npm search. Adds 17 terms spanning the plugin ecosystem (`sf-plugin`, `sfdx-plugin`, `oclif-plugin`), the problem space (`security-audit`, `compliance`, `devsecops`) and the frameworks the tool maps findings to (`owasp`, `soc2`, `iso27001`, `nzism`). Sets `homepage` and `bugs`, which were unset, so npm now links to the README and the issue tracker. The description now states the check count, attack-chain correlation, risk grading and framework coverage, and corrects the count to 88.
117
+
118
+ **The unsigned-plugin warning is now explained at the install step.** Salesforce's signature verification only accepts public keys served from `developer.salesforce.com`, with certificate pinning to that host, so no third-party plugin can be signed for it and every community plugin produces the same prompt. Previously the README handed you an install command and let you discover that warning unaided, which is a poor first impression from a security tool. It now says why the warning appears, points at the guarantees you can verify yourself (signed npm provenance, the read-only invariant test) instead of asking for trust, and documents the `unsignedPluginAllowList.json` path for CI installs where an interactive prompt would hang the job.
119
+
120
+ ## [v1.8.0 — forensic timeline](https://github.com/cclabsnz/sf-audit-plugin/releases/tag/v1.8.0) — 2026-08-05
121
+
122
+ Adds `sf audit timeline`. Existing usage is unaffected: no command, flag or output contract
123
+ changed, the check count is the same, and the security grade is untouched.
124
+
125
+ ### `sf audit timeline`
126
+
127
+ Salesforce splits one actor's activity across event types that share no common identifier. On a
128
+ real capture, **four types carry no `CLIENT_IP` column at all** — so filtering an event log by
129
+ address finds a fraction of the activity and misses every SOQL execution. Filtering by user finds
130
+ everything the *guest* user did, which on a community is everyone.
131
+
132
+ ```bash
133
+ sf audit timeline --window yesterday --seed ip:203.0.113.50
134
+ ```
135
+
136
+ It correlates a seed across every captured event type and writes a defensible timeline —
137
+ `timeline.csv`, `timeline.json` and `summary.md`. It runs **entirely offline** against captures
138
+ written by `sf audit events pull`, so it still works long after the org's retention window has
139
+ expired or its credentials have been revoked.
140
+
141
+ ### What it refuses to do
142
+
143
+ Cross-event correlation is easy to get confidently wrong, and a wrong answer reads as evidence.
144
+
145
+ - **A blank field never joins.** A blank `REQUEST_ID` used as a key stops identifying anything and
146
+ starts matching every row whose value is also blank.
147
+ - **A shared identity is not expanded.** A community guest user can stand for hundreds of
148
+ visitors. Refused by default, with the evidence reported rather than applied quietly.
149
+
150
+ Every output leads with what was actually captured, because *"no rows matched"* means two
151
+ opposite things: the actor did nothing, or nobody captured the hour they did it in.
152
+
153
+ ### Saying when
154
+
155
+ `--window` takes `yesterday`, `today`, `2h`, `90m`, a bare date (the whole day), a bare timestamp
156
+ (the hour containing it), or an exact ISO interval. Times are UTC. Omitting `--seed` returns the
157
+ whole window uncorrelated — where you look to find something worth seeding on. Asking for an
158
+ uncaptured window lists the days that were captured.
159
+
160
+ ### Also in this release
161
+
162
+ - `@cclabsnz/sf-core` 0.3.0 — hourly and Real-Time Event capture, atomic writes
163
+ - Security overrides raised to `fast-uri` 3.1.5 and `brace-expansion` 5.0.9
164
+ - `NamedCredentialsCheck` no longer crashes, or silently matches the wrong credential, when a
165
+ label contains regular-expression metacharacters
166
+
167
+ Full documentation in the README under *Forensic timeline*.
168
+
169
+ ## [v1.7.0](https://github.com/cclabsnz/sf-audit-plugin/releases/tag/v1.7.0) — 2026-08-03
170
+
171
+ Sixty-two commits since 1.6.1. No command, flag, or output contract changed —
172
+ existing usage is unaffected.
173
+
174
+ ### Shared platform layer
175
+
176
+ Flow and Apex reads now route through `@cclabsnz/sf-core`, consumed from the
177
+ registry. Report branding, fonts and HTML utilities moved there too.
178
+
179
+ sf-core 0.1.5 declares `@salesforce/core` as a **peer** dependency rather than
180
+ bundling its own. Every reference inside it is an `import type` — 4 `.d.ts`
181
+ mentions, 0 `.js` — so a runtime dependency only ever forced a second copy into
182
+ consumers and broke type unification across a major bump. sf-core now ships with
183
+ no runtime dependencies.
184
+
185
+ ### Security
186
+
187
+ - Read-only invariant coverage restored, and a network-egress invariant added —
188
+ both enforced in CI, so "cannot write to an org" and "nothing leaves the
189
+ machine" are tested rather than asserted
190
+ - Generated reports are self-contained: no CDN fetches, so opening a report
191
+ cannot phone out
192
+ - Org-data guard repaired. Its instance-host check had been failing open: a
193
+ negative lookahead under `grep -E`, which ERE does not support, so the branch
194
+ matched nothing while the step reported clean
195
+
196
+ ### Dependencies
197
+
198
+ `@salesforce/core` 9, `@salesforce/sf-plugins-core` 13, jest 30, `@types/node` 26.
199
+
200
+ TypeScript stays at 5 — TS 7 is the native rewrite and no published ts-jest
201
+ supports it yet (latest peers `>=4.3 <7`).
202
+
203
+ ### Repository
204
+
205
+ Flattened back to a single package now that the shared layer ships from the
206
+ registry and the intel plugin has its own repository.
207
+
208
+ ## [v1.6.1](https://github.com/cclabsnz/sf-audit-plugin/releases/tag/v1.6.1) — 2026-07-26
209
+
210
+ Security + supply-chain assurance release. First release published via the hardened, OIDC pipeline.
211
+
212
+ ### Fixes
213
+ - **fix(deps):** brace-expansion pinned to `5.0.8` — resolves high-severity DoS advisory [GHSA-mh99-v99m-4gvg](https://github.com/advisories/GHSA-mh99-v99m-4gvg) reaching production via `@oclif/core`.
214
+ - **fix(security):** Enhanced Domains check now parses the hostname and uses anchored patterns, so a URL that merely contains `.my.salesforce.com` can no longer be misclassified (CodeQL `js/regex/missing-regexp-anchor`, high).
215
+
216
+ ### Supply-chain assurance
217
+ - Published via **npm Trusted Publishing (OIDC)** with **build provenance** — the npm page shows a signed attestation linking this tarball to its source commit. No long-lived token.
218
+ - **CycloneDX SBOM** attached to this release.
219
+ - CI enforces a **read-only invariant** (build fails on any org-write path), plus CodeQL, OpenSSF Scorecard, a `pnpm audit` gate, and SHA-pinned actions with least-privilege permissions.
220
+
221
+ Install: `sf plugins install @cclabsnz/sf-audit`