- Rename 009-cli-terminal-control-sanitization.md to 010-cli-terminal-control-sanitization.md - Update ADR-009 to ADR-010 in frontmatter - Update ADR index reference in docs/agents/pull-requests.md Fixes #119
3.5 KiB
ADR-010: Neutralize Terminal Control Sequences in CLI Text Output
Status: Accepted Date: 2026-06-04
Context
CLI text mode (formatResults in format.go) writes untrusted SearXNG
result fields directly to the terminal after HTML entity unescaping
(UnescapeIfNeeded). If an upstream result contains ANSI or OSC control
bytes — including the HTML-entity-encoded form , which
html.UnescapeString decodes to a literal ESC — the program emits them
as terminal control sequences. This can alter terminal display state
and, in terminals that support OSC 52, may attempt clipboard writes.
The vulnerability was filed as a low-severity security finding (CAND-33fe0b85-RUNTIME-001) with proof-of-concept ESC bytes at byte offsets 221, 293, and 301 of formatted output.
The affected surface is CLI text mode terminal rendering. JSON output
goes through encoding/json and MCP responses reuse the same JSON path.
The data model returned to JSON and MCP consumers does not need to
change, but consumers should still treat returned strings as untrusted
data rather than terminal-ready text.
Decision
formatResults will run every user-controlled text field through a new
sanitizeTerminalControl helper in format.go that rewrites C0
controls (other than \t, \n), DEL, and C1 controls
(U+0080..U+009F) into visible \xNN escape sequences. All other
codepoints — including CJK, emoji, and accented Latin — are preserved
unchanged. Invalid UTF-8 bytes are also rewritten byte-by-byte.
The sanitizer is scoped to the text-format layer. The data model and the JSON path are untouched.
Rationale
- Localized to the affected surface. The data model is unchanged, so MCP consumers and downstream JSON parsers see exactly the same bytes they saw before. The fix targets only the rendering path that actually writes to a terminal.
- Visible encoding > silent stripping. A user reviewing a captured
transcript can still see
\x1b[31mredrather than a silent gap; the upstream payload survives in a safe form. - Preserves ordinary Unicode. CJK, emoji, and Latin diacritics round-trip byte-for-byte. The only codepoints rewritten are those that can act as terminal control sequences.
- Defense in depth. C0 controls other than ESC (BEL, BS, VT, FF, SO, SI, DLE..US) and the C1 control range are also rewritten. The cost is trivial and the safety margin against future payloads improves.
- Fast path keeps the common case cheap. A
hasUnsafeControlBytespre-scan returns the input string unchanged when no rewrite is needed, so legitimate result text does not allocate a new buffer.
Consequences
- A new helper
sanitizeTerminalControland a pre-scan helperhasUnsafeControlByteslive informat.gonext to the formatter that uses them. The internalsearxngpackage is not modified. - Golden capture (
golden_capture_test.go) is unaffected because the golden fixture contains no control bytes. - New unit tests in
format_sanitize_test.gocover ANSI, OSC 52, DCS, CSI, C0, C1, DEL, carriage returns, invalid UTF-8, HTML-entity-decoded ESC, and Unicode preservation. NewformatResults-level tests informat_test.golock end-to-end behavior for results, infoboxes, answers, suggestions, and query echo. docs/OUTPUT_FORMAT.mddocuments the sanitizer and the JSON / MCP unchanged-behavior contract.- If a future requirement needs to render ANSI color (unlikely for untrusted upstream content), this decision should be revisited with a TTY-only allowlist and an opt-out flag.