From a5e0f4194dc7f881cf2cdd3aea3359a2dbb05446 Mon Sep 17 00:00:00 2001
From: Jesse Merhi <79823012+jesse-merhi@users.noreply.github.com>
Date: Fri, 24 Jul 2026 14:30:38 +1000
Subject: [PATCH] docs(scanners): warn against printing secrets into
 user-defined scanner evidence

ClawScan preserves a user-defined scanner's stdout verbatim as raw evidence, so
a secret the scanner prints into its own JSON output is persisted as-is. Unlike
declared env values in error text, ClawScan cannot redact inside raw evidence
without corrupting it. Document that a scanner must not echo credentials into
its report (finding 9, resolved as a documented author contract rather than
code). Also correct the scanner id rule to note the lowercase and 64-character
limits added in the hardening series.
---
 docs/scanners.md | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/docs/scanners.md b/docs/scanners.md
index 85bbd6b..ec2fd2f 100644
--- a/docs/scanners.md
+++ b/docs/scanners.md
@@ -45,7 +45,7 @@ that config-backed run and accept these fields:
 
 | Field | Required | Meaning |
 | --- | --- | --- |
-| `id` | yes | Scanner ID using letters, digits, `_`, and `-`, starting with a letter or digit. It must not match a built-in scanner ID. |
+| `id` | yes | Scanner ID using lowercase letters, digits, `_`, and `-`, starting with a letter or digit, at most 64 characters. It must not match a built-in scanner ID. |
 | `command` | yes | Shell command to execute. Unquoted `{{target}}` is replaced with the safely passed resolved target; do not wrap the placeholder in shell quotes. |
 | `env` | no | Required environment variable names. Values stay in the process environment and are never stored in the config or artifact. |
 | `targets` | no | Supported target kinds: `skill`, `plugin`, and/or `url`. Defaults to `skill` and `url`. |
@@ -74,6 +74,13 @@ scanner's raw evidence; empty or non-JSON stdout produces a failed scanner
 result. Required environment variables are checked before any scanner starts.
 Artifacts record each requirement as only `present` or `missing`.
 
+> **Do not print secrets into evidence.** Because ClawScan stores the scanner's
+> stdout verbatim as raw evidence, any secret the scanner writes into its own
+> JSON output is persisted as-is. ClawScan redacts declared `env` values from
+> scanner *error* text, but it cannot redact inside raw evidence without
+> corrupting it. A user-defined scanner must not echo its API keys, tokens, or
+> other credentials into the JSON report it emits.
+
 User-defined scanners use the same execution path as built-in command-backed
 scanners. They run in the Docker sandbox by default, and declared `env` names
 are added to its environment allowlist. Use `--sandbox off` only when you