security_audit.py 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320
  1. """On-demand supply-chain audit for Hermes Agent installs.
  2. Vulnerabilities are looked up against OSV.dev (``api.osv.dev/v1/querybatch`` + ``/v1/vulns/{id}``).
  3. Single-shot, on-demand, never daily — see ``references/security-disclosure-triage.md``.
  4. """
  5. from __future__ import annotations
  6. import argparse
  7. import concurrent.futures
  8. import json
  9. import re
  10. import sys
  11. import urllib.error
  12. import urllib.request
  13. from dataclasses import dataclass, field
  14. from pathlib import Path
  15. from typing import Iterable, Optional
  16. from hermes_constants import get_hermes_home
  17. OSV_BATCH_URL = "https://api.osv.dev/v1/querybatch"
  18. OSV_VULN_URL = "https://api.osv.dev/v1/vulns/{vid}"
  19. OSV_BATCH_MAX = 1000 # OSV documented hard cap per request
  20. HTTP_TIMEOUT = 20
  21. DETAIL_PARALLELISM = 8
  22. # Severity ordering for --fail-on gating. UNKNOWN sits below LOW so it never blocks.
  23. SEVERITY_ORDER = {"UNKNOWN": 0, "LOW": 1, "MODERATE": 2, "MEDIUM": 2, "HIGH": 3, "CRITICAL": 4}
  24. @dataclass(frozen=True)
  25. class Component:
  26. """A single (name, version, ecosystem) tuple discovered on disk."""
  27. name: str
  28. version: str
  29. ecosystem: str # "PyPI" | "npm" — exactly as OSV expects
  30. source: str # human-readable origin, e.g. "venv", "plugin:foo", "mcp:bar"
  31. @dataclass
  32. class Vulnerability:
  33. osv_id: str
  34. severity: str = "UNKNOWN"
  35. summary: str = ""
  36. fixed_versions: list[str] = field(default_factory=list)
  37. @dataclass
  38. class Finding:
  39. component: Component
  40. vuln: Vulnerability
  41. def _discover_venv() -> list[Component]:
  42. """Every dist installed in the running Python's import path."""
  43. from importlib.metadata import distributions
  44. out: dict[tuple[str, str], Component] = {}
  45. for dist in distributions():
  46. try:
  47. name = (dist.metadata["Name"] or "").strip()
  48. except Exception:
  49. continue
  50. version = (dist.version or "").strip()
  51. if name.lower().replace("_", "-") == "hermes-agent" and version == "0.0.0":
  52. # pyproject declares 0.0.0 in source trees, which matches every advisory ever filed:
  53. # audit the running release instead, and skip the dist when no release is known.
  54. from hermes_cli.version_info import get_version_info
  55. version = get_version_info().base_version
  56. if version == "unknown":
  57. continue
  58. if name and version:
  59. out.setdefault((name.lower(), version), Component(name=name, version=version, ecosystem="PyPI", source="venv"))
  60. return list(out.values())
  61. # ``name[extras]==version ; marker`` — an exact pin, optionally with extras and an environment marker.
  62. _REQ_LINE = re.compile(r"^\s*(?P<name>[A-Za-z0-9][A-Za-z0-9._-]*)(?:\[[^\]]+\])?\s*==\s*(?P<version>[A-Za-z0-9._+!-]+)\s*(?:;.*)?$")
  63. def _match_pins(specs: Iterable[str]) -> list[tuple[str, str]]:
  64. """``name==version`` pairs for every spec that is an exact pin; all others are skipped."""
  65. return [(m.group("name"), m.group("version")) for spec in specs if (m := _REQ_LINE.match(spec))]
  66. def _parse_requirements(text: str) -> list[tuple[str, str]]:
  67. """Extract ``name==version`` pins. Loose specs (>=, ~=, no pin) are skipped: they can't map to
  68. a single OSV query, and false positives train users to ignore an audit tool's output.
  69. """
  70. lines = (raw.strip() for raw in text.splitlines())
  71. return _match_pins(line for line in lines if line and not line.startswith(("#", "-")))
  72. def _parse_pyproject_pins(text: str) -> list[tuple[str, str]]:
  73. """Pull ``name==version`` pins from a ``pyproject.toml`` ``dependencies`` list."""
  74. try:
  75. import tomllib
  76. project = tomllib.loads(text).get("project") or {}
  77. except Exception:
  78. return []
  79. optional = project.get("optional-dependencies") or {}
  80. groups = [project.get("dependencies")] + (list(optional.values()) if isinstance(optional, dict) else [])
  81. return _match_pins(str(x) for group in groups if isinstance(group, list) for x in group)
  82. _PLUGIN_PIN_FILES = (("requirements.txt", _parse_requirements), ("requirements-dev.txt", _parse_requirements),
  83. ("pyproject.toml", _parse_pyproject_pins))
  84. def _discover_plugins(hermes_home: Path) -> list[Component]:
  85. """Python deps declared by plugins under ``~/.hermes/plugins``. Plugins typically don't install
  86. into the venv, so their stated requirements are audit surface the venv scan misses.
  87. """
  88. plugins_dir = hermes_home / "plugins"
  89. if not plugins_dir.is_dir():
  90. return []
  91. out: list[Component] = []
  92. for plugin_dir in sorted(plugins_dir.iterdir()):
  93. if not plugin_dir.is_dir() or plugin_dir.name.startswith("."):
  94. continue
  95. for filename, parse in _PLUGIN_PIN_FILES:
  96. path = plugin_dir / filename
  97. try:
  98. pins = parse(path.read_text(encoding="utf-8-sig", errors="replace")) if path.is_file() else []
  99. except OSError:
  100. continue
  101. out.extend(Component(name=n, version=v, ecosystem="PyPI", source=f"plugin:{plugin_dir.name}") for n, v in pins)
  102. return out
  103. # Recognised pinned refs: ``npx [-y|--yes] [@scope/]pkg@1.2.3`` and ``uvx [--with] pkg==1.2.3``.
  104. # Unversioned names map to "latest" at runtime and aren't a stable audit subject.
  105. _NPX_PKG = re.compile(r"^(@[A-Za-z0-9._-]+/[A-Za-z0-9._-]+|[A-Za-z0-9._-]+)@([A-Za-z0-9._+-]+)$")
  106. _UVX_PKG = re.compile(r"^([A-Za-z0-9][A-Za-z0-9._-]*)==([A-Za-z0-9._+!-]+)$")
  107. # launcher basename -> (package-ref regex, OSV ecosystem)
  108. _MCP_LAUNCHERS = {"npx": (_NPX_PKG, "npm"), "uvx": (_UVX_PKG, "PyPI")}
  109. def _extract_mcp_component(server_name: str, command: str, args: list[str]) -> Optional[Component]:
  110. """Parse `command/args` into a Component, or None when the entry doesn't pin an auditable
  111. version (local paths, Docker images, unversioned npx, ...) — stay silent rather than guess.
  112. """
  113. cmd = (command or "").strip().lower()
  114. launcher = next((k for k in _MCP_LAUNCHERS if cmd.endswith(k)), None) # any prefix path
  115. # Skip flag tokens; the first non-flag token must be a pinned ref or we stay silent.
  116. ref = next((token for token in args if not token.startswith("-")), None)
  117. if launcher is None or ref is None:
  118. return None
  119. pattern, ecosystem = _MCP_LAUNCHERS[launcher]
  120. m = pattern.match(ref)
  121. return m and Component(name=m.group(1), version=m.group(2), ecosystem=ecosystem, source=f"mcp:{server_name}")
  122. def _discover_mcp() -> list[Component]:
  123. """Pinned MCP server packages from ``config.yaml``."""
  124. try:
  125. from hermes_cli.mcp_config import _get_mcp_servers
  126. except Exception:
  127. return []
  128. servers = _get_mcp_servers()
  129. if not isinstance(servers, dict):
  130. return []
  131. comps = (
  132. _extract_mcp_component(name, cfg.get("command", "") or "", [str(a) for a in cfg.get("args") or []])
  133. for name, cfg in servers.items()
  134. if isinstance(cfg, dict) and isinstance(cfg.get("args") or [], list)
  135. )
  136. return [c for c in comps if c]
  137. _HTTP_ERRORS = (urllib.error.URLError, TimeoutError, ConnectionError)
  138. def _http_json(url: str, payload: Optional[dict] = None) -> dict:
  139. """GET ``url`` (or POST ``payload`` as JSON when given) and decode the JSON body."""
  140. req = urllib.request.Request(url, method="GET") if payload is None else urllib.request.Request(
  141. url, data=json.dumps(payload).encode("utf-8"), method="POST", headers={"Content-Type": "application/json"})
  142. with urllib.request.urlopen(req, timeout=HTTP_TIMEOUT) as resp:
  143. return json.loads(resp.read().decode("utf-8"))
  144. def _osv_query_batch(components: list[Component]) -> dict[Component, list[str]]:
  145. """Return {component -> [osv_id, ...]} for components with any vulns."""
  146. findings: dict[Component, list[str]] = {}
  147. for chunk_start in range(0, len(components), OSV_BATCH_MAX):
  148. chunk = components[chunk_start:chunk_start + OSV_BATCH_MAX]
  149. payload = {"queries": [{"package": {"name": c.name, "ecosystem": c.ecosystem}, "version": c.version} for c in chunk]}
  150. try:
  151. resp = _http_json(OSV_BATCH_URL, payload)
  152. except _HTTP_ERRORS as exc:
  153. raise RuntimeError(f"OSV batch query failed: {exc}") from exc
  154. for comp, result in zip(chunk, resp.get("results") or []):
  155. if ids := [v.get("id") for v in (result or {}).get("vulns") or [] if v.get("id")]:
  156. findings[comp] = ids
  157. return findings
  158. def _osv_severity_from_record(record: dict) -> str:
  159. """CVSS-derived severity tier from an OSV vuln record.
  160. Top-level ``severity`` holds CVSS vector strings we can't tier without a lib, so use the GHSA
  161. ``database_specific`` bucket first, then the per-affected ``ecosystem_specific`` one.
  162. """
  163. candidates = [(record.get("database_specific") or {}).get("severity")] + [
  164. (entry.get("ecosystem_specific") or {}).get("severity") for entry in record.get("affected") or []]
  165. tiers = (sev.strip().upper() for sev in candidates if isinstance(sev, str))
  166. return next((tier for tier in tiers if tier in SEVERITY_ORDER), "UNKNOWN")
  167. def _osv_fixed_versions(record: dict) -> list[str]:
  168. fixes = [str(event["fixed"]) for entry in record.get("affected") or [] for rng in entry.get("ranges") or []
  169. for event in rng.get("events") or [] if "fixed" in event]
  170. return list(dict.fromkeys(fixes)) # dedupe, preserve order
  171. def _osv_fetch_details(vuln_ids: Iterable[str]) -> dict[str, Vulnerability]:
  172. """Fetch summary/severity for each unique vuln id, in parallel."""
  173. def _fetch_one(vid: str) -> Vulnerability:
  174. try:
  175. rec = _http_json(OSV_VULN_URL.format(vid=vid))
  176. except _HTTP_ERRORS:
  177. return Vulnerability(osv_id=vid)
  178. return Vulnerability(vid, _osv_severity_from_record(rec), (rec.get("summary") or "").strip(), _osv_fixed_versions(rec))
  179. unique = sorted({vid for vid in vuln_ids if vid})
  180. if not unique:
  181. return {}
  182. with concurrent.futures.ThreadPoolExecutor(max_workers=DETAIL_PARALLELISM) as pool:
  183. return {vuln.osv_id: vuln for vuln in pool.map(_fetch_one, unique)}
  184. def _discover_components(
  185. *, skip_venv: bool = False, skip_plugins: bool = False, skip_mcp: bool = False, hermes_home: Optional[Path] = None
  186. ) -> list[Component]:
  187. """Discover all scannable components across the enabled sources."""
  188. home = hermes_home or Path(get_hermes_home())
  189. sources = ((skip_venv, _discover_venv), (skip_plugins, lambda: _discover_plugins(home)), (skip_mcp, _discover_mcp))
  190. return [c for skip, discover in sources if not skip for c in discover()]
  191. def run_audit(*, components: Optional[list[Component]] = None, **discover_kwargs) -> list[Finding]:
  192. """Query OSV for ``components`` (or discover them with ``discover_kwargs`` when None; passing
  193. an already-discovered list avoids scanning the venv/plugins/MCP config a second time).
  194. """
  195. if components is None:
  196. components = _discover_components(**discover_kwargs)
  197. raw = _osv_query_batch(components) if components else {}
  198. if not raw:
  199. return []
  200. details = _osv_fetch_details(vid for ids in raw.values() for vid in ids)
  201. findings = [Finding(comp, details.get(vid) or Vulnerability(osv_id=vid)) for comp, ids in raw.items() for vid in ids]
  202. findings.sort(key=lambda f: (
  203. -SEVERITY_ORDER.get(f.vuln.severity, 0), f.component.source, f.component.name.lower(), f.vuln.osv_id
  204. ))
  205. return findings
  206. def _render_human(findings: list[Finding], total_components: int) -> str:
  207. if not findings:
  208. return f"No known vulnerabilities found across {total_components} component(s)."
  209. lines = [f"Found {len(findings)} known vulnerability finding(s) across {total_components} component(s):", ""]
  210. last_source = None
  211. for f in findings:
  212. c, v = f.component, f.vuln
  213. if c.source != last_source:
  214. lines.append(f"[{c.source}]")
  215. last_source = c.source
  216. lines.append(f" {v.severity.ljust(8)} {c.name}=={c.version} {v.osv_id}")
  217. if summary := v.summary:
  218. lines.append(f" {summary if len(summary) <= 100 else summary[:97] + '...'}")
  219. if v.fixed_versions:
  220. lines.append(f" fixed in: {', '.join(v.fixed_versions[:3])}")
  221. return "\n".join(lines)
  222. def _render_json(findings: list[Finding], total_components: int) -> str:
  223. payload = {
  224. "total_components_scanned": total_components,
  225. "finding_count": len(findings),
  226. "findings": [{
  227. "package": f.component.name, "version": f.component.version,
  228. "ecosystem": f.component.ecosystem, "source": f.component.source,
  229. "vuln_id": f.vuln.osv_id, "severity": f.vuln.severity,
  230. "summary": f.vuln.summary, "fixed_versions": f.vuln.fixed_versions,
  231. } for f in findings],
  232. }
  233. return json.dumps(payload, indent=2)
  234. def cmd_security_audit(args: argparse.Namespace) -> int:
  235. """Implementation of `hermes security audit`."""
  236. home = Path(get_hermes_home())
  237. output_json = bool(getattr(args, "json", False))
  238. fail_on = (getattr(args, "fail_on", None) or "critical").upper()
  239. if fail_on not in SEVERITY_ORDER:
  240. print(f"unknown --fail-on value: {fail_on.lower()} (choose from: low, moderate, high, critical)", file=sys.stderr)
  241. return 2
  242. skips = {k: bool(getattr(args, k, False)) for k in ("skip_venv", "skip_plugins", "skip_mcp")}
  243. components = _discover_components(hermes_home=home, **skips)
  244. total = len(components)
  245. if total == 0:
  246. print(json.dumps({"total_components_scanned": 0, "finding_count": 0, "findings": []}) if output_json
  247. else "No components discovered (everything skipped, or empty environment).")
  248. return 0
  249. try:
  250. findings = run_audit(hermes_home=home, components=components)
  251. except RuntimeError as exc:
  252. print(f"audit failed: {exc}", file=sys.stderr)
  253. return 2
  254. print((_render_json if output_json else _render_human)(findings, total))
  255. # Exit code: 1 iff any finding meets or exceeds the --fail-on threshold.
  256. threshold = SEVERITY_ORDER[fail_on]
  257. return int(any(SEVERITY_ORDER.get(f.vuln.severity, 0) >= threshold for f in findings))