secure-code-agent 0.10.0__tar.gz → 0.11.0__tar.gz

{secure_code_agent-0.10.0/src/secure_code_agent.egg-info → secure_code_agent-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: secure-code-agent
-Version: 0.10.0
+Version: 0.11.0
 Summary: Deterministic security gate + bounded AI remediation prompt generator. NIST SSDF / OWASP ASVS / CWE Top 25 anchored.
 Author: Marshall Guillory
 License: MIT
@@ -62,6 +62,34 @@ The sibling of [`maintainability-agent`](https://github.com/marshallguillory86/m
 
 ---
 
+## Try it in one command
+
+```bash
+pip install 'secure-code-agent[python-scanners]'
+secure-code-agent --demo
+```
+
+`--demo` generates a small application carrying seven real defects — SQL
+injection, command injection, unsafe deserialization, a weak hash, dynamic
+evaluation — audits it, and writes the work order you would hand an agent. The
+tree is generated at runtime into a temp directory, so installing this tool
+never puts vulnerable source on your disk.
+
+To audit something real:
+
+```bash
+secure-code-agent /path/to/repo
+```
+
+Any scanner that is missing is named, with the command to install it. This
+tool never installs anything itself — naming a command is not running one —
+and it will not grade what it could not examine. `--preflight` checks the
+whole floor before a run.
+
+A pure-Python repository requires six of the ten floor scanners; the Ruby,
+JavaScript and container tools are *not applicable* rather than missing, so a
+single-language project is never permanently incomplete.
+
 ## Why this exists
 
 AI coding agents ship code at human-review-saturating speed. Point them at a security finding and the documented anti-patterns are:
@@ -442,7 +470,7 @@ For agents that support invokable skills, this repo ships a portable skill under
 ## GitHub Action
 
 ```yaml
-- uses: marshallguillory86/secure-code-agent@v0.3.0
+- uses: marshallguillory86/secure-code-agent@v0.11.0
   with:
     config: secure-code-agent.json
     fail-on-gate: true
@@ -508,7 +536,7 @@ Full design philosophy in [`docs/design.md`](docs/design.md).
 - [`docs/calibration.md`](docs/calibration.md)   — The calibration study, its corpus, and what it found
 - [`docs/design.md`](docs/design.md)              — Architecture + non-goals + scanner protocol
 - [`docs/architecture.md`](docs/architecture.md)  — Audit of the system as built + remediation sequence
-- [`docs/release-blockers.md`](docs/release-blockers.md) — Open v0.3.0 release blockers (do not tag until closed)
+- [`docs/release-blockers.md`](docs/release-blockers.md) — the v0.3.0 release blockers, all closed (historical)
 - [`docs/standards.md`](docs/standards.md)        — NIST SSDF / OWASP / CWE / Scorecard / SARIF citations
 - [`docs/scoring.md`](docs/scoring.md)            — Weighting model + worked examples
 - [`docs/scanners.md`](docs/scanners.md)          — Per-scanner integrations + caveats

{secure_code_agent-0.10.0 → secure_code_agent-0.11.0}/README.md

@@ -16,6 +16,34 @@ The sibling of [`maintainability-agent`](https://github.com/marshallguillory86/m
 
 ---
 
+## Try it in one command
+
+```bash
+pip install 'secure-code-agent[python-scanners]'
+secure-code-agent --demo
+```
+
+`--demo` generates a small application carrying seven real defects — SQL
+injection, command injection, unsafe deserialization, a weak hash, dynamic
+evaluation — audits it, and writes the work order you would hand an agent. The
+tree is generated at runtime into a temp directory, so installing this tool
+never puts vulnerable source on your disk.
+
+To audit something real:
+
+```bash
+secure-code-agent /path/to/repo
+```
+
+Any scanner that is missing is named, with the command to install it. This
+tool never installs anything itself — naming a command is not running one —
+and it will not grade what it could not examine. `--preflight` checks the
+whole floor before a run.
+
+A pure-Python repository requires six of the ten floor scanners; the Ruby,
+JavaScript and container tools are *not applicable* rather than missing, so a
+single-language project is never permanently incomplete.
+
 ## Why this exists
 
 AI coding agents ship code at human-review-saturating speed. Point them at a security finding and the documented anti-patterns are:
@@ -396,7 +424,7 @@ For agents that support invokable skills, this repo ships a portable skill under
 ## GitHub Action
 
 ```yaml
-- uses: marshallguillory86/secure-code-agent@v0.3.0
+- uses: marshallguillory86/secure-code-agent@v0.11.0
   with:
     config: secure-code-agent.json
     fail-on-gate: true
@@ -462,7 +490,7 @@ Full design philosophy in [`docs/design.md`](docs/design.md).
 - [`docs/calibration.md`](docs/calibration.md)   — The calibration study, its corpus, and what it found
 - [`docs/design.md`](docs/design.md)              — Architecture + non-goals + scanner protocol
 - [`docs/architecture.md`](docs/architecture.md)  — Audit of the system as built + remediation sequence
-- [`docs/release-blockers.md`](docs/release-blockers.md) — Open v0.3.0 release blockers (do not tag until closed)
+- [`docs/release-blockers.md`](docs/release-blockers.md) — the v0.3.0 release blockers, all closed (historical)
 - [`docs/standards.md`](docs/standards.md)        — NIST SSDF / OWASP / CWE / Scorecard / SARIF citations
 - [`docs/scoring.md`](docs/scoring.md)            — Weighting model + worked examples
 - [`docs/scanners.md`](docs/scanners.md)          — Per-scanner integrations + caveats

{secure_code_agent-0.10.0 → secure_code_agent-0.11.0/src/secure_code_agent.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: secure-code-agent
-Version: 0.10.0
+Version: 0.11.0
 Summary: Deterministic security gate + bounded AI remediation prompt generator. NIST SSDF / OWASP ASVS / CWE Top 25 anchored.
 Author: Marshall Guillory
 License: MIT
@@ -62,6 +62,34 @@ The sibling of [`maintainability-agent`](https://github.com/marshallguillory86/m
 
 ---
 
+## Try it in one command
+
+```bash
+pip install 'secure-code-agent[python-scanners]'
+secure-code-agent --demo
+```
+
+`--demo` generates a small application carrying seven real defects — SQL
+injection, command injection, unsafe deserialization, a weak hash, dynamic
+evaluation — audits it, and writes the work order you would hand an agent. The
+tree is generated at runtime into a temp directory, so installing this tool
+never puts vulnerable source on your disk.
+
+To audit something real:
+
+```bash
+secure-code-agent /path/to/repo
+```
+
+Any scanner that is missing is named, with the command to install it. This
+tool never installs anything itself — naming a command is not running one —
+and it will not grade what it could not examine. `--preflight` checks the
+whole floor before a run.
+
+A pure-Python repository requires six of the ten floor scanners; the Ruby,
+JavaScript and container tools are *not applicable* rather than missing, so a
+single-language project is never permanently incomplete.
+
 ## Why this exists
 
 AI coding agents ship code at human-review-saturating speed. Point them at a security finding and the documented anti-patterns are:
@@ -442,7 +470,7 @@ For agents that support invokable skills, this repo ships a portable skill under
 ## GitHub Action
 
 ```yaml
-- uses: marshallguillory86/secure-code-agent@v0.3.0
+- uses: marshallguillory86/secure-code-agent@v0.11.0
   with:
     config: secure-code-agent.json
     fail-on-gate: true
@@ -508,7 +536,7 @@ Full design philosophy in [`docs/design.md`](docs/design.md).
 - [`docs/calibration.md`](docs/calibration.md)   — The calibration study, its corpus, and what it found
 - [`docs/design.md`](docs/design.md)              — Architecture + non-goals + scanner protocol
 - [`docs/architecture.md`](docs/architecture.md)  — Audit of the system as built + remediation sequence
-- [`docs/release-blockers.md`](docs/release-blockers.md) — Open v0.3.0 release blockers (do not tag until closed)
+- [`docs/release-blockers.md`](docs/release-blockers.md) — the v0.3.0 release blockers, all closed (historical)
 - [`docs/standards.md`](docs/standards.md)        — NIST SSDF / OWASP / CWE / Scorecard / SARIF citations
 - [`docs/scoring.md`](docs/scoring.md)            — Weighting model + worked examples
 - [`docs/scanners.md`](docs/scanners.md)          — Per-scanner integrations + caveats

{secure_code_agent-0.10.0 → secure_code_agent-0.11.0}/src/secure_code_agent.egg-info/SOURCES.txt

@@ -11,6 +11,7 @@ src/secure_code_audit/__init__.py
 src/secure_code_audit/baseline.py
 src/secure_code_audit/cli.py
 src/secure_code_audit/config.py
+src/secure_code_audit/demo.py
 src/secure_code_audit/findings.py
 src/secure_code_audit/git_tools.py
 src/secure_code_audit/history.py

{secure_code_agent-0.10.0 → secure_code_agent-0.11.0}/src/secure_code_audit/__init__.py

@@ -12,4 +12,4 @@
 #:
 #: PyPI is immutable, so 0.4.0 stays wrong. 0.5.0 is the first build whose
 #: artifacts name their own producer correctly.
-__version__ = "0.10.0"
+__version__ = "0.11.0"

{secure_code_agent-0.10.0 → secure_code_agent-0.11.0}/src/secure_code_audit/cli.py

@@ -15,6 +15,7 @@ from pathlib import Path
 
 from secure_code_audit import (
     __version__,
+    demo,
     instructions,
     remediation,
     renderers,
@@ -136,9 +137,22 @@ def _parser() -> argparse.ArgumentParser:
         "--trust-target-config",
         action="store_true",
         help=(
-            "Allow a config inside the audited tree to name executables from "
-            "that tree. Only for repositories you own. CLI-only by design: a "
-            "config file cannot grant itself this."
+            "Treat a config inside the audited tree as if you wrote it. This "
+            "grants it TWO things: (1) it may name executables from that tree, "
+            "which this host will then run, and (2) it may direct this tool's "
+            "outputs, baseline and history to paths outside the tree. Only for "
+            "repositories you own. CLI-only by design: a config file cannot "
+            "grant itself this."
+        ),
+    )
+
+    p.add_argument(
+        "--demo",
+        action="store_true",
+        help=(
+            "Audit a generated example application instead of a repository, so "
+            "a first run produces a real work order without a scanner scavenger "
+            "hunt. The tree is written to a temp directory and is never shipped."
         ),
     )
 
@@ -187,6 +201,16 @@ def main(argv: list[str] | None = None) -> int:
     if args.init_agent_standards:
         return _do_init_standards(args)
 
+    if getattr(args, "demo", False):
+        # `paths` defaults to ["."], so "was a path given" is a comparison
+        # against the default rather than a truth test.
+        if args.paths != ["."]:
+            sys.stderr.write("ERROR: --demo audits its own generated tree; drop the path.\n")
+            return 2
+        root = demo.build()
+        print(demo.describe(root))
+        args.paths = [str(root)]
+
     if args.target:
         # `--target` names an *agent* for --init-agent-standards, and it reads
         # exactly like the flag for "the repository to audit". It was accepted
@@ -299,6 +323,8 @@ def _print_preflight(rows: list[dict], unselected: list[str], blocking: list[str
 def _do_audit(args: argparse.Namespace) -> int:
     cfg, target, root = _prepare_audit(args)
     _require_configured_gates(args, cfg)
+    # Before anything is resolved or written, and before any scanner runs.
+    _assert_config_writes_are_contained(cfg, root, target)
     # Resolved before the scan so the run can recognise its own artifacts.
     paths = _resolve_outputs(args, cfg, root)
 
@@ -922,6 +948,102 @@ def _under_root(root: Path, value: str) -> Path:
     return path.resolve() if path.is_absolute() else (root / path).resolve()
 
 
+#: Config keys naming a file this tool writes.
+_WRITE_KEYS = (
+    "markdown_path",
+    "json_path",
+    "sarif_path",
+    "comment_path",
+    "prompt_path",
+    "security_pillar_path",
+    "baseline_path",
+    "history_path",
+)
+
+
+def _assert_config_writes_are_contained(cfg: config_mod.Config, root: Path, target: Path) -> None:
+    """A tree may not choose where the host writes.
+
+    D1 draws the line at *executing* what the tree supplies, and that was the
+    only boundary implemented. The tree could still choose file *paths*: the
+    default configuration is loaded from the audit target, and its
+    `outputs.*_path`, baseline and history values were resolved against the
+    root with no containment check at all. A repository shipping
+
+        {"outputs": {"markdown_path": "../../../../.bashrc"}}
+
+    had an ordinary audit overwrite that file, with the report's own content.
+    Arbitrary write is not a lesser thing than arbitrary execute; it is
+    usually a slower route to the same place.
+
+    Three escapes, all closed here and all in the red contract: `..`
+    traversal, an absolute path, and a **symlink inside the tree** pointing
+    out of it. The third is why this resolves before comparing rather than
+    checking the string — `escaped/report.md`, where `escaped` is a symlink
+    to the parent, is textually innocent.
+
+    **Only for a config the tree supplied.** An operator whose config lives
+    outside the audited tree keeps full authority over where things go, and
+    so does anyone passing `--trust-target-config`. Explicit CLI output flags
+    are never touched by this: `--output /tmp/report.md` is the operator
+    speaking, and they are checked nowhere in this function.
+
+    Raises ValueError, so the CLI exits 2 before any scanner runs and before
+    a single byte is written.
+    """
+    if not config_mod.target_config_is_untrusted(cfg, target):
+        return
+    for key in _WRITE_KEYS:
+        configured = cfg.outputs.get(key)
+        if not configured:
+            continue
+        destination = _under_root(root, configured)
+        if config_mod.is_within(destination, root):
+            continue
+        raise ValueError(
+            f"outputs.{key} in {cfg.source_path} resolves to {destination}, which is "
+            f"outside the audit root {root}. Configuration supplied by the audited "
+            f"tree may not choose where this tool writes. Pass the path on the "
+            f"command line instead, move the configuration outside the tree, or "
+            f"re-run with --trust-target-config if you wrote this file yourself."
+        )
+
+
+def _print_install_guidance(unavailable: list[str]) -> None:
+    """Say how to resolve a missing scanner, at the moment it is missing.
+
+    `--preflight` already produced exactly this — one install command per
+    scanner — and the failure path printed only the names. So the first run
+    of a fresh install reported four missing tools and left the operator to
+    find `--preflight` on their own, which is a scavenger hunt wearing a
+    coverage report.
+
+    The guidance is the adapter's own `install_hint`, so it cannot drift from
+    what `--preflight` says. The tool still installs nothing itself; naming
+    the command is not running it.
+    """
+    from secure_code_audit.scanners import SCANNERS
+
+    def hint_for(name: str) -> str:
+        """Empty rather than raising. Advice must never break a run, and an
+        imported SARIF can name a scanner this build does not ship."""
+        cls = SCANNERS.get(name)
+        if cls is None:
+            return ""
+        try:
+            return cls().unavailable_fix_hint() or ""
+        except Exception:  # noqa: BLE001 — see above
+            return ""
+
+    shown = [(name, hint) for name in unavailable if (hint := hint_for(name))]
+    if not shown:
+        return
+    print("  to resolve:")
+    for name, hint in shown:
+        print(f"    {name}: {hint}")
+    print("    (or --preflight to check the whole floor before a run)")
+
+
 def _print_summary(
     verdict, score, gate, ran, unavailable, coverage, paths, axes=(), trend=None
 ) -> None:
@@ -954,6 +1076,7 @@ def _print_summary(
     print(coverage_line)
     if unavailable:
         print(f"  unavailable: {', '.join(unavailable)}")
+        _print_install_guidance(unavailable)
     if not gate.passed:
         for reason in gate.reasons:
             print(f"  ✗ {reason}")

{secure_code_agent-0.10.0 → secure_code_agent-0.11.0}/src/secure_code_audit/config.py

@@ -141,6 +141,16 @@ DEFAULT_OUTPUTS: dict[str, str] = {
     "baseline_path": "secure-code-baseline.json",
     # Append-only trend. The score's one genuine use is movement over time.
     "history_path": ".secure-code/history.jsonl",
+    # The artifact maintainability-agent ingests (D3). Off unless declared,
+    # like sarif/json/comment — the default only supplies the name.
+    #
+    # It was missing here while `_resolve_outputs` read it, so
+    # `outputs.security_pillar_path` was a **dead key**: the validation loop
+    # below iterates this mapping, so a configured value never reached
+    # `cfg.outputs` and the resolver read `None` from it every time. That is
+    # the seventh instance of the defect `_resolve_outputs` already
+    # describes — "four of the six keys were dead the same way".
+    "security_pillar_path": "security-pillar.json",
 }
 
 
@@ -305,6 +315,51 @@ def is_within(path: Path, root: Path) -> bool:
     return resolved == root_resolved or root_resolved in resolved.parents
 
 
+def containment_root(target: Path) -> Path:
+    """The directory every containment decision is made against.
+
+    **A file target's trust boundary is its parent, not the file.** Auditing
+    `app.py` meant `is_within(<anything>, app.py)` was false for everything,
+    because nothing lives beneath a regular file — so every containment test
+    inverted to "allowed" at once. A `secure-code-agent.json` beside the file
+    read as *outside* the tree, and `--only-scanners bandit` with an in-tree
+    `command` executed a script from the audited repository without
+    `--trust-target-config`. The single-file shape silently opted out of the
+    guard that D1 exists to hold.
+
+    Directories are returned unchanged, so the ordinary repository audit is
+    unaffected.
+    """
+    resolved = target.resolve()
+    return resolved if resolved.is_dir() else resolved.parent
+
+
+def target_config_is_untrusted(config: Config, target: Path) -> bool:
+    """Was this configuration supplied by the audited tree?
+
+    Location, not provenance of the flag: a config *inside* the target is
+    repository content whether it was found by default discovery or named
+    explicitly with `--config`. An operator who means to trust it says so with
+    `--trust-target-config`.
+
+    **This is not the negation of `target_executables_allowed`, and writing it
+    as one was a live regression.** They disagree when there is no config file
+    at all. For execution, "no config" must still *deny* tree-local
+    executables — nothing has authorised them, and an absent file is not
+    permission. For writes, "no config" is simply nothing to distrust: the
+    built-in defaults are relative names that cannot escape. Collapsing the
+    two flipped the execution guard open for every run with no config, which
+    `test_defaults_never_allow_executables_from_the_tree` caught immediately.
+
+    Only `containment_root` is shared.
+    """
+    if config.trust_target_config:
+        return False
+    if config.source_path is None:
+        return False  # built-in defaults are relative names; nothing can escape
+    return is_within(config.source_path, containment_root(target))
+
+
 def target_executables_allowed(config: Config, target: Path) -> bool:
     """May this configuration name an executable inside the audited tree?
 
@@ -318,12 +373,15 @@ def target_executables_allowed(config: Config, target: Path) -> bool:
     repositories wholesale, so a config the operator keeps outside the tree
     still gets the documented tree-local interpreter workflow. Inside the tree,
     it takes an explicit `--trust-target-config`.
+
+    See `target_config_is_untrusted` for why this is *not* expressed as its
+    negation: an absent config denies here and is harmless there.
     """
     if config.trust_target_config:
         return True
     if config.source_path is None:
-        return False  # built-in defaults name no commands anyway
-    return not is_within(config.source_path, target)
+        return False  # nothing authorised a tree-local command
+    return not is_within(config.source_path, containment_root(target))
 
 
 #: Top-level keys the loader understands. Mirrors `properties` in
@@ -432,6 +490,19 @@ def _from_dict(raw: dict[str, Any]) -> Config:
     outputs = raw.get("outputs", {})
     if not isinstance(outputs, dict):
         raise ValueError("outputs must be a JSON object")
+    # D2 applies inside `outputs`, and it did not. The loop below iterates
+    # the *known* keys, so anything else was read by nobody and reported by
+    # nobody: `outputs.markdwon_path` was accepted in silence while the
+    # report went to the default path. That is precisely the failure D2 cites
+    # for top-level keys — "a typo'd gate name disabled a gate with no
+    # diagnostic" — surviving one level down because the check was never
+    # applied recursively.
+    unknown = sorted(set(outputs) - set(DEFAULT_OUTPUTS))
+    if unknown:
+        raise ValueError(
+            f"unknown outputs key(s): {', '.join(unknown)}. "
+            f"Known keys: {', '.join(sorted(DEFAULT_OUTPUTS))}"
+        )
     for k, default_v in DEFAULT_OUTPUTS.items():
         value = outputs.get(k, default_v)
         # `null` turns an output off. The markdown report and the work order

secure_code_agent-0.11.0/src/secure_code_audit/demo.py

@@ -0,0 +1,118 @@
+"""`secure-code-agent --demo` — a real work order in one command.
+
+**The first five minutes were a scavenger hunt.** A fresh install pointed at
+any repository reported `coverage: FAILED`, four missing scanners and an
+unverified A+; pointed at *this* repository it reported 0 to fix, 0 to review
+and 1,108 suppression candidates, because a security tool's tests are
+deliberately vulnerable fixtures. Both are correct and neither shows anyone
+what the tool is for.
+
+The demo is a small application carrying seven real defects, audited with
+whatever scanners are present. It answers the question a stranger actually
+has — *what does this produce?* — without a scavenger hunt.
+
+**The fixture is generated at runtime, never shipped.** Writing vulnerable
+source into the package would put it in every user's `site-packages`, and
+this project's own audit would flag its own demo. It is assembled from
+fragments here and written to a temporary directory, so no vulnerable literal
+exists in the installed files — the same technique the calibration controls
+use, for the same reason.
+"""
+
+from __future__ import annotations
+
+import tempfile
+from pathlib import Path
+
+#: Assembled rather than written out, so no matchable literal ships. Each
+#: entry is one defect a floor scanner is confident about.
+_PARTS: tuple[tuple[str, tuple[str, ...]], ...] = (
+    (
+        "db.py",
+        (
+            "def lookup(cursor, name):",
+            "    cursor.exec" + 'ute("SEL' + 'ECT * FROM users WHERE name = \'" + name + "\'")',
+            "    return cursor.fetchall()",
+        ),
+    ),
+    (
+        "shell.py",
+        (
+            "import subprocess",
+            "",
+            "def archive(path):",
+            "    return subprocess.call('tar -cf backup.tar ' + path, " + "shell=" + "True)",
+        ),
+    ),
+    (
+        "serialize.py",
+        (
+            "import pickle",
+            "",
+            "def restore(blob):",
+            "    return pickle." + "loads(blob)",
+        ),
+    ),
+    (
+        "crypto.py",
+        (
+            "import hashlib",
+            "",
+            "def fingerprint(data):",
+            "    return hashlib." + "md5(data).hexdigest()",
+        ),
+    ),
+    (
+        "calc.py",
+        (
+            "def evaluate(expression):",
+            "    return " + "eval" + "(expression)",
+        ),
+    ),
+    (
+        "config.py",
+        (
+            "import os",
+            "",
+            "DEBUG = True",
+            "TIMEOUT = int(os.environ.get('TIMEOUT', '30'))",
+        ),
+    ),
+)
+
+README = """\
+# secure-code-agent demo
+
+A small application with real defects, generated for this run and thrown away
+after. Point an agent at the work order printed alongside this audit.
+
+Nothing here is shipped in the package; it is assembled at runtime so that
+installing this tool never puts vulnerable source on your disk.
+"""
+
+
+def build(destination: Path | None = None) -> Path:
+    """Write the demo tree and return its root."""
+    root = destination or Path(tempfile.mkdtemp(prefix="secure-code-demo-"))
+    source = root / "src"
+    source.mkdir(parents=True, exist_ok=True)
+    for name, lines in _PARTS:
+        (source / name).write_text("\n".join(lines) + "\n", encoding="utf-8")
+    (root / "README.md").write_text(README, encoding="utf-8")
+    # No dependency manifest. A pinned-vulnerable `requirements.txt` was here
+    # and it made the demo worse, not better: eighteen pip-audit CVEs drowned
+    # the seven code defects the demo exists to show. It also surfaced a
+    # separate defect worth its own fix — those CVEs were filed on the
+    # **documentation** axis, because the manifest is a `.txt` file and the
+    # axis split reads the extension. A dependency finding is not
+    # documentation whatever the manifest is called.
+    return root
+
+
+def describe(root: Path) -> str:
+    return (
+        f"Demo tree: {root}\n"
+        f"  {len(_PARTS)} files carrying SQL injection, command injection, unsafe\n"
+        f"  deserialization, a weak hash, dynamic evaluation and a debug flag.\n"
+        f"  Generated for this run; delete it when you are done.\n"
+    )

{secure_code_agent-0.10.0 → secure_code_agent-0.11.0}/src/secure_code_audit/git_tools.py

@@ -76,11 +76,59 @@ def _matches(rel: str, name: str, pat: str) -> bool:
         bare = pat[3:] if pat.startswith("**/") else pat
         if not bare:  # a lone `**/` would otherwise exclude the entire tree
             return False
-        return rel.startswith(bare) or f"/{bare}" in f"/{rel}/"
+        return _matches_directory(rel, bare.rstrip("/"))
     bare = pat[3:] if pat.startswith("**/") else pat
     return fnmatch.fnmatch(rel, pat) or fnmatch.fnmatch(rel, bare) or fnmatch.fnmatch(name, bare)
 
 
+def _matches_directory(rel: str, name: str) -> bool:
+    """Does any directory component of `rel` match the glob `name`?
+
+    **The directory branch did no globbing at all.** It compared with
+    `startswith` and a substring test, so a pattern holding a glob was
+    *inert*: `*.egg-info/` matched nothing while `src/pkg.egg-info/` sat in
+    the tree being scanned, and `build-*/` and `test_*/` were the same. The
+    `**/` spelling was one instance of the class and fixing it left the rest
+    — an instance mistaken for a class, twice over, since
+    `maintainability-agent` found the same thing in its own matcher (its
+    D156) and reported the generalisation back.
+
+    **The final component is excluded from the comparison.** A trailing slash
+    says *directory*, so `*.egg-info/` must not match a **file** named
+    `notes.egg-info` — and it did, until this was narrowed. Every caller
+    filters to `path.is_file()` before asking, or asks about a finding's file
+    path, so nothing prunes directories and nothing needs the final component
+    to match. An earlier test asserted that it did; that was documenting an
+    accident as intent, and it is corrected alongside this.
+
+    **A pattern may name more than one segment.** `calibration/.corpus/` and
+    `src/generated/` are ordinary things to write, and the first version of
+    this globbed one component at a time — so no single component ever equalled
+    `calibration/.corpus` and the pattern went inert. That regression was
+    introduced *by* the fix for inert patterns and was caught one task later,
+    when the repository inventory started walking nineteen cloned corpus
+    repositories it was supposed to be excluding. Segments are matched as a
+    consecutive run.
+
+    An inert exclude is the worst kind of configuration defect: it reads as
+    intent, it never errors, and the only symptom is findings the operator
+    believed they had excluded.
+    """
+    wanted = [segment for segment in name.split("/") if segment]
+    if not wanted:
+        return False
+    # Directory components only: the last element of `rel` is the file.
+    components = rel.split("/")[:-1]
+    span = len(wanted)
+    for start in range(len(components) - span + 1):
+        if all(
+            fnmatch.fnmatch(component, pattern)
+            for component, pattern in zip(components[start : start + span], wanted, strict=True)
+        ):
+            return True
+    return False
+
+
 def in_scope(path: Path, include_exts: Iterable[str]) -> bool:
     """Does this path match the configured include_extensions?
     Dockerfile is matched by basename."""