mirror of
https://github.com/xlionjuan/searxng-mcp-go.git
synced 2026-11-17 04:17:51 +00:00
- 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
75 lines
3.5 KiB
Markdown
75 lines
3.5 KiB
Markdown
# 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
|
|
|
|
1. **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.
|
|
2. **Visible encoding > silent stripping.** A user reviewing a captured
|
|
transcript can still see `\x1b[31mred` rather than a silent gap; the
|
|
upstream payload survives in a safe form.
|
|
3. **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.
|
|
4. **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.
|
|
5. **Fast path keeps the common case cheap.** A `hasUnsafeControlBytes`
|
|
pre-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 `sanitizeTerminalControl` and a pre-scan helper
|
|
`hasUnsafeControlBytes` live in `format.go` next to the formatter
|
|
that uses them. The internal `searxng` package 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.go` cover ANSI, OSC 52, DCS,
|
|
CSI, C0, C1, DEL, carriage returns, invalid UTF-8,
|
|
HTML-entity-decoded ESC, and Unicode preservation. New
|
|
`formatResults`-level tests in
|
|
`format_test.go` lock end-to-end behavior for results, infoboxes,
|
|
answers, suggestions, and query echo.
|
|
- `docs/OUTPUT_FORMAT.md` documents 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.
|