image_provenance.py 3.6 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586
  1. """Image-authored deployment provenance for immutable Hermes runtimes.
  2. The image bakes ``/etc/hermes/image-provenance.json`` outside ``$HERMES_HOME`` and the checkout, so a
  3. bind-mounted checkout cannot hide the build fact and env/config cannot forge it. Absence preserves every
  4. source/package install path. Presence fails closed: an unreadable, non-regular, or malformed marker still
  5. means image-managed — an integrity defect, never permission to mutate the image in place."""
  6. from __future__ import annotations
  7. import json
  8. import stat
  9. from dataclasses import asdict, dataclass
  10. from pathlib import Path
  11. from typing import Any, Optional
  12. IMAGE_PROVENANCE_PATH = Path("/etc/hermes/image-provenance.json")
  13. IMAGE_PROVENANCE_SCHEMA = 1
  14. @dataclass(frozen=True)
  15. class ImageProvenance:
  16. """Validated provenance, or a fail-closed description of an invalid one."""
  17. schema: int
  18. deployment_kind: str
  19. manager: str
  20. image: Optional[str] = None
  21. version: Optional[str] = None
  22. revision: Optional[str] = None
  23. marker_path: str = ""
  24. valid: bool = True
  25. error: Optional[str] = None
  26. def to_dict(self) -> dict[str, Any]:
  27. return asdict(self)
  28. def _invalid(path: Path, reason: str) -> ImageProvenance:
  29. return ImageProvenance(IMAGE_PROVENANCE_SCHEMA, "image", "unknown", marker_path=str(path), valid=False, error=reason)
  30. def _optional_string(payload: dict, name: str) -> Optional[str]:
  31. value = payload.get(name)
  32. if value is not None and not isinstance(value, str):
  33. raise TypeError(name)
  34. return (value.strip() or None) if value is not None else None
  35. def read_image_provenance(marker_path: Optional[Path] = None) -> Optional[ImageProvenance]:
  36. """Read the baked marker without consulting environment or config. Never raises.
  37. ``marker_path`` is a dependency-injection seam for tests and alternate image builders."""
  38. path = IMAGE_PROVENANCE_PATH
  39. try:
  40. path = Path(marker_path) if marker_path is not None else path
  41. except BaseException as exc:
  42. return _invalid(path, f"marker_presence_unreadable:{type(exc).__name__}")
  43. try:
  44. marker_stat = path.lstat()
  45. except FileNotFoundError:
  46. return None
  47. except BaseException as exc: # permission errors and other lookup failures do not prove absence
  48. return _invalid(path, f"marker_presence_unreadable:{type(exc).__name__}")
  49. if not stat.S_ISREG(marker_stat.st_mode):
  50. return _invalid(path, "marker_not_regular_file")
  51. try:
  52. payload = json.loads(path.read_text(encoding="utf-8-sig"))
  53. except Exception as exc:
  54. # The file may disappear between lstat/read; it was nevertheless
  55. # observed present, so the decision remains fail-closed.
  56. return _invalid(path, f"marker_unreadable:{type(exc).__name__}")
  57. if not isinstance(payload, dict):
  58. return _invalid(path, "marker_not_object")
  59. schema = payload.get("schema")
  60. # ``bool`` subclasses ``int``: schema ``true`` must not be accepted as schema 1.
  61. if type(schema) is not int or schema != IMAGE_PROVENANCE_SCHEMA:
  62. return _invalid(path, "unsupported_marker_schema")
  63. if payload.get("deployment_kind") != "image":
  64. return _invalid(path, "invalid_deployment_kind")
  65. manager = payload.get("manager")
  66. if not isinstance(manager, str) or not manager.strip():
  67. return _invalid(path, "missing_manager")
  68. try:
  69. optional = {name: _optional_string(payload, name) for name in ("image", "version", "revision")}
  70. except TypeError as exc:
  71. return _invalid(path, f"invalid_{exc.args[0]}")
  72. return ImageProvenance(IMAGE_PROVENANCE_SCHEMA, "image", manager.strip(), marker_path=str(path), **optional)