Merge commit 'faec5fd' into fix/kvb-check-security-partial-cache

Resolution: rules, limits, line/file counts and not-covered judge the aliased tree path medusa scans and name the repository path; findings, cache key (tree path, repository path, not covered) and accept rows keep the real path.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Kevin Veen-BirkenbachandClaude Opus 5.5 committed 2026-11-13 17:03:20 +00:00
commit ed45b35dd7
2 files changed
+143 -27

No files matched your search

+59 -25
View File
@@ -20,6 +20,13 @@ Scan:
directory because medusa creates ~/.medusa on start, read from directory because medusa creates ~/.medusa on start, read from
`<dir>/medusa-scan-*.json`: a `findings` list whose entries carry `<dir>/medusa-scan-*.json`: a `findings` list whose entries carry
`severity` (critical, high, medium, low or info), `rule_id`, `file` and `line`. `severity` (critical, high, medium, low or info), `rule_id`, `file` and `line`.
medusa skips the SKIPPED suffixes (.mjs, .cjs, any case), so such a file is
copied under its name with ALIAS (.js) appended, again while a path or
folder of the change holds that name, or under the sha1 of its path with
ALIAS when that file name would pass NAME_MAX bytes; its findings are
fingerprinted from that copy and reported and accepted at its repository
path. Rules, coverage and not covered judge the tree path medusa scans and
name the repository path.
Rules: medusa's own RULES, read without running medusa from the medusa Rules: medusa's own RULES, read without running medusa from the medusa
package that the interpreter of medusa's shebang (an `env` program looked package that the interpreter of medusa's shebang (an `env` program looked
up on PATH) imports with medusa's environment: from core/parallel.py the up on PATH) imports with medusa's environment: from core/parallel.py the
@@ -49,8 +56,8 @@ Scan:
Cache: Cache:
The findings of a complete scan, keyed by the sha256 of this script, the The findings of a complete scan, keyed by the sha256 of this script, the
resolved medusa binary with its mtime and size, PATH, the files not covered, resolved medusa binary with its mtime and size, PATH, the files not covered,
every MEDUSA_* variable and every MEDUSA_* variable and the tree path, repository path, mode and
the path, mode and content sha256 of every scanned file, in content sha256 of every copied file, in
<council root>/security-cache/<key>.json for CACHE_SECONDS. A later scan <council root>/security-cache/<key>.json for CACHE_SECONDS. A later scan
with the same key reads them instead of running medusa; any edit of a with the same key reads them instead of running medusa; any edit of a
scanned file, of medusa or of this script misses. The folder is used only scanned file, of medusa or of this script misses. The folder is used only
@@ -114,6 +121,9 @@ SAFE = 100
SHOWN = 5 SHOWN = 5
REACH = 2 REACH = 2
WORKERS = 4 WORKERS = 4
SKIPPED = (".mjs", ".cjs")
ALIAS = ".js"
NAME_MAX = 255
CACHE = "security-cache" CACHE = "security-cache"
CACHE_SECONDS = 24 * 3600 CACHE_SECONDS = 24 * 3600
NOTHING = type(None) NOTHING = type(None)
@@ -188,18 +198,42 @@ def changed(root: Path, base: str) -> list[str]:
return sorted({p for p in listed.split("\0") if p}) return sorted({p for p in listed.split("\0") if p})
def copy(root: Path, paths: list[str], tree: Path) -> int: def alias(name: str, taken: set[str]) -> str:
copied = 0 """Returns:
the tree path of name, whose suffix medusa skips: its file name with
ALIAS appended, again while taken holds that path, or the sha1 of name
treated the same way when that file name would pass NAME_MAX bytes.
"""
folder = Path(name).parent
for stem in (Path(name).name, digest(name)):
scratch = stem + ALIAS
while (folder / scratch).as_posix() in taken:
scratch += ALIAS
if len(os.fsencode(scratch)) <= NAME_MAX:
break
return (folder / scratch).as_posix()
def copy(root: Path, paths: list[str], tree: Path) -> dict[str, str]:
"""Returns:
the tree path of every copied file mapped to its repository path.
"""
names = {}
taken = set(paths) | {parent.as_posix() for name in paths for parent in Path(name).parents}
for name in paths: for name in paths:
source = root / name source = root / name
# Trip-wire: a symlink's target may lie outside the repository; even a copied link lets the scan read it. # Trip-wire: a symlink's target may lie outside the repository; even a copied link lets the scan read it.
if source.is_symlink() or not source.is_file(): if source.is_symlink() or not source.is_file():
continue continue
target = tree / name scratch = name
if Path(name).suffix.lower() in SKIPPED:
scratch = alias(name, taken)
taken.add(scratch)
target = tree / scratch
target.parent.mkdir(parents=True, exist_ok=True) target.parent.mkdir(parents=True, exist_ok=True)
shutil.copy2(source, target) shutil.copy2(source, target)
copied += 1 names[scratch] = name
return copied return names
def located(name: str, tree: Path) -> str: def located(name: str, tree: Path) -> str:
@@ -308,9 +342,9 @@ def accept(argv: list[str]) -> int:
return 0 return 0
def findings(reports: Path, tree: Path) -> tuple[list[dict], dict]: def findings(reports: Path, tree: Path, names: dict[str, str]) -> tuple[list[dict], dict]:
"""Returns: """Returns:
the findings of medusa's report and its `scan_summary`. the findings of medusa's report at their repository paths and its `scan_summary`.
""" """
files = sorted(reports.glob("medusa-scan-*.json")) if reports.is_dir() else [] files = sorted(reports.glob("medusa-scan-*.json")) if reports.is_dir() else []
if not files: if not files:
@@ -331,12 +365,12 @@ def findings(reports: Path, tree: Path) -> tuple[list[dict], dict]:
if severity not in WEIGHTS: if severity not in WEIGHTS:
raise Unreadable(f"{files[-1].name}: a finding without a known severity") raise Unreadable(f"{files[-1].name}: a finding without a known severity")
line = entry.get("line") if isinstance(entry.get("line"), int) else None line = entry.get("line") if isinstance(entry.get("line"), int) else None
path = located(str(entry.get("file") or "?"), tree) scratch = located(str(entry.get("file") or "?"), tree)
sha1, context = fingerprint(tree, path, line) sha1, context = fingerprint(tree, scratch, line)
found.append({ found.append({
"severity": severity, "severity": severity,
"rule": entry.get("rule_id") if isinstance(entry.get("rule_id"), str) else None, "rule": entry.get("rule_id") if isinstance(entry.get("rule_id"), str) else None,
"path": path, "path": names.get(scratch, scratch),
"line": line, "line": line,
"sha1": sha1, "sha1": sha1,
"context": context, "context": context,
@@ -512,15 +546,16 @@ def cut(code: int, said: list[str], summary: dict, sizes: dict[str, tuple[int, i
return None return None
def keyed(medusa: str, tree: Path, missed: list[str]) -> str: def keyed(medusa: str, tree: Path, names: dict[str, str], missed: list[str]) -> str:
binary = Path(medusa).resolve() binary = Path(medusa).resolve()
info = binary.stat() info = binary.stat()
key = hashlib.sha256(Path(__file__).read_bytes()) key = hashlib.sha256(Path(__file__).read_bytes())
key.update(f"\0{binary}\0{info.st_mtime_ns}\0{info.st_size}\0{os.environ.get('PATH', '')}\0".encode()) key.update(f"\0{binary}\0{info.st_mtime_ns}\0{info.st_size}\0{os.environ.get('PATH', '')}\0".encode())
key.update("".join(f"{name}\0" for name in missed).encode() + b"\0") key.update("".join(f"{name}\0" for name in missed).encode() + b"\0")
key.update("".join(f"{k}={v}\0" for k, v in sorted(os.environ.items()) if k.startswith("MEDUSA_")).encode()) key.update("".join(f"{k}={v}\0" for k, v in sorted(os.environ.items()) if k.startswith("MEDUSA_")).encode())
for path in sorted(p for p in tree.rglob("*") if p.is_file()): for scratch, name in sorted(names.items()):
key.update(f"{path.relative_to(tree).as_posix()}\0{path.stat().st_mode & 0o777:o}\0".encode()) path = tree / scratch
key.update(f"{scratch}\0{name}\0{path.stat().st_mode & 0o777:o}\0".encode())
key.update(hashlib.sha256(path.read_bytes()).digest()) key.update(hashlib.sha256(path.read_bytes()).digest())
return key.hexdigest() return key.hexdigest()
@@ -577,31 +612,30 @@ def remember(folder: Path, key: str, found: list[dict]) -> None:
def scan(medusa: str, root: Path, base: str, cache: Path | None) -> tuple[int, list[dict], list[str]]: def scan(medusa: str, root: Path, base: str, cache: Path | None) -> tuple[int, list[dict], list[str]]:
"""Returns: """Returns:
the count of scanned files, their findings and the copied files of a the count of scanned files, their findings and the repository paths
type medusa never scans. of the copied files medusa never takes up.
""" """
with tempfile.TemporaryDirectory(prefix="kvb-security-") as scratch: with tempfile.TemporaryDirectory(prefix="kvb-security-") as scratch:
work = Path(scratch) work = Path(scratch)
tree, reports, home = work / "tree", work / "reports", work / "home" tree, reports, home = work / "tree", work / "reports", work / "home"
tree.mkdir() tree.mkdir()
home.mkdir() home.mkdir()
copy(root, changed(root, base), tree) names = copy(root, changed(root, base), tree)
env = {**os.environ, "HOME": str(home)} if not names:
sizes = sized(tree)
if not sizes:
return 0, [], [] return 0, [], []
env = {**os.environ, "HOME": str(home)}
known = rules(package(medusa, work, env)) known = rules(package(medusa, work, env))
if known is None: if known is None:
raise Uncovered("medusa's own types, exclusions and limits are unreadable from its source") raise Uncovered("medusa's own types, exclusions and limits are unreadable from its source")
missed = [name for name in sizes if not taken(name, known)] sizes = {names[scratch]: size for scratch, size in sized(tree).items() if taken(scratch, known)}
sizes = {name: size for name, size in sizes.items() if name not in missed} missed = sorted(set(names.values()) - sizes.keys())
scanned = len(sizes) scanned = len(sizes)
if not scanned: if not scanned:
raise Uncovered(f"medusa scans none of its files, not covered: {shown(missed)}") raise Uncovered(f"medusa scans none of its files, not covered: {shown(missed)}")
over = oversized(sizes, known) over = oversized(sizes, known)
if over: if over:
raise Uncovered(over) raise Uncovered(over)
key = keyed(medusa, tree, missed) key = keyed(medusa, tree, names, missed)
hit = recalled(cache, key) if cache else None hit = recalled(cache, key) if cache else None
if hit is not None: if hit is not None:
return scanned, hit, missed return scanned, hit, missed
@@ -611,7 +645,7 @@ def scan(medusa: str, root: Path, base: str, cache: Path | None) -> tuple[int, l
cwd=work, stdin=subprocess.DEVNULL, capture_output=True, check=False, env=env, cwd=work, stdin=subprocess.DEVNULL, capture_output=True, check=False, env=env,
) )
try: try:
found, summary = findings(reports, tree) found, summary = findings(reports, tree, names)
except Unreadable as error: except Unreadable as error:
raise Unreadable(f"{error} (medusa exit {result.returncode})") from None raise Unreadable(f"{error} (medusa exit {result.returncode})") from None
said = [line.replace(f"{tree}/", "").strip(" \t!⚠️") for line in result.stdout.decode(errors="replace").splitlines()] said = [line.replace(f"{tree}/", "").strip(" \t!⚠️") for line in result.stdout.decode(errors="replace").splitlines()]
+84 -2
View File
@@ -27,7 +27,7 @@ out.mkdir(parents=True)
limit = int(os.environ.get("FAKE_MEDUSA_FILE_LIMIT", str(2 * 1024 * 1024))) limit = int(os.environ.get("FAKE_MEDUSA_FILE_LIMIT", str(2 * 1024 * 1024)))
findings, taken, counted = [], 0, 0 findings, taken, counted = [], 0, 0
for path in sorted(p for p in target.rglob("*") if p.is_file()): for path in sorted(p for p in target.rglob("*") if p.is_file()):
if path.suffix not in (".py", ".json") and not path.name.startswith("Dockerfile"): if path.suffix.lower() not in (".py", ".json", ".js") and not path.name.startswith("Dockerfile"):
continue continue
if path.name == os.environ.get("FAKE_MEDUSA_LOSE") or any(p in str(path.relative_to(target)) for p in ("build", "env")): if path.name == os.environ.get("FAKE_MEDUSA_LOSE") or any(p in str(path.relative_to(target)) for p in ("build", "env")):
continue continue
@@ -67,7 +67,7 @@ PARALLEL = """MAX_SCAN_FILE_SIZE = {size}
class MedusaParallelScanner: class MedusaParallelScanner:
FILE_SCANNERS = {{".py": "python", ".json": "json"}} FILE_SCANNERS = {{".py": "python", ".json": "json", ".js": "javascript"}}
def find_scannable_files(self): def find_scannable_files(self):
special_exact_names: Set[str] = {{"mcp.json"}} special_exact_names: Set[str] = {{"mcp.json"}}
@@ -126,6 +126,7 @@ class TestSecurity(unittest.TestCase):
subprocess.run(["git", *args], cwd=self.repo, env=self.env, capture_output=True, check=True) subprocess.run(["git", *args], cwd=self.repo, env=self.env, capture_output=True, check=True)
def write(self, path: str, text: str) -> None: def write(self, path: str, text: str) -> None:
(self.repo / path).parent.mkdir(parents=True, exist_ok=True)
(self.repo / path).write_text(text, encoding="utf-8") (self.repo / path).write_text(text, encoding="utf-8")
def scan(self, *extra: str, env: dict[str, str]) -> subprocess.CompletedProcess: def scan(self, *extra: str, env: dict[str, str]) -> subprocess.CompletedProcess:
@@ -273,6 +274,87 @@ class TestSecurity(unittest.TestCase):
result = self.scan(env=self.env) result = self.scan(env=self.env)
self.assertEqual(result.stdout, "🛡️ security 100 % (medusa: 0 findings, 2 accepted in 1 file)\n") self.assertEqual(result.stdout, "🛡️ security 100 % (medusa: 0 findings, 2 accepted in 1 file)\n")
def test_mjs_and_cjs_files_medusa_skips_are_scanned_and_reported_at_their_repository_path(self):
line = "run(request.query) // MARK-HIGH"
self.write("tool.mjs", f"import run from 'run';\n{line}\n")
result = self.scan(env=self.env)
self.assertEqual(
(result.stdout, result.returncode),
("🛡️ security 75 % (medusa: 1 finding in 1 file: high tool.mjs:2)\n", 3),
)
sha1 = hashlib.sha1(line.encode()).hexdigest()
result = self.accept(
"--rule", "FAKE-HIGH", "--path", "tool.mjs", "--sha1", sha1, "--line", "2", "--reason", "fixture"
)
self.assertEqual(result.returncode, 0, result.stderr)
self.write("tool.mjs.js", "a // MARK-MEDIUM\n")
self.write("lib.CJS", "b // MARK-LOW\n")
result = self.scan(env=self.env)
self.assertEqual(
(result.stdout, result.returncode),
("🛡️ security 88 % (medusa: 2 findings, 1 accepted in 3 files: medium tool.mjs.js:1, low lib.CJS:1)\n", 3),
)
def test_a_folder_named_like_the_alias_keeps_both_paths_apart(self):
self.write("tool.mjs", "a // MARK-HIGH\n")
self.write("tool.mjs.js/inner.py", "b # MARK-LOW\n")
result = self.scan(env=self.env)
self.assertEqual(
(result.stdout, result.returncode),
("🛡️ security 73 % (medusa: 2 findings in 2 files: high tool.mjs:1, low tool.mjs.js/inner.py:1)\n", 3),
)
def test_the_cache_keeps_the_repository_path_of_an_aliased_file(self):
text = "a // MARK-HIGH\n"
self.write("tool.mjs", text)
first = json.loads(self.scan("--json", env=self.env).stdout)
(self.repo / "tool.mjs").unlink()
self.write("tool.mjs.js", text)
second = json.loads(self.scan("--json", env=self.env).stdout)
self.assertEqual([f["path"] for f in first["findings"] + second["findings"]], ["tool.mjs", "tool.mjs.js"])
def test_a_nested_mjs_file_is_reported_at_its_nested_path(self):
self.write("a/b/tool.mjs", "a // MARK-MEDIUM\n")
result = self.scan(env=self.env)
self.assertEqual(
(result.stdout, result.returncode),
("🛡️ security 90 % (medusa: 1 finding in 1 file: medium a/b/tool.mjs:1)\n", 3),
)
def test_an_mjs_file_name_without_room_for_the_alias_is_scanned_under_a_short_one(self):
name = "t" * 250 + ".mjs"
self.write(name, "a // MARK-LOW\n")
found = json.loads(self.scan("--json", env=self.env).stdout)
self.assertEqual((found["files"], [(f["path"], f["line"]) for f in found["findings"]]), (1, [(name, 1)]))
def test_an_mjs_only_diff_scores_from_a_real_scan_and_only_a_complete_run_is_cached(self):
argv = self.bin / "argv.json"
folder = self.base / "council" / "security-cache"
self.write("tool.mjs", "a // MARK-HIGH\n")
rerun = "medusa run incomplete, nothing cached, rerun once the host is idle"
timeout = "1 scanner error(s)/timeout(s) during scan: JavaScriptScanner (1)"
cases = (
({"FAKE_MEDUSA_STDOUT": f"⚠️ {timeout}\n"}, f"{rerun}: {timeout}"),
({"FAKE_MEDUSA_FILE_LIMIT": "4"}, f"{rerun}: medusa counted 0 of 2 lines"),
)
for extra, problem in cases:
with self.subTest(problem=problem):
argv.unlink(missing_ok=True)
result = self.scan(env={**self.env, **extra})
self.assertEqual((result.stdout, result.returncode), (f"🛡️ security – ({problem}: {HAND})\n", 4))
self.assertTrue(argv.exists())
self.assertEqual(list(folder.glob("*.json")), [])
scored = ("🛡️ security 75 % (medusa: 1 finding in 1 file: high tool.mjs:1)\n", 3)
argv.unlink()
result = self.scan(env=self.env)
self.assertEqual((result.stdout, result.returncode), scored)
self.assertTrue(argv.exists())
self.assertEqual(len(list(folder.glob("*.json"))), 1)
argv.unlink()
result = self.scan(env=self.env)
self.assertEqual((result.stdout, result.returncode), scored)
self.assertFalse(argv.exists())
def test_critical_exits_1_and_floors_at_0(self): def test_critical_exits_1_and_floors_at_0(self):
self.write("app.py", "a # MARK-CRITICAL\nb # MARK-CRITICAL\nc # MARK-CRITICAL\n") self.write("app.py", "a # MARK-CRITICAL\nb # MARK-CRITICAL\nc # MARK-CRITICAL\n")
result = self.scan(env=self.env) result = self.scan(env=self.env)