This document records the security review of rgq: the threat model, the weak points found,
how each was handled, and the residual risks you should know about — especially if you embed
rgq in a larger system.
rgq is a small CLI that parses a boolean query, spawns ripgrep (rg) as a subprocess, and
prints the set of matching file paths. It is written in safe Rust (no unsafe) and never
invokes a shell — rg is launched with an explicit argument vector, so there is no shell
metacharacter interpretation at any point.
The realistic adversaries for a search tool are:
- A hostile search target. You run
rgqover a directory you don't fully trust (a cloned repo, an unpacked archive, a shared upload dir). The attacker controls file names and file contents. This is the primary threat. - A hostile query.
rgqis embedded behind some interface and an untrusted party supplies the query string (or flags). - A hostile environment. Environment variables or
PATHare partially attacker-influenced.
rgq is an ordinary, non-setuid user tool. It does not drop privileges, sandbox, or run as a
daemon; it runs with exactly the privileges of the user who launched it.
| # | Finding | Severity | Status |
|---|---|---|---|
| 1 | Terminal escape-sequence injection via crafted filenames | Medium | Fixed |
| 2 | Newline-in-filename corrupting downstream pipelines | Low | Mitigated |
| 3 | DNF combinatorial blow-up (memory DoS) | Medium | Mitigated |
| 4 | Stack overflow via deeply nested query | Medium | Mitigated |
| 5 | Non-fatal rg I/O error / delete-race causing a hard failure |
Low | Fixed |
| 6 | rgq flag smuggling when embedding an untrusted query |
Medium | Documented |
| 7 | Arbitrary rg binary via RGQ_RG / PATH |
Low | Documented |
| 8 | Argument injection into rg (terms/paths read as flags) |
— | Not vulnerable |
| 9 | Shell / command injection | — | Not vulnerable |
| 10 | ReDoS via a regex term | — | Not vulnerable |
| 11 | RIPGREP_CONFIG_PATH → ripgrep --pre arbitrary command execution |
Critical | Fixed |
| 12 | Unicode bidi-override / invisible-character filename spoofing ("Trojan Source") | Medium | Fixed |
| 13 | Tree renderer: unbounded path depth (stack overflow) | Medium | Fixed |
| 14 | TOCTOU symlink race between candidate listing and narrowing | Low | Documented (inherent) |
| 15 | Supply-chain: dependency vulnerabilities | — | Checked: clean |
| 16 | No predictive check against aggregate --tree memory use (many large/deep files) |
Low | Added |
A file name may contain arbitrary bytes, including ANSI escape sequences (e.g.
evil\e[31m\e[2K\rsafe.txt). The default flat-list output wrote path bytes verbatim, so on an
interactive terminal those bytes execute: an attacker who controls a file name in a tree you
search could recolour text, clear lines, or move the cursor to spoof rgq's output — hide a
result, fake a "0 matches" line, or make one path look like another.
Fix. When stdout is a terminal, control bytes (0x00–0x1f, including ESC, newline,
CR; and 0x7f DEL) are escaped to a visible \xHH form in the human-facing modes (default list
and --tree). Bytes >= 0x80 pass through so legitimate non-ASCII names still display.
- Piped / redirected output stays raw, so tooling receives exact bytes.
--print0is always raw — it is the unambiguous machine form (NUL cannot occur in a path).
See sanitize_controls in src/cli.rs and the sanitize_* unit tests.
A file name containing a newline breaks line-oriented consumers (| xargs, while read),
potentially splitting one path into two. rgq provides --print0 (NUL-delimited), which is
the correct and safe form for piping into other tools (rgq -0 … | xargs -0 …). On a terminal,
newlines in names are escaped (finding 1). Byte-exact round-tripping through --print0 is
covered by tests.
Converting to disjunctive normal form can expand combinatorially: (a OR b) AND (c OR d) AND …
doubles per conjunct. Left unbounded, a crafted query could exhaust memory.
Mitigation. --max-clauses (default 1024) caps the clause count; the limit is checked
before any large allocation, and the per-step capacity hint is clamped, so exceeding it is a
clean usage error (exit 2), never an OOM. Long AND/OR chains are parsed iteratively (no
recursion), so only nesting depth recurses — see finding 4.
Deeply nested parentheses or NOT chains (((((…))))) recurse in the parser. A recursion-depth
limit (256) returns a clean error instead of overflowing the stack.
rg exits 2 on any error, including a non-fatal one such as a single unreadable file or a
file that vanished mid-search. Treating every exit 2 as fatal meant one such file failed the
whole query — and let an attacker race file deletions to deny results.
Fix. On exit 2 with output, rgq surfaces a warning: (with rg's message) and uses
the results it did get. A genuinely fatal error (bad regex, bad flag) produces empty output and
is still reported as an error with a non-zero exit.
If you build the argument list as rgq <untrusted-query>, a query like -uu cat or
--no-ignore secret is parsed as rgq's own flags, letting the supplier widen the search
scope (read hidden / ignored files) or change behaviour.
Guidance for embedders: always separate the untrusted query with --:
rgq -- "$UNTRUSTED_QUERY"After --, the whole query is positional and can never be read as an rgq flag (a leading-dash
term then just becomes a search term). Decide deliberately which scope flags, if any, you
expose to the untrusted caller, and keep the default --max-clauses in place.
rgq runs rg from PATH, or the binary named by the RGQ_RG environment variable. Whoever
controls that environment controls which program rgq executes. This is standard for any
tool that shells out, and not a privilege boundary here (rgq is not setuid and inherits your
environment). Do not run rgq with an attacker-controlled environment, and note that
RGQ_RG will execute any program you point it at. (Rust's Command does not search the
current directory, so a ./rg dropped into the tree you're searching is not executed unless
. is already in your PATH.)
A search term or a candidate path could otherwise be read by rg as an option (a term like
--type=foo, or a file literally named -rf). rgq prevents this structurally:
- every search pattern is passed after
-e, so it is always a pattern, never a flag; - every file path is passed after a
--end-of-options marker.
Tests cover a leading-dash search term and a file named like a flag.
rgq never builds or runs a shell command string. rg is spawned via std::process::Command
with a structured argument vector, so shell metacharacters in a query or filename have no special
meaning. (The original prototype's bash/xargs pipeline was deliberately dropped for exactly
this reason.)
Terms are regexes by default, but rgq uses ripgrep's default regex engine, which guarantees
linear-time matching (no catastrophic backtracking). rgq does not expose ripgrep's PCRE2
mode (-P). Pathologically large regexes are bounded by ripgrep's own --regex-size-limit.
The most serious finding in this review. Ripgrep itself reads the RIPGREP_CONFIG_PATH
environment variable and, if set, loads extra command-line flags from the file it points to —
before the flags rgq passes. Ripgrep also has a --pre <program> flag: when set, ripgrep
runs <program> <file> for every file it searches and searches the program's output instead
of the file. Put together: if an attacker can get RIPGREP_CONFIG_PATH pointed at a file
containing --pre /some/script, every rgq invocation runs /some/script once per file in
scope — arbitrary command execution, gated only by control over one environment variable.
This was confirmed with a working proof of concept against bare rg during this review (a
preprocessor script that wrote a sentinel file ran successfully via RIPGREP_CONFIG_PATH +
--pre), then verified end-to-end that the fix below blocks it.
Fix. Every rg invocation now includes --no-config, which makes ripgrep ignore
RIPGREP_CONFIG_PATH entirely. rgq already sets every flag it cares about explicitly, so it
never relied on the user's ripgrep config for anything — disabling it costs no functionality.
See base_args in src/rg.rs, every_mode_disables_rg_config_loading (unit test), and
ripgrep_config_path_cannot_inject_a_preprocessor_command (end-to-end test that plants the
exact attack and asserts the preprocessor never runs).
Finding 1 escaped raw control bytes, but a file name can also carry Unicode characters that
change how text displays without changing the underlying bytes — the "Trojan Source" class
(CVE-2021-42574). For example a file named cat<RLO>txt.gpj<PDF> (where <RLO>/<PDF> are the
right-to-left-override and pop-directional-formatting codepoints) renders as cat followed by
text that looks like jpg.txt, even though the real name ends in .gpj. These are multi-byte
UTF-8 sequences (>= 0x80) that the original control-byte escaping didn't touch — confirmed by
reproducing the spoofed rendering with a real crafted filename before fixing it.
Fix. The same TTY-only sanitizer now also escapes a denylist of bidirectional format
characters (LRE/RLE/PDF/LRO/RLO/LRI/RLI/FSI/PDI) and common invisible characters (zero-width
space/non-joiner/joiner, word joiner, BOM) to a visible \u{XXXX} form. This is deliberately
narrow: it does not attempt general homoglyph/confusable detection (e.g. Cyrillic vs Latin
lookalikes) — that's a much larger, fuzzy problem with real false-positive risk for legitimate
non-Latin filenames, and is a residual risk (see below), not something this fix claims to solve.
See DANGEROUS_CODEPOINTS in src/cli.rs.
The tree renderer recurses once per path-nesting level. A path's depth comes from whatever tree
rgq is pointed at, so it's attacker-influenceable; a standalone harness confirmed an unbounded
recursive implementation reliably stack-overflows around depth 50,000 (synthetic, in-memory —
independent of any filesystem PATH_MAX). Real filesystem paths can't reach that depth (Linux
PATH_MAX is ~4096 bytes, capping real nesting in the low thousands at most), so this was not
reachable through the normal rg --files pipeline — but the function had no guard and silently
depended on that external, implicit limit holding.
Fix. A depth cap (MAX_DEPTH = 100, mirroring the parser's existing recursion-depth guard)
truncates a path nested past the cap with a visible ... (truncated: nested past 100 levels)
marker instead of continuing to recurse. 100 is far beyond any real directory tree.
A note on how this fix was arrived at, in the interest of an honest record: the first attempt
replaced the recursion with an iterative, heap-stack-based traversal and was validated with a
test that rendered a synthetic, 2-million-level-deep path. That test itself allocated on the
order of terabytes (the per-level prefix string is cloned at every level, an O(depth²) cost
independent of recursive-vs-iterative implementation) and crashed the development host via the
OOM killer. The mistake was conflating "remove the stack-overflow class" with "depth should be
unbounded" — they're different problems, and once a sane depth cap is in place (which is needed
regardless, to bound the O(depth²) prefix-copy cost), plain bounded recursion is simpler and
sufficient; the iterative rewrite was reverted. The lesson generalizes: a fix for an
unbounded-input class should itself be validated with bounded inputs near the actual limit, not
yet-larger unbounded ones.
Per-clause narrowing (spec §8.1) seeds a candidate file list from one rg invocation, then passes
those same paths back to rg in a later invocation. If an attacker who can write into the
directory being searched swaps a candidate file for a symlink to a sensitive file (e.g.
/etc/shadow) between those two calls, the later call may search the symlink's target. The result
returned is still the original filename (not the target's), so what could leak is a single bit:
whether the targeted file matches a given term.
This is a classic local TOCTOU race shared by virtually every CLI tool that passes an explicit
file list to a second command (xargs, grep -f, etc.) — not specific to rgq's design. Fixing
it would require not passing paths back to rg as arguments at all (e.g. opening file descriptors
directly and feeding ripgrep's library crates instead of the rg binary), which is a different
architecture than the one this project deliberately chose (PLAN.md §2.1: spawn rg, don't
reimplement search) and is noted there as a possible future direction. Documented here rather than
"fixed" because no fix is possible without that larger architectural change; it requires local
write access to the search target, which is already a high level of access.
rgq's dependency tree is small (clap, thiserror, plus their transitive deps — all
widely-used, actively maintained crates; see cargo tree). cargo audit (RustSec advisory
database, 1,146 advisories at time of scan) reports zero vulnerabilities across all 57
resolved dependencies. This is a point-in-time result, not a guarantee — new advisories are
published continuously, so a clean scan today says nothing about a CVE disclosed next month
against a crate already in the dependency tree.
Automated in CI (.github/workflows/audit.yml): cargo audit now runs on every push/PR that
touches Cargo.toml/Cargo.lock, and on a weekly schedule independent of any code change —
the schedule is what catches a newly published advisory against an already-merged dependency,
which a merge-time-only check would miss entirely. .github/dependabot.yml complements this with
weekly automated PRs bumping outdated cargo and github-actions dependencies, so a flagged
vulnerability usually already has a fix available to merge.
Finding 13's MAX_DEPTH cap bounds the cost per matched file but not the number of matched
files: a query with very broad scope flags (-uu over a huge tree) and a permissive term could
match enough files, each individually near the depth cap, to add up to a large amount of memory
during --tree rendering — even though no single path is unbounded anymore.
Mitigation. Before rendering, rgq now computes an exact prediction of the rendered output
size and a conservative estimate of the trie's own memory footprint (tree::estimate_memory_bytes
— the output-size estimate is exact, not approximate: it runs the identical traversal render
itself uses, against a byte-counting sink instead of an accumulating buffer, so the two can never
silently drift apart), checks that against the system's real available memory (/proc/meminfo,
via src/membudget.rs), and refuses with a clear, actionable error rather than risk exhausting
memory — by default never letting estimated usage push total free system memory below 20%
(configurable: --min-free-mem-pct). The check is scoped to --tree, the one output mode whose
memory footprint can exceed the size of its input; the default list and --print0 modes write
each matched path once with no amplification and don't need it.
Limitation: the check reads host-level /proc/meminfo, so inside a memory-limited container
(e.g. docker run --memory=512m) it sees the host's full memory, not the cgroup limit, and would
not catch an OOM kill imposed by a tighter container limit. If memory introspection is unavailable
at all (non-Linux, sandboxed), rgq warns and proceeds rather than refusing to run.
- Expensive scans are still possible. A positive-free clause (e.g.
NOT foo) must scan every file in scope;rgqwarns on stderr but still runs it. If you exposergqto untrusted queries, impose your own time/CPU limits and keep the default--max-clauses. - Scope flags widen exposure by design.
-u/--no-ignoreand--hiddenintentionally include ignored/hidden files (which may hold secrets). Don't expose them to untrusted callers. rgqmirrorsrg's view of the filesystem. It respects.gitignore(inside a git repo),.ignore, and hidden-file rules exactly asrgdoes. It never follows symlinks for content (it doesn't read file contents at all —rgdoes), and never writes, deletes, or opens the paths it reports.- Use
--print0for any machine consumption of the output. Line-based parsing of the default output is only safe for filenames without newlines. - General homoglyph/confusable spoofing is out of scope. Finding 12 neutralizes bidi-override
and invisible characters specifically, not visual lookalikes in general (e.g. Cyrillic
аvs Latina). Don't rely onrgq's output to visually distinguish two filenames that are designed to look alike. - The TOCTOU race in finding 14 means a result set is a snapshot, not a guarantee — if the
search target is being concurrently modified by an untrusted party, don't treat
rgq's output as proof of what those files currently contain. - The
--treememory check (finding 16) sees host memory, not container limits. If you runrgqinside a memory-limited container, set--min-free-mem-pctconservatively (or useRGQ_MEM_AVAILABLE_BYTES/RGQ_MEM_TOTAL_BYTESto supply the real cgroup limit), since/proc/meminfoalone won't reflect it.
This is a portfolio/spec project. If you find an issue, open an issue on the repository.