@cclabsnz/sf-audit 1.25.1 → 1.27.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.
@@ -0,0 +1,59 @@
1
+ import type { AuditResult } from './AuditResult.js';
2
+ import type { Finding } from './Finding.js';
3
+ import { EFFORT_LABEL, WAVE_LABEL } from '../report/ActionPlan.js';
4
+ export interface SummaryAction {
5
+ rank: number;
6
+ wave: (typeof WAVE_LABEL)[keyof typeof WAVE_LABEL];
7
+ title: string;
8
+ severity: Finding['riskLevel'];
9
+ effort: (typeof EFFORT_LABEL)[keyof typeof EFFORT_LABEL];
10
+ /** Ids of the open findings it closes. */
11
+ closes: string[];
12
+ /** Labels (C1, P1…) of the chains it breaks. */
13
+ breaks: string[];
14
+ /** Labels of chains its findings take part in without breaking them. */
15
+ partOf: string[];
16
+ }
17
+ export interface SummaryChain {
18
+ label: string;
19
+ id: string;
20
+ title: string;
21
+ severity: Finding['riskLevel'];
22
+ /** The fix that stops the chain; named chains only. */
23
+ breakPoint?: string;
24
+ steps: number;
25
+ }
26
+ export interface AuditSummary {
27
+ orgId: string;
28
+ orgName: string;
29
+ isSandbox: boolean;
30
+ generatedAt: Date;
31
+ grade: AuditResult['grade'];
32
+ healthScore: number;
33
+ gradeReason?: string;
34
+ coverage?: {
35
+ percent: number;
36
+ checksAssessed: number;
37
+ checksRun: number;
38
+ notAssessed: string[];
39
+ };
40
+ /** Open findings by severity, as page one counts them, plus the other statuses. */
41
+ counts: {
42
+ open: Record<'CRITICAL' | 'HIGH' | 'MEDIUM' | 'LOW', number>;
43
+ info: number;
44
+ waived: number;
45
+ inconclusive: number;
46
+ passed: number;
47
+ };
48
+ /** The plan's conclusion in one sentence, as both reports state it. */
49
+ headline: string;
50
+ actions: SummaryAction[];
51
+ attackChains: SummaryChain[];
52
+ }
53
+ /**
54
+ * Page one of the report as data: grade and why, coverage, the fix-first plan and the attack paths.
55
+ * Smaller than the digest because it lists actions, not findings: each action names the finding ids it
56
+ * closes, and `sf audit explain <id>` gives the rest. Built for agents that triage before they read.
57
+ */
58
+ export declare function buildSummary(result: AuditResult): AuditSummary;
59
+ //# sourceMappingURL=summary.d.ts.map
@@ -0,0 +1,48 @@
1
+ import { findingStatus, openCounts } from './status.js';
2
+ import { buildActionPlan, chainLabels, planHeadline, EFFORT_LABEL, WAVE_LABEL } from '../report/ActionPlan.js';
3
+ /**
4
+ * Page one of the report as data: grade and why, coverage, the fix-first plan and the attack paths.
5
+ * Smaller than the digest because it lists actions, not findings: each action names the finding ids it
6
+ * closes, and `sf audit explain <id>` gives the rest. Built for agents that triage before they read.
7
+ */
8
+ export function buildSummary(result) {
9
+ const chains = result.attackChains ?? [];
10
+ const labels = chainLabels(chains);
11
+ const plan = buildActionPlan(result.findings, chains);
12
+ const open = openCounts(result);
13
+ const tally = (s) => result.findings.filter((f) => findingStatus(f) === s).length;
14
+ const out = {
15
+ orgId: result.orgId,
16
+ orgName: result.orgName,
17
+ isSandbox: result.isSandbox,
18
+ generatedAt: result.generatedAt,
19
+ grade: result.grade,
20
+ healthScore: result.healthScore,
21
+ counts: { open, info: tally('info'), waived: tally('waived'), inconclusive: tally('inconclusive'), passed: tally('passed') },
22
+ headline: planHeadline(plan, chains, open.HIGH),
23
+ actions: plan.map((a, i) => ({
24
+ rank: i + 1,
25
+ wave: WAVE_LABEL[a.wave],
26
+ title: a.title,
27
+ severity: a.severity,
28
+ effort: EFFORT_LABEL[a.effort],
29
+ closes: a.fixes.map((f) => f.id),
30
+ breaks: a.breaks.map((n) => labels[n]),
31
+ partOf: a.inChains.map((n) => labels[n]),
32
+ })),
33
+ attackChains: chains.map((c, i) => {
34
+ const chain = { label: labels[i], id: c.id, title: c.title, severity: c.severity, steps: c.steps.length };
35
+ if (c.abuseCase)
36
+ chain.breakPoint = c.abuseCase.breakPoint;
37
+ return chain;
38
+ }),
39
+ };
40
+ if (result.gradeReason !== undefined)
41
+ out.gradeReason = result.gradeReason;
42
+ if (result.coverage) {
43
+ const { percent, checksAssessed, checksRun, notAssessed } = result.coverage;
44
+ out.coverage = { percent, checksAssessed, checksRun, notAssessed };
45
+ }
46
+ return out;
47
+ }
48
+ //# sourceMappingURL=summary.js.map
@@ -4,7 +4,8 @@ import { renderAttackChainDagSvg } from './AttackChainDagRenderer.js';
4
4
  import { coverageSummary, coverageAdvice } from '../findings/coverage.js';
5
5
  import { techniqueLabel } from '../threats/attack.js';
6
6
  import { unknownMetrics } from '../findings/unknownMetrics.js';
7
- import { buildActionPlan, planHeadline, EFFORT_LABEL, WAVE_LABEL, WAVE_WHY } from '../report/ActionPlan.js';
7
+ import { buildActionPlan, planHeadline, chainLabels, EFFORT_LABEL, WAVE_LABEL, WAVE_WHY } from '../report/ActionPlan.js';
8
+ import { findingStatus, openCounts } from '../findings/status.js';
8
9
  import { DOMAINS, domainOf } from '../checks/domains.js';
9
10
  // The report is printed on white, in the executive report's palette. Every severity colour holds
10
11
  // at least 4.5:1 on white and under white text, so badges and counts stay legible when printed.
@@ -49,11 +50,6 @@ function metricRow(label, value, color, bar) {
49
50
  function inventoryCard(title, rows) {
50
51
  return `<div class="inv-card"><div class="inv-card-title">${esc(title)}</div>${rows.join('')}</div>`;
51
52
  }
52
- /** Open findings per severity: what the score and the executive report count (RULE-079). */
53
- function openCounts(result) {
54
- const open = result.findings.filter((f) => !f.passed && !f.inconclusive && !f.notAssessed && !f.waived);
55
- return Object.fromEntries(['CRITICAL', 'HIGH', 'MEDIUM', 'LOW'].map((l) => [l, open.filter((f) => f.riskLevel === l).length]));
56
- }
57
53
  function buildDashboard(result, counts) {
58
54
  const m = result.metrics;
59
55
  const gradeColor = GRADE_COLOR[result.grade] ?? UNKNOWN_COLOR;
@@ -149,15 +145,7 @@ function buildDashboard(result, counts) {
149
145
  // ── Report structure helpers ─────────────────────────────────────────────────
150
146
  const SEV_ORDER = { CRITICAL: 0, HIGH: 1, MEDIUM: 2, LOW: 3, INFO: 4 };
151
147
  const OTHER_DOMAIN = 'Other checks';
152
- function statusOf(f) {
153
- if (f.passed)
154
- return 'passed';
155
- if (f.inconclusive || f.notAssessed)
156
- return 'inconclusive';
157
- if (f.waived)
158
- return 'waived';
159
- return f.riskLevel === 'INFO' ? 'info' : 'open';
160
- }
148
+ const statusOf = findingStatus;
161
149
  /** Open findings first, worst first; then informational, waived, inconclusive and passed results. */
162
150
  const STATUS_ORDER = { open: 0, info: 1, waived: 2, inconclusive: 3, passed: 4 };
163
151
  function byPriority(a, b) {
@@ -177,11 +165,6 @@ function findingAnchors(findings) {
177
165
  }
178
166
  return out;
179
167
  }
180
- /** Chain labels as the executive report prints them: C1… for named chains, P1… for potential ones. */
181
- function chainLabels(chains) {
182
- let c = 0, p = 0;
183
- return chains.map((ch) => (ch.abuseCase ? `C${++c}` : `P${++p}`));
184
- }
185
168
  const slug = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
186
169
  /** The framework a compliance tag belongs to: 'SOC2-CC6.1' is SOC2; OWASP LLM tags ('LLM02') are one framework. */
187
170
  const frameworkOf = (tag) => (/^LLM\d/.test(tag) ? 'OWASP-LLM' : tag.split(/[-.]/)[0]);
@@ -38,6 +38,8 @@ export interface PlannedAction {
38
38
  * work is wave 3 and the rest wave 2. Within a wave, the most risk removed comes first.
39
39
  */
40
40
  export declare function buildActionPlan(findings: Finding[], chains: AttackChain[]): PlannedAction[];
41
+ /** Chain labels as the executive report prints them: C1… for named chains, P1… for potential ones. */
42
+ export declare function chainLabels(chains: AttackChain[]): string[];
41
43
  /** How long an action takes, in the words both reports print. */
42
44
  export declare const EFFORT_LABEL: {
43
45
  readonly quick: 'Under a day';
@@ -96,6 +96,11 @@ export function buildActionPlan(findings, chains) {
96
96
  }
97
97
  return actions.sort((a, b) => a.wave - b.wave || b.risk - a.risk || a.title.localeCompare(b.title));
98
98
  }
99
+ /** Chain labels as the executive report prints them: C1… for named chains, P1… for potential ones. */
100
+ export function chainLabels(chains) {
101
+ let c = 0, p = 0;
102
+ return chains.map((ch) => (ch.abuseCase ? `C${++c}` : `P${++p}`));
103
+ }
99
104
  /** How long an action takes, in the words both reports print. */
100
105
  export const EFFORT_LABEL = { quick: 'Under a day', moderate: 'Days', project: 'Weeks' };
101
106
  /** When to start each wave. */
@@ -0,0 +1,63 @@
1
+ import { CHECKS } from '../checks/registry.js';
2
+ import type { AuditResult } from '../findings/AuditResult.js';
3
+ import type { Finding } from '../findings/Finding.js';
4
+ import { type FindingStatus } from '../findings/status.js';
5
+ export interface CheckExplanation {
6
+ id: string;
7
+ name: string;
8
+ description: string;
9
+ domain?: string;
10
+ effort?: string;
11
+ impact?: string;
12
+ complianceTags: string[];
13
+ }
14
+ export interface FindingExplanation {
15
+ id: string;
16
+ title: string;
17
+ status: FindingStatus;
18
+ severity: Finding['riskLevel'];
19
+ detail: string;
20
+ remediation: string;
21
+ affectedCount: number;
22
+ affectedSample: string[];
23
+ /** Chains this finding is a step of, with whether fixing it breaks the chain. */
24
+ chains: Array<{
25
+ label: string;
26
+ title: string;
27
+ severity: Finding['riskLevel'];
28
+ breaksChain: boolean;
29
+ }>;
30
+ /** The fix-first action that closes it, if it is open. */
31
+ action?: {
32
+ rank: number;
33
+ wave: string;
34
+ title: string;
35
+ };
36
+ /** Other checks that reported a finding with the same id in this run. */
37
+ alsoFrom?: string[];
38
+ }
39
+ export interface Explanation {
40
+ check: CheckExplanation;
41
+ finding?: FindingExplanation;
42
+ /** With --file and a check id: that check's findings in the run. */
43
+ findings?: Array<{
44
+ id: string;
45
+ title: string;
46
+ status: FindingExplanation['status'];
47
+ severity: Finding['riskLevel'];
48
+ }>;
49
+ }
50
+ /** The check a finding id belongs to: the longest check id it starts with. */
51
+ export declare function checkForFindingId(id: string): (typeof CHECKS)[number] | undefined;
52
+ export declare function parseResult(json: string): AuditResult;
53
+ /** Why an explanation could not be built; the command turns it into a CLI error with this advice. */
54
+ export declare class ExplainError extends Error {
55
+ readonly suggestion: string;
56
+ constructor(message: string, suggestion: string);
57
+ }
58
+ /**
59
+ * Explain a check id, or a finding id from a run. With a run and the check's own id, list that
60
+ * check's findings in the run. Throws ExplainError for an unknown id or a finding not in the run.
61
+ */
62
+ export declare function explain(id: string, result?: AuditResult): Explanation;
63
+ //# sourceMappingURL=explain.d.ts.map
@@ -0,0 +1,102 @@
1
+ import { CHECKS } from '../checks/registry.js';
2
+ import { domainOf } from '../checks/domains.js';
3
+ import { getCheckMeta } from '../findings/CheckMeta.js';
4
+ import { getComplianceTags } from '../compliance/resolve.js';
5
+ import { buildActionPlan, chainLabels, EFFORT_LABEL, WAVE_LABEL } from './ActionPlan.js';
6
+ import { findingStatus } from '../findings/status.js';
7
+ /** How many affected items to show; the report has the rest. */
8
+ const SAMPLE = 5;
9
+ const statusOf = findingStatus;
10
+ /** The check a finding id belongs to: the longest check id it starts with. */
11
+ export function checkForFindingId(id) {
12
+ return CHECKS.filter((c) => id === c.id || id.startsWith(`${c.id}-`)).sort((a, b) => b.id.length - a.id.length)[0];
13
+ }
14
+ export function parseResult(json) {
15
+ const raw = JSON.parse(json);
16
+ const result = (raw.result ?? raw);
17
+ // A --digest result also has findings, but without ids or detail; --summary has none.
18
+ const full = Array.isArray(result.findings) && result.metrics !== undefined && result.findings.every((f) => typeof f.id === 'string' && 'detail' in f);
19
+ if (!full)
20
+ throw new Error('not a full audit result');
21
+ return result;
22
+ }
23
+ /** Why an explanation could not be built; the command turns it into a CLI error with this advice. */
24
+ export class ExplainError extends Error {
25
+ suggestion;
26
+ constructor(message, suggestion) {
27
+ super(message);
28
+ this.suggestion = suggestion;
29
+ }
30
+ }
31
+ /**
32
+ * Explain a check id, or a finding id from a run. With a run and the check's own id, list that
33
+ * check's findings in the run. Throws ExplainError for an unknown id or a finding not in the run.
34
+ */
35
+ export function explain(id, result) {
36
+ // A finding id does not always start with its check's id (apex-no-sharing-declaration is
37
+ // apex-sharing's), so a run's own checkId wins; the prefix is the fallback without one.
38
+ // Finding ids are not unique across checks; explain the first and name the others.
39
+ const matches = result?.findings.filter((f) => f.id === id) ?? [];
40
+ const inRun = matches[0];
41
+ const check = CHECKS.find((c) => c.id === (inRun?.checkId ?? id)) ??
42
+ checkForFindingId(id) ??
43
+ // A finding from an older report whose check has since been renamed or removed.
44
+ (inRun?.checkId ? { id: inRun.checkId, name: inRun.checkId, description: 'This check is not in the installed version of sf-audit.' } : undefined);
45
+ if (!check) {
46
+ throw new ExplainError(`No check or finding id matches '${id}'.`, result ? "Run 'sf audit list' for check ids." : "Run 'sf audit list' for check ids, or pass the run's report with --file to explain a finding.");
47
+ }
48
+ const meta = getCheckMeta(check.id);
49
+ const out = {
50
+ check: {
51
+ id: check.id,
52
+ name: check.name,
53
+ description: check.description,
54
+ domain: domainOf(check.id),
55
+ effort: meta ? EFFORT_LABEL[meta.effort] : undefined,
56
+ impact: meta?.impact,
57
+ complianceTags: getComplianceTags(check.id),
58
+ },
59
+ };
60
+ if (!result)
61
+ return out;
62
+ if (inRun) {
63
+ out.finding = explainFinding(inRun, result);
64
+ const others = matches.slice(1).map((f) => f.checkId).filter((c) => Boolean(c));
65
+ if (others.length > 0)
66
+ out.finding.alsoFrom = others;
67
+ }
68
+ else if (id === check.id) {
69
+ out.findings = result.findings
70
+ .filter((f) => f.checkId === check.id)
71
+ .map((f) => ({ id: f.id, title: f.title, status: statusOf(f), severity: f.riskLevel }));
72
+ }
73
+ else {
74
+ throw new ExplainError(`Finding '${id}' is not in this run.`, `Explain ${check.id} with the same file to list that check's findings.`);
75
+ }
76
+ return out;
77
+ }
78
+ function explainFinding(f, result) {
79
+ const chains = result.attackChains ?? [];
80
+ const labels = chainLabels(chains);
81
+ const plan = buildActionPlan(result.findings, chains);
82
+ const rank = plan.findIndex((a) => a.fixes.some((x) => x.id === f.id && x.checkId === f.checkId));
83
+ const items = f.affectedItems ?? [];
84
+ const out = {
85
+ id: f.id,
86
+ title: f.title,
87
+ status: statusOf(f),
88
+ severity: f.riskLevel,
89
+ detail: f.detail,
90
+ remediation: f.remediation,
91
+ affectedCount: items.length,
92
+ affectedSample: items.slice(0, SAMPLE).map((i) => i.label),
93
+ chains: chains.flatMap((c, i) => {
94
+ const step = c.steps.find((s) => s.findingId === f.id);
95
+ return step ? [{ label: labels[i], title: c.title, severity: c.severity, breaksChain: step.breaksChain === true }] : [];
96
+ }),
97
+ };
98
+ if (rank >= 0)
99
+ out.action = { rank: rank + 1, wave: WAVE_LABEL[plan[rank].wave], title: plan[rank].title };
100
+ return out;
101
+ }
102
+ //# sourceMappingURL=explain.js.map
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cclabsnz/sf-audit",
3
- "version": "1.25.1",
3
+ "version": "1.27.0",
4
4
  "description": "Read-only Salesforce security audit for the sf CLI: 109 checks, attack-chain correlation, A-F risk grading, compliance mapping, free EventLogFile capture, and Guest User Anomaly investigation.",
5
5
  "keywords": [
6
6
  "salesforce",