From 961759c08b39880bc99e874fcf53b24af1641878 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 4 Jun 2026 04:06:08 -0400
Subject: [PATCH] docs: document security finding helpers

---
 src/security/audit-channel-account-metadata.test.ts          | 1 +
 src/security/audit-channel-readonly-resolution.test.ts       | 1 +
 src/security/audit-channel-readonly-setup-fallback.test.ts   | 1 +
 src/security/audit-channel.collect.runtime.ts                | 1 +
 src/security/audit-config-include-perms.test.ts              | 1 +
 src/security/audit-config-symlink.test.ts                    | 1 +
 src/security/audit-extra.summary.ts                          | 1 +
 src/security/audit-loopback-logging.test.ts                  | 1 +
 src/security/audit-plugin-code-safety.test.ts                | 1 +
 src/security/audit-probe-failure.test.ts                     | 1 +
 src/security/audit-small-model-risk.test.ts                  | 1 +
 src/security/audit-synced-folder.test.ts                     | 1 +
 src/security/dangerous-config-flags-core.ts                  | 1 +
 src/security/dangerous-config-flags-current-snapshot.test.ts | 1 +
 src/security/dangerous-config-flags-current.ts               | 1 +
 src/security/dangerous-config-flags.ts                       | 1 +
 src/security/external-content-source.ts                      | 1 +
 src/security/external-content.test.ts                        | 1 +
 src/security/external-content.ts                             | 1 +
 src/security/fix.ts                                          | 1 +
 src/security/safe-regex.ts                                   | 1 +
 src/security/secret-equal.ts                                 | 1 +
 src/security/test-temp-cases.ts                              | 1 +
 src/security/windows-acl.test.ts                             | 1 +
 24 files changed, 24 insertions(+)

diff --git a/src/security/audit-channel-account-metadata.test.ts b/src/security/audit-channel-account-metadata.test.ts
index 1828337a617b..9b9e6a7fb0d8 100644
--- a/src/security/audit-channel-account-metadata.test.ts
+++ b/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";
diff --git a/src/security/audit-channel-readonly-resolution.test.ts b/src/security/audit-channel-readonly-resolution.test.ts
index 7bb19383db57..065520451130 100644
--- a/src/security/audit-channel-readonly-resolution.test.ts
+++ b/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";
diff --git a/src/security/audit-channel-readonly-setup-fallback.test.ts b/src/security/audit-channel-readonly-setup-fallback.test.ts
index 03fea8a3d365..fe2c2677fdf8 100644
--- a/src/security/audit-channel-readonly-setup-fallback.test.ts
+++ b/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";
diff --git a/src/security/audit-channel.collect.runtime.ts b/src/security/audit-channel.collect.runtime.ts
index a79e74d56b0b..9759c5b9f0e8 100644
--- a/src/security/audit-channel.collect.runtime.ts
+++ b/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 =
diff --git a/src/security/audit-config-include-perms.test.ts b/src/security/audit-config-include-perms.test.ts
index fae8cc61a953..8e5451fab7bf 100644
--- a/src/security/audit-config-include-perms.test.ts
+++ b/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";
diff --git a/src/security/audit-config-symlink.test.ts b/src/security/audit-config-symlink.test.ts
index 489c93d2c1c6..1c3d8d5a1919 100644
--- a/src/security/audit-config-symlink.test.ts
+++ b/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";
diff --git a/src/security/audit-extra.summary.ts b/src/security/audit-extra.summary.ts
index db28c85d16f8..f5433f3c7d7e 100644
--- a/src/security/audit-extra.summary.ts
+++ b/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";
diff --git a/src/security/audit-loopback-logging.test.ts b/src/security/audit-loopback-logging.test.ts
index 855f2ecbfb2c..b93bae66908e 100644
--- a/src/security/audit-loopback-logging.test.ts
+++ b/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";
diff --git a/src/security/audit-plugin-code-safety.test.ts b/src/security/audit-plugin-code-safety.test.ts
index 6b7ee547c7b4..d951dd341f39 100644
--- a/src/security/audit-plugin-code-safety.test.ts
+++ b/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";
 
diff --git a/src/security/audit-probe-failure.test.ts b/src/security/audit-probe-failure.test.ts
index 4fd3e7350779..6a88c54c6de4 100644
--- a/src/security/audit-probe-failure.test.ts
+++ b/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";
 
diff --git a/src/security/audit-small-model-risk.test.ts b/src/security/audit-small-model-risk.test.ts
index b094fb38aebc..0ca5c8dabb75 100644
--- a/src/security/audit-small-model-risk.test.ts
+++ b/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";
diff --git a/src/security/audit-synced-folder.test.ts b/src/security/audit-synced-folder.test.ts
index ea3c42cc2168..fa0d15201f53 100644
--- a/src/security/audit-synced-folder.test.ts
+++ b/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";
 
diff --git a/src/security/dangerous-config-flags-core.ts b/src/security/dangerous-config-flags-core.ts
index e2be3b5263bd..30a699c9abef 100644
--- a/src/security/dangerous-config-flags-core.ts
+++ b/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";
diff --git a/src/security/dangerous-config-flags-current-snapshot.test.ts b/src/security/dangerous-config-flags-current-snapshot.test.ts
index dc627d46a4e7..3222acffa034 100644
--- a/src/security/dangerous-config-flags-current-snapshot.test.ts
+++ b/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";
diff --git a/src/security/dangerous-config-flags-current.ts b/src/security/dangerous-config-flags-current.ts
index 99e4578138bb..ad500613c80e 100644
--- a/src/security/dangerous-config-flags-current.ts
+++ b/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";
diff --git a/src/security/dangerous-config-flags.ts b/src/security/dangerous-config-flags.ts
index 4823c4ce0a23..0c61fce5ed99 100644
--- a/src/security/dangerous-config-flags.ts
+++ b/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";
diff --git a/src/security/external-content-source.ts b/src/security/external-content-source.ts
index 8e48daf992df..7c26b82ad384 100644
--- a/src/security/external-content-source.ts
+++ b/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. */
diff --git a/src/security/external-content.test.ts b/src/security/external-content.test.ts
index a4997053a714..bb49698a0e09 100644
--- a/src/security/external-content.test.ts
+++ b/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,
diff --git a/src/security/external-content.ts b/src/security/external-content.ts
index 71365aa8b180..ca686a51b5fd 100644
--- a/src/security/external-content.ts
+++ b/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,
diff --git a/src/security/fix.ts b/src/security/fix.ts
index 7daa4445eb4a..45f6572f4813 100644
--- a/src/security/fix.ts
+++ b/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";
diff --git a/src/security/safe-regex.ts b/src/security/safe-regex.ts
index 7b10e21582cf..ee1d57f04261 100644
--- a/src/security/safe-regex.ts
+++ b/src/security/safe-regex.ts
@@ -1,3 +1,4 @@
+// Performs lightweight safe-regex checks for user-supplied patterns.
 type QuantifierRead = {
   consumed: number;
   minRepeat: number;
diff --git a/src/security/secret-equal.ts b/src/security/secret-equal.ts
index b197ffe08dd5..c6fc89c306b3 100644
--- a/src/security/secret-equal.ts
+++ b/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 {
diff --git a/src/security/test-temp-cases.ts b/src/security/test-temp-cases.ts
index 71fa9f32e23a..5340a648ff00 100644
--- a/src/security/test-temp-cases.ts
+++ b/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";
diff --git a/src/security/windows-acl.test.ts b/src/security/windows-acl.test.ts
index dff73e512b98..85b6d123680c 100644
--- a/src/security/windows-acl.test.ts
+++ b/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,