dockerls 1.0.0__py3-none-any.whl

dockerls/domain/value_objects/registry_audit.py

@@ -0,0 +1,195 @@
+"""O que se consegue apurar sobre uma imagem *pelo registry*, sem credencial.
+
+Auditar a configuração de um registry -- políticas de retenção, IAM, content
+trust -- exige credencial de nuvem e uma API diferente para cada provedor. Não
+é isto aqui. Este módulo é a parte que se mede com o protocolo OCI e mais nada,
+e é deliberadamente essa: um relatório que precisa de acesso administrativo
+para existir é um relatório que ninguém roda.
+
+O que dá para apurar assim é menos do que parece e mais do que se costuma
+olhar:
+
+* a referência resolve para um digest, e qual;
+* a referência que a pessoa usou já era um digest, ou era uma tag;
+* a tag já mudou de digest desde que esta ferramenta começou a olhar -- que é
+  a única evidência *medida* de que ela é mutável, em vez da configuração
+  declarada de imutabilidade, que ninguém confere;
+* existe assinatura cosign publicada para aquele digest;
+* existe atestação cosign publicada para aquele digest;
+* o registry respondeu sem nenhuma credencial -- ou seja, a imagem é legível
+  por qualquer pessoa da internet.
+
+Cada achado é tri-estado por construção. `UNKNOWN` não é um detalhe do formato:
+sem ele, "o registry não respondeu" viraria "não há assinatura", e essa é
+exatamente a substituição que faz um relatório de segurança mentir.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from dockerls.domain.value_objects.tristate import Tristate
+
+
+class AuditCheck(StrEnum):
+    """Cada coisa que se pergunta ao registry."""
+
+    RESOLVABLE = "RESOLVABLE"
+    PINNED_REFERENCE = "PINNED_REFERENCE"
+    TAG_STABLE = "TAG_STABLE"
+    SIGNATURE_PRESENT = "SIGNATURE_PRESENT"
+    ATTESTATION_PRESENT = "ATTESTATION_PRESENT"
+    PUBLICLY_READABLE = "PUBLICLY_READABLE"
+
+
+#: Checagens que são relatadas e nunca alertam. `PUBLICLY_READABLE` está aqui
+#: porque "público" é o estado *correto* de uma imagem base oficial e o estado
+#: errado de um artefato interno -- e a diferença entre os dois é a intenção de
+#: quem publicou, que esta ferramenta não tem como medir. Transformar o fato em
+#: alerta seria afirmar uma intenção; relatá-lo sem alertar entrega o fato a
+#: quem sabe qual era.
+_INFORMATIONAL = frozenset({AuditCheck.PUBLICLY_READABLE})
+
+
+@dataclass(frozen=True)
+class AuditFinding:
+    """Uma resposta do registry, com o que ela significa."""
+
+    check: AuditCheck
+    state: Tristate
+    detail: str = ""
+
+    @property
+    def is_informational(self) -> bool:
+        """Se é um fato relatado sem juízo de valor. Ver `_INFORMATIONAL`."""
+        return self.check in _INFORMATIONAL
+
+    @property
+    def is_alert(self) -> bool:
+        """Se este achado pede ação.
+
+        `UNKNOWN` nunca é alerta e nunca é aprovação: é ausência de resposta, e
+        entra no relatório como tal.
+        """
+        if not self.state.is_known or self.check in _INFORMATIONAL:
+            return False
+        return self.state.is_false
+
+    @property
+    def is_unmeasured(self) -> bool:
+        return not self.state.is_known
+
+    def explain(self) -> str:
+        return _EXPLANATIONS[self.check][str(self.state)]
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "check": str(self.check),
+            "state": str(self.state),
+            "alert": self.is_alert,
+            "explanation": self.explain(),
+            "detail": self.detail,
+        }
+
+
+_EXPLANATIONS: dict[AuditCheck, dict[str, str]] = {
+    AuditCheck.RESOLVABLE: {
+        "true": "the registry answered which digest this reference points at",
+        "false": (
+            "the registry did not resolve this reference: without a digest, nothing "
+            "else here can be measured"
+        ),
+        "unknown": "the registry could not be asked",
+    },
+    AuditCheck.PINNED_REFERENCE: {
+        "true": "the reference is already a digest: it points at specific bytes",
+        "false": (
+            "the reference is a tag: what was tested and what runs can be different "
+            "bytes with no change of yours"
+        ),
+        "unknown": "the shape of the reference could not be determined",
+    },
+    AuditCheck.TAG_STABLE: {
+        "true": "this tag has not changed digest since we started watching it",
+        "false": (
+            "this tag has already changed digest: measured evidence that it is "
+            "mutable, whatever the registry immutability setting says"
+        ),
+        "unknown": (
+            "there is no history for this tag: what happened before the first "
+            "observation is unknown, not absent"
+        ),
+    },
+    AuditCheck.SIGNATURE_PRESENT: {
+        "true": "a cosign signature is published for this digest",
+        "false": (
+            "no cosign signature is published for this digest: nobody publicly "
+            "attested to producing these bytes"
+        ),
+        "unknown": "the registry could not be asked about the signature",
+    },
+    AuditCheck.ATTESTATION_PRESENT: {
+        "true": "a cosign attestation is published for this digest",
+        "false": (
+            "no attestation is published for this digest: the registry holds no "
+            "record of how this image was built"
+        ),
+        "unknown": "the registry could not be asked about the attestation",
+    },
+    AuditCheck.PUBLICLY_READABLE: {
+        "true": (
+            "the registry answered with no credential at all: anyone on the internet "
+            "can pull this image and inspect what is inside it. Whether that is a "
+            "problem depends on what it exists for, and only you know that part"
+        ),
+        "false": "the registry required a credential to answer",
+        "unknown": "whether anonymous access is allowed could not be determined",
+    },
+}
+
+
+@dataclass(frozen=True)
+class RegistryAudit:
+    """O conjunto de respostas para uma referência."""
+
+    reference: str
+    digest: str = ""
+    findings: tuple[AuditFinding, ...] = field(default_factory=tuple)
+
+    @property
+    def alerts(self) -> tuple[AuditFinding, ...]:
+        return tuple(f for f in self.findings if f.is_alert)
+
+    @property
+    def unmeasured(self) -> tuple[AuditFinding, ...]:
+        return tuple(f for f in self.findings if f.is_unmeasured)
+
+    def summary(self) -> str:
+        if not self.findings:
+            return "nothing could be established about this reference"
+        partes = [f"{len(self.alerts)} finding(s) that want attention"]
+        if self.unmeasured:
+            partes.append(f"{len(self.unmeasured)} not measured")
+        return ", ".join(partes)
+
+    def caveat(self) -> str:
+        return (
+            "this audit uses the OCI protocol alone, with no cloud credential: it "
+            "does not read retention policies, IAM, or the provider immutability "
+            "settings. What it measures, it measures for real; what it does not, it "
+            "says it did not"
+        )
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "reference": self.reference,
+            "digest": self.digest,
+            "summary": self.summary(),
+            "caveat": self.caveat(),
+            "alerts": len(self.alerts),
+            "unmeasured": len(self.unmeasured),
+            "findings": [f.to_dict() for f in self.findings],
+        }

dockerls/domain/value_objects/registry_target.py

@@ -0,0 +1,225 @@
+"""Para onde a imagem vai, e o que cada provedor exige antes de aceitar.
+
+O `--push` existente rodava `docker push <tag>` com a tag local, exatamente
+como ela foi construída. Numa tag sem host -- `dockerls:1.3.2`, que é a forma
+que todo mundo digita -- isso vira uma tentativa de publicar em
+`docker.io/library/dockerls`, que falha com "denied" para qualquer pessoa que
+não seja mantenedora de uma imagem oficial. E o assistente interativo oferecia
+escolher entre "dockerhub", "ghcr" e "harbor" sem usar a resposta para nada:
+nenhuma delas mudava o destino do push.
+
+Este módulo é a peça que faltava. Ele não fala com registry nenhum -- é
+domínio puro, testável sem rede -- e responde três perguntas que precisam de
+resposta *antes* do build começar:
+
+* **para onde**, montando a referência completa a partir de host, namespace,
+  repositório e tag;
+* **isso é válido para este provedor**, porque as regras diferem de verdade: o
+  Artifact Registry do Google exige `projeto/repositório` no caminho, o ACR do
+  Azure exige um host `<registro>.azurecr.io`, e o Docker Hub exige um
+  namespace que não seja `library`;
+* **como autenticar**, nomeando o comando de login de cada provedor, já que é
+  a primeira coisa que falta quando um push é recusado.
+
+Perguntar antes do build, e não depois, é o ponto: descobrir que o destino
+está errado depois de escanear e construir desperdiça o trabalho todo, e é
+justamente quando a pessoa está mais propensa a publicar em qualquer lugar só
+para não repetir a espera.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from enum import StrEnum
+
+
+class RegistryProvider(StrEnum):
+    """Quem hospeda o destino. Determina validação e forma de login."""
+
+    DOCKER_HUB = "Docker Hub"
+    AZURE_ACR = "Azure Container Registry"
+    GOOGLE_ARTIFACT_REGISTRY = "Google Artifact Registry"
+    GOOGLE_CONTAINER_REGISTRY = "Google Container Registry"
+    DHI = "Docker Hardened Images"
+    GITHUB_GHCR = "GitHub Container Registry"
+    OTHER = "Registry privado"
+
+
+#: Hosts que significam Docker Hub.
+_DOCKER_HUB_HOSTS = frozenset({"", "docker.io", "index.docker.io", "registry-1.docker.io"})
+
+#: `<registro>.azurecr.io`, incluindo as nuvens soberanas (`.azurecr.cn`,
+#: `.azurecr.us`), que são o mesmo produto em outra geografia.
+_ACR_HOST = re.compile(r"^[a-z0-9]+\.azurecr\.(io|cn|us)$")
+
+#: `<região>-docker.pkg.dev` do Artifact Registry.
+_GAR_HOST = re.compile(r"^[a-z0-9-]+-docker\.pkg\.dev$")
+
+#: O GCR clássico, incluindo os espelhos regionais (`eu.gcr.io`).
+_GCR_HOST = re.compile(r"^(?:[a-z0-9]+\.)?gcr\.io$")
+
+#: Componente de caminho aceito por qualquer registry OCI.
+_PATH_COMPONENT = re.compile(r"^[a-z0-9]+(?:(?:[._]|__|-+)[a-z0-9]+)*$")
+
+#: Tag OCI.
+_TAG = re.compile(r"^[a-zA-Z0-9_][a-zA-Z0-9._-]{0,127}$")
+
+
+def detect_provider(host: str) -> RegistryProvider:
+    """Quem hospeda `host`. Um host desconhecido é registry privado, não erro."""
+    value = host.strip().lower()
+    if value in _DOCKER_HUB_HOSTS:
+        return RegistryProvider.DOCKER_HUB
+    if _ACR_HOST.match(value):
+        return RegistryProvider.AZURE_ACR
+    if _GAR_HOST.match(value):
+        return RegistryProvider.GOOGLE_ARTIFACT_REGISTRY
+    if _GCR_HOST.match(value):
+        return RegistryProvider.GOOGLE_CONTAINER_REGISTRY
+    if value == "dhi.io":
+        return RegistryProvider.DHI
+    if value == "ghcr.io":
+        return RegistryProvider.GITHUB_GHCR
+    return RegistryProvider.OTHER
+
+
+#: Como autenticar em cada provedor. Nomeado porque é o que falta em quase
+#: todo push recusado, e porque a mensagem genérica do Docker ("denied")
+#: não diz qual comando resolve.
+LOGIN_HINTS: dict[RegistryProvider, str] = {
+    RegistryProvider.DOCKER_HUB: (
+        "docker login  (or `dockerls login`, which stores it in the keyring)"
+    ),
+    RegistryProvider.AZURE_ACR: "az acr login --name <registry>",
+    RegistryProvider.GOOGLE_ARTIFACT_REGISTRY: (
+        "gcloud auth configure-docker <region>-docker.pkg.dev"
+    ),
+    RegistryProvider.GOOGLE_CONTAINER_REGISTRY: "gcloud auth configure-docker gcr.io",
+    RegistryProvider.DHI: "docker login dhi.io  (requires a Docker Hardened Images subscription)",
+    RegistryProvider.GITHUB_GHCR: (
+        "echo $GITHUB_TOKEN | docker login ghcr.io -u <username> --password-stdin"
+    ),
+    RegistryProvider.OTHER: "docker login <host>",
+}
+
+
+class InvalidRegistryTargetError(ValueError):
+    """O destino não é publicável como está, com o motivo em texto."""
+
+
+@dataclass(frozen=True)
+class RegistryTarget:
+    """Um destino de publicação completo, validado por provedor.
+
+    `namespace` é o caminho entre o host e o repositório, e é onde os
+    provedores divergem: no Docker Hub é o usuário ou organização; no ACR
+    costuma ser vazio ou um agrupamento livre; no Artifact Registry é
+    obrigatoriamente `<projeto>/<repositório>`.
+    """
+
+    host: str
+    repository: str
+    tag: str
+    namespace: str = ""
+
+    @property
+    def provider(self) -> RegistryProvider:
+        return detect_provider(self.host)
+
+    @property
+    def path(self) -> str:
+        parts = [p for p in (self.namespace.strip("/"), self.repository.strip("/")) if p]
+        return "/".join(parts)
+
+    @property
+    def reference(self) -> str:
+        """A referência que vai para `docker tag` e `docker push`."""
+        host = self.host.strip().strip("/")
+        base = f"{host}/{self.path}" if host else self.path
+        return f"{base}:{self.tag}"
+
+    @property
+    def login_hint(self) -> str:
+        return LOGIN_HINTS[self.provider]
+
+    def validate(self) -> None:
+        """Levanta `InvalidRegistryTargetError` com o motivo, ou não faz nada.
+
+        Validar aqui, antes do build, é o objetivo do módulo: um destino
+        malformado descoberto depois do scan custa o build inteiro.
+        """
+        if not self.repository.strip():
+            raise InvalidRegistryTargetError("the destination repository cannot be empty")
+        if not _TAG.match(self.tag or ""):
+            raise InvalidRegistryTargetError(f"invalid tag: {self.tag!r}")
+        for component in self.path.split("/"):
+            if not _PATH_COMPONENT.match(component):
+                raise InvalidRegistryTargetError(
+                    f"invalid path component: {component!r} "
+                    "(lowercase, digits, and the . _ - separators)"
+                )
+        self._validate_provider()
+
+    def _validate_provider(self) -> None:
+        provider = self.provider
+        if provider is RegistryProvider.DOCKER_HUB:
+            # Sem namespace, `docker push` mira `library/<repo>`, que é
+            # reservado às imagens oficiais: o push é recusado com "denied" e
+            # a mensagem não explica por quê.
+            if not self.namespace.strip("/"):
+                raise InvalidRegistryTargetError(
+                    "Docker Hub requires the user or organization as the namespace "
+                    "(e.g. myorg/dockerls); without it the push targets library/, "
+                    "which is reserved for official images"
+                )
+            if self.namespace.strip("/").lower() == "library":
+                raise InvalidRegistryTargetError(
+                    "`library` is the namespace of Docker Hub official images and "
+                    "does not accept third-party publishing"
+                )
+        elif provider is RegistryProvider.GOOGLE_ARTIFACT_REGISTRY:
+            # gcr.io aceitava `projeto/imagem`; o Artifact Registry exige o
+            # repositório no caminho, e omiti-lo falha só na hora do push.
+            if len(self.path.split("/")) < 3:
+                raise InvalidRegistryTargetError(
+                    "Artifact Registry requires <project>/<repository>/<image> in the "
+                    "path (e.g. my-project/containers/dockerls)"
+                )
+        elif provider is RegistryProvider.DHI:
+            raise InvalidRegistryTargetError(
+                "dhi.io is a Docker image catalogue, not a publish destination: it "
+                "distributes hardened images and does not accept pushes"
+            )
+
+    @classmethod
+    def parse(cls, destination: str, tag: str) -> RegistryTarget:
+        """Monta um destino a partir de `host/namespace/repo` e uma tag.
+
+        O host é reconhecido pela mesma regra do Docker -- primeiro componente
+        com ponto, dois-pontos, ou igual a `localhost` --, e o que sobra é
+        dividido em namespace e repositório.
+        """
+        value = destination.strip().strip("/")
+        if not value:
+            raise InvalidRegistryTargetError("empty destination")
+        # Uma tag embutida no destino é ambiguidade, não conveniência: qual
+        # das duas vale, a de `--tag` ou a colada aqui?
+        head = value.split("/", 1)[0]
+        if ":" in value.rsplit("/", 1)[-1]:
+            raise InvalidRegistryTargetError(
+                "give the destination without a tag; the tag comes from --tag so "
+                "there are never two"
+            )
+
+        if "." in head or ":" in head or head.lower() == "localhost":
+            host, _, rest = value.partition("/")
+        else:
+            host, rest = "", value
+        if not rest:
+            raise InvalidRegistryTargetError(
+                f"the destination {destination!r} does not name a repository"
+            )
+
+        namespace, _, repository = rest.rpartition("/")
+        return cls(host=host, repository=repository, tag=tag, namespace=namespace)

dockerls/domain/value_objects/remediation_score.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from dockerls.domain.entities.scan_result import ScanResult
+
+
+#: Faixas de `fixable / total` e a nota que cada uma vale. É uma escala
+#: ordinal de cinco degraus, deliberadamente -- não uma porcentagem. A
+#: proporção exata oscila a cada atualização de banco de vulnerabilidades, e
+#: um número que muda de 41% para 39% sozinho sugere uma precisão que o dado
+#: não tem. O degrau responde à pergunta que interessa: "dá para consertar a
+#: maior parte disto?".
+_BANDS: tuple[tuple[float, int], ...] = (
+    (1.0, 100),
+    (0.75, 80),
+    (0.5, 60),
+    (0.25, 40),
+)
+_LOWEST_BAND = 20
+
+
+class RemediationScore:
+    """Quão remediável é um scan, numa escala ordinal de 0 a 100.
+
+    **Não é a porcentagem de vulnerabilidades corrigíveis.** É a razão
+    `fixable / total` mapeada em cinco degraus:
+
+    | fixable / total | nota |
+    |-----------------|------|
+    | 100%            | 100  |
+    | >= 75%          |  80  |
+    | >= 50%          |  60  |
+    | >= 25%          |  40  |
+    | < 25%           |  20  |
+    | sem vulns       | 100  |
+
+    Ou seja: 16 corrigíveis em 170 (9,4%) valem **20**, e isso está correto.
+    Ler esse 20 como "20%" -- que era o que o terminal sugeria ao imprimir um
+    `%` ao lado -- faz o número parecer errado por um fator de dois. Quem
+    quiser a proporção crua a tem impressa ao lado, em `analyze`.
+    """
+
+    def __init__(self, scan: ScanResult):
+        self._scan = scan
+        self._value = self._calculate()
+
+    @property
+    def value(self) -> int:
+        return self._value
+
+    def _calculate(self) -> int:
+        total = self._scan.total_count
+        if total == 0:
+            return 100
+
+        ratio = self._scan.fixable_count / total
+        for threshold, score in _BANDS:
+            if ratio >= threshold:
+                return score
+        return _LOWEST_BAND

dockerls/domain/value_objects/scan_history.py

@@ -0,0 +1,183 @@
+"""How an image's vulnerability counts moved across scans over time.
+
+`tag_history.py` answers "did the bytes behind this reference change";
+this answers the question underneath it -- "when this reference was
+scanned again, did the count of findings go up or down". Neither implies
+the other: a tag can move to a new digest with fewer CVEs, or stay on the
+exact same digest while the scanner's database learns about a new one
+between two runs.
+
+Same two choices as `tag_history.py`, for the same reasons:
+
+* **Only a change enters.** Scanning the same reference twice with the
+  same digest and the same counts is not a second event; recording it
+  anyway would bury the actual changes in noise.
+* **The first observation is never the one pruning drops.** It anchors
+  "since when", and a history that starts at an arbitrary later point is
+  a history that lies about how long it has been watching.
+
+Nothing here claims a reference was ever *clean*: the history begins at
+the first scan this tool happened to run, and whatever came before that is
+unknown, not absent.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, replace
+
+#: Same ceiling as `tag_history.py`, for the same reason: enough
+#: observations to see a trend, small enough that a whole fleet's history
+#: does not turn the cache into a database by accident.
+MAX_OBSERVATIONS = 24
+
+#: The dimensions tracked and, in this order, reported when they change.
+_FIELDS = ("critical", "high", "medium", "low", "total")
+
+
+@dataclass(frozen=True)
+class ScanObservation:
+    """One scan's counts, and when this tool saw them."""
+
+    digest: str
+    observed_at: str
+    critical: int = 0
+    high: int = 0
+    medium: int = 0
+    low: int = 0
+    total: int = 0
+
+    def counts(self) -> tuple[int, ...]:
+        """The tracked dimensions as a tuple, in `_FIELDS` order -- for
+        comparing two observations without naming every field."""
+        return tuple(getattr(self, name) for name in _FIELDS)
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "digest": self.digest,
+            "observed_at": self.observed_at,
+            **{name: getattr(self, name) for name in _FIELDS},
+        }
+
+    @staticmethod
+    def from_dict(raw: object) -> ScanObservation | None:
+        """An observation from the cache, or `None` when the row is unusable.
+
+        The cache is content from outside this call: a corrupted entry or
+        one written by an earlier version must not take down a scan.
+        """
+        if not isinstance(raw, dict):
+            return None
+        digest = raw.get("digest")
+        observed = raw.get("observed_at")
+        if not isinstance(digest, str) or not isinstance(observed, str) or not digest.strip():
+            return None
+        counts: dict[str, int] = {}
+        for name in _FIELDS:
+            value = raw.get(name, 0)
+            if not isinstance(value, int) or isinstance(value, bool) or value < 0:
+                return None
+            counts[name] = value
+        return ScanObservation(digest=digest.strip(), observed_at=observed.strip(), **counts)
+
+
+@dataclass(frozen=True)
+class ScanHistory:
+    """What is known about a reference's vulnerability counts, in order."""
+
+    reference: str
+    observations: tuple[ScanObservation, ...] = field(default_factory=tuple)
+    #: Same accounting as `TagHistory.dropped`: observations pruned off the
+    #: front, counted rather than silently forgotten.
+    dropped: int = 0
+
+    @property
+    def is_empty(self) -> bool:
+        return not self.observations
+
+    @property
+    def scans(self) -> int:
+        """Total scans this history has ever recorded, pruned ones included."""
+        return len(self.observations) + self.dropped
+
+    @property
+    def first_seen(self) -> str:
+        return self.observations[0].observed_at if self.observations else ""
+
+    @property
+    def latest(self) -> ScanObservation | None:
+        return self.observations[-1] if self.observations else None
+
+    def explain(self) -> str:
+        """The sentence that turns two counts into a fact worth reading."""
+        if self.is_empty:
+            return "first scan recorded for this reference: there is no history to compare against"
+        if len(self.observations) == 1:
+            return f"first scan recorded on {self.first_seen}; nothing to compare it to yet"
+
+        previous, current = self.observations[-2], self.observations[-1]
+        deltas = _describe_deltas(previous, current)
+        if not deltas:
+            return f"unchanged since the previous scan on {previous.observed_at}"
+        return f"since {previous.observed_at}: " + ", ".join(deltas)
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "reference": self.reference,
+            "scans": self.scans,
+            "dropped_observations": self.dropped,
+            "first_seen": self.first_seen,
+            "explanation": self.explain(),
+            "observations": [o.to_dict() for o in self.observations],
+        }
+
+    @staticmethod
+    def from_dict(reference: str, raw: object) -> ScanHistory:
+        """Reconstructs from the cache, discarding whatever does not parse.
+
+        An unreadable history becomes an empty one -- which is honest:
+        nothing usable is known about this reference. Never an exception:
+        this is an extra on top of the scan, not something that may block it.
+        """
+        if not isinstance(raw, dict):
+            return ScanHistory(reference=reference)
+        entries = raw.get("observations")
+        if not isinstance(entries, list):
+            return ScanHistory(reference=reference)
+        parsed = [o for o in (ScanObservation.from_dict(e) for e in entries) if o is not None]
+        dropped = raw.get("dropped_observations")
+        return ScanHistory(
+            reference=reference,
+            observations=tuple(parsed),
+            dropped=dropped if isinstance(dropped, int) and dropped >= 0 else 0,
+        )
+
+
+def _describe_deltas(previous: ScanObservation, current: ScanObservation) -> list[str]:
+    deltas = []
+    for name in _FIELDS:
+        change = getattr(current, name) - getattr(previous, name)
+        if change:
+            deltas.append(f"{name} {change:+d}")
+    return deltas
+
+
+def record(history: ScanHistory, observation: ScanObservation) -> ScanHistory:
+    """The history with this observation incorporated.
+
+    An observation whose digest and every count match the last one
+    recorded changes nothing worth saying, so it is dropped -- the same
+    rule `tag_history.record` applies to a tag that did not move.
+    """
+    if not observation.digest.strip():
+        return history
+    if history.observations:
+        last = history.observations[-1]
+        if last.digest == observation.digest and last.counts() == observation.counts():
+            return history
+
+    entries = (*history.observations, observation)
+    dropped = history.dropped
+    if len(entries) > MAX_OBSERVATIONS:
+        dropped += len(entries) - MAX_OBSERVATIONS
+        entries = (entries[0], *entries[-(MAX_OBSERVATIONS - 1) :])
+    return replace(history, observations=entries, dropped=dropped)