docs: document security audit helpers

steipete · steipete · commit 0e8c5fd85d20 · 2026-06-04T04:04:43.000-04:00
diff --git a/src/config/plugin-auto-enable.core.test.ts b/src/config/plugin-auto-enable.core.test.ts
@@ -1,3 +1,4 @@
+// Covers core plugin auto-enable behavior and bundled plugin defaults.
 import fs from "node:fs";
 import path from "node:path";
 import { afterAll, afterEach, describe, expect, it, vi } from "vitest";
diff --git a/src/security/audit-channel-test-helpers.ts b/src/security/audit-channel-test-helpers.ts
@@ -1,3 +1,4 @@
+// Provides channel plugin fixtures for security audit tests.
 import type { ChannelPlugin } from "../channels/plugins/types.js";
 import type { OpenClawConfig } from "../config/config.js";
 
diff --git a/src/security/audit-channel.ts b/src/security/audit-channel.ts
@@ -1,3 +1,4 @@
+// Audits channel configuration for exposure, auth, and trust risks.
 import { uniqueStrings } from "@openclaw/normalization-core/string-normalization";
 import {
   hasConfiguredUnavailableCredentialStatus,
diff --git a/src/security/audit-deep-code-safety.ts b/src/security/audit-deep-code-safety.ts
@@ -1,3 +1,4 @@
+// Audits code paths for deep safety risks that require manual review.
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import type { SecurityAuditFinding } from "./audit.types.js";
 
diff --git a/src/security/audit-exec-safe-bins.test.ts b/src/security/audit-exec-safe-bins.test.ts
@@ -1,3 +1,4 @@
+// Covers safe-bin audit decisions for exec commands.
 import { describe, expect, it } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
 import { collectExecRuntimeFindings } from "./audit.js";
diff --git a/src/security/audit-exec-sandbox-host.test.ts b/src/security/audit-exec-sandbox-host.test.ts
@@ -1,3 +1,4 @@
+// Covers exec sandbox host audit findings.
 import { describe, expect, it } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
 import { collectExecRuntimeFindings } from "./audit.js";
diff --git a/src/security/audit-extra.async.test.ts b/src/security/audit-extra.async.test.ts
@@ -1,3 +1,4 @@
+// Covers asynchronous extra security audit checks.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/security/audit-extra.sync.ts b/src/security/audit-extra.sync.ts
@@ -1,3 +1,4 @@
+// Runs synchronous extra security audit checks.
 import {
   normalizeOptionalLowercaseString,
   normalizeOptionalString,
diff --git a/src/security/audit-filesystem-windows.test.ts b/src/security/audit-filesystem-windows.test.ts
@@ -1,3 +1,4 @@
+// Covers Windows filesystem security audit behavior.
 import fs from "node:fs/promises";
 import path from "node:path";
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
diff --git a/src/security/audit-gateway-auth-selection.test.ts b/src/security/audit-gateway-auth-selection.test.ts
@@ -1,3 +1,4 @@
+// Verifies gateway auth selection audit behavior.
 import { describe, expect, it } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
 import { resolveGatewayProbeAuthSafe, resolveGatewayProbeTarget } from "../gateway/probe-auth.js";
diff --git a/src/security/audit-gateway-config.ts b/src/security/audit-gateway-config.ts
@@ -1,3 +1,4 @@
+// Audits gateway config for bind, auth, and exposure risks.
 import { isIP } from "node:net";
 import {
   normalizeLowercaseStringOrEmpty,
diff --git a/src/security/audit-gateway-exposure.test.ts b/src/security/audit-gateway-exposure.test.ts
@@ -1,3 +1,4 @@
+// Covers gateway exposure audit classification.
 import { describe, expect, it } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
 import { collectGatewayConfigFindings } from "./audit-gateway-config.js";
diff --git a/src/security/audit-gateway-tools-http.test.ts b/src/security/audit-gateway-tools-http.test.ts
@@ -1,3 +1,4 @@
+// Verifies gateway tool HTTP exposure audit findings.
 import { describe, expect, it } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
 import { collectGatewayConfigFindings } from "./audit-gateway-config.js";
diff --git a/src/security/audit-node-command-findings.test.ts b/src/security/audit-node-command-findings.test.ts
@@ -1,3 +1,4 @@
+// Verifies node command security audit findings.
 import { describe, expect, it } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
 import {
diff --git a/src/security/audit-plugins-trust.test.ts b/src/security/audit-plugins-trust.test.ts
@@ -1,3 +1,4 @@
+// Covers plugin trust audit findings and remediation hints.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/security/audit-sandbox-browser.test.ts b/src/security/audit-sandbox-browser.test.ts
@@ -1,3 +1,4 @@
+// Covers browser sandbox security audit findings.
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
 import { collectSandboxBrowserHashLabelFindings } from "./audit-extra.async.js";
diff --git a/src/security/audit-trust-model.test.ts b/src/security/audit-trust-model.test.ts
@@ -1,3 +1,4 @@
+// Verifies trust-model audit findings and severity mapping.
 import { describe, expect, it } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
 import {
diff --git a/src/security/context-visibility.test.ts b/src/security/context-visibility.test.ts
@@ -1,3 +1,4 @@
+// Verifies security context visibility decisions.
 import { describe, expect, it } from "vitest";
 import {
   evaluateSupplementalContextVisibility,
diff --git a/src/security/context-visibility.ts b/src/security/context-visibility.ts
@@ -1,3 +1,4 @@
+// Applies security visibility policy to context and account data.
 import type { ContextVisibilityMode } from "../config/types.base.js";
 
 /** Supplemental context classes that can be hidden independently from the main message. */
diff --git a/src/security/core-dangerous-config-flags.ts b/src/security/core-dangerous-config-flags.ts
@@ -1,3 +1,4 @@
+// Detects dangerous core config flags during security audits.
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 
 /** List enabled core config flags that intentionally weaken security posture. */
diff --git a/src/security/exec-filesystem-policy.ts b/src/security/exec-filesystem-policy.ts
@@ -1,3 +1,4 @@
+// Resolves filesystem policy for exec and sandbox tool use.
 import { pickSandboxToolPolicy } from "../agents/sandbox-tool-policy.js";
 import { resolveSandboxConfigForAgent } from "../agents/sandbox/config.js";
 import { resolveSandboxToolPolicyForAgent } from "../agents/sandbox/tool-policy.js";
diff --git a/src/security/fix.test.ts b/src/security/fix.test.ts
@@ -1,3 +1,4 @@
+// Covers security fixer behavior for supported audit findings.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/security/install-policy.ts b/src/security/install-policy.ts
@@ -1,3 +1,4 @@
+// Checks install policy constraints for package and plugin operations.
 import { spawn } from "node:child_process";
 import fs from "node:fs/promises";
 import path from "node:path";
diff --git a/src/security/system-tags.ts b/src/security/system-tags.ts
@@ -1,3 +1,4 @@
+// Detects suspicious system-style tags in external content.
 const BRACKETED_SYSTEM_TAG_RE = /\[\s*(System\s*Message|System|Assistant|Internal)\s*\]/gi;
 const LINE_SYSTEM_PREFIX_RE = /^(\s*)System:(?=\s|$)/gim;
 

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Covers core plugin auto-enable behavior and bundled plugin defaults.`
`1`	`2`	`import fs from "node:fs";`
`2`	`3`	`import path from "node:path";`
`3`	`4`	`import { afterAll, afterEach, describe, expect, it, vi } from "vitest";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Provides channel plugin fixtures for security audit tests.`
`1`	`2`	`import type { ChannelPlugin } from "../channels/plugins/types.js";`
`2`	`3`	`import type { OpenClawConfig } from "../config/config.js";`
`3`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Audits channel configuration for exposure, auth, and trust risks.`
`1`	`2`	`import { uniqueStrings } from "@openclaw/normalization-core/string-normalization";`
`2`	`3`	`import {`
`3`	`4`	`hasConfiguredUnavailableCredentialStatus,`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Audits code paths for deep safety risks that require manual review.`
`1`	`2`	`import type { OpenClawConfig } from "../config/types.openclaw.js";`
`2`	`3`	`import type { SecurityAuditFinding } from "./audit.types.js";`
`3`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Covers safe-bin audit decisions for exec commands.`
`1`	`2`	`import { describe, expect, it } from "vitest";`
`2`	`3`	`import type { OpenClawConfig } from "../config/config.js";`
`3`	`4`	`import { collectExecRuntimeFindings } from "./audit.js";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Covers exec sandbox host audit findings.`
`1`	`2`	`import { describe, expect, it } from "vitest";`
`2`	`3`	`import type { OpenClawConfig } from "../config/config.js";`
`3`	`4`	`import { collectExecRuntimeFindings } from "./audit.js";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Covers asynchronous extra security audit checks.`
`1`	`2`	`import fs from "node:fs/promises";`
`2`	`3`	`import os from "node:os";`
`3`	`4`	`import path from "node:path";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Runs synchronous extra security audit checks.`
`1`	`2`	`import {`
`2`	`3`	`normalizeOptionalLowercaseString,`
`3`	`4`	`normalizeOptionalString,`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Covers Windows filesystem security audit behavior.`
`1`	`2`	`import fs from "node:fs/promises";`
`2`	`3`	`import path from "node:path";`
`3`	`4`	`import { afterAll, beforeAll, describe, expect, it } from "vitest";`
Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// Verifies gateway auth selection audit behavior.`
`1`	`2`	`import { describe, expect, it } from "vitest";`
`2`	`3`	`import type { OpenClawConfig } from "../config/config.js";`
`3`	`4`	`import { resolveGatewayProbeAuthSafe, resolveGatewayProbeTarget } from "../gateway/probe-auth.js";`