compose-guard 0.1.0__py3-none-any.whl

compose_guard/__init__.py

@@ -0,0 +1,5 @@
+"""Compose Guard: lint Docker Compose files for security and reliability problems."""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

compose_guard/__main__.py

@@ -0,0 +1,6 @@
+"""Allow ``python -m compose_guard``."""
+
+from compose_guard.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

compose_guard/cli.py

@@ -0,0 +1,182 @@
+"""Command-line interface: argument parsing, file discovery and exit codes."""
+
+from __future__ import annotations
+
+import argparse
+import dataclasses
+import os
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+from typing import NoReturn, TextIO
+
+from compose_guard import __version__
+from compose_guard.config import DEFAULT_CONFIG_NAME, FAIL_ON_CHOICES, Config, load_config
+from compose_guard.engine import lint
+from compose_guard.errors import ComposeGuardError, InputError
+from compose_guard.loader import load_bytes
+from compose_guard.model import ComposeFile
+from compose_guard.report import FORMATS, render
+from compose_guard.rules import RULES, RULES_BY_ID
+
+PROG = "compose-guard"
+
+EXIT_OK = 0
+EXIT_FINDINGS = 1
+EXIT_USAGE = 2
+EXIT_INTERRUPTED = 130
+EXIT_BROKEN_PIPE = 141
+
+# The Compose specification's lookup order for a project's default file.
+DEFAULT_FILES = ("compose.yaml", "compose.yml", "docker-compose.yaml", "docker-compose.yml")
+
+STDIN_NAME = "<stdin>"
+
+
+class _Parser(argparse.ArgumentParser):
+    def error(self, message: str) -> NoReturn:
+        self.print_usage(sys.stderr)
+        self.exit(EXIT_USAGE, f"{self.prog}: error: {message}\n")
+
+
+DESCRIPTION = "Lint Docker Compose files for security, misconfiguration and reliability problems."
+EPILOG = (
+    "exit codes: 0 no unsuppressed finding at or above --fail-on, 1 at least one such finding, "
+    "2 usage or input error, 130 interrupted, 141 output pipe closed"
+)
+FILES_HELP = (
+    f"Compose files to lint; '-' reads standard input (default: the first of "
+    f"{', '.join(DEFAULT_FILES)} in the current directory)"
+)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = _Parser(prog=PROG, description=DESCRIPTION, epilog=EPILOG)
+    parser.add_argument("files", nargs="*", metavar="FILE", help=FILES_HELP)
+    parser.add_argument("--version", action="version", version=f"{PROG} {__version__}")
+    parser.add_argument(
+        "--format", choices=FORMATS, default="text", help="output format (default: text)"
+    )
+    parser.add_argument(
+        "--fail-on",
+        choices=FAIL_ON_CHOICES,
+        default=None,
+        help="exit 1 if an unsuppressed finding has this severity or worse (default: error)",
+    )
+    parser.add_argument(
+        "--config",
+        metavar="PATH",
+        type=Path,
+        help=f"configuration file (default: {DEFAULT_CONFIG_NAME} in the current directory)",
+    )
+    parser.add_argument(
+        "--ignore",
+        metavar="IDS",
+        action="append",
+        default=[],
+        help="comma-separated rule IDs to ignore, added to the config file's list",
+    )
+    parser.add_argument(
+        "--show-suppressed", action="store_true", help="also list suppressed findings"
+    )
+    parser.add_argument("--list-rules", action="store_true", help="describe every rule and exit")
+    return parser
+
+
+def _parse_ignore(parser: argparse.ArgumentParser, values: Sequence[str]) -> frozenset[str]:
+    ids = {part.strip().upper() for value in values for part in value.split(",") if part.strip()}
+    unknown = sorted(ids - set(RULES_BY_ID))
+    if unknown:
+        parser.error(
+            f"unknown rule ID(s) for --ignore: {', '.join(unknown)} "
+            f"(valid: {', '.join(RULES_BY_ID)})"
+        )
+    return frozenset(ids)
+
+
+def _discover(parser: argparse.ArgumentParser) -> list[str]:
+    for name in DEFAULT_FILES:
+        if Path(name).is_file():
+            return [name]
+    parser.error(f"no Compose file given and none of {', '.join(DEFAULT_FILES)} found")
+
+
+def _read(path: str, stdin: TextIO) -> ComposeFile:
+    if path == "-":
+        return load_bytes(stdin.buffer.read(), STDIN_NAME)
+    target = Path(path)
+    # Windows raises PermissionError for directories, not IsADirectoryError.
+    if target.is_dir():
+        raise InputError("is a directory", file=path)
+    try:
+        data = target.read_bytes()
+    except FileNotFoundError:
+        raise InputError("no such file", file=path) from None
+    except IsADirectoryError:
+        raise InputError("is a directory", file=path) from None
+    except OSError as exc:
+        raise InputError(f"cannot read file: {exc.strerror}", file=path) from None
+    return load_bytes(data, path)
+
+
+def _config(args: argparse.Namespace) -> Config:
+    if args.config is not None:
+        return load_config(args.config, RULES_BY_ID)
+    default = Path(DEFAULT_CONFIG_NAME)
+    if default.is_file():
+        return load_config(default, RULES_BY_ID)
+    return Config()
+
+
+def list_rules() -> str:
+    blocks = []
+    for rule in RULES:
+        blocks.append(
+            f"{rule.id}  {rule.severity.value:<7}  {rule.title}\n"
+            f"    {rule.rationale}\n"
+            f"    fix: {rule.fix}"
+        )
+    return "\n\n".join(blocks) + "\n"
+
+
+def _run(argv: Sequence[str] | None, stdout: TextIO, stdin: TextIO) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.list_rules:
+        stdout.write(list_rules())
+        return EXIT_OK
+
+    cli_ignores = _parse_ignore(parser, args.ignore)
+    paths = args.files or _discover(parser)
+    if paths.count("-") > 1:
+        parser.error("standard input ('-') can only be given once")
+
+    file_config = _config(args)
+    # Command-line flags add to (--ignore) or override (--fail-on) the config file.
+    config = dataclasses.replace(
+        file_config,
+        ignore=file_config.ignore | cli_ignores,
+        fail_on=args.fail_on or file_config.fail_on,
+    )
+    files = [_read(path, stdin) for path in paths]
+    report = lint(files, config)
+    stdout.write(render(report, args.format, show_suppressed=args.show_suppressed))
+    stdout.flush()
+    return EXIT_FINDINGS if report.fails(config.fail_on or "error") else EXIT_OK
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    try:
+        return _run(argv, sys.stdout, sys.stdin)
+    except ComposeGuardError as exc:
+        sys.stderr.write(f"{PROG}: error: {exc}\n")
+        return EXIT_USAGE
+    except KeyboardInterrupt:
+        sys.stderr.write(f"{PROG}: interrupted\n")
+        return EXIT_INTERRUPTED
+    except BrokenPipeError:
+        # The reader went away (e.g. `| head`). Point stdout at devnull so the interpreter's
+        # final flush does not raise again, and exit quietly.
+        devnull = os.open(os.devnull, os.O_WRONLY)
+        os.dup2(devnull, sys.stdout.fileno())
+        return EXIT_BROKEN_PIPE

compose_guard/config.py

@@ -0,0 +1,150 @@
+"""The ``.compose-guard.yml`` configuration file.
+
+```yaml
+ignore: [CD015]
+services:
+  worker:
+    ignore: [CD007]
+severity:
+  CD010: warning
+fail_on: warning
+```
+"""
+
+from __future__ import annotations
+
+from collections.abc import Collection, Mapping
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from compose_guard.errors import InputError
+from compose_guard.loader import parse_mapping
+from compose_guard.model import Located, LocatedMap, Severity, Value
+from compose_guard.rules.base import mapping, sequence, text
+
+DEFAULT_CONFIG_NAME = ".compose-guard.yml"
+FAIL_ON_CHOICES = ("error", "warning", "note", "never")
+
+_TOP_LEVEL_KEYS = ("ignore", "services", "severity", "fail_on")
+_SERVICE_KEYS = ("ignore",)
+_SEVERITIES = tuple(severity.value for severity in Severity)
+
+
+@dataclass(frozen=True)
+class Config:
+    ignore: frozenset[str] = frozenset()
+    service_ignores: Mapping[str, frozenset[str]] = field(default_factory=dict)
+    severity: Mapping[str, Severity] = field(default_factory=dict)
+    fail_on: str | None = None
+
+    def ignores(self, rule_id: str, service: str | None) -> bool:
+        """Whether ``rule_id`` is ignored globally or for ``service``."""
+        if rule_id in self.ignore:
+            return True
+        return service is not None and rule_id in self.service_ignores.get(service, frozenset())
+
+
+def load_config(path: Path, known_rules: Collection[str]) -> Config:
+    """Read and validate a config file. Raises :class:`InputError` naming the problem."""
+    display = str(path)
+    try:
+        data = path.read_bytes()
+    except FileNotFoundError:
+        raise InputError("config file not found", file=display) from None
+    except OSError as exc:
+        raise InputError(f"cannot read config file: {exc.strerror}", file=display) from None
+    try:
+        source = data.decode("utf-8-sig")
+    except UnicodeDecodeError:
+        raise InputError("config file is not valid UTF-8", file=display) from None
+    root = parse_mapping(source, display)
+    if root is None:
+        return Config()
+    return _Parser(display, known_rules).parse(root)
+
+
+class _Parser:
+    def __init__(self, path: str, known_rules: Collection[str]) -> None:
+        self._path = path
+        self._known = known_rules
+
+    def _error(self, message: str, at: Located[object]) -> InputError:
+        return InputError(message, file=self._path, line=at.line)
+
+    def _check_keys(self, raw: LocatedMap, allowed: tuple[str, ...], where: str) -> None:
+        for name in raw:
+            if name not in allowed:
+                raise self._error(
+                    f"unknown key '{name}' in {where}; valid keys are: {', '.join(allowed)}",
+                    raw.key(name),
+                )
+
+    def _rule_id(self, value: Located[Value]) -> str:
+        rule_id = text(value)
+        if rule_id is None or rule_id not in self._known:
+            shown = rule_id if rule_id is not None else "(not a string)"
+            raise self._error(
+                f"unknown rule ID '{shown}'; valid IDs are: {', '.join(sorted(self._known))}",
+                value,
+            )
+        return rule_id
+
+    def _rule_list(self, value: Located[Value], where: str) -> frozenset[str]:
+        items = sequence(value)
+        if items is None:
+            raise self._error(f"'{where}' must be a list of rule IDs", value)
+        return frozenset(self._rule_id(item) for item in items)
+
+    def parse(self, root: LocatedMap) -> Config:
+        self._check_keys(root, _TOP_LEVEL_KEYS, "config file")
+        ignore = self._rule_list(root["ignore"], "ignore") if "ignore" in root else frozenset()
+        return Config(
+            ignore=ignore,
+            service_ignores=self._services(root.get("services")),
+            severity=self._severity(root.get("severity")),
+            fail_on=self._fail_on(root.get("fail_on")),
+        )
+
+    def _services(self, value: Located[Value] | None) -> dict[str, frozenset[str]]:
+        if value is None:
+            return {}
+        services = mapping(value)
+        if services is None:
+            raise self._error("'services' must be a mapping of service names", value)
+        result = {}
+        for name in services:
+            settings = mapping(services[name])
+            if settings is None:
+                raise self._error(f"'services.{name}' must be a mapping", services[name])
+            self._check_keys(settings, _SERVICE_KEYS, f"'services.{name}'")
+            if "ignore" in settings:
+                result[name] = self._rule_list(settings["ignore"], f"services.{name}.ignore")
+        return result
+
+    def _severity(self, value: Located[Value] | None) -> dict[str, Severity]:
+        if value is None:
+            return {}
+        overrides = mapping(value)
+        if overrides is None:
+            raise self._error("'severity' must be a mapping of rule IDs to severities", value)
+        result = {}
+        for name in overrides:
+            rule_id = self._rule_id(overrides.key(name))
+            level = text(overrides[name])
+            if level not in _SEVERITIES:
+                raise self._error(
+                    f"invalid severity for {rule_id}; valid values are: {', '.join(_SEVERITIES)}",
+                    overrides[name],
+                )
+            result[rule_id] = Severity(level)
+        return result
+
+    def _fail_on(self, value: Located[Value] | None) -> str | None:
+        if value is None:
+            return None
+        level = text(value)
+        if level not in FAIL_ON_CHOICES:
+            raise self._error(
+                f"invalid 'fail_on'; valid values are: {', '.join(FAIL_ON_CHOICES)}", value
+            )
+        return level

compose_guard/engine.py

@@ -0,0 +1,73 @@
+"""Lint loaded files: run rules, apply severity overrides and suppressions."""
+
+from __future__ import annotations
+
+import dataclasses
+from collections.abc import Sequence
+from dataclasses import dataclass
+from enum import Enum
+
+from compose_guard.config import Config
+from compose_guard.model import ComposeFile, Finding, Severity
+from compose_guard.rules import RULES_BY_ID, run_rules, sort_key
+from compose_guard.suppress import parse_suppressions
+
+
+class Suppression(Enum):
+    """Why a finding was suppressed. Values are SARIF ``suppression.kind`` values."""
+
+    INLINE = "inSource"
+    CONFIG = "external"
+
+
+@dataclass(frozen=True)
+class Result:
+    finding: Finding
+    suppression: Suppression | None = None
+
+
+@dataclass(frozen=True)
+class Report:
+    files: tuple[str, ...]
+    results: tuple[Result, ...]
+
+    @property
+    def findings(self) -> list[Finding]:
+        """Unsuppressed findings."""
+        return [r.finding for r in self.results if r.suppression is None]
+
+    @property
+    def suppressed(self) -> list[Result]:
+        return [r for r in self.results if r.suppression is not None]
+
+    def count(self, severity: Severity) -> int:
+        return sum(1 for finding in self.findings if finding.severity is severity)
+
+    def fails(self, fail_on: str) -> bool:
+        """Whether any unsuppressed finding is at or above ``fail_on`` (or never, for "never")."""
+        if fail_on == "never":
+            return False
+        threshold = Severity(fail_on).rank
+        return any(finding.severity.rank >= threshold for finding in self.findings)
+
+
+def lint_file(compose: ComposeFile, config: Config) -> list[Result]:
+    inline = parse_suppressions(compose.source, compose.path, RULES_BY_ID)
+    results = []
+    for finding in run_rules(compose):
+        override = config.severity.get(finding.rule_id)
+        if override is not None:
+            finding = dataclasses.replace(finding, severity=override)
+        if inline.covers(finding.rule_id, finding.line):
+            results.append(Result(finding, Suppression.INLINE))
+        elif config.ignores(finding.rule_id, finding.service):
+            results.append(Result(finding, Suppression.CONFIG))
+        else:
+            results.append(Result(finding))
+    return results
+
+
+def lint(files: Sequence[ComposeFile], config: Config) -> Report:
+    results = [result for compose in files for result in lint_file(compose, config)]
+    results.sort(key=lambda result: sort_key(result.finding))
+    return Report(files=tuple(compose.path for compose in files), results=tuple(results))

compose_guard/errors.py

@@ -0,0 +1,28 @@
+"""Exception types raised by Compose Guard."""
+
+from __future__ import annotations
+
+
+class ComposeGuardError(Exception):
+    """Base class for all errors Compose Guard reports to the user."""
+
+
+class InputError(ComposeGuardError):
+    """A problem with an input file or configuration.
+
+    ``file`` and ``line`` locate the problem when known. ``str()`` renders the
+    ``<file>:<line>: <message>`` form used on stderr.
+    """
+
+    def __init__(self, message: str, *, file: str | None = None, line: int | None = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.file = file
+        self.line = line
+
+    def __str__(self) -> str:
+        if self.file is None:
+            return self.message
+        if self.line is None:
+            return f"{self.file}: {self.message}"
+        return f"{self.file}:{self.line}: {self.message}"

compose_guard/interpolation.py

@@ -0,0 +1,20 @@
+"""Detect Compose variable interpolation (detection only, values are never resolved).
+
+Compose substitutes ``${VAR}``, ``${VAR:-default}``, ``${VAR-default}``, ``${VAR:?err}``,
+``${VAR?err}``, ``${VAR:+alt}``, ``${VAR+alt}`` and ``$VAR``. ``$$`` is an escaped literal
+``$``. Rules treat an interpolated value as unknown.
+"""
+
+from __future__ import annotations
+
+import re
+
+_NAME = r"[A-Za-z_][A-Za-z0-9_]*"
+
+# "$$" is matched first so an escaped dollar is consumed before it can start a reference.
+_TOKEN = re.compile(rf"\$\$|\$\{{{_NAME}(?:(?::?[-?+])[^}}]*)?\}}|\${_NAME}")
+
+
+def contains_interpolation(text: str) -> bool:
+    """Return True if ``text`` contains at least one variable reference."""
+    return any(match.group() != "$$" for match in _TOKEN.finditer(text))

compose_guard/loader.py

@@ -0,0 +1,196 @@
+"""Load Compose files into located values.
+
+PyYAML's ``load`` functions throw away source positions, so this module calls ``yaml.compose``
+with ``SafeLoader`` to get a node tree with marks and converts the nodes itself. Aliases are
+already shared nodes in that tree; merge keys (``<<``) are applied here with YAML 1.1 semantics.
+No Python objects other than plain scalars, ``LocatedMap`` and tuples are ever constructed.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+
+import yaml
+from yaml.constructor import SafeConstructor
+from yaml.nodes import MappingNode, Node, ScalarNode, SequenceNode
+
+from compose_guard.errors import InputError
+from compose_guard.model import ComposeFile, Located, LocatedMap, Scalar, Service, Value
+
+MAX_NODES = 100_000
+"""Upper bound on values produced while converting one document (alias-bomb protection)."""
+
+MAX_DEPTH = 100
+"""Upper bound on nesting depth, far beyond anything a real Compose file needs."""
+
+_TAG = "tag:yaml.org,2002:"
+_MERGE_TAG = _TAG + "merge"
+
+_constructor = SafeConstructor()
+
+# Only these scalar constructors are used. Any other tag (timestamps, binary, Compose's own
+# ``!reset`` / ``!override``) keeps its source text as a string.
+_SCALAR_CONSTRUCTORS: dict[str, Callable[[ScalarNode], Scalar]] = {
+    _TAG + "null": lambda node: None,
+    _TAG + "bool": _constructor.construct_yaml_bool,
+    _TAG + "int": _constructor.construct_yaml_int,
+    _TAG + "float": _constructor.construct_yaml_float,
+}
+
+
+def load_bytes(data: bytes, path: str) -> ComposeFile:
+    """Decode ``data`` as UTF-8 (a leading BOM is allowed) and load it."""
+    try:
+        text = data.decode("utf-8-sig")
+    except UnicodeDecodeError as exc:
+        line = data[: exc.start].count(b"\n") + 1
+        raise InputError("file is not valid UTF-8", file=path, line=line) from None
+    return load_text(text, path)
+
+
+def load_text(text: str, path: str) -> ComposeFile:
+    """Parse ``text`` and build a :class:`ComposeFile`. Raises :class:`InputError`."""
+    root = parse_mapping(text, path)
+    if root is None:
+        raise InputError("file is empty", file=path, line=1)
+    return ComposeFile(path=path, source=text, root=root, services=_services(root, path))
+
+
+def parse_mapping(text: str, path: str) -> LocatedMap | None:
+    """Parse a single YAML document whose top level must be a mapping.
+
+    Returns ``None`` for an empty document. Used for Compose files and the config file alike.
+    """
+    root_node = _compose(text, path)
+    if root_node is None:
+        return None
+    if not isinstance(root_node, MappingNode):
+        raise InputError("top-level value must be a mapping", file=path, line=_line(root_node))
+    root = _Converter(path).convert(root_node)
+    assert isinstance(root.value, LocatedMap)  # a MappingNode always converts to a LocatedMap
+    return root.value
+
+
+def _compose(text: str, path: str) -> Node | None:
+    try:
+        node: Node | None = yaml.compose(text, Loader=yaml.SafeLoader)
+    except yaml.MarkedYAMLError as exc:
+        mark = exc.problem_mark or exc.context_mark
+        line = mark.line + 1 if mark is not None else None
+        if exc.context == "expected a single document in the stream":
+            raise InputError(
+                "multiple YAML documents in one file are not supported", file=path, line=line
+            ) from None
+        raise InputError(f"invalid YAML: {exc.problem}", file=path, line=line) from None
+    except yaml.YAMLError as exc:  # a reader error without a mark
+        raise InputError(f"invalid YAML: {exc}", file=path) from None
+    except RecursionError:
+        raise InputError("document is nested too deeply", file=path) from None
+    return node
+
+
+def _services(root: LocatedMap, path: str) -> tuple[Service, ...]:
+    if "services" not in root:
+        raise InputError("missing top-level 'services' key", file=path, line=1)
+    services_key, services_value = root.entry("services")
+    if not isinstance(services_value.value, LocatedMap):
+        raise InputError("'services' must be a mapping", file=path, line=services_key.line)
+
+    services = []
+    for name in services_value.value:
+        if name.startswith("x-"):
+            continue
+        key, value = services_value.value.entry(name)
+        if not isinstance(value.value, LocatedMap):
+            raise InputError(f"service '{name}' must be a mapping", file=path, line=key.line)
+        services.append(Service(name=name, line=key.line, column=key.column, raw=value.value))
+    return tuple(services)
+
+
+def _line(node: Node) -> int:
+    return node.start_mark.line + 1
+
+
+def _column(node: Node) -> int:
+    return node.start_mark.column + 1
+
+
+class _Converter:
+    """Convert a composed node tree to located values, counting what it produces."""
+
+    def __init__(self, path: str) -> None:
+        self._path = path
+        self._count = 0
+        self._active: set[int] = set()
+
+    def convert(self, node: Node, depth: int = 0) -> Located[Value]:
+        self._count += 1
+        if self._count > MAX_NODES:
+            raise InputError("document expands to too many nodes", file=self._path)
+        if depth > MAX_DEPTH:
+            raise InputError("document is nested too deeply", file=self._path, line=_line(node))
+
+        if isinstance(node, ScalarNode):
+            return Located(_scalar(node), _line(node), _column(node), raw=node.value)
+
+        if id(node) in self._active:
+            raise InputError("recursive alias", file=self._path, line=_line(node))
+        self._active.add(id(node))
+        try:
+            value: Value
+            if isinstance(node, MappingNode):
+                value = self._mapping(node, depth)
+            else:
+                assert isinstance(node, SequenceNode)  # the only remaining node kind
+                value = tuple(self.convert(item, depth + 1) for item in node.value)
+        finally:
+            self._active.discard(id(node))
+        return Located(value, _line(node), _column(node))
+
+    def _mapping(self, node: MappingNode, depth: int) -> LocatedMap:
+        merged: dict[str, tuple[Located[str], Located[Value]]] = {}
+        explicit: dict[str, tuple[Located[str], Located[Value]]] = {}
+
+        for key_node, value_node in node.value:
+            if key_node.tag == _MERGE_TAG:
+                # Earlier merge sources win over later ones, so only fill keys not yet seen.
+                for source in self._merge_sources(value_node, depth):
+                    for name in source:
+                        merged.setdefault(name, source.entry(name))
+                continue
+
+            key = self._key(key_node)
+            if key.value in explicit:
+                raise InputError(f"duplicate key '{key.value}'", file=self._path, line=key.line)
+            explicit[key.value] = (key, self.convert(value_node, depth + 1))
+
+        # Keys written in the mapping itself win over merged keys.
+        return LocatedMap({**merged, **explicit})
+
+    def _merge_sources(self, node: Node, depth: int) -> Iterable[LocatedMap]:
+        items = node.value if isinstance(node, SequenceNode) else [node]
+        sources = []
+        for item in items:
+            if not isinstance(item, MappingNode):
+                raise InputError(
+                    "merge key '<<' must refer to a mapping or a list of mappings",
+                    file=self._path,
+                    line=_line(item),
+                )
+            converted = self.convert(item, depth + 1).value
+            assert isinstance(converted, LocatedMap)  # a MappingNode always converts to one
+            sources.append(converted)
+        return sources
+
+    def _key(self, node: Node) -> Located[str]:
+        if not isinstance(node, ScalarNode):
+            raise InputError("mapping keys must be scalars", file=self._path, line=_line(node))
+        # Keys keep their source text: ``on:`` stays "on" instead of becoming True.
+        return Located(node.value, _line(node), _column(node), raw=node.value)
+
+
+def _scalar(node: ScalarNode) -> Scalar:
+    construct = _SCALAR_CONSTRUCTORS.get(node.tag)
+    if construct is None:
+        return str(node.value)
+    return construct(node)