docs: document security finding helpers

src/security/audit-channel-account-metadata.test.ts

@@ -1,3 +1,4 @@
+// Covers channel account metadata security audit findings.
 import { describe, expect, it } from "vitest";
 import type { ChannelPlugin } from "../channels/plugins/types.js";
 import type { OpenClawConfig } from "../config/config.js";

src/security/audit-channel-readonly-resolution.test.ts

@@ -1,3 +1,4 @@
+// Verifies readonly channel audit resolution behavior.
 import { describe, expect, it } from "vitest";
 import type { ChannelPlugin } from "../channels/plugins/types.js";
 import type { OpenClawConfig } from "../config/config.js";

src/security/audit-channel-readonly-setup-fallback.test.ts

@@ -1,3 +1,4 @@
+// Covers channel readonly setup fallback audit behavior.
 import { describe, expect, it, vi } from "vitest";
 import type { ChannelPlugin } from "../channels/plugins/types.plugin.js";
 import type { OpenClawConfig } from "../config/config.js";

src/security/audit-channel.collect.runtime.ts

@@ -1,3 +1,4 @@
+// Runtime boundary for collecting channel security audit findings.
 import { collectChannelSecurityFindings as collectChannelSecurityFindingsImpl } from "./audit-channel.js";
 
 type CollectChannelSecurityFindings =

src/security/audit-config-include-perms.test.ts

@@ -1,3 +1,4 @@
+// Covers config include-file permission audit findings.
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";

src/security/audit-config-symlink.test.ts

@@ -1,3 +1,4 @@
+// Verifies config symlink security audit findings.
 import fs from "node:fs/promises";
 import path from "node:path";
 import { afterAll, beforeAll, describe, expect, it } from "vitest";

src/security/audit-extra.summary.ts

@@ -1,3 +1,4 @@
+// Summarizes extra security audit findings for user-facing output.
 import { resolveProviderToolPolicy } from "../agents/agent-tools.policy.js";
 import { parseModelRef } from "../agents/model-selection-normalize.js";
 import { resolveSandboxConfigForAgent } from "../agents/sandbox/config.js";

src/security/audit-loopback-logging.test.ts

@@ -1,3 +1,4 @@
+// Covers loopback logging exposure audit findings.
 import { describe, expect, it } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
 import { withEnvAsync } from "../test-utils/env.js";

src/security/audit-plugin-code-safety.test.ts

@@ -1,3 +1,4 @@
+// Covers plugin code safety audit findings.
 import { describe, expect, it } from "vitest";
 import { collectDeepCodeSafetyFindings } from "./audit-deep-code-safety.js";
 

src/security/audit-probe-failure.test.ts

@@ -1,3 +1,4 @@
+// Verifies probe failure audit reporting.
 import { describe, expect, it } from "vitest";
 import { collectDeepProbeFindings } from "./audit-deep-probe-findings.js";
 

src/security/audit-small-model-risk.test.ts

@@ -1,3 +1,4 @@
+// Covers small-model risk audit findings.
 import { describe, expect, it } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
 import { collectSmallModelRiskFindings } from "./audit-extra.summary.js";

src/security/audit-synced-folder.test.ts

@@ -1,3 +1,4 @@
+// Verifies synced-folder security audit findings.
 import { describe, expect, it } from "vitest";
 import { collectSyncedFolderFindings } from "./audit-extra.sync.js";
 

src/security/dangerous-config-flags-core.ts

@@ -1,3 +1,4 @@
+// Defines core dangerous config flag metadata for security audits.
 import { DANGEROUS_SANDBOX_DOCKER_BOOLEAN_KEYS } from "../agents/sandbox/config.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { isRecord } from "../utils.js";

src/security/dangerous-config-flags-current-snapshot.test.ts

@@ -1,3 +1,4 @@
+// Verifies current dangerous-config snapshot output.
 import { afterEach, describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
 import { resolvePluginConfigContractsById } from "../plugins/config-contracts.js";

src/security/dangerous-config-flags-current.ts

@@ -1,3 +1,4 @@
+// Collects dangerous config flag findings from the current config shape.
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { collectPluginConfigContractMatches } from "../plugins/config-contract-matches.js";
 import { getCurrentPluginMetadataSnapshot } from "../plugins/current-plugin-metadata-snapshot.js";

src/security/dangerous-config-flags.ts

@@ -1,3 +1,4 @@
+// Collects dangerous config flag findings across agents and runtime config.
 import { resolveAgentWorkspaceDir, resolveDefaultAgentId } from "../agents/agent-scope.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
 import { collectPluginConfigContractMatches } from "../plugins/config-contract-matches.js";

src/security/external-content-source.ts

@@ -1,3 +1,4 @@
+// Normalizes source identifiers for externally supplied content.
 import { normalizeLowercaseStringOrEmpty } from "@openclaw/normalization-core/string-coerce";
 
 /** Hook session sources that carry untrusted external content into agent prompts. */

src/security/external-content.test.ts

@@ -1,3 +1,4 @@
+// Covers external content tokenization and source tagging.
 import { describe, expect, it } from "vitest";
 import {
   buildSafeExternalPrompt,

src/security/external-content.ts

@@ -1,3 +1,4 @@
+// Wraps external content with source tags and random boundary tokens.
 import { randomBytes } from "node:crypto";
 export {
   isExternalHookSession,

src/security/fix.ts

@@ -1,3 +1,4 @@
+// Applies safe automatic fixes for supported security audit findings.
 import fs from "node:fs/promises";
 import path from "node:path";
 import { resolveDefaultAgentId } from "../agents/agent-scope.js";

src/security/safe-regex.ts

@@ -1,3 +1,4 @@
+// Performs lightweight safe-regex checks for user-supplied patterns.
 type QuantifierRead = {
   consumed: number;
   minRepeat: number;

src/security/secret-equal.ts

@@ -1,3 +1,4 @@
+// Compares secret strings with timing-safe equality.
 import { timingSafeEqual } from "node:crypto";
 
 function padSecretBytes(bytes: Buffer, length: number): Buffer {

src/security/test-temp-cases.ts

@@ -1,3 +1,4 @@
+// Provides temporary filesystem cases for security audit tests.
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";

src/security/windows-acl.test.ts

@@ -1,3 +1,4 @@
+// Covers Windows ACL audit and permission detection behavior.
 import { beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
 import {
   DEFAULT_WINDOWS_SYSTEM_ROOT,