@cclabsnz/sf-audit 1.26.0 → 1.28.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.
- package/CHANGELOG.md +74 -0
- package/README.md +15 -3
- package/lib/checks/CheckEngine.js +2 -3
- package/lib/checks/selection.d.ts +13 -0
- package/lib/checks/selection.js +24 -0
- package/lib/commands/audit/explain.d.ts +16 -0
- package/lib/commands/audit/explain.js +79 -0
- package/lib/commands/audit/security.d.ts +4 -2
- package/lib/commands/audit/security.js +22 -2
- package/lib/compliance/catalogs/hiso10029.d.ts +2 -1
- package/lib/compliance/catalogs/hiso10029.js +23 -34
- package/lib/compliance/catalogs/index.js +3 -2
- package/lib/compliance/catalogs/nzism.js +19 -30
- package/lib/compliance/mapping.d.ts +13 -0
- package/lib/compliance/mapping.js +45 -13
- package/lib/compliance/nz/citations.generated.d.ts +45 -0
- package/lib/compliance/nz/citations.generated.js +4752 -0
- package/lib/compliance/nz/types.d.ts +21 -0
- package/lib/compliance/nz/types.js +2 -0
- package/lib/compliance/resolve.js +11 -6
- package/lib/compliance/types.d.ts +1 -1
- package/lib/findings/status.d.ts +8 -0
- package/lib/findings/status.js +20 -0
- package/lib/findings/summary.d.ts +59 -0
- package/lib/findings/summary.js +48 -0
- package/lib/renderers/ClientReportRenderer.js +1 -1
- package/lib/renderers/HtmlRenderer.js +3 -20
- package/lib/report/ActionPlan.d.ts +2 -0
- package/lib/report/ActionPlan.js +5 -0
- package/lib/report/ComplianceMatrix.js +2 -1
- package/lib/report/explain.d.ts +63 -0
- package/lib/report/explain.js +102 -0
- package/package.json +1 -1
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
export type CitationBasis = 'scf' | 'direct';
|
|
2
|
+
export interface HsupCitation {
|
|
3
|
+
id: string;
|
|
4
|
+
basis: CitationBasis;
|
|
5
|
+
reason?: string;
|
|
6
|
+
findings?: string[];
|
|
7
|
+
}
|
|
8
|
+
export interface NzismCitation {
|
|
9
|
+
section: string;
|
|
10
|
+
basis: CitationBasis;
|
|
11
|
+
controls?: string[];
|
|
12
|
+
reason?: string;
|
|
13
|
+
findings?: string[];
|
|
14
|
+
}
|
|
15
|
+
export interface CheckNzCitations {
|
|
16
|
+
scf: string[];
|
|
17
|
+
hsup: HsupCitation[];
|
|
18
|
+
hml: string[];
|
|
19
|
+
nzism: NzismCitation[];
|
|
20
|
+
}
|
|
21
|
+
//# sourceMappingURL=types.d.ts.map
|
|
@@ -2,8 +2,8 @@ import { CHECK_CONTROL_MAP } from './mapping.js';
|
|
|
2
2
|
import { getControl } from './catalogs/index.js';
|
|
3
3
|
const PACKS = {
|
|
4
4
|
universal: ['OWASP', 'OWASP_LLM', 'SOC2', 'ISO27001'],
|
|
5
|
-
nz: ['ISO27001', '
|
|
6
|
-
all: ['OWASP', 'OWASP_LLM', 'SOC2', 'ISO27001', 'SBS', '
|
|
5
|
+
nz: ['ISO27001', 'HISO10029_3', 'HISO10029_4', 'PRIVACY_ACT', 'NZISM'],
|
|
6
|
+
all: ['OWASP', 'OWASP_LLM', 'SOC2', 'ISO27001', 'SBS', 'HISO10029_3', 'HISO10029_4', 'PRIVACY_ACT', 'NZISM', 'HIPAA', 'GDPR'],
|
|
7
7
|
};
|
|
8
8
|
export function packFrameworks(pack) {
|
|
9
9
|
return PACKS[pack];
|
|
@@ -28,10 +28,13 @@ export function resolveControls(checkId, opts = {}) {
|
|
|
28
28
|
export function getComplianceTags(checkId) {
|
|
29
29
|
return CHECK_CONTROL_MAP[checkId] ?? [];
|
|
30
30
|
}
|
|
31
|
+
// `hiso` selects both HISO parts; `hiso-provider` (10029.3, health organisations) and
|
|
32
|
+
// `hiso-supplier` (10029.4, their suppliers) select one. Which applies depends on who owns the org.
|
|
31
33
|
const ALIAS = {
|
|
32
34
|
owasp: 'OWASP', 'owasp-llm': 'OWASP_LLM', llm: 'OWASP_LLM',
|
|
33
35
|
soc2: 'SOC2', iso: 'ISO27001', iso27001: 'ISO27001', sbs: 'SBS',
|
|
34
|
-
privacy: 'PRIVACY_ACT', 'privacy-act': 'PRIVACY_ACT',
|
|
36
|
+
privacy: 'PRIVACY_ACT', 'privacy-act': 'PRIVACY_ACT', nzism: 'NZISM',
|
|
37
|
+
hiso: ['HISO10029_3', 'HISO10029_4'], 'hiso-provider': 'HISO10029_3', 'hiso-supplier': 'HISO10029_4',
|
|
35
38
|
hipaa: 'HIPAA', gdpr: 'GDPR',
|
|
36
39
|
};
|
|
37
40
|
/** Resolve a --frameworks value: a pack name (universal|nz|all) or a comma list of aliases. */
|
|
@@ -41,9 +44,11 @@ export function resolveFrameworks(input) {
|
|
|
41
44
|
return packFrameworks(v);
|
|
42
45
|
const out = [];
|
|
43
46
|
for (const part of v.split(',').map((s) => s.trim())) {
|
|
44
|
-
const
|
|
45
|
-
|
|
46
|
-
out.
|
|
47
|
+
const fws = ALIAS[part];
|
|
48
|
+
for (const fw of fws === undefined ? [] : Array.isArray(fws) ? fws : [fws]) {
|
|
49
|
+
if (!out.includes(fw))
|
|
50
|
+
out.push(fw);
|
|
51
|
+
}
|
|
47
52
|
}
|
|
48
53
|
return out;
|
|
49
54
|
}
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
export type Framework = 'OWASP' | 'OWASP_LLM' | 'SOC2' | 'ISO27001' | 'SBS' | '
|
|
1
|
+
export type Framework = 'OWASP' | 'OWASP_LLM' | 'SOC2' | 'ISO27001' | 'SBS' | 'HISO10029_3' | 'HISO10029_4' | 'PRIVACY_ACT' | 'NZISM' | 'HIPAA' | 'GDPR';
|
|
2
2
|
export interface ControlDef {
|
|
3
3
|
id: string;
|
|
4
4
|
framework: Framework;
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
import type { AuditResult } from './AuditResult.js';
|
|
2
|
+
import type { Finding } from './Finding.js';
|
|
3
|
+
/** What a finding counts as on the report's page one; the HTML report, --summary and explain share it. */
|
|
4
|
+
export type FindingStatus = 'open' | 'info' | 'waived' | 'inconclusive' | 'passed';
|
|
5
|
+
export declare function findingStatus(f: Finding): FindingStatus;
|
|
6
|
+
/** Open findings per severity: what the score and the executive report count (RULE-079). */
|
|
7
|
+
export declare function openCounts(result: AuditResult): Record<'CRITICAL' | 'HIGH' | 'MEDIUM' | 'LOW', number>;
|
|
8
|
+
//# sourceMappingURL=status.d.ts.map
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
export function findingStatus(f) {
|
|
2
|
+
if (f.passed)
|
|
3
|
+
return 'passed';
|
|
4
|
+
if (f.inconclusive || f.notAssessed)
|
|
5
|
+
return 'inconclusive';
|
|
6
|
+
if (f.waived)
|
|
7
|
+
return 'waived';
|
|
8
|
+
return f.riskLevel === 'INFO' ? 'info' : 'open';
|
|
9
|
+
}
|
|
10
|
+
/** Open findings per severity: what the score and the executive report count (RULE-079). */
|
|
11
|
+
export function openCounts(result) {
|
|
12
|
+
const open = result.findings.filter((f) => findingStatus(f) === 'open');
|
|
13
|
+
return {
|
|
14
|
+
CRITICAL: open.filter((f) => f.riskLevel === 'CRITICAL').length,
|
|
15
|
+
HIGH: open.filter((f) => f.riskLevel === 'HIGH').length,
|
|
16
|
+
MEDIUM: open.filter((f) => f.riskLevel === 'MEDIUM').length,
|
|
17
|
+
LOW: open.filter((f) => f.riskLevel === 'LOW').length,
|
|
18
|
+
};
|
|
19
|
+
}
|
|
20
|
+
//# sourceMappingURL=status.js.map
|
|
@@ -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
|
|
@@ -32,7 +32,7 @@ const TACTIC_SHORT = {
|
|
|
32
32
|
const FRAMEWORK_LABEL = {
|
|
33
33
|
OWASP: 'OWASP Top 10', OWASP_LLM: 'OWASP LLM Top 10', SOC2: 'SOC 2', ISO27001: 'ISO/IEC 27001',
|
|
34
34
|
SBS: 'Security Benchmark for Salesforce', PRIVACY_ACT: 'NZ Privacy Act',
|
|
35
|
-
|
|
35
|
+
HISO10029_3: 'HISO 10029.3 (providers)', HISO10029_4: 'HISO 10029.4 (suppliers)', NZISM: 'NZISM', HIPAA: 'HIPAA', GDPR: 'GDPR',
|
|
36
36
|
};
|
|
37
37
|
/** The grade's reason in words: "F: 7 CRITICAL (4 findings, 3 attack chains) (D allows none)" reads as a sentence. */
|
|
38
38
|
function gradeInWords(grade, reason) {
|
|
@@ -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
|
-
|
|
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';
|
package/lib/report/ActionPlan.js
CHANGED
|
@@ -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. */
|
|
@@ -23,7 +23,8 @@ export function buildComplianceMatrix(result, frameworks) {
|
|
|
23
23
|
for (const f of active) {
|
|
24
24
|
if (!f.checkId)
|
|
25
25
|
continue;
|
|
26
|
-
|
|
26
|
+
// Per-finding tags: HISO 10029 and NZISM citations can be scoped to some of a check's findings.
|
|
27
|
+
for (const id of f.complianceTags ?? CHECK_CONTROL_MAP[f.checkId] ?? []) {
|
|
27
28
|
if (hits.has(id))
|
|
28
29
|
hits.get(id).push(f);
|
|
29
30
|
}
|
|
@@ -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.
|
|
3
|
+
"version": "1.28.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",
|