001 names the install proof (the migration test's stub install and a docker build of orchestrator/ without INFINITO_ARTEFACT_BASE); 002 decision 10 hands the sky extraction to cosmos requirement 001, Skills only reviews the switch; 010 decision 6 caches semgrep and gitleaks findings per file, with their configs as cross-file inputs. 🎯 Fix: 95 % 💥 Break: 1 % 💸 Tokens: 100 % ⏱️ Velocity: 100 % 🛡️ Security: 100 % 🏆 Score: 94 🚦 Gate: ✅ 90/5, tokens and velocity <= 100, security 100 % Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
9.1 KiB
9.1 KiB
010 - Security Scan Cache per File
User Story
As an agent running kvb-check-security on many branches and sessions, I
want the MEDUSA findings of every unchanged file reused under an exact
per-file key, so that one changed file rescans only that file and the same
file is never scanned twice across branches and sessions.
Decisions (operator-confirmed 2026-11-14; do not re-litigate)
- Depends on: quality 003 (the result store). Independent of 009 and 011.
- Timing: implementation starts once the running agent lanes are done and quality 003 has shipped its store.
- Today, measured:
keyed()inscripts/security.pyhashes the script, the medusa binary's path, mtime and size,PATH, the files not covered, everyMEDUSA_*variable and, per copied file, its tree path, repository path, mode and content; one entry per whole diff lives in<council root>/security-cache/forCACHE_SECONDS(24 h), and medusa runs with--no-cache. One changed file therefore rescans the whole diff, and an unchanged file on another branch or in another session is scanned again; the ModelAttackScanner needs 71.8 s for one 2949-line file. - Key per file: the sha256 of the file content, the medusa version
(2026.7.0 today, from its dist-info), a digest of medusa's rule set (its
rules/tree and the RULES thatsecurity.pyreads from medusa's source) and the digest ofsecurity.py. No time expiry: the key changes whenever anything relevant changes. Rejected: the whole-diff key (today's behaviour); a 24 h expiry (a key that changes with every input needs none). - What selects and runs a scanner joins the key (proposed): medusa
picks scanners by extension, exact name, prefix and parent folder name
(
ai_context_scanner,rag_security_scanner,mcp_config_scannerandagent_memory_scannerreadfile_path.parent.name), and most scanners call external tools found onPATH(shellcheck, semgrep, gitleaks, trivy and more). The key therefore also holds the scanned tree path, the file mode, everyMEDUSA_*variable and the resolved path, size and mtime of each external tool, as today's key holdsPATH. Without them a moved file or a newly installed tool would reuse findings it never produced. - Cross-file check first: before any per-file entry is written, prove
that medusa's findings for a file do not depend on other files of the
scan tree; where a cross-file rule exists, the files it reads stay per
diff. Found while drafting, medusa 2026.7.0:
trivy_scannerrunstrivy fson the file's parent folder,rust_scannerwalks up toCargo.toml,_find_config_fileinscanners/base.pywalks up for tool configuration past the scratch tree into/tmp, anddocker_compose_scannerruns in the file's folder.medusa scanhas no flag that selects scanners, so a file thatFILE_SCANNERSroutes to a cross-file scanner stays in a per-diff group, keyed like today minus the expiry. The check is an acceptance criterion. Operator 2026-11-17: semgrep and gitleaks run over the whole tree but match within one file, so they count as file-local oncetest_findings_file_localshows it; their configuration files (.semgrepignore,.gitleaks.toml,.gitleaksignore) joinCROSS_FILE. Rejected: semgrep and gitleaks as cross-file routes, which would leave nearly every code file per diff. - Through the quality store: entries are written and read with
quality store putandget(quality 003) under toolmedusa;<council root>/security-cache/goes away. A payload holds per finding onlyrule,lineandseverity, as quality decision 23 allows.sha1andcontextare line hashes, which decision 23 keeps out of stored data, sosecurity.pyrecomputes them from the file after a hit; the file content is part of the key, so they come out identical. - Incomplete scans are never cached: a run with a non-zero exit, a FAULT
or SKIP line, a
files_scannedorlines_scannedshortfall, an unreadable report or a file never covered writes no entry for any of its files, asscan()does today. - Accepted findings unchanged:
security-accepted.jsonl,accept, the rule, path, sha1 and context match and the score formula stay as they are. - A store failure costs time only: a missing quality binary or a store miss on error runs medusa as today; it never yields a score without a scan.
- Rejected: radio digest. The operator rejected it on 2026-11-14: every radio message stays in full in the hooks, because each one is sent for a reason.
Approach
flowchart TD
subgraph P["🧭 0 · Preparation"]
P1["📋 Write requirement"] --> P2{"✅ Operator approves?"}
P2 -- "✏️ corrections" --> P1
end
P2 -- "🤖 yes" --> A1
subgraph A["🔬 A · Cross-file check"]
A1["🧪 Scan fixtures alone and together"]
A1 --> A2["📋 List cross-file routes"]
A2 --> AF{"💬 Operator agrees with the list?"}
AF -- "✏️ changes" --> A1
end
AF -- "👍 fits" --> B0
subgraph B["🗝️ B · Per-file key and store"]
B0{"📦 quality 003 store shipped?"}
B0 -- "⏳ no: wait" --> B0
B0 -- "✅ yes" --> B1["🧩 Key, payload, store calls"]
B1 --> B2{"🧪 Unit and integration green?"}
B2 -- "🔴 no: fix" --> B1
B2 -- "🟢 yes" --> B3{"⏱️ Unchanged diff under 2 s?"}
B3 -- "🔴 no: fix" --> B1
B3 -- "🟢 yes" --> BF{"💬 Operator feedback?"}
BF -- "✏️ changes" --> B1
end
BF -- "👍 fits" --> D1["🏁 Review, commit with operator OK, hand-over"]
Acceptance Criteria
Cross-file check
test_findings_file_local: for a fixture set covering everyFILE_SCANNERSroute, each file's findings scanned alone equal its findings scanned inside the full fixture tree; every route where they differ is listed inCROSS_FILEinsecurity.py.CROSS_FILEholds the routes oftrivy_scanner,rust_scanneranddocker_compose_scanner, the configuration names that_find_config_filelooks up and.semgrepignore,.gitleaks.tomland.gitleaksignore, unlesstest_findings_file_localproves one of them file-local; the semgrep and gitleaks routes themselves are not in it.test_cross_file_group_rescans: changing a sibling of a file in the per-diff group (aCargo.tomlnext to a.rsfile) rescans the group.
Key
test_key_per_file: with 10 scanned files of which 1 changed, medusa's scratch tree holds that 1 file and the other 9 come from the store.test_key_across_branches: an unchanged file on a second branch, scanned by a second process, hits without running medusa.test_key_parts: each of content, medusa version, rule set digest,security.pydigest, tree path, mode, aMEDUSA_*variable and an external tool's mtime changes the key.rg -n CACHE_SECONDS scripts/security.pyfinds nothing.- The medusa command line still carries
--no-cache.
Store
test_store_payload_fields: every stored finding holds exactlyrule,lineandseverity.test_hit_fingerprints_match:sha1andcontextof a hit equal those of a fresh scan of the same file.test_no_legacy_cache_dir: a scan writes nothing under<council root>/security-cache/.test_store_missing_runs_scan: without the quality binary, or with a store that errors, the scan runs and its output equals today's.
Incomplete scans and accepted findings
test_incomplete_caches_nothing: a FAULT line, a non-zero exit, alines_scannedshortfall, a SKIP line and an unreadable report each leave zero store entries for every file of that run.- The existing accepted-findings tests in
tests/test_security.pypass unchanged, andtest_hit_accepts_like_scan: a hit with an accepted finding leaves the score as a fresh scan does. test_hit_output_identical: output line,--jsonand exit code of a hit equal those of a fresh scan of the same diff.
Speed and scope
- A second
security.pyrun over an unchanged diff holding the 2949-line file that took 71.8 s finishes in under 2 s (time). - The implementation's diff touches no file of
kvb-org-radio.
Tests
- Unit
test_key_parts,test_store_payload_fieldsand theCROSS_FILErouting oftaken()results.
- Integration
- Real medusa on fixture trees with a temporary
XDG_CACHE_HOME:test_findings_file_local,test_key_per_file,test_key_across_branches,test_cross_file_group_rescans,test_incomplete_caches_nothing,test_hit_fingerprints_match.
- Real medusa on fixture trees with a temporary
- E2E
tests/e2e/test_security_cache_e2e.py: two worktrees of skills on branches sharing unchanged files; after the secondsecurity.pyrun,quality store stats --tool medusacounts new rows only for the files the second branch changed, and its score equals a run with the store removed.