From 75c8fbbdfaced0ff17db92447be76e7b7f7b800d 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 684c505..eef21b8 100644
--- a/docs/scanners.md
+++ b/docs/scanners.md
@@ -47,7 +47,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 non-secret environment variable names passed to the scanner. Their values are not automatically redacted from scanner error text. |
 | `secretEnv` | no | Required secret environment variable names passed to the scanner. Their values are redacted from scanner error text regardless of how the names are spelled. |
@@ -88,6 +88,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.** ClawScan preserves valid scanner
+> stdout as raw JSON evidence, so any secret the scanner writes into that JSON
+> is persisted. Values declared in `secretEnv` are redacted from scanner error
+> text, but ClawScan does not rewrite raw evidence. 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` and
 `secretEnv` names are added to its environment allowlist. Put every sensitive