dockerls 1.0.0__py3-none-any.whl

dockerls/utils/ignore_file.py

@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+import re
+from datetime import date
+from pathlib import Path
+
+import yaml
+from loguru import logger
+from pydantic import BaseModel, field_validator
+
+from dockerls.domain.value_objects.vex import VexJustification, parse_justification
+
+DEFAULT_IGNORE_FILENAME = ".dockerls-ignore.yaml"
+
+#: A forma mínima de um identificador de aviso. Larga o bastante para
+#: `CVE-2024-1234`, `GHSA-xxxx-yyyy-zzzz`, `DSA-5555-1`, `RUSTSEC-2024-0001`
+#: e `ALAS2-2024-2500`; estreita o bastante para recusar o vazio, que casa
+#: com todo achado que o scanner reportou sem identificador.
+_ADVISORY_ID = re.compile(r"^[A-Z][A-Z0-9]*(?:[-_.][A-Z0-9]+)+$")
+
+
+class IgnoreRule(BaseModel):
+    cve: str
+    justification: str = ""
+    expires: date | None = None
+    #: A justificativa **do padrão VEX**, quando quem escreveu a regra
+    #: souber declarar uma. Opcional de propósito: `not_affected` é uma
+    #: afirmação técnica com vocabulário fechado, e a maioria das isenções
+    #: é decisão de risco ("aceito até o Q3"), que não é nenhuma delas.
+    #:
+    #: Sem ela, o documento OpenVEX sai como `affected` com a justificativa
+    #: em texto -- o consumidor vê a exceção e o motivo, sem receber uma
+    #: alegação técnica que ninguém fez. Ver `domain/value_objects/vex.py`.
+    vex_justification: str = ""
+
+    @field_validator("vex_justification")
+    @classmethod
+    def _known_vex_justification(cls, v: str) -> str:
+        """Recusa um valor que não existe no padrão.
+
+        Aceitá-lo produziria um documento VEX que outra ferramenta rejeita
+        na leitura -- e o erro apareceria longe daqui, sem dizer que veio
+        de uma linha do arquivo de isenções.
+        """
+        text = v.strip().lower()
+        if not text:
+            return ""
+        if parse_justification(text) is None:
+            allowed = ", ".join(str(j) for j in VexJustification)
+            raise ValueError(f"unknown VEX justification {v!r}; expected one of: {allowed}")
+        return text
+
+    @field_validator("cve")
+    @classmethod
+    def _upper_cve(cls, v: str) -> str:
+        """Normaliza o identificador, e recusa um que não identifica nada.
+
+        Um `cve: ""` passava por aqui e entrava no conjunto de isenções como
+        a string vazia. As isenções são aplicadas com
+        `vuln.cve_id.upper() not in ignored`, e um scanner **deixa
+        `cve_id` vazio** quando o aviso não tem identificador publicado --
+        o Trivy faz exatamente isso, como o exportador SARIF documenta. Uma
+        única linha em branco no arquivo de isenções apagava portanto
+        *todos* os achados sem identificador do relatório, e com eles do
+        score, do tier e do veredito de produção: vulnerabilidades reais
+        somem e a imagem sobe de nota.
+
+        A forma exigida é frouxa de propósito -- `GHSA-...`, `DSA-...`,
+        `RUSTSEC-...` e `ALAS-...` são identificadores legítimos e não
+        parecem com `CVE-`. O que ela recusa é o que não identifica: vazio,
+        espaço em branco, e qualquer coisa curta demais para ser um
+        identificador de aviso.
+        """
+        text = v.strip().upper()
+        if not _ADVISORY_ID.match(text):
+            raise ValueError(
+                f"{v!r} does not name an advisory. An exemption has to say which "
+                "vulnerability it exempts: a blank id matches every finding the "
+                "scanner reported without one, and silently drops them from the scan"
+            )
+        return text
+
+    @property
+    def is_expired(self) -> bool:
+        if self.expires is None:
+            return False
+        return date.today() > self.expires
+
+
+def load_ignore_rules(path: Path | None = None) -> list[IgnoreRule]:
+    """Load CVE ignore rules from a `.dockerls-ignore.yaml` file. Expired
+    rules are dropped (a vulnerability whose exemption lapsed is no longer
+    ignored). Missing or malformed files degrade to "no rules" rather than
+    failing the scan."""
+    target = path or Path.cwd() / DEFAULT_IGNORE_FILENAME
+    if not target.exists():
+        return []
+
+    try:
+        raw = yaml.safe_load(target.read_text(encoding="utf-8")) or {}
+    except yaml.YAMLError as e:
+        logger.warning(f"Could not parse {target}: {e}")
+        return []
+
+    entries = raw.get("ignores", []) if isinstance(raw, dict) else []
+    rules: list[IgnoreRule] = []
+    for entry in entries:
+        try:
+            rule = IgnoreRule.model_validate(entry)
+        except Exception as e:
+            logger.warning(f"Skipping invalid ignore rule {entry}: {e}")
+            continue
+        if rule.is_expired:
+            logger.info(f"Ignore rule for {rule.cve} expired on {rule.expires}, no longer applied")
+            continue
+        rules.append(rule)
+    return rules
+
+
+def active_ignored_cve_ids(rules: list[IgnoreRule]) -> set[str]:
+    """Identificadores isentos e ainda válidos.
+
+    A string vazia é filtrada de novo aqui, e não só no validador: este
+    conjunto é comparado contra `vuln.cve_id`, que é vazio nos achados sem
+    identificador publicado, e um `""` que escapasse -- por uma `IgnoreRule`
+    construída em código, sem passar pelo arquivo -- apagaria todos eles do
+    relatório sem deixar rastro. Duas guardas para um erro que some em
+    silêncio é o preço certo.
+    """
+    return {r.cve for r in rules if not r.is_expired and r.cve.strip()}

dockerls/utils/rate_limit.py

@@ -0,0 +1,130 @@
+"""Client-side rate limiting and circuit breaking for external APIs.
+
+Every provider DockerLs talks to has a budget: the GitHub REST API allows 60
+requests an hour to an anonymous client, Docker Hub throttles pulls, and a
+registry that is having a bad day answers 5xx to everything. Two failure
+modes follow from that, and both are the caller's fault rather than the
+API's:
+
+* a burst that spends the whole budget in the first second of a run, so the
+  rest of the run gets 403s that look like the data does not exist;
+* a retry loop that keeps hammering an endpoint which is already failing,
+  turning a slow dependency into a hung command.
+
+The token bucket addresses the first: requests are paced, and a caller that
+asks faster than the budget allows waits rather than being refused. The
+circuit breaker addresses the second: after a run of consecutive failures
+the breaker opens and calls fail *immediately* for a cooldown, so an
+unreachable provider costs one timeout instead of one per candidate. It
+closes again after a single successful probe.
+
+Neither ever turns a failure into a success. An open breaker raises, and the
+caller reports the source as unavailable -- which is the honest outcome, and
+the one the rest of this codebase is built to represent.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import random
+import time
+from dataclasses import dataclass, field
+
+#: Jitter applied to the wait a caller computes, as a fraction of that wait.
+#: Without it, N workers that all hit the limit at once wake up at the same
+#: instant and collide again -- a thundering herd of their own making.
+JITTER_FRACTION = 0.1
+
+
+class RateLimiter:
+    """Token bucket: at most `rate` operations per `period` seconds, on average.
+
+    Bursts up to `burst` are allowed, because the common shape here is a
+    handful of parallel lookups followed by a long quiet stretch, and pacing
+    those to a strict interval would only add latency for no protection.
+    """
+
+    def __init__(self, rate: int, period: float = 1.0, burst: int | None = None):
+        if rate < 1:
+            raise ValueError("rate must be at least 1")
+        if period <= 0:
+            raise ValueError("period must be positive")
+        self._rate = rate
+        self._period = period
+        self._capacity = float(burst if burst is not None else rate)
+        self._tokens = self._capacity
+        self._updated = time.monotonic()
+        self._lock = asyncio.Lock()
+
+    async def acquire(self) -> None:
+        """Wait until a token is available, then consume it."""
+        while True:
+            async with self._lock:
+                now = time.monotonic()
+                elapsed = now - self._updated
+                self._updated = now
+                self._tokens = min(
+                    self._capacity, self._tokens + elapsed * (self._rate / self._period)
+                )
+                if self._tokens >= 1.0:
+                    self._tokens -= 1.0
+                    return
+                deficit = 1.0 - self._tokens
+                wait = deficit * (self._period / self._rate)
+            # Slept outside the lock so waiting callers do not serialize on
+            # each other's sleeps.
+            # Timing jitter, not a secret: this decides how long a waiting
+            # caller sleeps so N workers do not wake in lockstep. A CSPRNG
+            # here would buy nothing -- there is nothing to predict and
+            # nothing to forge.
+            jitter = random.random()  # nosec B311 # noqa: S311 - scheduling, not crypto
+            await asyncio.sleep(wait * (1.0 + jitter * JITTER_FRACTION))
+
+
+class CircuitOpenError(RuntimeError):
+    """The breaker is open: the provider is failing and is not being called."""
+
+
+@dataclass
+class CircuitBreaker:
+    """Stop calling a provider that is consistently failing.
+
+    State is intentionally minimal -- consecutive failures and the time the
+    breaker opened. There is no half-open request accounting: the first call
+    after the cooldown is the probe, and its outcome decides whether the
+    breaker closes or re-opens.
+    """
+
+    #: Consecutive failures that trip the breaker.
+    threshold: int = 5
+    #: Seconds the breaker stays open before allowing a probe.
+    cooldown: float = 60.0
+    _failures: int = field(default=0, init=False)
+    _opened_at: float = field(default=0.0, init=False)
+
+    @property
+    def is_open(self) -> bool:
+        if self._failures < self.threshold:
+            return False
+        return (time.monotonic() - self._opened_at) < self.cooldown
+
+    def check(self, provider: str) -> None:
+        """Raise `CircuitOpenError` when the provider is being skipped."""
+        if self.is_open:
+            remaining = self.cooldown - (time.monotonic() - self._opened_at)
+            raise CircuitOpenError(
+                f"{provider} is unavailable after {self._failures} consecutive "
+                f"failures; retrying in {max(0.0, remaining):.0f}s"
+            )
+
+    def record_success(self) -> None:
+        self._failures = 0
+        self._opened_at = 0.0
+
+    def record_failure(self) -> None:
+        self._failures += 1
+        if self._failures >= self.threshold:
+            # Re-stamped on every failure past the threshold so a provider
+            # that keeps failing keeps the breaker open, rather than
+            # re-opening the floodgates one cooldown after the first trip.
+            self._opened_at = time.monotonic()

dockerls/utils/resources.py

@@ -0,0 +1,183 @@
+"""How much of this machine DockerLs may actually use.
+
+Concurrency here is not the usual "how many coroutines" question. Each
+worker slot holds a **scanner process**: `trivy image` reads a multi-hundred
+megabyte vulnerability database, unpacks image layers and matches packages,
+using a full core and hundreds of megabytes of RSS while it does. Ten of
+them at once on a two-core CI runner does not go ten times faster -- it goes
+slower, evicts the page cache, and can get the whole job OOM-killed.
+
+The default was a flat `workers = 10`, chosen with no reference to the
+machine. This module replaces the guess with a measurement, and it is
+deliberately **container-aware**: inside Docker or Kubernetes,
+`os.cpu_count()` reports the host's cores while the cgroup allows a
+fraction of one. A tool whose whole purpose is analysing containers is
+routinely run inside one, so reading the host's numbers is not a small
+inaccuracy -- it is the common case, and it is where the oversubscription
+hurts most.
+
+Nothing here is a hard limit on what the operator may ask for. An explicit
+`--workers` is still honoured: the point is that the *default* should fit
+the machine it lands on, and that asking for more than the machine has
+should say so out loud.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from loguru import logger
+
+#: Memory one scanner process should be assumed to need. Trivy's resident
+#: set while matching a large image sits in the hundreds of megabytes; this
+#: is the conservative end, because the cost of underestimating it is an
+#: OOM kill and the cost of overestimating it is one fewer parallel scan.
+SCANNER_MEMORY_BYTES = 768 * 1024 * 1024
+
+#: Never derive fewer than this. One worker is always possible, and a
+#: machine that reports something absurd should still make progress.
+MIN_RECOMMENDED = 1
+
+#: Never derive more than this, however large the machine. Past this point
+#: the bottleneck is the registry and the disk, not the CPU, and every extra
+#: process is another few hundred megabytes for no throughput.
+MAX_RECOMMENDED = 16
+
+_CGROUP_V2_CPU = Path("/sys/fs/cgroup/cpu.max")
+_CGROUP_V2_MEMORY = Path("/sys/fs/cgroup/memory.max")
+_CGROUP_V1_QUOTA = Path("/sys/fs/cgroup/cpu/cpu.cfs_quota_us")
+_CGROUP_V1_PERIOD = Path("/sys/fs/cgroup/cpu/cpu.cfs_period_us")
+_CGROUP_V1_MEMORY = Path("/sys/fs/cgroup/memory/memory.limit_in_bytes")
+_MEMINFO = Path("/proc/meminfo")
+
+
+def cpu_capacity() -> float:
+    """Cores this process may actually use, honouring cgroup quota.
+
+    Three sources, narrowest wins: the cgroup CPU quota (what a container
+    is allowed), the CPU affinity mask (what a taskset or a scheduler
+    policy permits), and the machine's core count. A quota of 0.5 cores
+    returns 0.5, not 1 -- the caller decides how to round, and rounding up
+    to 1 at the bottom is the caller's floor, not a fact about the machine.
+    """
+    candidates: list[float] = []
+
+    try:
+        candidates.append(float(len(os.sched_getaffinity(0))))
+    except (AttributeError, OSError):
+        count = os.cpu_count()
+        if count:
+            candidates.append(float(count))
+
+    quota = _cgroup_cpu_quota()
+    if quota is not None:
+        candidates.append(quota)
+
+    return min(candidates) if candidates else 1.0
+
+
+def available_memory_bytes() -> int | None:
+    """Memory this process can count on, or None when it cannot be read.
+
+    `MemAvailable` rather than `MemFree`: the kernel's own estimate of what
+    can be allocated without swapping, which is the number that decides
+    whether starting another scanner is survivable. A cgroup limit, when
+    present and lower, wins -- that is the ceiling the OOM killer uses.
+    """
+    values = [v for v in (_meminfo_available(), _cgroup_memory_limit()) if v is not None]
+    return min(values) if values else None
+
+
+def recommended_workers() -> int:
+    """How many scanner processes this machine should run at once.
+
+    The minimum of what the CPU allows and what memory allows, clamped.
+    Both terms matter and they fail differently: too many for the CPU makes
+    the run slower, too many for the memory makes it die.
+    """
+    by_cpu = max(MIN_RECOMMENDED, int(cpu_capacity()))
+
+    memory = available_memory_bytes()
+    by_memory = (
+        max(MIN_RECOMMENDED, int(memory // SCANNER_MEMORY_BYTES))
+        if memory is not None
+        else MAX_RECOMMENDED
+    )
+
+    return max(MIN_RECOMMENDED, min(by_cpu, by_memory, MAX_RECOMMENDED))
+
+
+def describe_capacity() -> str:
+    """One line for the logs, so a slow run can be explained afterwards."""
+    memory = available_memory_bytes()
+    memory_text = f"{memory / (1024**3):.1f} GiB available" if memory else "memory unknown"
+    return f"{cpu_capacity():.2g} usable CPU(s), {memory_text}"
+
+
+def _cgroup_cpu_quota() -> float | None:
+    """Cores permitted by the cgroup, v2 first then v1, or None if unlimited."""
+    text = _read(_CGROUP_V2_CPU)
+    if text:
+        parts = text.split()
+        if len(parts) == 2 and parts[0] != "max":
+            quota, period = _to_float(parts[0]), _to_float(parts[1])
+            if quota and period and period > 0:
+                return quota / period
+        return None
+
+    quota = _to_float(_read(_CGROUP_V1_QUOTA))
+    period = _to_float(_read(_CGROUP_V1_PERIOD))
+    if quota is not None and quota > 0 and period:
+        return quota / period
+    return None
+
+
+def _cgroup_memory_limit() -> int | None:
+    for path in (_CGROUP_V2_MEMORY, _CGROUP_V1_MEMORY):
+        text = _read(path)
+        if not text or text == "max":
+            continue
+        value = _to_float(text)
+        # cgroup v1 writes an enormous sentinel to mean "no limit"; anything
+        # at that scale is not a real container budget.
+        if value is not None and 0 < value < (1 << 62):
+            return int(value)
+    return None
+
+
+def _meminfo_available() -> int | None:
+    text = _read(_MEMINFO)
+    if not text:
+        return None
+    for line in text.splitlines():
+        if line.startswith("MemAvailable:"):
+            parts = line.split()
+            if len(parts) >= 2:
+                value = _to_float(parts[1])
+                if value is not None:
+                    return int(value * 1024)  # reported in kB
+    return None
+
+
+def _read(path: Path) -> str:
+    """Read a small pseudo-file, treating every failure as "not present".
+
+    These paths are absent on macOS, absent outside containers, and
+    unreadable under some sandboxes. None of that is an error worth
+    surfacing: the caller simply falls back to the next source.
+    """
+    try:
+        return path.read_text(encoding="utf-8").strip()
+    except OSError:
+        return ""
+
+
+def _to_float(text: str | None) -> float | None:
+    if not text:
+        return None
+    try:
+        return float(text)
+    except ValueError:
+        logger.debug(f"Unexpected value in a resource limit file: {text!r}")
+        return None

dockerls/utils/retry.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from tenacity import AsyncRetrying, stop_after_attempt, wait_exponential
+
+DEFAULT_MAX_ATTEMPTS = 3
+DEFAULT_BACKOFF_BASE = 2.0
+MAX_BACKOFF_SECONDS = 10.0
+
+
+def retry_policy(
+    max_attempts: int = DEFAULT_MAX_ATTEMPTS,
+    backoff_base: float = DEFAULT_BACKOFF_BASE,
+) -> AsyncRetrying:
+    """Build a retry policy from configuration.
+
+    A `@retry(...)` decorator is evaluated once at import time, which is why
+    `retry_max_attempts` and `retry_backoff_base` could be declared as
+    settings and documented while having no possible effect. Building the
+    policy per call is what lets configuration actually reach it.
+
+    `reraise=True` so callers still see the original exception rather than
+    tenacity's RetryError wrapper -- the existing error handling in the
+    clients catches httpx errors by type.
+    """
+    return AsyncRetrying(
+        stop=stop_after_attempt(max(1, max_attempts)),
+        wait=wait_exponential(
+            multiplier=1, exp_base=max(1.1, backoff_base), max=MAX_BACKOFF_SECONDS
+        ),
+        reraise=True,
+    )

dockerls/utils/safe_yaml.py

@@ -0,0 +1,166 @@
+"""YAML parsing for documents fetched from the internet.
+
+Every YAML this tool reads comes from somewhere it does not control -- the
+Docker Hardened Images catalogue is fetched over HTTPS from GitHub, and a
+proxy, a compromised mirror or a malicious fork can put anything in the
+response body. `yaml.load` would be remote code execution outright; even
+`yaml.safe_load` is only safe against *construction*, not against
+resource exhaustion: a few hundred bytes of nested aliases expand into
+gigabytes (the "billion laughs" / YAML bomb), and a deeply nested document
+can exhaust the C stack during composition.
+
+So parsing here is guarded on three axes before the loader ever runs:
+
+* **size** -- the document is refused above a byte budget, so a hostile or
+  misconfigured endpoint cannot stream an unbounded body into memory;
+* **expansion size** -- anchors are legitimate in these definitions, so
+  they are not banned; instead the document is *composed* into a node graph
+  (where an alias is a shared reference, and therefore costs nothing) and
+  the size it would expand to is computed over that graph before anything
+  is constructed. A counting heuristic is not enough here and this is worth
+  stating plainly: nine levels of nine-fold aliasing is only ~72 aliases --
+  comfortably under any sane per-document count -- and expands to 387
+  million nodes. What has to be bounded is the product, not the tally;
+* **nesting depth** -- measured on the parsed result, and refused above a
+  bound no legitimate image definition comes close to.
+
+A refusal raises `UnsafeYAMLError`, which callers treat as "this definition
+could not be read" -- never as "this definition is empty".
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import yaml
+
+#: 4 MiB. The largest definition in the DHI catalogue is under 100 KiB, so
+#: this leaves two orders of magnitude of headroom while still bounding the
+#: memory a single hostile response can cost.
+MAX_DOCUMENT_BYTES = 4 * 1024 * 1024
+
+#: Nodes the document may expand to. Measured on the composed graph before
+#: construction, so a bomb is refused in linear time instead of being
+#: discovered when memory runs out. Real definitions compose a few thousand
+#: nodes; this leaves two orders of magnitude of headroom.
+MAX_EXPANDED_NODES = 1_000_000
+
+#: Composition depth of the parsed structure. Image definitions nest about
+#: six levels; anything past this is a stack-exhaustion attempt.
+MAX_DEPTH = 32
+
+
+class UnsafeYAMLError(ValueError):
+    """A document was refused before or after parsing, on a safety bound."""
+
+
+def safe_load_yaml(raw: str | bytes, *, origin: str = "<yaml>") -> Any:
+    """Parse `raw` with `yaml.safe_load` behind explicit resource bounds.
+
+    Returns whatever the document contained (usually a dict). Raises
+    `UnsafeYAMLError` when a bound is exceeded or the document is malformed
+    -- the caller decides what an unreadable definition means, and in this
+    codebase it always means "unknown", never "clean".
+    """
+    text = raw.decode("utf-8", errors="replace") if isinstance(raw, bytes) else raw
+
+    encoded_size = len(text.encode("utf-8", errors="replace"))
+    if encoded_size > MAX_DOCUMENT_BYTES:
+        raise UnsafeYAMLError(
+            f"{origin}: document is {encoded_size} bytes, over the {MAX_DOCUMENT_BYTES} limit"
+        )
+
+    # Compose, measure, then construct -- in that order. Composition builds
+    # a graph in which an alias is one edge rather than a copy, so it is
+    # bounded by the document's own length; construction is what multiplies,
+    # and it does not happen until the expansion has been shown to be safe.
+    # SafeLoader is used throughout: it constructs only plain scalars, lists
+    # and dicts, never arbitrary objects from `!!python/object` tags.
+    loader = yaml.SafeLoader(text)
+    try:
+        try:
+            node = loader.get_single_node()
+        except yaml.YAMLError as e:
+            raise UnsafeYAMLError(f"{origin}: malformed YAML ({e})") from e
+        except RecursionError as e:
+            raise UnsafeYAMLError(f"{origin}: document nesting exhausted the parser") from e
+
+        if node is None:
+            return None
+
+        expanded = _expanded_size(node, {})
+        if expanded > MAX_EXPANDED_NODES:
+            raise UnsafeYAMLError(
+                f"{origin}: document expands to at least {expanded} nodes, over the "
+                f"{MAX_EXPANDED_NODES} limit (alias-expansion bomb)"
+            )
+
+        try:
+            data = loader.construct_document(node)
+        except yaml.YAMLError as e:
+            raise UnsafeYAMLError(f"{origin}: malformed YAML ({e})") from e
+        except RecursionError as e:
+            raise UnsafeYAMLError(f"{origin}: document nesting exhausted the parser") from e
+    finally:
+        loader.dispose()
+
+    depth = _depth(data)
+    if depth > MAX_DEPTH:
+        raise UnsafeYAMLError(f"{origin}: nesting depth {depth} exceeds the {MAX_DEPTH} limit")
+    return data
+
+
+def _expanded_size(node: yaml.Node, memo: dict[int, int]) -> int:
+    """How many nodes `node` would become once every alias is expanded.
+
+    The composed graph shares anchored nodes, so each one is measured once
+    and memoised by identity; a node referenced nine times contributes its
+    size nine times to its parent's total. That is exactly the quantity a
+    YAML bomb maximises, and computing it costs one walk of the graph.
+
+    Totals are clamped to the limit as they accumulate. Without the clamp
+    the arithmetic itself becomes the denial of service: the classic bomb's
+    true size is a 400-million-digit intermediate nobody needs to compute in
+    order to know it is too big.
+    """
+    cached = memo.get(id(node))
+    if cached is not None:
+        return cached
+
+    if isinstance(node, yaml.ScalarNode):
+        memo[id(node)] = 1
+        return 1
+
+    total = 1
+    children: list[yaml.Node] = []
+    if isinstance(node, yaml.SequenceNode):
+        children = list(node.value)
+    elif isinstance(node, yaml.MappingNode):
+        children = [child for pair in node.value for child in pair]
+
+    for child in children:
+        total += _expanded_size(child, memo)
+        if total > MAX_EXPANDED_NODES:
+            total = MAX_EXPANDED_NODES + 1
+            break
+
+    memo[id(node)] = total
+    return total
+
+
+def _depth(value: Any, level: int = 0) -> int:
+    """Nesting depth of an already-parsed structure.
+
+    Iterative rather than recursive on the hot path would be safer still,
+    but the loader has already bounded what can reach here: `MAX_DEPTH` is
+    checked against a structure `yaml.SafeLoader` managed to build, and the
+    loader raises `RecursionError` (handled above) well before Python's own
+    limit on anything deeper.
+    """
+    if level > MAX_DEPTH:
+        return level
+    if isinstance(value, dict):
+        return max((_depth(v, level + 1) for v in value.values()), default=level)
+    if isinstance(value, list | tuple):
+        return max((_depth(v, level + 1) for v in value), default=level)
+    return level