ghostrules 0.1.0__py3-none-any.whl

ghostrules/scanner.py

@@ -0,0 +1,244 @@
+"""The scan pipeline: discover -> load -> run rules -> suppress -> decode pass -> filter -> sort."""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Iterable
+from dataclasses import replace
+from pathlib import Path
+from typing import Any
+
+from ghostrules._compat import tomllib
+from ghostrules.config import Config
+from ghostrules.jsonloc import strip_jsonc
+from ghostrules.models import Finding, ScanResult, ScanTarget
+from ghostrules.rules import Rule, all_rules
+from ghostrules.secrets import mask_secrets
+from ghostrules.targets import Candidate, discover, home_targets
+
+# Invisible-character findings must never be silenceable from inside the scanned file.
+NEVER_SUPPRESS: frozenset[str] = frozenset({"GR001", "GR002"})
+
+_IGNORE_RE = re.compile(r"ghostrules-ignore(?:\s*:\s*((?:GR\d{3}(?:\s*,\s*)?)+))?", re.IGNORECASE)
+_RULE_ID_RE = re.compile(r"GR\d{3}", re.IGNORECASE)
+
+# Maps a 1-based line number to the rule ids it ignores; ``None`` means every rule.
+Suppressions = dict[int, "frozenset[str] | None"]
+
+
+def parse_structured(path: str, text: str) -> tuple[Any, str | None]:
+    """Parse JSON (tolerating JSONC) or TOML by extension. Returns ``(parsed, error)``."""
+    lowered = path.lower()
+    try:
+        if lowered.endswith(".json"):
+            body = text.removeprefix("\ufeff")
+            try:
+                return json.loads(body), None
+            except json.JSONDecodeError:
+                return json.loads(strip_jsonc(body)), None
+        if lowered.endswith(".toml"):
+            return tomllib.loads(text.removeprefix("\ufeff")), None
+    except (json.JSONDecodeError, tomllib.TOMLDecodeError, RecursionError) as exc:
+        return None, str(exc)
+    return None, None
+
+
+def load_target(
+    candidate: Candidate, label: str | None = None, allow_domains: tuple[str, ...] = ()
+) -> ScanTarget:
+    """Read a candidate as UTF-8 (``surrogateescape``, so bad bytes never crash) and parse it."""
+    data = candidate.abs_path.read_bytes()
+    text = data.decode("utf-8", errors="surrogateescape")
+    path = label or candidate.rel
+    parsed, error = (None, None) if candidate.kind == "other" else parse_structured(path, text)
+    return ScanTarget(
+        path=path,
+        kind=candidate.kind,
+        text=text,
+        parsed=parsed,
+        parse_error=error,
+        allow_domains=allow_domains,
+    )
+
+
+def parse_suppressions(lines: Iterable[str]) -> Suppressions:
+    """Find ``ghostrules-ignore[: GR010,GR012]`` markers; each covers its line and the next."""
+    table: Suppressions = {}
+    for number, line in enumerate(lines, start=1):
+        match = _IGNORE_RE.search(line)
+        if not match:
+            continue
+        ids = match.group(1)
+        scope = frozenset(m.upper() for m in _RULE_ID_RE.findall(ids)) if ids else None
+        for covered in (number, number + 1):
+            existing = table.get(covered, frozenset())
+            if scope is None or existing is None:
+                table[covered] = None
+            else:
+                table[covered] = existing | scope
+    return table
+
+
+def is_suppressed(finding: Finding, table: Suppressions) -> bool:
+    """Whether an inline marker silences this finding (never GR001/GR002)."""
+    if finding.rule_id in NEVER_SUPPRESS or finding.line not in table:
+        return False
+    scope = table[finding.line]
+    return scope is None or finding.rule_id in scope
+
+
+def _applicable(rules: Iterable[Rule], config: Config) -> list[Rule]:
+    return [r for r in rules if r.id not in config.disable]
+
+
+def _run_rules(target: ScanTarget, rules: Iterable[Rule], errors: list[str]) -> list[Finding]:
+    """Run applicable rules; a crashing rule is recorded in ``errors`` rather than aborting."""
+    found: list[Finding] = []
+    for r in rules:
+        if target.kind not in r.applies_to:
+            continue
+        try:
+            found.extend(r.check(target))
+        except Exception as exc:  # a buggy rule must not hide every other finding
+            detail = mask_secrets(f"{type(exc).__name__}: {exc}")
+            errors.append(f"rule {r.id} failed on {target.path}: {detail}")
+    return found
+
+
+def _scan_decoded(
+    target: ScanTarget, parents: Iterable[Finding], rules: Iterable[Rule], errors: list[str]
+) -> list[Finding]:
+    """Run ``scans_decoded`` rules over hidden text recovered by other rules.
+
+    Results are attributed to the parent's location, carry the decoded text, and get +1 severity.
+    """
+    decoding_rules = [r for r in rules if r.scans_decoded]
+    derived: list[Finding] = []
+    for parent in parents:
+        if not parent.decoded:
+            continue
+        virtual = ScanTarget(
+            path=target.path,
+            kind="instructions",
+            text=parent.decoded,
+            origin=parent.rule_id,
+            allow_domains=target.allow_domains,
+        )
+        for hit in _run_rules(virtual, decoding_rules, errors):
+            derived.append(
+                replace(
+                    hit,
+                    severity=hit.severity.bumped(),
+                    line=parent.line,
+                    column=parent.column,
+                    end_column=parent.end_column,
+                    snippet=parent.snippet,
+                    decoded=parent.decoded,
+                    message=f"{hit.message} (found in hidden text decoded by {parent.rule_id})",
+                )
+            )
+    return derived
+
+
+def scan_target(
+    target: ScanTarget, config: Config, rules: Iterable[Rule]
+) -> tuple[list[Finding], int, list[str]]:
+    """Scan one target. Returns ``(findings, suppressed_count, errors)``.
+
+    Findings derived from decoded hidden text are added after suppression is applied, so an
+    inline ignore comment can never silence something that was hidden in invisible characters.
+    """
+    errors: list[str] = []
+    active = _applicable(rules, config)
+    table = parse_suppressions(target.lines)
+    kept: list[Finding] = []
+    suppressed = 0
+    for finding in _run_rules(target, active, errors):
+        if is_suppressed(finding, table):
+            suppressed += 1
+        else:
+            kept.append(finding)
+    kept.extend(_scan_decoded(target, kept, active, errors))
+    return kept, suppressed, errors
+
+
+def _dedupe(findings: Iterable[Finding]) -> list[Finding]:
+    unique: dict[tuple[object, ...], Finding] = {}
+    for f in findings:
+        key = (f.rule_id, f.path, f.line, f.column, f.end_column, f.title, f.decoded)
+        unique.setdefault(key, f)
+    return list(unique.values())
+
+
+def sort_findings(findings: Iterable[Finding]) -> list[Finding]:
+    """Order by severity (most severe first), hidden-text findings first among equals, then
+    files closer to the root, path, line, column and rule id."""
+    return sorted(
+        findings,
+        key=lambda f: (
+            -int(f.severity),
+            not f.decoded,
+            f.path.count("/"),
+            f.path,
+            f.line,
+            f.column,
+            f.rule_id,
+        ),
+    )
+
+
+def scan_paths(
+    paths: Iterable[Path],
+    config: Config,
+    *,
+    all_files: bool = False,
+    include_home: bool = False,
+    rules: Iterable[Rule] | None = None,
+    home_dir: Path | None = None,
+) -> ScanResult:
+    """Scan one or more files/directories (plus user-level configs with ``include_home``).
+
+    With a single root, reported paths are relative to it; with several, each path is prefixed
+    by the root as given so entries stay unambiguous.
+    """
+    rule_list = list(all_rules() if rules is None else rules)
+    roots = list(paths)
+    result = ScanResult(config_source=config.source)
+
+    candidates: list[tuple[Candidate, str]] = []
+    for root in roots:
+        if not root.exists():
+            result.errors.append(f"path not found: {root}")
+            continue
+        for cand in discover(
+            root, all_files=all_files, exclude=config.exclude, extra_targets=config.extra_targets
+        ):
+            label = cand.rel if len(roots) == 1 or root.is_file() else (root / cand.rel).as_posix()
+            candidates.append((cand, label))
+    if include_home:
+        candidates.extend((cand, cand.rel) for cand in home_targets(home_dir))
+
+    seen: set[Path] = set()
+    findings: list[Finding] = []
+    for cand, label in candidates:
+        resolved = cand.abs_path.resolve()
+        if resolved in seen:
+            continue
+        seen.add(resolved)
+        try:
+            target = load_target(cand, label, config.allow_domains)
+        except OSError as exc:
+            result.warnings.append(f"cannot read {label}: {exc.strerror or exc}")
+            continue
+        result.scanned_files += 1
+        if target.parse_error:
+            result.warnings.append(mask_secrets(f"cannot parse {label}: {target.parse_error}"))
+        kept, suppressed, errors = scan_target(target, config, rule_list)
+        findings.extend(kept)
+        result.suppressed += suppressed
+        result.errors.extend(errors)
+
+    visible = [f for f in _dedupe(findings) if f.severity >= config.min_severity]
+    result.findings = sort_findings(visible)
+    return result

ghostrules/secrets.py

@@ -0,0 +1,219 @@
+"""Secret detection and masking. Every piece of output goes through this module.
+
+Masking rule: a secret of at least 20 characters is shown as its first 4 and last 4 characters
+around ``****…`` (``ghp_****…a1b2``); shorter ones as ``****``. ``mask_secrets`` finds secrets in
+arbitrary text (known token formats, bearer tokens, URL passwords, and ``key=value`` pairs whose
+key name looks secret and whose value looks like one). It is idempotent. ``Finding`` applies it to
+all of its text fields, so no reporter can print an unmasked secret.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from collections import Counter
+from collections.abc import Iterable
+from typing import NamedTuple
+
+_MASK_MIN_LENGTH = 20
+_MIN_GENERIC_LENGTH = 16
+_MIN_GENERIC_ENTROPY = 3.5
+
+# (label, pattern). The named group ``s`` is the secret part; no group means the whole match.
+_KNOWN_SOURCES: tuple[tuple[str, str], ...] = (
+    ("GitHub token", r"(?<![A-Za-z0-9])gh[pousr]_[A-Za-z0-9]{36,255}"),
+    ("GitHub fine-grained token", r"(?<![A-Za-z0-9])github_pat_[A-Za-z0-9_]{22,255}"),
+    ("Anthropic API key", r"(?<![A-Za-z0-9])sk-ant-[A-Za-z0-9_-]{20,}"),
+    ("OpenAI API key", r"(?<![A-Za-z0-9])sk-(?:proj-)?[A-Za-z0-9_-]{20,}"),
+    ("AWS access key", r"(?<![A-Za-z0-9])(?:AKIA|ASIA)[0-9A-Z]{16}"),
+    ("Slack token", r"(?<![A-Za-z0-9])xox[baprs]-[A-Za-z0-9-]{10,}"),
+    ("Google API key", r"(?<![A-Za-z0-9])AIza[0-9A-Za-z_-]{35}"),
+    ("GitLab token", r"(?<![A-Za-z0-9])glpat-[0-9A-Za-z_-]{20,}"),
+    ("Hugging Face token", r"(?<![A-Za-z0-9])hf_[A-Za-z0-9]{30,}"),
+    ("npm token", r"(?<![A-Za-z0-9])npm_[A-Za-z0-9]{36,}"),
+    (
+        "Slack webhook",
+        r"https://hooks\.slack\.com/services/T[A-Z0-9]+/B[A-Z0-9]+/(?P<s>[A-Za-z0-9*…]+)",
+    ),
+    (
+        "Discord webhook",
+        r"https://(?:ptb\.|canary\.)?discord(?:app)?\.com/api/(?:v\d+/)?webhooks/\d+/"
+        r"(?P<s>[A-Za-z0-9_*…-]+)",
+    ),
+    ("Bearer token", r"Bearer\s+(?P<s>[A-Za-z0-9._~+/-]{20,}={0,2})"),
+)
+_BOUNDARY = r"(?<![A-Za-z0-9])"
+KNOWN_SECRET_PATTERNS: tuple[tuple[str, re.Pattern[str]], ...] = tuple(
+    (label, re.compile(pattern)) for label, pattern in _KNOWN_SOURCES
+)
+# For masking, secrets glued to other letters ("xghp_...") must still be hidden, so the
+# word-boundary guard used for *detection* is dropped. The ambiguous OpenAI prefix ("sk-" also ends
+# words like "task-") then needs a digit and some entropy to count.
+_MASK_PATTERNS: tuple[tuple[str, re.Pattern[str]], ...] = tuple(
+    (label, re.compile(pattern.replace(_BOUNDARY, ""))) for label, pattern in _KNOWN_SOURCES
+)
+
+_NAME_WORDS = r"(?:token|secret|key|password|passwd|auth)"
+_SECRET_NAME_RE = re.compile(_NAME_WORDS, re.IGNORECASE)
+_VALUE_CHARS = r"[^\s\"'`,;&)}\]]"
+_KEY_VALUE_RES = (
+    # key = value / "key": "value" / key: value
+    re.compile(
+        rf"(?<![\w.-])(?P<k>[\"']?[\w.-]*{_NAME_WORDS}[\w.-]*[\"']?\s*[:=]\s*[\"']?)"
+        rf"(?P<s>{_VALUE_CHARS}{{16,}})",
+        re.IGNORECASE,
+    ),
+    # --api-token VALUE
+    re.compile(
+        rf"(?<![\w.-])(?P<k>--[\w-]*{_NAME_WORDS}[\w-]*\s+[\"']?)(?P<s>{_VALUE_CHARS}{{16,}})",
+        re.IGNORECASE,
+    ),
+)
+_URL_PASSWORD_RE = re.compile(r"://[^/\s:@]+:(?P<s>[^@\s/]{3,})@")
+_PLACEHOLDER_WORDS_RE = re.compile(
+    r"(?:your|my)[-_ ].*(?:here|key|token|secret|password)"
+    r"|x{4,}|\*{4,}|\.{3,}|changeme|placeholder|redacted|example-?token|todo",
+    re.IGNORECASE,
+)
+
+
+class Replacement(NamedTuple):
+    """Replace ``text[start:end]`` by ``text``."""
+
+    start: int
+    end: int
+    text: str
+
+
+def shannon_entropy(text: str) -> float:
+    """Shannon entropy in bits per character."""
+    if not text:
+        return 0.0
+    total = len(text)
+    return -sum(n / total * math.log2(n / total) for n in Counter(text).values())
+
+
+def mask_value(value: str) -> str:
+    """Mask one secret: ``ghp_****…a1b2`` for long values, ``****`` for short ones."""
+    if len(value) < _MASK_MIN_LENGTH:
+        return "****"
+    return f"{value[:4]}****…{value[-4:]}"
+
+
+def is_placeholder(value: str) -> bool:
+    """True for variable references (``${VAR}``, ``<token>``) and dummy values."""
+    s = value.strip()
+    return (
+        not s
+        or "${" in s
+        or "{{" in s
+        or s.startswith(("$", "<"))
+        or (s.startswith("%") and s.endswith("%"))
+        or len(set(s)) == 1
+        or "****" in s
+        or _PLACEHOLDER_WORDS_RE.fullmatch(s) is not None
+    )
+
+
+def is_secret_key_name(name: str) -> bool:
+    """Whether a key/flag/variable name suggests it holds a secret."""
+    return _SECRET_NAME_RE.search(name) is not None
+
+
+def looks_like_secret_value(value: str) -> bool:
+    """Heuristic for a generic secret: long, high-entropy, no spaces, not a placeholder/URL/path."""
+    if (
+        len(value) < _MIN_GENERIC_LENGTH
+        or any(c.isspace() for c in value)
+        or is_placeholder(value)
+        or value.startswith(("/", "~", "./", "../"))
+        or re.match(r"[A-Za-z][A-Za-z0-9+.-]*://", value)
+        or re.match(r"[A-Za-z]:[\\/]", value)
+    ):
+        return False
+    return shannon_entropy(value) >= _MIN_GENERIC_ENTROPY
+
+
+def known_secret(text: str) -> tuple[str, str] | None:
+    """The first known-format secret in ``text`` as ``(label, secret)``, or ``None``."""
+    for label, pattern in KNOWN_SECRET_PATTERNS:
+        group = "s" if "s" in pattern.groupindex else 0
+        for m in pattern.finditer(text):
+            if not is_placeholder(m.group(group)):
+                return label, m.group(group)
+    return None
+
+
+def _plausible_glued_key(value: str) -> bool:
+    return any(c.isdigit() for c in value) and shannon_entropy(value) >= _MIN_GENERIC_ENTROPY
+
+
+def _candidates(text: str, extra: Iterable[str]) -> list[Replacement]:
+    found: list[Replacement] = []
+    for label, pattern in _MASK_PATTERNS:
+        for m in pattern.finditer(text):
+            group = "s" if "s" in pattern.groupindex else 0
+            value = m.group(group)
+            if is_placeholder(value):
+                continue
+            glued = m.start(group) > 0 and text[m.start(group) - 1].isalnum()
+            if label == "OpenAI API key" and glued and not _plausible_glued_key(value):
+                continue
+            found.append(Replacement(m.start(group), m.end(group), mask_value(value)))
+    for m in _URL_PASSWORD_RE.finditer(text):
+        found.append(Replacement(m.start("s"), m.end("s"), "****"))
+    for pattern in _KEY_VALUE_RES:
+        for m in pattern.finditer(text):
+            if looks_like_secret_value(m.group("s")):
+                found.append(Replacement(m.start("s"), m.end("s"), mask_value(m.group("s"))))
+    for secret in extra:
+        if secret:
+            for m in re.finditer(re.escape(secret), text):
+                found.append(Replacement(m.start(), m.end(), mask_value(secret)))
+    return found
+
+
+def mask_spans(text: str, extra: Iterable[str] = ()) -> list[Replacement]:
+    """Non-overlapping replacements masking every secret in ``text``.
+
+    ``extra`` lists exact secret values the caller already knows (for example a generic secret
+    found by a rule) that must be masked wherever they occur.
+    """
+    kept: list[Replacement] = []
+    for rep in sorted(_candidates(text, tuple(extra)), key=lambda r: (r.start, -r.end)):
+        if not kept or rep.start >= kept[-1].end:
+            kept.append(rep)
+    return kept
+
+
+def apply_spans(text: str, spans: Iterable[Replacement]) -> str:
+    """Apply replacements produced by ``mask_spans``."""
+    out: list[str] = []
+    pos = 0
+    for rep in spans:
+        out.append(text[pos : rep.start])
+        out.append(rep.text)
+        pos = rep.end
+    out.append(text[pos:])
+    return "".join(out)
+
+
+def map_offset(spans: Iterable[Replacement], offset: int, *, end: bool = False) -> int:
+    """Translate an offset in the original text to the masked text.
+
+    An offset inside a replaced secret snaps to the start of its replacement (or to its end when
+    ``end`` is true), so a span covering a secret still covers its mask.
+    """
+    shift = 0
+    for rep in spans:
+        if offset <= rep.start:
+            break
+        if offset < rep.end:
+            return rep.start + shift + (len(rep.text) if end else 0)
+        shift += len(rep.text) - (rep.end - rep.start)
+    return offset + shift
+
+
+def mask_secrets(text: str, extra: Iterable[str] = ()) -> str:
+    """Return ``text`` with every secret masked."""
+    return apply_spans(text, mask_spans(text, extra))

ghostrules/targets.py

@@ -0,0 +1,220 @@
+"""Which files ghostrules scans, and how it finds them. Extend the glob lists below."""
+
+from __future__ import annotations
+
+import os
+import re
+import sys
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+from functools import cache
+from pathlib import Path
+
+from ghostrules.models import Kind
+
+INSTRUCTION_GLOBS: tuple[str, ...] = (
+    "AGENTS.md",
+    "**/AGENTS.md",
+    "AGENT.md",
+    "CLAUDE.md",
+    "CLAUDE.local.md",
+    "**/CLAUDE.md",
+    ".claude/commands/**/*.md",
+    ".claude/agents/**/*.md",
+    ".claude/skills/**/*.md",
+    "**/SKILL.md",
+    ".cursorrules",
+    ".cursor/rules/**/*.mdc",
+    ".cursor/rules/**/*.md",
+    ".github/copilot-instructions.md",
+    ".github/instructions/**/*.instructions.md",
+    ".github/prompts/**/*.prompt.md",
+    ".github/chatmodes/**/*.md",
+    ".windsurfrules",
+    ".windsurf/rules/**",
+    ".clinerules",
+    ".clinerules/**",
+    ".roo/rules*/**",
+    ".roorules",
+    "GEMINI.md",
+    ".gemini/**/*.md",
+    ".junie/guidelines.md",
+    ".kiro/steering/**/*.md",
+    ".continue/rules/**",
+    "CONVENTIONS.md",
+)
+
+CONFIG_GLOBS: tuple[str, ...] = (
+    ".mcp.json",
+    "mcp.json",
+    ".cursor/mcp.json",
+    ".vscode/mcp.json",
+    ".gemini/settings.json",
+    "claude_desktop_config.json",
+    ".roo/mcp.json",
+    ".claude/settings.json",
+    ".claude/settings.local.json",
+    ".aider.conf.yml",
+)
+
+SKIP_DIRS: frozenset[str] = frozenset({".git", "node_modules", ".venv"})
+MAX_OTHER_FILE_BYTES = 2 * 1024 * 1024
+_BINARY_SNIFF_BYTES = 8192
+
+
+@dataclass(frozen=True)
+class Candidate:
+    """A file selected for scanning. ``rel`` is the display path (POSIX separators)."""
+
+    abs_path: Path
+    rel: str
+    kind: Kind
+
+
+def glob_to_regex(pattern: str) -> re.Pattern[str]:
+    """Compile a glob into a case-insensitive regex over POSIX relative paths.
+
+    ``*`` and ``?`` stay within one path segment; ``**/`` matches zero or more directories and a
+    trailing ``**`` matches everything below.
+    """
+    pattern = pattern.replace("\\", "/")  # patterns written with Windows separators
+    out: list[str] = []
+    i = 0
+    while i < len(pattern):
+        if pattern.startswith("**/", i):
+            out.append("(?:.*/)?")
+            i += 3
+        elif pattern.startswith("**", i):
+            out.append(".*")
+            i += 2
+        elif pattern[i] == "*":
+            out.append("[^/]*")
+            i += 1
+        elif pattern[i] == "?":
+            out.append("[^/]")
+            i += 1
+        else:
+            out.append(re.escape(pattern[i]))
+            i += 1
+    return re.compile("".join(out), re.IGNORECASE)
+
+
+@cache
+def _compile_all(globs: tuple[str, ...]) -> tuple[re.Pattern[str], ...]:
+    return tuple(glob_to_regex(g) for g in globs)
+
+
+def matches_any(rel: str, globs: Iterable[str]) -> bool:
+    """True if the relative path (either separator style) matches any glob."""
+    rel = rel.replace("\\", "/")
+    return any(p.fullmatch(rel) for p in _compile_all(tuple(globs)))
+
+
+def classify_path(rel: str, extra_targets: Iterable[str] = ()) -> Kind | None:
+    """Kind of a known target file, or ``None`` if the path is not a default/extra target."""
+    if matches_any(rel, INSTRUCTION_GLOBS) or matches_any(rel, extra_targets):
+        return "instructions"
+    if matches_any(rel, CONFIG_GLOBS):
+        return "config"
+    return None
+
+
+def looks_binary(path: Path) -> bool:
+    """Heuristic: a NUL byte in the first 8 KiB means binary."""
+    try:
+        with path.open("rb") as handle:
+            return b"\x00" in handle.read(_BINARY_SNIFF_BYTES)
+    except OSError:
+        return True
+
+
+def _acceptable_other(path: Path) -> bool:
+    """Whether an unrecognised file is worth scanning under ``--all-files``."""
+    try:
+        if path.stat().st_size > MAX_OTHER_FILE_BYTES:
+            return False
+    except OSError:
+        return False
+    return not looks_binary(path)
+
+
+def discover(
+    root: Path,
+    *,
+    all_files: bool = False,
+    exclude: Iterable[str] = (),
+    extra_targets: Iterable[str] = (),
+) -> list[Candidate]:
+    """Find scannable files under ``root`` (or the single file ``root``).
+
+    Symlinks are never followed. Known targets are always selected whatever their size or
+    content, so padding a file cannot hide it; the size and binary checks only gate the
+    unrecognised files that ``all_files`` adds. An explicitly named file is always scanned.
+    """
+    excludes = tuple(exclude)
+    extras = tuple(extra_targets)
+    if root.is_file():
+        kind = classify_path(root.name, extras) or "other"
+        return [Candidate(root, root.name, kind)]
+
+    found: list[Candidate] = []
+    for dirpath, dirnames, filenames in os.walk(root, followlinks=False):
+        dirnames[:] = sorted(d for d in dirnames if d not in SKIP_DIRS)
+        base = Path(dirpath)
+        for name in sorted(filenames):
+            path = base / name
+            if path.is_symlink():
+                continue
+            rel = path.relative_to(root).as_posix()
+            if excludes and matches_any(rel, excludes):
+                continue
+            known = classify_path(rel, extras)
+            if known is not None:
+                found.append(Candidate(path, rel, known))
+            elif all_files and _acceptable_other(path):
+                found.append(Candidate(path, rel, "other"))
+    return found
+
+
+def _desktop_config(home: Path, platform: str, env: Mapping[str, str]) -> Path:
+    if platform == "darwin":
+        return home / "Library/Application Support/Claude/claude_desktop_config.json"
+    if platform == "win32":
+        appdata = env.get("APPDATA")
+        base = Path(appdata) if appdata else home / "AppData/Roaming"
+        return base / "Claude/claude_desktop_config.json"
+    return home / ".config/Claude/claude_desktop_config.json"
+
+
+def home_targets(
+    home: Path | None = None,
+    platform: str | None = None,
+    env: Mapping[str, str] | None = None,
+) -> list[Candidate]:
+    """User-level agent configs that exist on this machine (``--home``). Missing ones are skipped.
+
+    Unlike repo scanning, symlinks are accepted here: dotfile managers commonly symlink these.
+    """
+    home = home or Path.home()
+    platform = platform or sys.platform
+    env = os.environ if env is None else env
+    entries: list[tuple[Path, Kind]] = [
+        (home / ".claude.json", "config"),
+        (home / ".claude/settings.json", "config"),
+        (home / ".claude/CLAUDE.md", "instructions"),
+        (home / ".cursor/mcp.json", "config"),
+        (home / ".codeium/windsurf/mcp_config.json", "config"),
+        (home / ".gemini/settings.json", "config"),
+        (home / ".codex/config.toml", "config"),
+        (_desktop_config(home, platform, env), "config"),
+    ]
+    out: list[Candidate] = []
+    for path, kind in entries:
+        if not path.is_file():
+            continue
+        try:
+            label = "~/" + path.relative_to(home).as_posix()
+        except ValueError:
+            label = path.as_posix()
+        out.append(Candidate(path, label, kind))
+    return out