@cclabsnz/sf-audit 1.9.0 → 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.
- package/CHANGELOG.md +22 -0
- package/README.md +9 -1
- package/lib/commands/audit/preflight.d.ts +13 -0
- package/lib/commands/audit/preflight.js +56 -0
- package/lib/commands/audit/security.d.ts +4 -2
- package/lib/commands/audit/security.js +8 -1
- package/lib/findings/digest.d.ts +50 -0
- package/lib/findings/digest.js +56 -0
- package/lib/preflight/permissionMap.d.ts +47 -0
- package/lib/preflight/permissionMap.js +84 -0
- package/lib/preflight/readPermissions.d.ts +11 -0
- package/lib/preflight/readPermissions.js +20 -0
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -11,6 +11,28 @@ published note and carries the signed provenance attestation and CycloneDX SBOM
|
|
|
11
11
|
|
|
12
12
|
Merged to `main`, not yet released.
|
|
13
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
|
+
|
|
14
36
|
## [v1.9.0](https://github.com/cclabsnz/sf-audit-plugin/releases/tag/v1.9.0) — 2026-09-07
|
|
15
37
|
|
|
16
38
|
Two compliance catalogs, three attack chains, and a restructured documentation set — but
|
package/README.md
CHANGED
|
@@ -52,6 +52,7 @@ check id.
|
|
|
52
52
|
| `--format` / `-f` | `html` | `html`, `md`, `json`, `executive` — comma-separated |
|
|
53
53
|
| `--fail-on` | (none) | Exit 1 if any finding is at or above `CRITICAL`/`HIGH`/`MEDIUM`/`LOW`. For CI |
|
|
54
54
|
| `--fail-on-inconclusive` | `false` | Exit 3 if any check could not gather evidence. For CI |
|
|
55
|
+
| `--digest` | `false` | Compact result for programmatic callers — no passing checks, no prose, capped lists |
|
|
55
56
|
| `--checks` | *(all)* | Run only these check ids |
|
|
56
57
|
| `--frameworks` | `universal` | Compliance matrix scope for the executive report |
|
|
57
58
|
|
|
@@ -65,8 +66,14 @@ sf audit security --target-org myOrg --fail-on HIGH --fail-on-inconclusive
|
|
|
65
66
|
# Branded, client-ready PDF-able report
|
|
66
67
|
sf audit security --target-org myOrg --format executive --prepared-for "Acme Health"
|
|
67
68
|
|
|
69
|
+
# What can this audit user actually establish? Ask before spending a run
|
|
70
|
+
sf audit preflight --target-org myOrg
|
|
71
|
+
|
|
68
72
|
# Machine-readable: result on stdout, progress logging suppressed
|
|
69
73
|
sf audit security --target-org myOrg --json
|
|
74
|
+
|
|
75
|
+
# Compact result for an agent or script
|
|
76
|
+
sf audit security --target-org myOrg --json --digest
|
|
70
77
|
```
|
|
71
78
|
|
|
72
79
|
### Exit codes
|
|
@@ -196,7 +203,7 @@ Grade bands, the full config shape and worked examples: **[docs/SCORING.md](docs
|
|
|
196
203
|
|
|
197
204
|
## Other commands
|
|
198
205
|
|
|
199
|
-
Beyond the audit itself, the plugin ships
|
|
206
|
+
Beyond the audit itself, the plugin ships five commands. Each is documented in
|
|
200
207
|
**[docs/COMMANDS.md](docs/COMMANDS.md)**.
|
|
201
208
|
|
|
202
209
|
| Command | What it does |
|
|
@@ -204,6 +211,7 @@ Beyond the audit itself, the plugin ships four commands. Each is documented in
|
|
|
204
211
|
| `sf audit history` / `sf audit diff` | Every run auto-archives to `~/.sf/audit-history/{orgId}`. Show posture drift across runs as a table plus an HTML timeline, or diff any two report JSONs |
|
|
205
212
|
| `sf audit events pull` | Capture the org's **free** daily `EventLogFile` logs to local disk before the ~1-day retention window drops them — no Event Monitoring / Shield add-on needed. Idempotent, safe to cron |
|
|
206
213
|
| `sf audit timeline` | Reconstruct one actor's activity across every captured event type, entirely offline. Refuses to expand a shared identity or join on a blank field, and always reports capture coverage first |
|
|
214
|
+
| `sf audit preflight` | Read the running user's effective permissions in one query and report which checks will produce a verdict and which will return inconclusive — **before** an audit is run |
|
|
207
215
|
| `sf audit apps` | Read the `RestApi` event log to compare what each connected app actually *uses* against what its run-as user is *granted*, and emit a suggested least-privilege permission set |
|
|
208
216
|
|
|
209
217
|
To triage captured logs for abuse patterns, pair `events pull` with the companion CLI
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
import { SfCommand } from '@salesforce/sf-plugins-core';
|
|
2
|
+
import { type PreflightResult } from '../../preflight/permissionMap.js';
|
|
3
|
+
export default class AuditPreflightCommand extends SfCommand<PreflightResult> {
|
|
4
|
+
static summary: string;
|
|
5
|
+
static description: string;
|
|
6
|
+
static examples: string[];
|
|
7
|
+
static flags: {
|
|
8
|
+
'target-org': import("@oclif/core/interfaces").OptionFlag<import("@salesforce/core").Org, import("@oclif/core/interfaces").CustomOptions>;
|
|
9
|
+
};
|
|
10
|
+
run(): Promise<PreflightResult>;
|
|
11
|
+
private printPreflight;
|
|
12
|
+
}
|
|
13
|
+
//# sourceMappingURL=preflight.d.ts.map
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
import { SfCommand, Flags } from '@salesforce/sf-plugins-core';
|
|
2
|
+
import { CHECKS } from '../../checks/registry.js';
|
|
3
|
+
import { buildPreflight } from '../../preflight/permissionMap.js';
|
|
4
|
+
import { readEffectivePermissions } from '../../preflight/readPermissions.js';
|
|
5
|
+
import { buildApiClients } from '../../lib/wire.js';
|
|
6
|
+
export default class AuditPreflightCommand extends SfCommand {
|
|
7
|
+
static summary = 'Report what this audit user will and will not be able to establish';
|
|
8
|
+
static description = "Reads the running user's effective permissions in a single query and reports which checks will " +
|
|
9
|
+
'produce a verdict and which will return inconclusive, before an audit is run. The audit itself can ' +
|
|
10
|
+
'only report a permission gap after it has already come back blind; this answers the same question ' +
|
|
11
|
+
'up front, while it is still cheap to fix. Read-only, and opens no more than one query.';
|
|
12
|
+
static examples = [
|
|
13
|
+
'<%= config.bin %> <%= command.id %> --target-org myOrg',
|
|
14
|
+
'<%= config.bin %> <%= command.id %> --target-org myOrg --json',
|
|
15
|
+
];
|
|
16
|
+
static flags = {
|
|
17
|
+
'target-org': Flags.requiredOrg(),
|
|
18
|
+
};
|
|
19
|
+
async run() {
|
|
20
|
+
const { flags } = await this.parse(AuditPreflightCommand);
|
|
21
|
+
const conn = flags['target-org'].getConnection();
|
|
22
|
+
const { soql } = buildApiClients(conn);
|
|
23
|
+
const granted = await readEffectivePermissions(soql);
|
|
24
|
+
const preflight = buildPreflight(granted, CHECKS);
|
|
25
|
+
this.printPreflight(preflight);
|
|
26
|
+
return preflight;
|
|
27
|
+
}
|
|
28
|
+
printPreflight(p) {
|
|
29
|
+
this.log('');
|
|
30
|
+
if (p.missing.length === 0) {
|
|
31
|
+
this.log(` All ${CHECKS.length} checks can gather evidence. Nothing to grant.`);
|
|
32
|
+
this.log('');
|
|
33
|
+
return;
|
|
34
|
+
}
|
|
35
|
+
this.log(` ${p.willRun} of ${CHECKS.length} checks can gather evidence.`);
|
|
36
|
+
if (p.willBeInconclusive.length > 0) {
|
|
37
|
+
this.log(` ${p.willBeInconclusive.length} will return inconclusive as things stand.`);
|
|
38
|
+
}
|
|
39
|
+
this.log('');
|
|
40
|
+
this.log(' Missing permissions');
|
|
41
|
+
this.log(' ───────────────────');
|
|
42
|
+
for (const m of p.missing) {
|
|
43
|
+
this.log(` ${m.blocking ? '[blocking] ' : ''}${m.label} (${m.permission})`);
|
|
44
|
+
this.log(` ${m.impact}`);
|
|
45
|
+
if (m.affectedChecks.length > 0) {
|
|
46
|
+
this.log(` Affects ${m.affectedChecks.length} check${m.affectedChecks.length !== 1 ? 's' : ''}: ${m.affectedChecks.join(', ')}`);
|
|
47
|
+
}
|
|
48
|
+
this.log('');
|
|
49
|
+
}
|
|
50
|
+
if (!p.canRun) {
|
|
51
|
+
this.log(' The audit cannot run at all until the blocking permission is granted.');
|
|
52
|
+
this.log('');
|
|
53
|
+
}
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
//# sourceMappingURL=preflight.js.map
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import { SfCommand } from '@salesforce/sf-plugins-core';
|
|
2
2
|
import type { AuditResult } from '../../findings/AuditResult.js';
|
|
3
|
-
|
|
3
|
+
import { type AuditDigest } from '../../findings/digest.js';
|
|
4
|
+
export default class SecurityAuditCommand extends SfCommand<AuditResult | AuditDigest> {
|
|
4
5
|
static summary: string;
|
|
5
6
|
static description: string;
|
|
6
7
|
static examples: string[];
|
|
@@ -9,6 +10,7 @@ export default class SecurityAuditCommand extends SfCommand<AuditResult> {
|
|
|
9
10
|
format: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
|
|
10
11
|
output: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
|
|
11
12
|
'fail-on': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
|
|
13
|
+
digest: import("@oclif/core/interfaces").BooleanFlag<boolean>;
|
|
12
14
|
'fail-on-inconclusive': import("@oclif/core/interfaces").BooleanFlag<boolean>;
|
|
13
15
|
checks: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
|
|
14
16
|
'scoring-config': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
|
|
@@ -18,7 +20,7 @@ export default class SecurityAuditCommand extends SfCommand<AuditResult> {
|
|
|
18
20
|
frameworks: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
|
|
19
21
|
'resolve-domains': import("@oclif/core/interfaces").BooleanFlag<boolean>;
|
|
20
22
|
};
|
|
21
|
-
run(): Promise<AuditResult>;
|
|
23
|
+
run(): Promise<AuditResult | AuditDigest>;
|
|
22
24
|
/** Resolve --checks to the checks to run, erroring on any unknown ID. */
|
|
23
25
|
private resolveChecks;
|
|
24
26
|
/** Resolve --format to a validated list, erroring on any unknown format. */
|
|
@@ -13,6 +13,7 @@ import { buildAuditContext, resolveOrgInfo } from '../../lib/wire.js';
|
|
|
13
13
|
import { loadScoringConfig } from '../../findings/loadScoringConfig.js';
|
|
14
14
|
import { HistoryStore } from '../../history/HistoryStore.js';
|
|
15
15
|
import { EXIT_FINDINGS, EXIT_INCONCLUSIVE, resolveExitCode, violationsFor } from '../../findings/exitCode.js';
|
|
16
|
+
import { buildDigest } from '../../findings/digest.js';
|
|
16
17
|
const RENDERERS = {
|
|
17
18
|
html: new HtmlRenderer(),
|
|
18
19
|
md: new MarkdownRenderer(),
|
|
@@ -42,6 +43,10 @@ export default class SecurityAuditCommand extends SfCommand {
|
|
|
42
43
|
summary: 'Exit with code 1 if any finding is at or above this severity.',
|
|
43
44
|
options: ['CRITICAL', 'HIGH', 'MEDIUM', 'LOW'],
|
|
44
45
|
}),
|
|
46
|
+
digest: Flags.boolean({
|
|
47
|
+
summary: 'Return a compact, token-cheap result: no passing checks, no detail prose, capped affected lists.',
|
|
48
|
+
default: false,
|
|
49
|
+
}),
|
|
45
50
|
'fail-on-inconclusive': Flags.boolean({
|
|
46
51
|
summary: 'Exit with code 3 if any check could not gather evidence. Off by default.',
|
|
47
52
|
default: false,
|
|
@@ -114,8 +119,10 @@ export default class SecurityAuditCommand extends SfCommand {
|
|
|
114
119
|
this.printSummary(result);
|
|
115
120
|
this.log('');
|
|
116
121
|
this.log(' Deep dives: https://softwareinsights.dev · Remediation help: https://cloudcounsel.co.nz');
|
|
122
|
+
// Exit code is resolved from the full result: the digest drops passing checks,
|
|
123
|
+
// which the threshold logic must still be able to see and discount.
|
|
117
124
|
this.applyExitCode(result, flags['fail-on'], flags['fail-on-inconclusive']);
|
|
118
|
-
return result;
|
|
125
|
+
return flags.digest ? buildDigest(result) : result;
|
|
119
126
|
}
|
|
120
127
|
/** Resolve --checks to the checks to run, erroring on any unknown ID. */
|
|
121
128
|
resolveChecks(raw) {
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
import type { RiskLevel } from '@cclabsnz/sf-core';
|
|
2
|
+
import type { AttackChain } from '../chains/AttackChain.js';
|
|
3
|
+
import type { AuditResult } from './AuditResult.js';
|
|
4
|
+
export interface DigestFinding {
|
|
5
|
+
checkId?: string;
|
|
6
|
+
riskLevel: RiskLevel;
|
|
7
|
+
title: string;
|
|
8
|
+
remediation: string;
|
|
9
|
+
complianceTags?: string[];
|
|
10
|
+
/** Total affected items. Present only when the finding named any. */
|
|
11
|
+
affectedCount?: number;
|
|
12
|
+
/** First few affected labels, for orientation. Never the whole list. */
|
|
13
|
+
affectedSample?: string[];
|
|
14
|
+
}
|
|
15
|
+
export interface DigestInconclusive {
|
|
16
|
+
checkId?: string;
|
|
17
|
+
title: string;
|
|
18
|
+
}
|
|
19
|
+
export interface DigestCounts {
|
|
20
|
+
critical: number;
|
|
21
|
+
high: number;
|
|
22
|
+
medium: number;
|
|
23
|
+
low: number;
|
|
24
|
+
info: number;
|
|
25
|
+
passed: number;
|
|
26
|
+
inconclusive: number;
|
|
27
|
+
}
|
|
28
|
+
export interface AuditDigest {
|
|
29
|
+
orgId: string;
|
|
30
|
+
orgName: string;
|
|
31
|
+
isSandbox: boolean;
|
|
32
|
+
generatedAt: Date;
|
|
33
|
+
healthScore: number;
|
|
34
|
+
grade: AuditResult['grade'];
|
|
35
|
+
counts: DigestCounts;
|
|
36
|
+
findings: DigestFinding[];
|
|
37
|
+
inconclusive: DigestInconclusive[];
|
|
38
|
+
attackChains: AttackChain[];
|
|
39
|
+
}
|
|
40
|
+
/**
|
|
41
|
+
* A token-cheap view of an audit, for callers that reason over the result rather
|
|
42
|
+
* than read it.
|
|
43
|
+
*
|
|
44
|
+
* Passing checks are counted but not listed, `detail` prose is dropped in favour of
|
|
45
|
+
* `remediation`, and affected-item lists — which are unbounded and dominate a large
|
|
46
|
+
* org's report — collapse to a count plus a short sample. Attack chains survive
|
|
47
|
+
* intact: there are few of them and they carry the analysis.
|
|
48
|
+
*/
|
|
49
|
+
export declare function buildDigest(result: AuditResult): AuditDigest;
|
|
50
|
+
//# sourceMappingURL=digest.d.ts.map
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
/** How many affected-item labels to keep before falling back to a bare count. */
|
|
2
|
+
const SAMPLE_LIMIT = 3;
|
|
3
|
+
const isActive = (f) => f.passed !== true && f.inconclusive !== true;
|
|
4
|
+
function toDigestFinding(f) {
|
|
5
|
+
const out = {
|
|
6
|
+
checkId: f.checkId,
|
|
7
|
+
riskLevel: f.riskLevel,
|
|
8
|
+
title: f.title,
|
|
9
|
+
remediation: f.remediation,
|
|
10
|
+
};
|
|
11
|
+
if (f.complianceTags !== undefined)
|
|
12
|
+
out.complianceTags = f.complianceTags;
|
|
13
|
+
if (f.affectedItems !== undefined && f.affectedItems.length > 0) {
|
|
14
|
+
out.affectedCount = f.affectedItems.length;
|
|
15
|
+
out.affectedSample = f.affectedItems.slice(0, SAMPLE_LIMIT).map((i) => i.label);
|
|
16
|
+
}
|
|
17
|
+
return out;
|
|
18
|
+
}
|
|
19
|
+
function countBy(findings) {
|
|
20
|
+
const counts = { critical: 0, high: 0, medium: 0, low: 0, info: 0, passed: 0, inconclusive: 0 };
|
|
21
|
+
for (const f of findings) {
|
|
22
|
+
if (f.passed === true)
|
|
23
|
+
counts.passed += 1;
|
|
24
|
+
else if (f.inconclusive === true)
|
|
25
|
+
counts.inconclusive += 1;
|
|
26
|
+
else
|
|
27
|
+
counts[f.riskLevel.toLowerCase()] += 1;
|
|
28
|
+
}
|
|
29
|
+
return counts;
|
|
30
|
+
}
|
|
31
|
+
/**
|
|
32
|
+
* A token-cheap view of an audit, for callers that reason over the result rather
|
|
33
|
+
* than read it.
|
|
34
|
+
*
|
|
35
|
+
* Passing checks are counted but not listed, `detail` prose is dropped in favour of
|
|
36
|
+
* `remediation`, and affected-item lists — which are unbounded and dominate a large
|
|
37
|
+
* org's report — collapse to a count plus a short sample. Attack chains survive
|
|
38
|
+
* intact: there are few of them and they carry the analysis.
|
|
39
|
+
*/
|
|
40
|
+
export function buildDigest(result) {
|
|
41
|
+
return {
|
|
42
|
+
orgId: result.orgId,
|
|
43
|
+
orgName: result.orgName,
|
|
44
|
+
isSandbox: result.isSandbox,
|
|
45
|
+
generatedAt: result.generatedAt,
|
|
46
|
+
healthScore: result.healthScore,
|
|
47
|
+
grade: result.grade,
|
|
48
|
+
counts: countBy(result.findings),
|
|
49
|
+
findings: result.findings.filter(isActive).map(toDigestFinding),
|
|
50
|
+
inconclusive: result.findings
|
|
51
|
+
.filter((f) => f.inconclusive === true)
|
|
52
|
+
.map((f) => ({ checkId: f.checkId, title: f.title })),
|
|
53
|
+
attackChains: result.attackChains ?? [],
|
|
54
|
+
};
|
|
55
|
+
}
|
|
56
|
+
//# sourceMappingURL=digest.js.map
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
import type { AuditCache } from '@cclabsnz/sf-core';
|
|
2
|
+
import type { SecurityCheck } from '../checks/SecurityCheck.js';
|
|
3
|
+
export type AuditPermission = 'ApiEnabled' | 'ViewSetup' | 'ViewAllUsers' | 'ViewHealthCheckScreen' | 'AuthorApex' | 'ViewEventLogFiles';
|
|
4
|
+
export interface PermissionSpec {
|
|
5
|
+
/** Field on UserPermissionAccess carrying the effective grant. */
|
|
6
|
+
readonly field: string;
|
|
7
|
+
readonly label: string;
|
|
8
|
+
/** What the audit loses without it. */
|
|
9
|
+
readonly impact: string;
|
|
10
|
+
/**
|
|
11
|
+
* Cache keys whose producers and consumers need this permission. The affected
|
|
12
|
+
* check list is derived from the registry via these keys rather than hand-written,
|
|
13
|
+
* so a check added later is covered without touching this file.
|
|
14
|
+
*
|
|
15
|
+
* Empty for permissions too broad to attribute to specific checks.
|
|
16
|
+
*/
|
|
17
|
+
readonly cacheKeys: ReadonlyArray<keyof AuditCache>;
|
|
18
|
+
/** The audit cannot run at all without this. */
|
|
19
|
+
readonly blocking?: boolean;
|
|
20
|
+
}
|
|
21
|
+
export declare const AUDIT_PERMISSIONS: Readonly<Record<AuditPermission, PermissionSpec>>;
|
|
22
|
+
export interface MissingPermission {
|
|
23
|
+
permission: AuditPermission;
|
|
24
|
+
label: string;
|
|
25
|
+
impact: string;
|
|
26
|
+
blocking: boolean;
|
|
27
|
+
affectedChecks: string[];
|
|
28
|
+
}
|
|
29
|
+
export interface PreflightResult {
|
|
30
|
+
canRun: boolean;
|
|
31
|
+
granted: AuditPermission[];
|
|
32
|
+
missing: MissingPermission[];
|
|
33
|
+
/** Checks expected to produce a verdict. */
|
|
34
|
+
willRun: number;
|
|
35
|
+
/** Checks expected to return inconclusive, deduplicated across permissions. */
|
|
36
|
+
willBeInconclusive: string[];
|
|
37
|
+
}
|
|
38
|
+
/** Check ids that need `permission`, derived from the registry's declared cache wiring. */
|
|
39
|
+
export declare function checksRequiring(permission: AuditPermission, checks?: readonly SecurityCheck[]): string[];
|
|
40
|
+
/**
|
|
41
|
+
* What this audit user will and will not be able to establish, before spending a run.
|
|
42
|
+
*
|
|
43
|
+
* The tool can only report a permission gap after the audit has already come back
|
|
44
|
+
* blind; this answers the same question up front, when it is still cheap to fix.
|
|
45
|
+
*/
|
|
46
|
+
export declare function buildPreflight(granted: Record<AuditPermission, boolean>, checks?: readonly SecurityCheck[]): PreflightResult;
|
|
47
|
+
//# sourceMappingURL=permissionMap.d.ts.map
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
import { CHECKS } from '../checks/registry.js';
|
|
2
|
+
export const AUDIT_PERMISSIONS = {
|
|
3
|
+
ApiEnabled: {
|
|
4
|
+
field: 'PermissionsApiEnabled',
|
|
5
|
+
label: 'API Enabled',
|
|
6
|
+
impact: 'All access is via SOQL/Tooling/REST. Without it the audit cannot run at all.',
|
|
7
|
+
cacheKeys: [],
|
|
8
|
+
blocking: true,
|
|
9
|
+
},
|
|
10
|
+
ViewSetup: {
|
|
11
|
+
field: 'PermissionsViewSetup',
|
|
12
|
+
label: 'View Setup and Configuration',
|
|
13
|
+
impact: 'Reads the bulk of the surface — connected apps, remote sites, CSP, named credentials, auth config, ' +
|
|
14
|
+
'Experience sites, and Tooling metadata. Most setup and configuration checks return inconclusive without it.',
|
|
15
|
+
cacheKeys: [],
|
|
16
|
+
},
|
|
17
|
+
ViewAllUsers: {
|
|
18
|
+
field: 'PermissionsViewAllUsers',
|
|
19
|
+
label: 'View All Users',
|
|
20
|
+
impact: 'Enumerates every User, PermissionSetAssignment and TwoFactorInfo org-wide. Without it the user, ' +
|
|
21
|
+
'admin and MFA checks under-count and miss accounts outside the role hierarchy.',
|
|
22
|
+
cacheKeys: ['mfaRegistrations', 'effectivePermissions'],
|
|
23
|
+
},
|
|
24
|
+
ViewHealthCheckScreen: {
|
|
25
|
+
field: 'PermissionsViewHealthCheck',
|
|
26
|
+
label: 'View Health Check',
|
|
27
|
+
impact: 'Reads SecurityHealthCheck and its risks. Health Check and password/session baselines are inconclusive without it.',
|
|
28
|
+
cacheKeys: ['healthCheckRisks'],
|
|
29
|
+
},
|
|
30
|
+
AuthorApex: {
|
|
31
|
+
field: 'PermissionsAuthorApex',
|
|
32
|
+
label: 'Author Apex (read-only use)',
|
|
33
|
+
impact: 'The only standard gate exposing ApexClass/ApexTrigger/ApexPage Body via the Tooling API. ' +
|
|
34
|
+
'Grants no ability to modify org data. The code-security checks are inconclusive without it.',
|
|
35
|
+
cacheKeys: ['apexBodies', 'vfPageBodies'],
|
|
36
|
+
},
|
|
37
|
+
ViewEventLogFiles: {
|
|
38
|
+
field: 'PermissionsViewEventLogFiles',
|
|
39
|
+
label: 'View Event Log Files',
|
|
40
|
+
impact: 'Reads EventLogFile. Whether login and API activity is monitored cannot be established without it.',
|
|
41
|
+
cacheKeys: ['eventLogSummary'],
|
|
42
|
+
},
|
|
43
|
+
};
|
|
44
|
+
const usesKey = (check, key) => (check.dependsOnCache?.includes(key) ?? false) || (check.populatesCache?.includes(key) ?? false);
|
|
45
|
+
/** Check ids that need `permission`, derived from the registry's declared cache wiring. */
|
|
46
|
+
export function checksRequiring(permission, checks = CHECKS) {
|
|
47
|
+
const { cacheKeys } = AUDIT_PERMISSIONS[permission];
|
|
48
|
+
if (cacheKeys.length === 0)
|
|
49
|
+
return [];
|
|
50
|
+
return checks.filter((c) => cacheKeys.some((k) => usesKey(c, k))).map((c) => c.id);
|
|
51
|
+
}
|
|
52
|
+
/**
|
|
53
|
+
* What this audit user will and will not be able to establish, before spending a run.
|
|
54
|
+
*
|
|
55
|
+
* The tool can only report a permission gap after the audit has already come back
|
|
56
|
+
* blind; this answers the same question up front, when it is still cheap to fix.
|
|
57
|
+
*/
|
|
58
|
+
export function buildPreflight(granted, checks = CHECKS) {
|
|
59
|
+
const permissions = Object.keys(AUDIT_PERMISSIONS);
|
|
60
|
+
const missing = [];
|
|
61
|
+
const inconclusive = new Set();
|
|
62
|
+
for (const permission of permissions) {
|
|
63
|
+
if (granted[permission])
|
|
64
|
+
continue;
|
|
65
|
+
const spec = AUDIT_PERMISSIONS[permission];
|
|
66
|
+
const affectedChecks = checksRequiring(permission, checks);
|
|
67
|
+
affectedChecks.forEach((id) => inconclusive.add(id));
|
|
68
|
+
missing.push({
|
|
69
|
+
permission,
|
|
70
|
+
label: spec.label,
|
|
71
|
+
impact: spec.impact,
|
|
72
|
+
blocking: spec.blocking === true,
|
|
73
|
+
affectedChecks,
|
|
74
|
+
});
|
|
75
|
+
}
|
|
76
|
+
return {
|
|
77
|
+
canRun: !missing.some((m) => m.blocking),
|
|
78
|
+
granted: permissions.filter((p) => granted[p]),
|
|
79
|
+
missing,
|
|
80
|
+
willRun: checks.length - inconclusive.size,
|
|
81
|
+
willBeInconclusive: [...inconclusive],
|
|
82
|
+
};
|
|
83
|
+
}
|
|
84
|
+
//# sourceMappingURL=permissionMap.js.map
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
import type { SoqlClient } from '@cclabsnz/sf-core';
|
|
2
|
+
import { type AuditPermission } from './permissionMap.js';
|
|
3
|
+
/**
|
|
4
|
+
* The running user's *effective* permissions — profile unioned with every assigned
|
|
5
|
+
* permission set — in one read.
|
|
6
|
+
*
|
|
7
|
+
* UserPermissionAccess returns exactly one row scoped to the caller, so this needs no
|
|
8
|
+
* assignment join and no aggregation. Read-only, like everything else here.
|
|
9
|
+
*/
|
|
10
|
+
export declare function readEffectivePermissions(soql: SoqlClient): Promise<Record<AuditPermission, boolean>>;
|
|
11
|
+
//# sourceMappingURL=readPermissions.d.ts.map
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
import { AUDIT_PERMISSIONS } from './permissionMap.js';
|
|
2
|
+
/**
|
|
3
|
+
* The running user's *effective* permissions — profile unioned with every assigned
|
|
4
|
+
* permission set — in one read.
|
|
5
|
+
*
|
|
6
|
+
* UserPermissionAccess returns exactly one row scoped to the caller, so this needs no
|
|
7
|
+
* assignment join and no aggregation. Read-only, like everything else here.
|
|
8
|
+
*/
|
|
9
|
+
export async function readEffectivePermissions(soql) {
|
|
10
|
+
const permissions = Object.keys(AUDIT_PERMISSIONS);
|
|
11
|
+
const fields = permissions.map((p) => AUDIT_PERMISSIONS[p].field);
|
|
12
|
+
const result = await soql.query(`SELECT ${fields.join(', ')} FROM UserPermissionAccess`);
|
|
13
|
+
const row = result.records[0] ?? {};
|
|
14
|
+
const granted = {};
|
|
15
|
+
for (const permission of permissions) {
|
|
16
|
+
granted[permission] = row[AUDIT_PERMISSIONS[permission].field] === true;
|
|
17
|
+
}
|
|
18
|
+
return granted;
|
|
19
|
+
}
|
|
20
|
+
//# sourceMappingURL=readPermissions.js.map
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@cclabsnz/sf-audit",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.10.0",
|
|
4
4
|
"description": "Read-only Salesforce security audit for the sf CLI: 88 checks, attack-chain correlation, A-F risk grading, and compliance mapping to OWASP, SOC 2, ISO 27001, NZISM and more.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"salesforce",
|