@cclabsnz/sf-audit 1.18.1 → 1.20.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 (41) hide show
  1. package/CHANGELOG.md +64 -0
  2. package/lib/apps/apiLogSource.js +3 -2
  3. package/lib/chains/AttackChain.d.ts +12 -0
  4. package/lib/chains/ChainEngine.js +12 -3
  5. package/lib/chains/namedChains.d.ts +72 -0
  6. package/lib/chains/namedChains.js +381 -207
  7. package/lib/checks/CheckEngine.js +5 -2
  8. package/lib/checks/impl/AgentActionSurfaceCheck.js +2 -13
  9. package/lib/checks/impl/AgentInventoryCheck.js +2 -15
  10. package/lib/checks/impl/ApexLoggingCheck.js +2 -0
  11. package/lib/checks/impl/GuestApiAccessCheck.js +2 -0
  12. package/lib/checks/impl/GuestUserAccessCheck.js +2 -0
  13. package/lib/checks/impl/UsersAndAdminsCheck.js +91 -26
  14. package/lib/checks/support/missingObject.js +2 -1
  15. package/lib/checks/support/schema.js +1 -1
  16. package/lib/commands/audit/incident/collect.js +2 -1
  17. package/lib/findings/Finding.d.ts +7 -0
  18. package/lib/findings/unknownMetrics.d.ts +5 -0
  19. package/lib/findings/unknownMetrics.js +29 -0
  20. package/lib/history/DiffEngine.js +6 -1
  21. package/lib/incident/collect/orgErrors.js +3 -1
  22. package/lib/incident/collect/streamGuestLogs.js +3 -2
  23. package/lib/lib/apiErrorText.d.ts +8 -0
  24. package/lib/lib/apiErrorText.js +15 -0
  25. package/lib/renderers/AttackChainDagRenderer.d.ts +5 -1
  26. package/lib/renderers/AttackChainDagRenderer.js +16 -31
  27. package/lib/renderers/ClientReportRenderer.js +4 -1
  28. package/lib/renderers/HtmlRenderer.js +23 -7
  29. package/lib/renderers/MarkdownRenderer.js +61 -2
  30. package/lib/renderers/SarifRenderer.js +10 -2
  31. package/lib/threats/linddun.d.ts +3 -0
  32. package/lib/threats/linddun.js +40 -0
  33. package/lib/threats/resolve.d.ts +8 -0
  34. package/lib/threats/resolve.js +18 -0
  35. package/lib/threats/stride.d.ts +3 -0
  36. package/lib/threats/stride.js +120 -0
  37. package/lib/threats/types.d.ts +16 -0
  38. package/lib/threats/types.js +22 -0
  39. package/lib/threats/view.d.ts +27 -0
  40. package/lib/threats/view.js +51 -0
  41. package/package.json +4 -4
@@ -1,5 +1,6 @@
1
1
  import { buildAuditResult } from '../findings/scoring.js';
2
2
  import { getComplianceTags } from '../compliance/resolve.js';
3
+ import { threatsFor } from '../threats/resolve.js';
3
4
  import { ChainEngine } from '../chains/ChainEngine.js';
4
5
  import { applyWaivers } from '../waivers/applyWaivers.js';
5
6
  import { permissionLabelsFor } from '../preflight/permissions.js';
@@ -93,13 +94,15 @@ export class CheckEngine {
93
94
  try {
94
95
  const result = await check.run(this.ctx);
95
96
  const tags = getComplianceTags(check.id);
96
- findings.push(...result.findings.map((f) => ({ ...f, checkId: check.id, complianceTags: tags })));
97
+ findings.push(...result.findings.map((f) => ({
98
+ ...f, checkId: check.id, complianceTags: tags, threats: threatsFor(check.id, f.threats),
99
+ })));
97
100
  if (result.metrics) {
98
101
  metrics = { ...metrics, ...result.metrics };
99
102
  }
100
103
  }
101
104
  catch (err) {
102
- findings.push(buildErrorFinding(check, err));
105
+ findings.push({ ...buildErrorFinding(check, err), threats: threatsFor(check.id) });
103
106
  }
104
107
  }
105
108
  // Waivers apply before correlation but do not remove findings from it: an accepted weakness
@@ -1,4 +1,5 @@
1
- import { isApiError } from '@cclabsnz/sf-core';
1
+ // Shared, so MALFORMED_QUERY (a bug in the query) is never read as an absent feature.
2
+ import { isMissingObjectError } from '../support/missingObject.js';
2
3
  // An agent carrying more than this many actions has a large, hard-to-review surface. Info
3
4
  // only — a big surface is not a vulnerability by itself, but it is worth surfacing.
4
5
  const ACTION_COUNT_THRESHOLD = 15;
@@ -6,18 +7,6 @@ const ACTION_COUNT_THRESHOLD = 15;
6
7
  // them as write-capable). Apex and Flow can both mutate data; where the type string is
7
8
  // unknown/ambiguous we deliberately err toward flagging and say so in the finding.
8
9
  const WRITE_CAPABLE_TYPE_HINTS = ['apex', 'flow'];
9
- function isMissingObjectError(err) {
10
- if (isApiError(err)) {
11
- if (/INVALID_TYPE|NOT_FOUND|MALFORMED_QUERY/i.test(err.errorCode))
12
- return true;
13
- if (err.statusCode === 404)
14
- return true;
15
- }
16
- const msg = (err instanceof Error ? err.message : String(err)).toLowerCase();
17
- return (msg.includes('not supported') ||
18
- msg.includes('invalid type') ||
19
- msg.includes('sobject type'));
20
- }
21
10
  export class AgentActionSurfaceCheck {
22
11
  id = 'agent-action-surface';
23
12
  name = 'Agent Action Surface';
@@ -1,4 +1,6 @@
1
1
  import { isApiError } from '@cclabsnz/sf-core';
2
+ // Shared, so MALFORMED_QUERY (a bug in the query) is never read as an absent feature.
3
+ import { isMissingObjectError } from '../support/missingObject.js';
2
4
  // BotDefinition.Type values that denote an Agentforce / GenAI agent rather than a
3
5
  // classic Einstein Bot. Matched case-insensitively; anything else (typically 'Bot')
4
6
  // is treated as a classic bot. LIKE-style matching so exact enum spellings across
@@ -7,21 +9,6 @@ const AGENT_TYPE_HINTS = ['agent', 'einsteinservice', 'einsteincopilot', 'genai'
7
9
  // Permission set license labels that grant Agentforce / Einstein Agent capability.
8
10
  // Substring match so exact SKU names are not load-bearing.
9
11
  const AGENT_LICENSE_HINTS = ['agentforce', 'einstein agent'];
10
- // A Tooling error whose cause is "the object does not exist" (feature absent) rather
11
- // than a transient/permission failure. Mirrors classifyEventLogAccessError's not-enabled arm.
12
- function isMissingObjectError(err) {
13
- if (isApiError(err)) {
14
- if (/INVALID_TYPE|NOT_FOUND|MALFORMED_QUERY/i.test(err.errorCode))
15
- return true;
16
- if (err.statusCode === 404)
17
- return true;
18
- }
19
- const msg = (err instanceof Error ? err.message : String(err)).toLowerCase();
20
- return (msg.includes('not supported') ||
21
- msg.includes('invalid type') ||
22
- msg.includes('is not supported') ||
23
- msg.includes('sobject type'));
24
- }
25
12
  export class AgentInventoryCheck {
26
13
  id = 'agent-inventory';
27
14
  name = 'Agentforce Agent Inventory';
@@ -96,6 +96,8 @@ export class ApexLoggingCheck {
96
96
  findings.push({
97
97
  id: 'apex-logging-sensitive-data',
98
98
  category: this.category,
99
+ // A disclosure, not a repudiation gap: its fix removes logging (RULE-103).
100
+ threats: { stride: ['I'] },
99
101
  riskLevel: 'HIGH',
100
102
  title: `${sensitiveLogClasses.length} Apex class(es) may log sensitive data: SBS-CODE-004`,
101
103
  detail: 'SBS-CODE-004 prohibits logging sensitive data (passwords, tokens, session IDs, PII) in Apex. The flagged classes appear to pass sensitive variable names or credential values directly to System.debug(), which writes them to debug logs accessible to any administrator who can view debug logs.',
@@ -75,6 +75,8 @@ export class GuestApiAccessCheck {
75
75
  findings.push({
76
76
  id: 'guest-api-hard-delete',
77
77
  category: this.category,
78
+ // Irreversible deletion takes the data away; it is not a disclosure.
79
+ threats: { stride: ['D', 'T'] },
78
80
  riskLevel: 'CRITICAL',
79
81
  title: `${hardDeleteGuests.size} guest user(s) have Bulk API Hard Delete`,
80
82
  detail: '"Bulk API Hard Delete" lets the holder permanently delete records, skipping the recycle bin. On a guest user this hands an unauthenticated visitor an irreversible destructive capability.',
@@ -97,6 +97,8 @@ export class GuestUserAccessCheck {
97
97
  findings.push({
98
98
  id: 'guest-user-write-access',
99
99
  category: this.category,
100
+ // Writing is tampering, not the disclosure the rest of this check reports.
101
+ threats: { stride: ['T', 'I'] },
100
102
  riskLevel: 'CRITICAL',
101
103
  title: 'Guest user profile(s) have write access to Salesforce objects',
102
104
  affectedItems: writeViolations.map((v) => {
@@ -14,20 +14,37 @@ export class UsersAndAdminsCheck {
14
14
  // Total active, non-frozen users
15
15
  const activeUsersResult = await ctx.soql.query('SELECT COUNT() FROM User WHERE IsActive = true AND Id NOT IN (SELECT UserId FROM UserLogin WHERE IsFrozen = true)');
16
16
  const totalActiveUsers = activeUsersResult.totalSize;
17
- const broadPermResult = await ctx.soql.query(`SELECT Assignee.Id, Assignee.Username, Assignee.Name, Assignee.Profile.Name,
18
- PermissionSet.Name, PermissionSet.IsOwnedByProfile,
19
- PermissionSet.PermissionsModifyAllData, PermissionSet.PermissionsViewAllData,
20
- PermissionSet.PermissionsManageUsers, PermissionSet.PermissionsCustomizeApplication,
21
- PermissionSet.PermissionsAuthorApex
22
- FROM PermissionSetAssignment
17
+ const psaFrom = `FROM PermissionSetAssignment
23
18
  WHERE (PermissionSet.PermissionsModifyAllData = true
24
19
  OR PermissionSet.PermissionsViewAllData = true
25
20
  OR PermissionSet.PermissionsManageUsers = true
26
21
  OR PermissionSet.PermissionsCustomizeApplication = true
27
22
  OR PermissionSet.PermissionsAuthorApex = true)
28
23
  AND Assignee.IsActive = true
29
- AND AssigneeId NOT IN (SELECT UserId FROM UserLogin WHERE IsFrozen = true)`);
30
- const broadPerms = broadPermResult.records;
24
+ AND AssigneeId NOT IN (SELECT UserId FROM UserLogin WHERE IsFrozen = true)`;
25
+ // queryAll reads every page (sf-core 0.12+), but assignments can change between the read and the
26
+ // COUNT(). The COUNT() says how many rows there are, so a short read is detected (INT-004).
27
+ const broadPerms = await ctx.soql.queryAll(`SELECT Assignee.Id, Assignee.Username, Assignee.Name, Assignee.Profile.Name,
28
+ PermissionSet.Name, PermissionSet.IsOwnedByProfile,
29
+ PermissionSet.PermissionsModifyAllData, PermissionSet.PermissionsViewAllData,
30
+ PermissionSet.PermissionsManageUsers, PermissionSet.PermissionsCustomizeApplication,
31
+ PermissionSet.PermissionsAuthorApex
32
+ ${psaFrom}`);
33
+ // `partial` means the rows may be incomplete: the COUNT reports more than came back, or the
34
+ // COUNT itself failed, so completeness cannot be confirmed. Counts are then lower bounds.
35
+ let psaTotal;
36
+ try {
37
+ psaTotal = (await ctx.soql.query(`SELECT COUNT() ${psaFrom}`)).totalSize;
38
+ }
39
+ catch {
40
+ psaTotal = undefined;
41
+ }
42
+ const partial = psaTotal === undefined || psaTotal > broadPerms.length;
43
+ const readNote = psaTotal === undefined
44
+ ? 'whether every assignment was read could not be confirmed'
45
+ : `read ${broadPerms.length} of ${psaTotal} assignments`;
46
+ // "At least N" when the read may be partial: the count is a lower bound, still definite.
47
+ const count = (n) => (partial ? `At least ${n}` : `${n}`);
31
48
  // Group by permission — a user may appear multiple times (once per permission set granting them)
32
49
  const modifyAllUsers = broadPerms.filter((r) => r.PermissionSet.PermissionsModifyAllData);
33
50
  const viewAllUsers = broadPerms.filter((r) => r.PermissionSet.PermissionsViewAllData);
@@ -61,13 +78,43 @@ export class UsersAndAdminsCheck {
61
78
  category: this.category,
62
79
  // Every org needs an administrator: grade on how many hold unrestricted control.
63
80
  riskLevel: sandboxCap(superAdminIds.length > 5 ? 'CRITICAL' : superAdminIds.length > 3 ? 'HIGH' : 'LOW'),
64
- title: `${superAdminIds.length} user(s) hold the super-admin permission combination (ViewAllData + ModifyAllData + ManageUsers)`,
81
+ title: `${count(superAdminIds.length)} user(s) hold the super-admin permission combination (ViewAllData + ModifyAllData + ManageUsers)`,
65
82
  detail: 'SBS-ACS-004 requires documented justification for any user holding all three of ViewAllData, ModifyAllData, and ManageUsers simultaneously. This combination is equivalent to unrestricted org control.' +
66
83
  (superAdminIds.length > 5 ? sandboxNote : ''),
67
84
  remediation: 'Reduce to the minimum necessary permissions. Document justification for each user in the system of record. Consider breaking this into role-specific permission sets.',
68
85
  affectedItems: superAdminItems,
69
86
  });
70
87
  }
88
+ // Every org with an active System Administrator has holders of both permissions, so zero means
89
+ // the assignments were not visible to the audit user, or not all were read. Zero is unknown:
90
+ // inconclusive, never a pass and never an active exposure (INT-004). A non-zero count from a
91
+ // partial read is a definite lower bound, so it stays active at that bound's severity.
92
+ const modifyUnknown = modifyAllCount === 0;
93
+ const viewUnknown = viewAllCount === 0;
94
+ const unknownTitle = (perm) => partial
95
+ ? `Could not confirm who holds ${perm}: ${readNote}`
96
+ : `Could not confirm who holds ${perm}`;
97
+ const unknownDetail = (perm) => partial
98
+ ? `No ${perm} holder was found, but ${readNote}, so holders may be in the rows not read.`
99
+ : `No active user was found holding ${perm}, yet every org with an active System Administrator has at least one. The audit user most likely cannot see PermissionSetAssignment rows, so this is unknown, not clean.`;
100
+ const RE_RUN = 'Re-run the audit: permission set assignments changed while it was reading them, or the count of them could not be read.';
101
+ const SEE_ROWS = 'Re-run as a user with View Setup and Configuration (or View All Users) so permission set assignments are visible.';
102
+ // A short read needs a fresh read; a failed COUNT may also mean the rows are not visible, so the
103
+ // visibility advice applies too.
104
+ const unknownRemediation = !partial ? SEE_ROWS : psaTotal === undefined ? `${SEE_ROWS} ${RE_RUN}` : RE_RUN;
105
+ // On a partial read, a count can also fall under its reporting threshold and not appear at all.
106
+ // This finding is the machine-readable signal for every count from the read (INT-004).
107
+ if (partial) {
108
+ findings.push({
109
+ id: 'users-and-admins-read-incomplete',
110
+ category: this.category,
111
+ riskLevel: 'INFO',
112
+ inconclusive: true,
113
+ title: `Permission assignments were not fully read: ${readNote}`,
114
+ detail: 'Counts of Modify All Data, View All Data, super-admin, Customize Application and Author Apex holders are lower bounds. A count under its reporting threshold, or a super-admin whose permissions fell in the rows not read, may not be reported at all; such a super-admin is rated under Modify All Data instead.',
115
+ remediation: unknownRemediation,
116
+ });
117
+ }
71
118
  // Rate Modify All Data on the holders the super-admin finding does not already cover, so the
72
119
  // same users are not counted towards the grade twice. The finding still lists every holder.
73
120
  const superAdminSet = new Set(superAdminIds);
@@ -79,25 +126,41 @@ export class UsersAndAdminsCheck {
79
126
  findings.push({
80
127
  id: 'users-modify-all-data',
81
128
  category: this.category,
82
- riskLevel: modifyRisk,
83
- title: `${modifyAllCount} user(s) have Modify All Data permission`,
84
- // The population is always reported; at the lowest band it asks for no change.
85
- passed: modifyRisk === 'LOW' || undefined,
86
- detail: 'Modify All Data grants unrestricted write access across all objects. This is one of the most powerful permissions in Salesforce.' +
87
- coveredNote +
88
- (modifyRisk === 'HIGH' && otherModifyAll > 5 ? sandboxNote : ''),
89
- remediation: 'Limit Modify All Data to essential system administrators only. Review each user and remove the permission from any non-essential accounts.',
129
+ riskLevel: modifyUnknown ? 'INFO' : modifyRisk,
130
+ ...(modifyUnknown ? { inconclusive: true } : {}),
131
+ title: modifyUnknown
132
+ ? unknownTitle('Modify All Data')
133
+ : `${count(modifyAllCount)} user(s) have Modify All Data permission`,
134
+ // The population is always reported; at the lowest band it asks for no change. Zero holders
135
+ // is unknown and a partial read is a lower bound, so neither is a pass (INT-004).
136
+ passed: (!modifyUnknown && !partial && modifyRisk === 'LOW') || undefined,
137
+ detail: modifyUnknown
138
+ ? unknownDetail('Modify All Data')
139
+ : 'Modify All Data grants unrestricted write access across all objects. This is one of the most powerful permissions in Salesforce.' +
140
+ coveredNote +
141
+ (modifyRisk === 'HIGH' && otherModifyAll > 5 ? sandboxNote : '') +
142
+ (partial ? ` This is a lower bound: ${readNote}.` : ''),
143
+ remediation: modifyUnknown
144
+ ? unknownRemediation
145
+ : 'Limit Modify All Data to essential system administrators only. Review each user and remove the permission from any non-essential accounts.',
90
146
  affectedItems: modifyAllUsers.map((r) => userItem(r)),
91
147
  });
92
148
  const viewRisk = viewAllCount > 10 ? 'HIGH' : viewAllCount > 5 ? 'MEDIUM' : 'LOW';
93
149
  findings.push({
94
150
  id: 'users-view-all-data',
95
151
  category: this.category,
96
- riskLevel: viewRisk,
97
- title: `${viewAllCount} user(s) have View All Data permission`,
98
- passed: viewRisk === 'LOW' || undefined,
99
- detail: 'View All Data grants unrestricted read access across all objects, bypassing sharing rules and record-level security.',
100
- remediation: 'Limit View All Data to essential users. Consider using permission sets scoped to specific objects instead.',
152
+ riskLevel: viewUnknown ? 'INFO' : viewRisk,
153
+ ...(viewUnknown ? { inconclusive: true } : {}),
154
+ title: viewUnknown
155
+ ? unknownTitle('View All Data')
156
+ : `${count(viewAllCount)} user(s) have View All Data permission`,
157
+ passed: (!viewUnknown && !partial && viewRisk === 'LOW') || undefined,
158
+ detail: viewUnknown
159
+ ? unknownDetail('View All Data')
160
+ : 'View All Data grants unrestricted read access across all objects, bypassing sharing rules and record-level security.' + (partial ? ` This is a lower bound: ${readNote}.` : ''),
161
+ remediation: viewUnknown
162
+ ? unknownRemediation
163
+ : 'Limit View All Data to essential users. Consider using permission sets scoped to specific objects instead.',
101
164
  affectedItems: viewAllUsers.map((r) => userItem(r)),
102
165
  });
103
166
  if (customizeAppCount > 5) {
@@ -105,7 +168,7 @@ export class UsersAndAdminsCheck {
105
168
  id: 'users-customize-application',
106
169
  category: this.category,
107
170
  riskLevel: 'MEDIUM',
108
- title: `${customizeAppCount} user(s) have Customize Application permission`,
171
+ title: `${count(customizeAppCount)} user(s) have Customize Application permission`,
109
172
  detail: 'Customize Application allows users to make metadata changes, including modifying page layouts, custom fields, and application settings.',
110
173
  remediation: 'Customize Application allows metadata changes. Review and reduce to essential configuration administrators.',
111
174
  affectedItems: customizeAppUsers.map((r) => userItem(r)),
@@ -116,7 +179,7 @@ export class UsersAndAdminsCheck {
116
179
  id: 'users-author-apex',
117
180
  category: this.category,
118
181
  riskLevel: 'MEDIUM',
119
- title: `${authorApexCount} user(s) have Author Apex permission`,
182
+ title: `${count(authorApexCount)} user(s) have Author Apex permission`,
120
183
  detail: 'Author Apex allows users to write and deploy Apex code, which can execute server-side logic with elevated privileges.',
121
184
  remediation: 'Author Apex allows code deployment. Limit to developers with a genuine need.',
122
185
  affectedItems: authorApexUsers.map((r) => userItem(r)),
@@ -126,8 +189,10 @@ export class UsersAndAdminsCheck {
126
189
  findings,
127
190
  metrics: {
128
191
  totalActiveUsers,
129
- modifyAllDataUsersCount: modifyAllCount,
130
- viewAllDataUsersCount: viewAllCount,
192
+ // An unknown or lower-bound count is left out rather than reported as an exact number;
193
+ // see unknownMetrics.
194
+ ...(modifyUnknown || partial ? {} : { modifyAllDataUsersCount: modifyAllCount }),
195
+ ...(viewUnknown || partial ? {} : { viewAllDataUsersCount: viewAllCount }),
131
196
  },
132
197
  };
133
198
  }
@@ -14,7 +14,8 @@ export function isMissingObjectError(err) {
14
14
  // would report an unchecked area as clean.
15
15
  if (/INVALID_TYPE|NOT_FOUND/i.test(err.errorCode))
16
16
  return true;
17
- if (err.statusCode === 404)
17
+ // sf-core 0.12: a Connection-path 404 with no Salesforce code carries no statusCode.
18
+ if (err.statusCode === 404 || err.errorCode === 'ERROR_HTTP_404')
18
19
  return true;
19
20
  }
20
21
  const msg = (err instanceof Error ? err.message : String(err)).toLowerCase();
@@ -1,7 +1,7 @@
1
1
  import { isApiError } from '@cclabsnz/sf-core';
2
2
  const cache = new WeakMap();
3
3
  function isNotFound(err) {
4
- if (isApiError(err) && (err.statusCode === 404 || /NOT_FOUND|INVALID_TYPE/i.test(err.errorCode)))
4
+ if (isApiError(err) && (err.statusCode === 404 || /NOT_FOUND|INVALID_TYPE|^ERROR_HTTP_404$/i.test(err.errorCode)))
5
5
  return true;
6
6
  const msg = err instanceof Error ? err.message : String(err);
7
7
  return /NOT_FOUND|requested resource does not exist|is not supported/i.test(msg);
@@ -1,6 +1,7 @@
1
1
  import * as path from 'node:path';
2
2
  import { SfCommand, Flags } from '@salesforce/sf-plugins-core';
3
3
  import { buildAuditContext, resolveOrgInfo } from '../../../lib/wire.js';
4
+ import { apiErrorText } from '../../../lib/apiErrorText.js';
4
5
  import { collectBundle, defaultIncidentRoot } from '../../../incident/collect/collectBundle.js';
5
6
  export default class AuditIncidentCollectCommand extends SfCommand {
6
7
  static summary = 'Collect a guest-filtered evidence bundle for a Guest User Anomaly investigation';
@@ -35,7 +36,7 @@ export default class AuditIncidentCollectCommand extends SfCommand {
35
36
  ({ manifest } = await collectBundle({ soql: ctx.soql, rest: ctx.rest, orgId: orgInfo.id, orgName: orgInfo.name }, { sinceDays: flags.since, window: flags.window, event: flags.event, ipRangeFiles: flags['ip-ranges'] ?? [], outputDir: dir, warn: (m) => this.warn(m) }));
36
37
  }
37
38
  catch (e) {
38
- const message = e instanceof Error ? e.message : String(e);
39
+ const message = apiErrorText(e);
39
40
  this.error(`${message} (partial bundle kept at ${dir}; re-run with --output "${dir}" to resume)`, { exit: 1 });
40
41
  }
41
42
  const collected = manifest.logs.filter((l) => l.status === 'collected').length;
@@ -1,5 +1,6 @@
1
1
  import type { RiskLevel } from '@cclabsnz/sf-core';
2
2
  import type { Capability } from '../chains/Capability.js';
3
+ import type { FindingThreats } from '../threats/types.js';
3
4
  export interface AffectedItem {
4
5
  label: string;
5
6
  url?: string;
@@ -30,6 +31,12 @@ export interface Finding {
30
31
  * Populated by CheckEngine from ComplianceMapping after each check runs.
31
32
  */
32
33
  complianceTags?: string[];
34
+ /**
35
+ * STRIDE and LINDDUN categories. Populated by CheckEngine from the threat maps; a check may set
36
+ * either list inline to override its check-level entry for this finding. Carries no weight in
37
+ * scoring, grading or --fail-on (RULE-105).
38
+ */
39
+ threats?: FindingThreats;
33
40
  /**
34
41
  * True when the check could not gather evidence due to insufficient permissions.
35
42
  * Scored as INFO (no impact on health score) but displayed distinctly.
@@ -0,0 +1,5 @@
1
+ import type { OrgMetrics } from '@cclabsnz/sf-core';
2
+ import type { Finding } from './Finding.js';
3
+ /** Metrics that are unknown in this result, so must not be shown or compared as numbers. */
4
+ export declare function unknownMetrics(findings: Finding[]): Set<keyof OrgMetrics>;
5
+ //# sourceMappingURL=unknownMetrics.d.ts.map
@@ -0,0 +1,29 @@
1
+ /**
2
+ * Metrics whose value is only meaningful when the finding that reports the same count was
3
+ * definite. A result fills missing metrics with 0, so without this an unreadable count shows as a
4
+ * reassuring zero on the dashboard and as an "improvement" in a history diff (INT-004).
5
+ */
6
+ const METRIC_SOURCE = {
7
+ modifyAllDataUsersCount: 'users-modify-all-data',
8
+ viewAllDataUsersCount: 'users-view-all-data',
9
+ };
10
+ /**
11
+ * Whether a source finding gives its metric an exact value. Not when it is missing (the check did
12
+ * not run, or failed) or inconclusive; not when its title is a lower bound ("At least N", a capped
13
+ * read); and not for "0 user(s)", which is how v1.17 and earlier archived an unreadable count.
14
+ */
15
+ function exact(source) {
16
+ if (!source || source.inconclusive === true)
17
+ return false;
18
+ return !/^(At least |0 user\(s\))/.test(source.title);
19
+ }
20
+ /** Metrics that are unknown in this result, so must not be shown or compared as numbers. */
21
+ export function unknownMetrics(findings) {
22
+ const unknown = new Set();
23
+ for (const [key, id] of Object.entries(METRIC_SOURCE)) {
24
+ if (!exact(findings.find((f) => f.id === id)))
25
+ unknown.add(key);
26
+ }
27
+ return unknown;
28
+ }
29
+ //# sourceMappingURL=unknownMetrics.js.map
@@ -1,4 +1,5 @@
1
1
  import { METRIC_META, metricDirection } from './metricMeta.js';
2
+ import { unknownMetrics } from '../findings/unknownMetrics.js';
2
3
  function detailChanged(a, b) {
3
4
  return (a.detail !== b.detail ||
4
5
  a.remediation !== b.remediation ||
@@ -30,9 +31,13 @@ export function computeDiff(baseline, current) {
30
31
  findingChanges.push({ type: 'resolved', finding: prev });
31
32
  }
32
33
  }
33
- // Metric deltas — only emit when before !== after
34
+ // Metric deltas — only emit when before !== after, and only between two known values: an
35
+ // unreadable count is stored as 0, and a drop to it is not an improvement.
36
+ const unknown = new Set([...unknownMetrics(baseline.findings), ...unknownMetrics(current.findings)]);
34
37
  const metricDeltas = [];
35
38
  for (const key of Object.keys(METRIC_META)) {
39
+ if (unknown.has(key))
40
+ continue;
36
41
  const before = baseline.metrics[key];
37
42
  const after = current.metrics[key];
38
43
  if (before === after)
@@ -1,6 +1,8 @@
1
+ // src/incident/collect/orgErrors.ts
2
+ import { apiErrorText } from '../../lib/apiErrorText.js';
1
3
  /** Only 'unavailable' and 'no-permission' may degrade collection; everything else must abort it. */
2
4
  export function classifyOrgError(e) {
3
- const m = e instanceof Error ? e.message : String(e);
5
+ const m = apiErrorText(e);
4
6
  if (/INVALID_TYPE|is not supported|not supported/i.test(m))
5
7
  return 'unavailable';
6
8
  if (/INSUFFICIENT_ACCESS|HTTP 403/i.test(m))
@@ -2,6 +2,7 @@
2
2
  import { rmSync, renameSync, statfsSync } from 'node:fs';
3
3
  import { join } from 'node:path';
4
4
  import { secureFs } from '@cclabsnz/sf-core';
5
+ import { apiErrorText } from '../../lib/apiErrorText.js';
5
6
  import { degrades } from './orgErrors.js';
6
7
  import { filterLogFile, MissingColumnsError } from '../csv.js';
7
8
  import { logPath } from '../bundleIo.js';
@@ -92,7 +93,7 @@ onLogDone = () => { }) {
92
93
  settled = { type, day, status: 'collected', ...r, file: rel };
93
94
  }
94
95
  catch (e) {
95
- if (e?.code === 'ENOSPC' || /HTTP 401/.test(String(e))) {
96
+ if (e?.code === 'ENOSPC' || /HTTP 401/.test(apiErrorText(e))) {
96
97
  rmSync(part, { force: true });
97
98
  rmSync(raw, { force: true });
98
99
  rmSync(tmp, { recursive: true, force: true });
@@ -101,7 +102,7 @@ onLogDone = () => { }) {
101
102
  warn(`Could not collect ${type} for ${day}: ${e instanceof MissingColumnsError ? e.message : String(e)}`);
102
103
  settled = e instanceof MissingColumnsError
103
104
  ? blank(type, day, 'failed', e.message)
104
- : blank(type, day, /INSUFFICIENT_ACCESS|HTTP 403/i.test(String(e)) ? 'no-permission' : 'failed', String(e));
105
+ : blank(type, day, /INSUFFICIENT_ACCESS|HTTP 403/i.test(apiErrorText(e)) ? 'no-permission' : 'failed', apiErrorText(e));
105
106
  rmSync(part, { force: true });
106
107
  }
107
108
  finally {
@@ -0,0 +1,8 @@
1
+ /**
2
+ * An error's Salesforce code, HTTP status and message as one string, for classifiers that match
3
+ * on text. sf-core 0.12 keeps the code out of the message (`INVALID_SESSION_ID` arrives as
4
+ * "Session expired or invalid"), and an error body with no Salesforce code is
5
+ * `ERROR_HTTP_<status>` with no status on the Connection path; both read here as "HTTP <status>".
6
+ */
7
+ export declare function apiErrorText(e: unknown): string;
8
+ //# sourceMappingURL=apiErrorText.d.ts.map
@@ -0,0 +1,15 @@
1
+ /**
2
+ * An error's Salesforce code, HTTP status and message as one string, for classifiers that match
3
+ * on text. sf-core 0.12 keeps the code out of the message (`INVALID_SESSION_ID` arrives as
4
+ * "Session expired or invalid"), and an error body with no Salesforce code is
5
+ * `ERROR_HTTP_<status>` with no status on the Connection path; both read here as "HTTP <status>".
6
+ */
7
+ export function apiErrorText(e) {
8
+ if (!(e instanceof Error))
9
+ return String(e);
10
+ const { errorCode, statusCode } = e;
11
+ const code = typeof errorCode === 'string' ? errorCode : '';
12
+ const status = typeof statusCode === 'number' ? statusCode : /^ERROR_HTTP_(\d{3})$/.exec(code)?.[1];
13
+ return [code, status === undefined ? '' : `HTTP ${status}`, e.message].filter(Boolean).join(' ');
14
+ }
15
+ //# sourceMappingURL=apiErrorText.js.map
@@ -2,6 +2,10 @@ import type { AttackChain } from '../chains/AttackChain.js';
2
2
  export interface DagRenderOptions {
3
3
  theme?: 'dark' | 'light';
4
4
  }
5
- export declare function identifyCutPointIndex(chain: AttackChain): number;
5
+ /**
6
+ * Indices of the steps in the chain's break point: removing every one of them stops a named chain.
7
+ * Empty for potential chains, which have no proven break point (MN-060).
8
+ */
9
+ export declare function breakPointIndices(chain: AttackChain): number[];
6
10
  export declare function renderAttackChainDagSvg(chain: AttackChain, opts?: DagRenderOptions): string;
7
11
  //# sourceMappingURL=AttackChainDagRenderer.d.ts.map
@@ -1,7 +1,7 @@
1
1
  // src/renderers/AttackChainDagRenderer.ts
2
2
  //
3
- // Draws an attack chain as an inline SVG strip of step cards joined by arrows, with the step whose
4
- // fix breaks the chain marked as the cut-point. The executive report runs under a strict CSP (no
3
+ // Draws an attack chain as an inline SVG strip of step cards joined by arrows, with the steps that
4
+ // make up a named chain's proven break point marked (RULE-111). Potential chains have none. The executive report runs under a strict CSP (no
5
5
  // script, inline style only), so the output is self-contained: no <script>, no event handlers, no
6
6
  // <foreignObject>, no external references. Every chain/step string is escaped before it is placed
7
7
  // in text or an attribute; colours come only from fixed lookup tables.
@@ -14,28 +14,12 @@ const SEV_COLORS = {
14
14
  };
15
15
  /** Cards per row before the strip wraps, so long chains stay readable when scaled to page width. */
16
16
  const MAX_PER_ROW = 4;
17
- export function identifyCutPointIndex(chain) {
18
- if (!chain.steps || chain.steps.length === 0)
19
- return 0;
20
- const rem = (chain.remediation || '').toLowerCase();
21
- for (let i = 0; i < chain.steps.length; i++) {
22
- const s = chain.steps[i];
23
- if (s.findingId && rem.includes(s.findingId.toLowerCase()))
24
- return i;
25
- if (s.title && rem.includes(s.title.toLowerCase()))
26
- return i;
27
- }
28
- const sevRank = { CRITICAL: 4, HIGH: 3, MEDIUM: 2, LOW: 1, INFO: 0 };
29
- let bestIdx = 0;
30
- let bestRank = -1;
31
- for (let i = 0; i < chain.steps.length; i++) {
32
- const rank = sevRank[chain.steps[i].severity ?? 'LOW'] ?? 1;
33
- if (rank > bestRank) {
34
- bestRank = rank;
35
- bestIdx = i;
36
- }
37
- }
38
- return bestIdx;
17
+ /**
18
+ * Indices of the steps in the chain's break point: removing every one of them stops a named chain.
19
+ * Empty for potential chains, which have no proven break point (MN-060).
20
+ */
21
+ export function breakPointIndices(chain) {
22
+ return (chain.steps ?? []).flatMap((s, i) => (s.breaksChain ? [i] : []));
39
23
  }
40
24
  /** Truncate by code point (never splitting a surrogate pair); escaping happens after. */
41
25
  function truncate(str, maxLen) {
@@ -47,7 +31,7 @@ export function renderAttackChainDagSvg(chain, opts = {}) {
47
31
  const steps = chain.steps ?? [];
48
32
  if (steps.length === 0)
49
33
  return '';
50
- const cutPointIdx = identifyCutPointIndex(chain);
34
+ const cutPoints = new Set(breakPointIndices(chain));
51
35
  const cardW = 220;
52
36
  const cardH = 96;
53
37
  const gap = 52;
@@ -75,23 +59,24 @@ export function renderAttackChainDagSvg(chain, opts = {}) {
75
59
  const nodesSvg = steps
76
60
  .map((step, idx) => {
77
61
  const { x, y } = posOf(idx);
78
- const isCut = idx === cutPointIdx;
62
+ const isCut = cutPoints.has(idx);
79
63
  const sevRaw = String(step.severity ?? 'LOW');
80
64
  const sevCol = sevColors[sevRaw] ?? sevColors.INFO;
81
65
  const sev = esc(truncate(sevRaw, 10));
82
66
  const title = esc(truncate(String(step.title || step.findingId || ''), 26));
83
- const cap = esc(truncate(String(step.capability ?? ''), 24));
67
+ // An inferred capability is a fallback, not something the finding grants (RULE-110).
68
+ const cap = step.capabilityInferred ? '' : esc(truncate(String(step.capability ?? ''), 24));
84
69
  const stroke = isCut ? cutAccent : cardBorder;
85
70
  const strokeWidth = isCut ? '2.5' : '1';
86
71
  const dash = isCut ? ' stroke-dasharray="4 2"' : '';
87
72
  const cutBadge = isCut
88
73
  ? `<g transform="translate(${x + cardW - 84}, ${y - 10})">
89
74
  <rect width="80" height="18" rx="4" fill="${cutAccent}" />
90
- <text x="40" y="12" fill="#ffffff" font-size="9" font-weight="700" text-anchor="middle" font-family="system-ui, sans-serif">✂ CUT-POINT</text>
75
+ <text x="40" y="12" fill="#ffffff" font-size="9" font-weight="700" text-anchor="middle" font-family="system-ui, sans-serif">✂ BREAK POINT</text>
91
76
  </g>`
92
77
  : '';
93
78
  const cutNote = isCut
94
- ? `<text x="${x + 10}" y="${y + cardH - 10}" fill="${cutAccent}" font-size="9" font-weight="600" font-family="system-ui, sans-serif">★ Remediating breaks chain</text>`
79
+ ? `<text x="${x + 10}" y="${y + cardH - 10}" fill="${cutAccent}" font-size="9" font-weight="600" font-family="system-ui, sans-serif">${cutPoints.size > 1 ? 'Fix every ✂ step' : 'Fixing this breaks it'}</text>`
95
80
  : '';
96
81
  return `<g class="dag-node${isCut ? ' dag-cut-point' : ''}">
97
82
  <rect x="${x}" y="${y}" width="${cardW}" height="${cardH}" rx="8" fill="${cardBg}" stroke="${stroke}" stroke-width="${strokeWidth}"${dash} />
@@ -99,8 +84,8 @@ export function renderAttackChainDagSvg(chain, opts = {}) {
99
84
  <circle cx="${x + 18}" cy="${y + 20}" r="4" fill="${sevCol}" />
100
85
  <text x="${x + 28}" y="${y + 24}" fill="${sevCol}" font-size="10" font-weight="700" font-family="system-ui, sans-serif">STEP ${idx + 1} · ${sev}</text>
101
86
  <text x="${x + 10}" y="${y + 44}" fill="${textColor}" font-size="12" font-weight="600" font-family="system-ui, sans-serif">${title}</text>
102
- <rect x="${x + 10}" y="${y + 54}" width="${cardW - 20}" height="18" rx="4" fill="${pillBg}" />
103
- <text x="${x + 16}" y="${y + 67}" fill="${mutedColor}" font-size="10" font-family="ui-monospace, monospace">grants: ${cap}</text>
87
+ ${cap ? `<rect x="${x + 10}" y="${y + 54}" width="${cardW - 20}" height="18" rx="4" fill="${pillBg}" />
88
+ <text x="${x + 16}" y="${y + 67}" fill="${mutedColor}" font-size="10" font-family="ui-monospace, monospace">grants: ${cap}</text>` : ''}
104
89
  ${cutNote}
105
90
  </g>`;
106
91
  })
@@ -183,9 +183,12 @@ ${impact}${chained}<p><strong>Fix:</strong> ${esc(f.remediation)}</p></div>`;
183
183
  const dagSvg = renderAttackChainDagSvg(c, { theme: 'light' });
184
184
  return `<div class="card scenario" style="--c:${SEV_COLOR[c.severity]}">
185
185
  <div class="row"><h3>${esc(c.title)}</h3>${this.chip(c.severity, c.severity)}</div>
186
+ ${c.abuseCase ? `<p><strong>Abuse case:</strong> ${esc(c.abuseCase.actor)} wants to ${esc(c.abuseCase.goal)}.</p>` : ''}
186
187
  <p>${esc(c.narrative)}</p>
187
188
  ${dagSvg}
188
- <p><strong>Breaks the chain:</strong> ${esc(c.remediation)}</p></div>`;
189
+ ${c.abuseCase
190
+ ? `<p><strong>Breaks the chain:</strong> ${esc(c.abuseCase.breakPoint)}</p><p class="muted"><strong>Full remediation:</strong> ${esc(c.remediation)}</p>`
191
+ : `<p><strong>Recommended fixes:</strong> ${esc(c.remediation)}</p>`}</div>`;
189
192
  }).join('');
190
193
  return `${this.sectionHead(numStr, 'Attack Scenarios')}<p class="muted">How findings combine into real attack paths.</p>${items}`;
191
194
  }