cqs is a local code search tool for developers. It runs on your machine, indexes your code, and answers semantic queries.

1. Path traversal: Commands cannot read files outside project root
2. FTS injection: Search queries sanitized before SQLite FTS5 MATCH operations
3. Database corruption: PRAGMA quick_check(1) on write-mode opens (opt-out via CQS_SKIP_INTEGRITY_CHECK=1). Read-only opens skip the check entirely — reads cannot introduce corruption and the index is rebuildable via cqs index --force
4. Reference config trust: Warnings logged when reference configs override project settings

• Malicious code in your project: If your code contains exploits, indexing won't stop them
• Local privilege escalation: cqs runs with your permissions
• Side-channel attacks: Beyond timing, not in scope for a local tool
• Indirect prompt injection from indexed content: cqs relays code, comments, summaries, and notes verbatim to AI consumers; injection payloads inside those surfaces survive the relay. See Indirect Prompt Injection below.

cqs's primary consumer is AI agents. By design, cqs faithfully relays the content it has indexed — code, comments, doc strings, LLM-generated summaries, and developer notes — into the agent's context window. Any of those surfaces can carry indirect prompt injection payloads: instructions disguised as content that try to redirect the consuming agent ("Ignore prior instructions and...", "This function is safe to call with sudo", etc.).

cqs cannot reliably distinguish a legitimate doc comment from a malicious one. Defence has to live partly in the agent (treat retrieved code as untrusted input) and partly in cqs's protocol (make the trust boundary loud and visible).

• audit-mode: cqs audit-mode on excludes notes from rankings and forces direct code examination. Mitigates the runtime side of shared-notes injection.

• No automatic execution: cqs never executes indexed code; the threat is purely textual relay into agent context.

• --improve-docs review gate (since v1.30.1): by default, cqs index --improve-docs writes proposed doc comments as unified-diff patches to .cqs/proposed-docs/<rel>.patch instead of mutating source files in place. Review with git diff and apply with git apply .cqs/proposed-docs/**/*.patch. Pass --apply to opt back into direct write-back; the run prints a warning when it does.

• First-encounter shared-notes gate (since v1.30.1): on the first cqs index against a repo containing docs/notes.toml, cqs prompts to confirm before indexing the notes — committed notes affect search rankings and surface in agent context. Acceptance is persisted to .cqs/.accepted-shared-notes so the prompt doesn't repeat. Pass --accept-shared-notes to bypass for CI / scripted use; non-TTY stdin auto-skips the notes pass with a warning so CI never hangs. (#1168)

• trust_level + reference_name on chunk JSON (since v1.30.1, three-tier as of #1221): every chunk-returning JSON output (search, gather, task, scout, onboard, read, read --focus, context, similar) carries one of:

  • "user-code" — chunk lives in the user's project store and did not match any vendored-path prefix at index time.
  • "vendored-code" — chunk lives in the user's project store but its origin passed through a configured vendored-path segment (default list: vendor, third_party, node_modules, .cargo, target, dist, build; override via [index].vendored_paths in .cqs.toml). Treat as third-party content for indirect-injection purposes — same threat profile as reference-code. (#1221, schema v24)
  • "reference-code" (with reference_name) — chunk lives in a cqs ref reference index. Wins over vendored-code when both apply: the per-reference name is the more useful agent-facing signal.

  Scope of user-code after #1221. trust_level: "user-code" now means "from the user's project store AND not under a configured vendored-path prefix". Vendored upstream content (vendor/, third_party/, node_modules/, etc.) is structurally distinguished as "vendored-code" at index time — the structural fix the SEC-V1.30.1-5 doc-only stop-gap acknowledged was needed. Caveats that still apply: (1) user-code does not mean "authored by the user" — generated code under src/ is still user-code. (2) Developer notes (docs/notes.toml content surfaced via cqs notes mention) still ride the user-code label since they're stored separately and don't pass through the chunk pipeline. (3) Reindex required to retroactively flag pre-v24 chunks: the v23→v24 migration adds the column with default 0; only the next cqs index (or cqs watch re-emit) populates it.

• CQS_TRUST_DELIMITERS is on by default (since v1.30.2): every chunk's content is wrapped in <<<chunk:{id}>>> ... <<</chunk:{id}>>> markers so prompt-injection guards downstream of cqs can detect content boundaries even when the agent inlines the rendered string into a larger prompt. Set CQS_TRUST_DELIMITERS=0 to opt out (raw text). Was opt-in in v1.30.1. (#1167, #1181)

• LLM summary validation (since v1.30.1): every summary headed for the llm_summaries cache passes through cqs::llm::validation::validate_summary before insertion. Catches lazy injections (leading "Ignore prior" / "Disregard"; embedded code fences; embedded URLs) and enforces a 1500-char hard length cap. Configurable via CQS_SUMMARY_VALIDATION=strict|loose|off (default loose: log + keep on pattern match, truncate over-long; strict drops pattern-matched summaries entirely). Doc-comment generation is intentionally exempt — its prose is imperative by design and would false-positive; it has its own review gate (#1166). (#1170)

• _meta.handling_advice is opt-in via CQS_ULTRASECURITY=1 (was always-on v1.30.2 → v1.39.x; opt-in since v1.40.0): every JSON-emitting command surface (emit_json, batch write_json_line, daemon socket) accepts an _meta.handling_advice string framing the response as untrusted-by-default for any consuming agent. trust_level signals origin, not safety; injection_flags lists which heuristics fired but cqs never refuses to relay. Default-on through v1.39.x added ~80 bytes to every response — telemetry showed agents reduced their cqs search rate from 79% → 6% mid-April → early May, attributable to the always-on advisory plus per-result advisory fields (#1181 → #1593). v1.40.0 (#1593, #1601-#1613) inverted the default: under Posture::Friendly (no env var or CQS_ULTRASECURITY=0), _meta.handling_advice is omitted; under Posture::Adversarial (CQS_ULTRASECURITY=1, set explicitly for adversarial deployments like cqs-as-MCP-server), it's emitted on every envelope as before. The advisory is unchanged when present; only the default emission posture flipped. (#1181 → #1593 → #1613)

• _meta.worktree_stale + _meta.worktree_name (#1254): when a cqs command runs from inside a git worktree that has no .cqs/ of its own, cqs auto-discovers the main project's index via the worktree's .git/commondir link and serves queries against main's .cqs/. Every JSON envelope from that process carries worktree_stale: true plus the worktree's directory name in worktree_name. Consuming agents should treat the served snapshot as reflecting main's branch, not uncommitted edits in the worktree — fall back to reading absolute worktree paths for any chunk that's about to be edited. The fields are absent (skipped) for the non-worktree happy path so the wire shape only grows when the redirect actually fires. Closes the worktree-leakage class of bugs documented in feedback_agent_worktrees.md.

• Per-chunk injection_flags array is opt-in/skip-when-default since v1.40.0 (was always-on v1.30.2 → v1.39.x): every chunk-returning JSON output accepts an injection_flags field listing which injection heuristics fired on the chunk's raw content (e.g. ["leading-directive", "code-fence", "embedded-url"]). Under Posture::Friendly (default v1.40.0+), the field is skipped when empty (the typical case) to keep the wire shape lean; emitted as a populated array when at least one heuristic fires. Under Posture::Adversarial (CQS_ULTRASECURITY=1), the field is force-emitted on every chunk including the empty-array case, preserving the v1.30.2 schema-stability contract for adversarial deployments. cqs labels — never refuses to relay. Agents that want a stricter posture can refuse to act on chunks with non-empty injection_flags. (#1181 → #1602 → #1613)

These are defence in depth, not absolute protection. Subtle injections (a summary that is superficially correct but biased) will still get through. The agent-side defence — treat retrieved code as untrusted input, sandbox tool calls, never execute payload-shaped output — remains the load-bearing layer.

cqs runs locally by default. No network telemetry. Optional local command logging to .cqs/telemetry.jsonl — active when CQS_TELEMETRY=1 is set OR when the telemetry file already exists (persists across shells/subprocesses). Never transmitted. Delete the file to opt out. The optional --llm-summaries flag sends function code to the Anthropic API (see below).

The only network activity is:

• Model download (cqs init): Downloads embedding model from HuggingFace Hub

  • Default since v1.35.0: huggingface.co/onnx-community/embeddinggemma-300m-ONNX (~1.2GB FP32 ONNX bundle + ~20MB tokenizer)
  • Preset: bge-large (BAAI/bge-large-en-v1.5, ~1.2GB) — former default; opt-in via CQS_EMBEDDING_MODEL=bge-large
  • Preset: e5-base (intfloat/e5-base-v2, ~438MB)
  • Preset: nomic-coderank (jamie8johnson/CodeRankEmbed-onnx, ~547MB) — code-specialised, opt-in via CQS_EMBEDDING_MODEL=nomic-coderank (#1110)
  • Custom: any HuggingFace repo via [embedding] config or CQS_EMBEDDING_MODEL env var. Custom model configs download ONNX files from the specified repo — only configure repos you trust.
  • One-time download per model, cached in ~/.cache/huggingface/

• Reranker model download (first --rerank use): Downloads cross-encoder model from HuggingFace Hub

  • Model: ms-marco-MiniLM-L-6-v2 (cross-encoder)
  • One-time download, cached in ~/.cache/huggingface/

• LLM summaries (cqs index --llm-summaries): Sends function code to the Anthropic API

• HyDE queries (cqs index --llm-summaries --hyde-queries): Sends function descriptions to the Anthropic API for synthetic query generation

• Model export (cqs export-model): Spawns Python optimum.exporters.onnx which downloads the specified HuggingFace model and converts to ONNX format

No other network requests are made. Without --llm-summaries or export-model, all operations are offline.

cqs serve --open historically spawned the OS browser launcher with the full http://<bind>/?token=<token> URL on argv. That places the token in /proc/<pid>/cmdline (Linux) / wmic process get CommandLine (Windows) for any local user to read until the launcher exits, and audit subsystems (auditd, ETW) typically capture exec command lines independently of process lifetime — same surface the per-launch banner already avoids by routing the token to stderr instead of journald.

Mitigation (#1337 / SEC-V1.33-1): when cqs serve runs with auth enabled (the default), --open no longer spawns a browser. The CLI prints a notice instructing the user to paste the banner URL manually; the token is never written to a subprocess argv. With --no-auth there is no token to leak and --open continues to launch the browser normally.

The convert module spawns external processes for format conversion:

Attack surface:

• CQS_PDF_SCRIPT env var: If set, the convert module executes the specified script instead of the default PDF conversion logic. This allows arbitrary script execution under the user's permissions.
• Output directory: Generated Markdown files are written to the --output directory. The output path is not sandboxed beyond normal filesystem permissions.

Mitigations:

• Symlink filtering: Symlinks are skipped during directory walks and archive extraction
• Zip-slip containment: Extracted paths are validated to stay within the output directory
• Page count limits: PDF conversion enforces a maximum page count to bound processing time

The export-model command spawns Python to convert HuggingFace models to ONNX format:

Attack surface:

• Repo ID: Passed to python -m optimum.exporters.onnx --model <repo>. Validated to contain / and reject ", \n, \ characters (SEC-18).
• Output directory: Model files and model.toml written to --output path. Not sandboxed beyond filesystem permissions.
• Python execution: Spawns Python with user permissions to run optimum library code.

Mitigations:

• Repo ID format validation prevents injection (SEC-18)
• Output path canonicalized via dunce::canonicalize (PB-30)
• model.toml restricted to 0o600 permissions on Unix (SEC-19)

The cqs read command validates paths:

let canonical = dunce::canonicalize(&file_path)?;
let project_canonical = dunce::canonicalize(root)?;
if !canonical.starts_with(&project_canonical) {
    bail!("Path traversal not allowed: {}", path);
}

This blocks:

• ../../../etc/passwd - resolved and rejected
• Absolute paths outside project - rejected
• Symlinks pointing outside - resolved then rejected

cqs has two symlink-handling regimes, depending on the entry point.

Symlinks are skipped entirely — enumerate_files / enumerate_files_iter in src/lib.rs (search for WalkBuilder::follow_links(false)) and cqs convert's archive extraction skip them in extract paths. The walker never opens the link's target.

This is conservative: a monorepo workspace that uses in-tree symlinks to share common code will silently miss those files. Workaround: replace the symlinks with the actual files (or use a [references] config block to index the shared tree as a separate slot).

When the user passes a path on the command line, cqs canonicalizes it (dunce::canonicalize), then validates the resolved path against the project root.

cqs ref add --source <path> redirect surfacing (since v1.30.2, #1222): when the user-supplied --source path resolves through a symlink to a different filesystem location, cmd_ref_add emits a tracing::warn! (and a WARN: line on stderr in non---quiet text mode) naming both the user-supplied and resolved paths. JSON output gains a warnings: ["source path '<input>' resolved via symlink to '<target>'"] field. The reference is still indexed at the resolved path — the warning exists so an operator who ran cqs ref add foo vendored-monorepo-pull/ against a symlink to ~/work/customer-A-private/ can see what they actually pulled in. Lexical normalization (.., ., repeated separators) is applied before comparison so purely syntactic differences in the input don't trigger false positives.

TOCTOU consideration: A symlink could theoretically be changed between canonicalization and read. This is a standard filesystem race condition that affects all programs. Mitigation would require O_NOFOLLOW or similar, which would break legitimate symlink use cases on cqs read.

Recommendation: If you don't trust symlinks in your project, remove them. The directory-walk path is already conservative.

Several cfg(unix) paths apply file-mode hardening that the cfg(not(unix)) arms can't replicate without per-file ACL programming. Documented here so the SEC promises don't read as universal when they're actually Linux/macOS-specific.

• Linux/macOS: file is created with mode(0o600) so it's never world-readable; the audit token can't be read by other accounts on a shared host.
• Windows: file is created via std::fs::write and inherits the parent directory's DACL. The default %LOCALAPPDATA%\cqs\ location inherits user-only ACLs from the user profile, which is fine — but operators with roaming profiles, or who've relocated %LOCALAPPDATA% to a shared mount (some enterprise deployments), can end up with the audit-mode file readable by other authenticated users on the same machine.
• Recommendation: on Windows, verify the parent directory's ACL doesn't grant read to other users before treating the audit-mode marker as a confidentiality boundary. Audit-mode is a debugging aid, not a credential store; the file contains a timestamp + opt-in flag, not a token.

• Linux/macOS: apply_db_file_perms sets mode(0o600) after creation.
• Windows: apply_db_file_perms(_path: &Path) {} is a no-op. Same DACL inheritance story as above. The cache contains chunk content_hashes + embedding vectors — not directly sensitive, but the same operator-environment caveat applies.

• Linux/macOS: identity is (dev, inode) — durable across mtime changes from --force reindexes.
• Windows / non-Unix: identity falls back to mtime, which can collide if two --force operations run in the same second. The legacy backup discovery path (used only for the v18→v19 migration on existing indexes) may misidentify a fresh DB as the pre-migration one. Mitigated in practice because the v18→v19 migration shipped over a year ago and operators on current schemas don't hit this code path.

• The cqs hook install script body assumes cqs is on PATH from a POSIX-style shell. On Windows-native Git (cmd.exe / PowerShell), the inherited PATH from MSYS shells doesn't always carry over. Operators on native-Windows git should use Git for Windows' bundled bash for the hook scripts to fire reliably.

These limitations are tracked as Windows-specific issues in the v1.33.0 audit batch (#1353, #1354, #1355).

• Stored in .cqs/slots/<name>/index.db (SQLite with WAL mode; PR #1105 introduced per-slot layout, pre-migration projects may still see the legacy .cqs/index.db)
• Contains: code chunks, embeddings (768-dim vectors for default embeddinggemma-300m since v1.35.0; 1024-dim for bge-large preset), file metadata
• Add .cqs/ to .gitignore to avoid committing
• Database is not encrypted - it contains your code
• Schema v27 (#1497) adds chunks.needs_embedding; chunks created during a --llm-summaries reindex skip the initial cold embed and get embedded once the LLM-enriched description is available, then cleared by enrichment_pass. This is behavior-visible to anyone tracing a "why isn't this chunk in HNSW yet?" path mid-index — see docs/audit-triage.md Cluster A for the gap closures (DS-V1.38-1/2/3/8, #1514).

• Dependabot: Automated weekly checks for crate updates
• CI workflow: Runs clippy with -D warnings to catch issues
• cargo audit: Runs in CI, allowed warnings documented in audit.toml
• No secrets in CI: Build and test only, no publish credentials exposed

The main branch is protected by a GitHub ruleset:

• Pull requests required: All changes go through PR
• Status checks required: test, clippy, fmt must pass
• Force push blocked: History cannot be rewritten

Known advisories and mitigations:

Run cargo audit to check current status.

Report security issues to: https://github.com/jamie8johnson/cqs/issues

Use a private security advisory for sensitive issues.