diff --git a/AGENTS.md b/AGENTS.md index b3578f0..442c0fe 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -18,6 +18,8 @@ Develop inspectable, reproducible, **defensive** reliability and security resear ## Local testbed gate - Never enable GitHub Pages, publish a project URL/dashboard, or add a hosted endpoint for this repository. +- Pin trusted host directory/file descriptors for any state-changing VM or evidence operation. Refuse group/other-writable ancestors, unexpected symlinks, and public evidence directories; no path-based revalidation after a slow process call. +- Evidence sealing and verification require a quiescent or externally snapshotted input; SHA-256 does not prove point-in-time consistency against malicious simultaneous writers. - Keep guest networking disabled by default. No NIC, NAT, bridge, public graphics or host passthrough without separate explicit scope review. - Never run scripts/testbed.py prepare or snapshot, virsh define/start, or any other state-changing host step without operator approval. GitHub CI must only test pure/mocked code. - Do not represent a successful static XML audit as proof of real network containment or a completed RHEL experiment. diff --git a/README.md b/README.md index a65b631..6ab802d 100644 --- a/README.md +++ b/README.md @@ -44,7 +44,7 @@ To inventory an evidence directory, write the manifest **outside** the evidence uv run --no-project python scripts/evidence.py seal --input ./local/capture-001 --output ./local/capture-001.manifest.json uv run --no-project python scripts/evidence.py verify --input ./local/capture-001 --manifest ./local/capture-001.manifest.json -The example requires the capture directory to exist. The manifest is deterministic (no generated timestamp), records relative paths, byte sizes and SHA-256 digests, rejects symlinks, and will not overwrite an existing manifest. For provenance, separately record target/kernel/package versions, test configuration, seed, exact source SHA, time, tool versions, and whether the test actually executed. A manifest establishes byte identity, not scientific validity. +The example requires the capture directory to exist. The manifest is deterministic (no generated timestamp), records relative paths, byte sizes and SHA-256 digests, rejects symlinks, and will not overwrite an existing manifest. Its output directory must be operator-owned and private (0700); it writes the manifest as 0600 using pinned directory descriptors. Seal only a quiescent or externally snapshotted evidence tree: per-file race checks cannot guarantee a global point-in-time view. For provenance, separately record target/kernel/package versions, test configuration, seed, exact source SHA, time, tool versions, and whether the test actually executed. A manifest establishes byte identity, not scientific validity. ## Virtual testbed (RHEL-LAB-002) diff --git a/docs/DAYBREAK_GATE.md b/docs/DAYBREAK_GATE.md index 7f7c005..a9aa4a5 100644 --- a/docs/DAYBREAK_GATE.md +++ b/docs/DAYBREAK_GATE.md @@ -1,6 +1,6 @@ # Daybreak Defense Factory — staged security gate -**Status: NOT RUN.** RHEL-LAB-002 code should be reviewed through an ordinary GitHub PR and the non-privileged Python CI tests *before* requesting a Daybreak repository scan. Daybreak has not been authorized to run a scan by this milestone. +**Status: TWO SOURCE AUDITS COMPLETED, FINDINGS UNDER REMEDIATION.** Daybreak scanned RHEL-LAB at commit `889248b59e4e2cb7c06d8a635c0a07cb2cd39c1e` in runs `wfr_2ef0982c13d785cbdfbf9ecc157a3ccc863cb4085e09dcd70e9124f86bae68f2` and `wfr_f166c5a69c210c6a14bdb64c37311e11fffd8e8dd8a0e0e5e0bd0e0dfb0cac99`. Eight repository-source findings (three medium, five low) are being addressed. Neither a completed audit nor a green CI workflow proves a live RHEL guest is safe; **no RHEL experiments have been executed**. ## Controlled progression diff --git a/docs/VIRTUAL_TESTBED.md b/docs/VIRTUAL_TESTBED.md index 30f3b59..fca553d 100644 --- a/docs/VIRTUAL_TESTBED.md +++ b/docs/VIRTUAL_TESTBED.md @@ -8,7 +8,7 @@ This milestone supplies an offline-first *host-side implementation*, not a prein - One x86_64 guest, 2 vCPUs, 4096 MiB RAM, standalone 48 GiB QCOW2 virtual disk. Configuration is in lab/testbed.json. - **No guest NIC, bridge, NAT, hostdev, host share, USB redirection, graphics listener or public service** in the generated domain XML. - Serial PTY console only. Guest ISO must be obtained separately from authorized Red Hat distribution; no proprietary image is committed. -- Images, private receipts and XML live in an operator-selected private 0700 directory **outside the Git repository**. +- Images, private receipts and XML live in a pinned, operator-owned 0700 directory under trusted ancestors **outside the Git repository**. - Every host-changing command is explicit, opt-in, and fail-closed. No automatic boot, package installation, VM definition, snapshot restore, or host network configuration. - A definition/active XML audit rejects unexpected disks, device passthrough, guest networking and external graphics. **This is a configuration audit, not proof of effective egress isolation.** - No GitHub Pages, public dashboard or network endpoint. @@ -17,7 +17,7 @@ This milestone supplies an offline-first *host-side implementation*, not a prein Use a personally controlled Linux host with KVM support and local libvirt/QEMU tools installed by the operator according to their OS instructions. You need virsh, qemu-img, a working per-user qemu:///session connection, access to /dev/kvm and sufficient disk space. Do not install packages automatically as part of CI or this project. -Check the actual hardware, hypervisor, firmware support, host ownership, VM resource budget, filesystem permissions and guest media authenticity yourself. The scripted plan **does not** check that a physical host is isolated. +Check the actual hardware, hypervisor, firmware support, host ownership, VM resource budget, filesystem permissions and guest media authenticity yourself. The lab-root parent and ancestors must be root/operator-owned and not group/other writable (the root-owned sticky /tmp convention is recognized); a new lab root is created 0700. Avoid shared mountpoints. The scripted plan **does not** check that a physical host is isolated. Download the correct RHEL installer ISO using your own authorized account, verify its official checksum/signature, and keep it outside Git. No vendor access credential belongs in a script, PR or public log. @@ -76,7 +76,7 @@ The snapshot command: 4. Refuses existing destination/receipt names and uses a no-clobber hard-link for final publication. 5. Records SHA-256, exact source commit, byte count and UTC time in a local receipt. -This is an **offline disk copy**, not a libvirt RAM-state snapshot and not a guaranteed atomic capture against hostile/concurrent writers. Never use qemu-img against a running VM disk. +This is an **offline disk copy**, not a libvirt RAM-state snapshot and not a guaranteed atomic capture against hostile/concurrent writers. The operation now pins trusted directory and file descriptors, pre-creates output with exclusive owner-only permissions and invokes qemu-img through inherited Linux /proc/self/fd handles; `/proc` must be available. A non-cooperating writer with the operator's identity or a live guest can still invalidate a snapshot. Never use qemu-img against a running VM disk. Verify the resulting evidence directory using scripts/evidence.py, storing its manifest outside the directory being sealed. Preserve guest kernel, release, package versions, original media checksum, VM settings, snapshot identifiers, command line, exit status and negative findings in a separate private baseline receipt. diff --git a/scripts/evidence.py b/scripts/evidence.py index 40ed421..5e7e84a 100644 --- a/scripts/evidence.py +++ b/scripts/evidence.py @@ -1,8 +1,8 @@ #!/usr/bin/env python3 -"""Deterministic SHA-256 file inventory for an operator-controlled evidence directory. +"""Deterministic evidence manifests using descriptor-pinned, no-follow traversal. -The manifest establishes byte identity only. It is not a signature, chain of custody, -proof of origin, or proof that an experiment executed. No network or guest access. +A SHA-256 manifest describes observed bytes, not signed chain of custody. +Use a quiescent/external snapshot for a point-in-time inventory. """ from __future__ import annotations @@ -10,99 +10,151 @@ import hashlib import json import os +import stat import sys from pathlib import Path +try: + from . import safe_fs +except ImportError: # direct invocation: python scripts/evidence.py + import safe_fs + SCHEMA = "qsol-rhel-evidence/v1" class EvidenceError(ValueError): - """Invalid input, unsafe file type, or a mismatched evidence manifest.""" + """Evidence tree changed, file type unsupported, or manifest mismatch.""" + + +def _identity(info: os.stat_result) -> tuple[int, int, int]: + return info.st_dev, info.st_ino, info.st_mode + + +def _unchanged(first: os.stat_result, last: os.stat_result) -> bool: + return (_identity(first) == _identity(last) + and first.st_size == last.st_size + and first.st_mtime_ns == last.st_mtime_ns + and first.st_ctime_ns == last.st_ctime_ns) + + +def _scan(fd: int, prefix: str, files: list[dict], depth: int = 0) -> None: + if depth > 256: + raise EvidenceError("evidence directory nesting exceeds safety limit") + before_dir = os.fstat(fd) + with os.scandir(fd) as iterator: + entries = sorted(iterator, key=lambda entry: entry.name) + for entry in entries: + relative = f"{prefix}/{entry.name}" if prefix else entry.name + observed = entry.stat(follow_symlinks=False) + if stat.S_ISLNK(observed.st_mode): + raise EvidenceError(f"symlink is not permitted: {relative!a}") + # Open relative to the pinned parent. O_NONBLOCK prevents raced FIFOs + # from blocking; fstat validates the object actually opened. + child_fd = os.open(entry.name, safe_fs.FILE_READ_FLAGS, dir_fd=fd) + try: + opened = os.fstat(child_fd) + if _identity(observed) != _identity(opened): + raise EvidenceError(f"evidence entry changed while opening: {relative!a}") + if stat.S_ISDIR(opened.st_mode): + _scan(child_fd, relative, files, depth + 1) + elif stat.S_ISREG(opened.st_mode): + digest = hashlib.sha256() + count = 0 + while True: + chunk = os.read(child_fd, 1024 * 1024) + if not chunk: + break + digest.update(chunk) + count += len(chunk) + final = os.fstat(child_fd) + if not _unchanged(opened, final) or count != final.st_size: + raise EvidenceError(f"evidence file changed during hashing: {relative!a}") + files.append({"path": relative, "bytes": count, + "sha256": digest.hexdigest()}) + else: + raise EvidenceError(f"non-regular file is not permitted: {relative!a}") + finally: + os.close(child_fd) + if not _unchanged(before_dir, os.fstat(fd)): + raise EvidenceError(f"evidence directory changed during traversal: {prefix!a}") + + +def _inventory_fd(root_fd: int) -> dict: + files: list[dict] = [] + _scan(root_fd, "", files) + files.sort(key=lambda item: item["path"]) + return {"schema": SCHEMA, "algorithm": "sha256", "files": files} -def _root(path: Path) -> Path: - if path.is_symlink() or not path.is_dir(): - raise EvidenceError(f"input must be a real directory: {path}") - return path.resolve() +def inventory(input_dir: Path) -> dict: + """Fail closed on symlink, special file, unreadable subtree, observed race.""" + with safe_fs.directory(input_dir) as root_fd: + return _inventory_fd(root_fd) -def inventory(input_dir: Path) -> dict: - """List relative regular files in stable order; reject symlinks and special files.""" - root = _root(input_dir) - files = [] - directories = [root] - while directories: - directory = directories.pop() - # pathlib.Path.rglob() may suppress scandir errors on some Python - # versions. Explicit scandir traversal makes incomplete evidence fatal. - with os.scandir(directory) as iterator: - children = sorted(iterator, key=lambda entry: entry.name) - for entry in children: - path = Path(entry.path) - relative = path.relative_to(root).as_posix() - if entry.is_symlink(): - raise EvidenceError(f"symlink is not permitted: {relative}") - if entry.is_dir(follow_symlinks=False): - directories.append(path) - continue - if not entry.is_file(follow_symlinks=False): - raise EvidenceError(f"non-regular file is not permitted: {relative}") - digest = hashlib.sha256() - size = 0 - with path.open("rb") as source: - for chunk in iter(lambda: source.read(1024 * 1024), b""): - digest.update(chunk) - size += len(chunk) - files.append({"path": relative, "bytes": size, "sha256": digest.hexdigest()}) - files.sort(key=lambda item: item["path"]) - return {"schema": SCHEMA, "algorithm": "sha256", "files": files} +def _manifest_location(manifest: Path) -> tuple[Path, str]: + value = safe_fs.absolute(manifest) + if value.name in ("", ".", ".."): + raise EvidenceError("manifest basename is invalid") + return value.parent, value.name def seal(input_dir: Path, output: Path) -> dict: - """Write a fresh, deterministic manifest outside the captured directory.""" - root = _root(input_dir) - target = output.resolve() - if target == root or root in target.parents: - raise EvidenceError("manifest must be stored outside the input directory") - if output.is_symlink(): - raise EvidenceError("manifest output may not be a symlink") - report = inventory(root) - # Exclusive creation refuses to replace an existing manifest or symlink. - with output.open("x", encoding="utf-8", newline="\n") as stream: - json.dump(report, stream, indent=2, sort_keys=True) - stream.write("\n") - return report + """Write manifest with mode 0600 relative to a pinned private directory.""" + parent, name = _manifest_location(output) + with safe_fs.directory(input_dir) as root_fd: + st = os.fstat(root_fd) + root_identity = (st.st_dev, st.st_ino) + with safe_fs.directory(parent, private=True, forbidden=root_identity) as dest_fd: + report = _inventory_fd(root_fd) + fd = os.open(name, safe_fs.FILE_WRITE_FLAGS, 0o600, dir_fd=dest_fd) + with os.fdopen(fd, "w", encoding="utf-8", newline="\n") as stream: + json.dump(report, stream, indent=2, sort_keys=True) + stream.write("\n") + stream.flush() + os.fsync(stream.fileno()) + return report def verify(input_dir: Path, manifest: Path) -> dict: - """Recompute file inventory and fail on any missing, extra or modified file.""" - if manifest.is_symlink() or not manifest.is_file(): - raise EvidenceError("manifest must be an existing regular file (not a symlink)") - with manifest.open("r", encoding="utf-8") as stream: - expected = json.load(stream) - actual = inventory(input_dir) - if expected != actual: - raise EvidenceError("manifest mismatch: missing, extra, altered, or invalid files") - return actual + """Verify manifest and evidence via pinned FDs, refusing observed changes.""" + parent, name = _manifest_location(manifest) + with safe_fs.directory(input_dir) as root_fd: + st = os.fstat(root_fd) + with safe_fs.directory(parent, private=True, + forbidden=(st.st_dev, st.st_ino)) as manifest_fd: + fd = os.open(name, safe_fs.FILE_READ_FLAGS, dir_fd=manifest_fd) + try: + first = os.fstat(fd) + if not stat.S_ISREG(first.st_mode): + raise EvidenceError("manifest must be a regular file") + with os.fdopen(os.dup(fd), "r", encoding="utf-8") as stream: + expected = json.load(stream) + if not _unchanged(first, os.fstat(fd)): + raise EvidenceError("manifest changed while reading") + finally: + os.close(fd) + actual = _inventory_fd(root_fd) + if expected != actual: + raise EvidenceError("manifest mismatch: missing, extra, altered or invalid files") + return actual def main(argv: list[str] | None = None) -> int: parser = argparse.ArgumentParser(description=__doc__) - subparsers = parser.add_subparsers(dest="command", required=True) - seal_parser = subparsers.add_parser("seal", help="write a fresh SHA-256 manifest") - seal_parser.add_argument("--input", required=True, type=Path) - seal_parser.add_argument("--output", required=True, type=Path) - verify_parser = subparsers.add_parser("verify", help="verify an existing manifest") - verify_parser.add_argument("--input", required=True, type=Path) - verify_parser.add_argument("--manifest", required=True, type=Path) + subs = parser.add_subparsers(dest="command", required=True) + p_seal = subs.add_parser("seal", help="write a fresh SHA-256 manifest") + p_seal.add_argument("--input", required=True, type=Path) + p_seal.add_argument("--output", required=True, type=Path) + p_verify = subs.add_parser("verify", help="verify existing manifest") + p_verify.add_argument("--input", required=True, type=Path) + p_verify.add_argument("--manifest", required=True, type=Path) args = parser.parse_args(argv) try: - if args.command == "seal": - report = seal(args.input, args.output) - else: - report = verify(args.input, args.manifest) - except (EvidenceError, OSError, ValueError, TypeError) as exc: - print(f"FAIL: {exc}", file=sys.stderr) + report = seal(args.input, args.output) if args.command == "seal" else verify(args.input, args.manifest) + except (EvidenceError, safe_fs.UnsafePath, OSError, ValueError, TypeError) as exc: + # Escape attacker-provided filenames and terminal control characters. + print("FAIL: " + ascii(str(exc))[1:-1], file=sys.stderr) return 1 print(f"PASS: {len(report['files'])} evidence files; {args.command}") return 0 diff --git a/scripts/safe_fs.py b/scripts/safe_fs.py new file mode 100644 index 0000000..fdb2ccc --- /dev/null +++ b/scripts/safe_fs.py @@ -0,0 +1,120 @@ +"""Pinned, no-follow directory helpers for local-only research storage.""" +from __future__ import annotations + +import os +import stat +from contextlib import contextmanager +from pathlib import Path + +DIR_FLAGS = os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW | os.O_CLOEXEC +FILE_READ_FLAGS = os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK | os.O_CLOEXEC +FILE_RDWR_CREATE_FLAGS = os.O_RDWR | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW | os.O_CLOEXEC +FILE_WRITE_FLAGS = os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW | os.O_CLOEXEC + + +class UnsafePath(ValueError): + """A path crosses an untrusted or ambiguous filesystem boundary.""" + + +def absolute(path: str | Path) -> Path: + path = Path(path) + if ".." in path.parts: + raise UnsafePath("parent traversal is forbidden") + if not path.is_absolute(): + path = Path.cwd() / path + return path + + +def _trusted(directory_stat: os.stat_result) -> None: + owner = directory_stat.st_uid + mode = directory_stat.st_mode + if owner not in (0, os.geteuid()): + raise UnsafePath("directory ancestor belongs to another user") + if mode & 0o022: + # Root-owned sticky directories such as /tmp prevent other users + # from renaming operator-owned child entries. + if not (owner == 0 and mode & stat.S_ISVTX): + raise UnsafePath("directory ancestor is group/other writable") + + +@contextmanager +def directory(path: str | Path, *, trusted: bool = True, + private: bool = False, forbidden: tuple[int, int] | None = None): + """Open every path component with O_NOFOLLOW; pin the final directory FD.""" + p = absolute(path) + fd = os.open("/", DIR_FLAGS) + try: + if trusted: + _trusted(os.fstat(fd)) + for component in p.parts[1:]: + next_fd = os.open(component, DIR_FLAGS, dir_fd=fd) + os.close(fd) + fd = next_fd + info = os.fstat(fd) + if trusted: + _trusted(info) + if forbidden is not None and (info.st_dev, info.st_ino) == forbidden: + raise UnsafePath("manifest destination is within evidence root") + info = os.fstat(fd) + if private and (info.st_uid != os.geteuid() or info.st_mode & 0o077): + raise UnsafePath("directory must be operator-owned and private (0700)") + yield fd + finally: + os.close(fd) + + +@contextmanager +def lab_directory(path: str | Path, *, create: bool = False): + """Pin an operator-owned private lab root with an opened trusted parent.""" + p = absolute(path) + if p.name in ("", ".", ".."): + raise UnsafePath("invalid lab root") + with directory(p.parent) as parent_fd: + if create: + try: + os.mkdir(p.name, 0o700, dir_fd=parent_fd) + except FileExistsError: + pass # verify existing directory instead of trusting pathname + fd = os.open(p.name, DIR_FLAGS, dir_fd=parent_fd) + try: + info = os.fstat(fd) + if info.st_uid != os.geteuid() or info.st_mode & 0o077: + raise UnsafePath("lab root must be operator-owned and private") + yield fd + finally: + os.close(fd) + + +@contextmanager +def private_child_directory(parent_fd: int, name: str, *, create: bool = False): + if name in ("", ".", "..") or "/" in name: + raise UnsafePath("invalid child directory name") + if create: + try: + os.mkdir(name, 0o700, dir_fd=parent_fd) + except FileExistsError: + pass + fd = os.open(name, DIR_FLAGS, dir_fd=parent_fd) + try: + info = os.fstat(fd) + if info.st_uid != os.geteuid() or info.st_mode & 0o077: + raise UnsafePath("child directory must be operator-owned and private") + yield fd + finally: + os.close(fd) + + +def exists_at(fd: int, name: str) -> bool: + try: + os.stat(name, dir_fd=fd, follow_symlinks=False) + except FileNotFoundError: + return False + return True + + +def regular_at(parent_fd: int, name: str) -> int: + fd = os.open(name, FILE_READ_FLAGS, dir_fd=parent_fd) + if not stat.S_ISREG(os.fstat(fd).st_mode): + os.close(fd) + raise UnsafePath("only regular file inputs are supported") + return fd diff --git a/scripts/testbed.py b/scripts/testbed.py index d25a0a4..de6c3a3 100644 --- a/scripts/testbed.py +++ b/scripts/testbed.py @@ -16,6 +16,11 @@ from pathlib import Path from xml.etree import ElementTree as ET +try: + from . import safe_fs +except ImportError: # direct invocation + import safe_fs + SCHEMA = "qsol-rhel-testbed/v1" REPO = Path(__file__).resolve().parent.parent URI = "qemu:///session" @@ -64,23 +69,22 @@ def absolute_path(text: str) -> Path: for entry in (path, *path.parents): if entry.is_symlink(): raise TestbedError(f"symlink in host path: {entry}") - return path.resolve(strict=False) + return path def state_dir(text: str, *, must_exist: bool = False) -> Path: + """Validate trusted ancestors; mutating operations later pin their own FDs.""" root = absolute_path(text) if root == REPO or REPO in root.parents: raise TestbedError("state must live outside the Git repository") + # This closes the lower-trust ancestor boundary even when the root is absent. + with safe_fs.directory(root.parent): + pass if root.exists(): - if not root.is_dir(): - raise TestbedError("state path is not a directory") - info = root.stat() - if info.st_uid != os.geteuid() or stat.S_IMODE(info.st_mode) & 0o077: - raise TestbedError("state directory must be user-owned and mode 0700") + with safe_fs.lab_directory(root): + pass elif must_exist: raise TestbedError("state directory not prepared") - elif not root.parent.is_dir(): - raise TestbedError("state directory parent must already exist") return root @@ -213,10 +217,11 @@ def _diagnostic(value: str | bytes | None) -> str: return value -def local_command(args: list[str], timeout: int = 30) -> str: +def local_command(args: list[str], timeout: int = 30, + *, pass_fds: tuple[int, ...] = ()) -> str: try: result = subprocess.run(args, check=True, timeout=timeout, - capture_output=True, text=True) + capture_output=True, text=True, pass_fds=pass_fds) except subprocess.CalledProcessError as exc: raise TestbedError( f"{args[0]} returned exit status {exc.returncode}; " @@ -256,19 +261,27 @@ def prepare(cfg: dict, root: Path, iso: Path, token: str | None) -> dict: need("qemu-img") disk, definition = paths(root) xml = render_xml(cfg, root, iso) - if any(path.exists() or path.is_symlink() for path in (disk, definition)): - raise TestbedError("refusing to replace existing disk/XML") - if not root.exists(): - root.mkdir(mode=0o700) - old_umask = os.umask(0o077) - try: - local_command(["qemu-img", "create", "-f", "qcow2", - str(disk), f"{cfg['disk_gib']}G"], timeout=120) - fd = os.open(definition, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600) + # Keep an operator-owned, private lab FD open across all host mutations. + # qemu-img receives an inherited FD, never a mutable ancestor pathname. + with safe_fs.lab_directory(root, create=True) as lab_fd: + if any(safe_fs.exists_at(lab_fd, name) + for name in ("disk.qcow2", "domain.xml")): + raise TestbedError("refusing to replace existing disk/XML") + disk_fd = os.open("disk.qcow2", + safe_fs.FILE_RDWR_CREATE_FLAGS, + 0o600, dir_fd=lab_fd) + try: + local_command(["qemu-img", "create", "-f", "qcow2", + f"/proc/self/fd/{disk_fd}", f"{cfg['disk_gib']}G"], + timeout=120, pass_fds=(disk_fd,)) + finally: + os.close(disk_fd) + fd = os.open("domain.xml", safe_fs.FILE_WRITE_FLAGS, 0o600, + dir_fd=lab_fd) with os.fdopen(fd, "w", encoding="utf-8") as stream: stream.write(xml) - finally: - os.umask(old_umask) + stream.flush() + os.fsync(stream.fileno()) return {"status": "PREPARED_NOT_DEFINED_OR_BOOTED", "definition": str(definition), "disk": str(disk), "manual_next": f"virsh -c {URI} define {definition}"} @@ -284,14 +297,24 @@ def audit_defined(cfg: dict, root: Path, iso: Path) -> dict: "limitation": "Does not prove host egress isolation or prevent races."} -def hash_file(path: Path) -> tuple[str, int]: +def hash_fd(fd: int) -> tuple[str, int]: + """Hash a stable, already opened regular descriptor.""" + before = os.fstat(fd) + if not stat.S_ISREG(before.st_mode): + raise TestbedError("snapshot output is not a regular file") + os.lseek(fd, 0, os.SEEK_SET) digest = hashlib.sha256() - size = 0 - with path.open("rb") as stream: - for block in iter(lambda: stream.read(1024 * 1024), b""): - digest.update(block) - size += len(block) - return digest.hexdigest(), size + count = 0 + for chunk in iter(lambda: os.read(fd, 1024 * 1024), b""): + digest.update(chunk) + count += len(chunk) + after = os.fstat(fd) + if ((before.st_dev, before.st_ino, before.st_size, + before.st_mtime_ns, before.st_ctime_ns) + != (after.st_dev, after.st_ino, after.st_size, + after.st_mtime_ns, after.st_ctime_ns) or count != after.st_size): + raise TestbedError("snapshot image changed during hashing") + return digest.hexdigest(), count def snapshot(cfg: dict, root: Path, iso: Path, label: str, sha: str, @@ -300,48 +323,70 @@ def snapshot(cfg: dict, root: Path, iso: Path, label: str, sha: str, if LABEL.fullmatch(label) is None or SHA.fullmatch(sha) is None: raise TestbedError("invalid snapshot label or exact Git commit SHA") need("qemu-img") - disk, _ = paths(root) - if disk.is_symlink() or not disk.is_file(): - raise TestbedError("local disk absent or symlinked") - folder = root / "snapshots" - if folder.is_symlink() or (folder.exists() and not folder.is_dir()): - raise TestbedError("snapshots directory is unsafe") - dest = folder / f"{label}.qcow2" - receipt = folder / f"{label}.receipt.json" - if any(p.exists() or p.is_symlink() for p in (dest, receipt)): - raise TestbedError("snapshot or receipt already exists") - audit_defined(cfg, root, iso) - state = local_command(["virsh", "-c", URI, "domstate", cfg["name"]]) - if state != "shut off": - raise TestbedError(f"domain is not shut off: {state}") - metadata = json.loads(local_command(["qemu-img", "info", "--output=json", str(disk)])) - if metadata.get("format") != "qcow2" or metadata.get("backing-filename"): - raise TestbedError("only standalone QCOW2 images are supported") - if not folder.exists(): - folder.mkdir(mode=0o700) - temporary = folder / f".pending-{secrets.token_hex(16)}.qcow2" - if temporary.exists(): - raise TestbedError("temporary snapshot name collision") - # QEMU warns against processing disks being used by another process. - local_command(["qemu-img", "convert", "-f", "qcow2", "-O", "qcow2", - str(disk), str(temporary)], timeout=3600) - if temporary.is_symlink() or not temporary.is_file(): - raise TestbedError("conversion did not produce a regular disk image") - digest, size = hash_file(temporary) - os.link(temporary, dest) # atomic no-clobber publication - temporary.unlink() - report = { - "schema": "qsol-rhel-snapshot/v1", "domain": cfg["name"], - "label": label, "source_commit": sha, "sha256": digest, - "bytes": size, "captured_utc": datetime.now(timezone.utc).isoformat(), - "claim": "OFFLINE_DISK_COPY_ONLY", - "limitation": "No guarantee against another process starting/writing this VM.", - } - with receipt.open("x", encoding="utf-8") as stream: - json.dump(report, stream, indent=2, sort_keys=True) - stream.write("\n") - return {"status": "SNAPSHOT_CREATED", "image": str(dest), - "receipt": str(receipt), "sha256": digest} + with safe_fs.lab_directory(root) as lab_fd: + source_fd = safe_fs.regular_at(lab_fd, "disk.qcow2") + try: + audit_defined(cfg, root, iso) + state = local_command(["virsh", "-c", URI, "domstate", cfg["name"]]) + if state != "shut off": + raise TestbedError(f"domain is not shut off: {state}") + source_path = f"/proc/self/fd/{source_fd}" + metadata = json.loads(local_command( + ["qemu-img", "info", "--output=json", source_path], + pass_fds=(source_fd,))) + if metadata.get("format") != "qcow2" or metadata.get("backing-filename"): + raise TestbedError("only standalone QCOW2 images are supported") + source_before = os.fstat(source_fd) + with safe_fs.private_child_directory(lab_fd, "snapshots", + create=True) as snapshot_fd: + destination = f"{label}.qcow2" + receipt_name = f"{label}.receipt.json" + if (safe_fs.exists_at(snapshot_fd, destination) + or safe_fs.exists_at(snapshot_fd, receipt_name)): + raise TestbedError("snapshot or receipt already exists") + temporary = f".pending-{secrets.token_hex(16)}.qcow2" + temp_fd = os.open(temporary, safe_fs.FILE_RDWR_CREATE_FLAGS, + 0o600, dir_fd=snapshot_fd) + published = False + try: + local_command(["qemu-img", "convert", "-f", "qcow2", "-O", "qcow2", + source_path, f"/proc/self/fd/{temp_fd}"], + timeout=3600, pass_fds=(source_fd, temp_fd)) + source_after = os.fstat(source_fd) + if ((source_before.st_size, source_before.st_mtime_ns, source_before.st_ctime_ns) + != (source_after.st_size, source_after.st_mtime_ns, source_after.st_ctime_ns)): + raise TestbedError("source disk changed during offline copy") + digest, size = hash_fd(temp_fd) + report = { + "schema": "qsol-rhel-snapshot/v1", "domain": cfg["name"], + "label": label, "source_commit": sha, "sha256": digest, + "bytes": size, "captured_utc": datetime.now(timezone.utc).isoformat(), + "claim": "OFFLINE_DISK_COPY_ONLY", + "limitation": "A non-cooperating writer may still change guest state.", + } + os.link(temporary, destination, src_dir_fd=snapshot_fd, + dst_dir_fd=snapshot_fd, follow_symlinks=False) + published = True + fd = os.open(receipt_name, safe_fs.FILE_WRITE_FLAGS, + 0o600, dir_fd=snapshot_fd) + with os.fdopen(fd, "w", encoding="utf-8") as stream: + json.dump(report, stream, indent=2, sort_keys=True) + stream.write("\n") + stream.flush() + os.fsync(stream.fileno()) + except Exception: + if published: + os.unlink(destination, dir_fd=snapshot_fd) + raise + finally: + os.close(temp_fd) + os.unlink(temporary, dir_fd=snapshot_fd) + finally: + os.close(source_fd) + return {"status": "SNAPSHOT_CREATED", + "image": str(root / "snapshots" / f"{label}.qcow2"), + "receipt": str(root / "snapshots" / f"{label}.receipt.json"), + "sha256": digest} def main(argv: list[str] | None = None) -> int: @@ -370,7 +415,7 @@ def main(argv: list[str] | None = None) -> int: report = audit_defined(cfg, root, iso) else: report = snapshot(cfg, root, iso, args.label, args.source_sha, args.approve) - except (TestbedError, OSError, ValueError, subprocess.SubprocessError, ET.ParseError) as exc: + except (TestbedError, safe_fs.UnsafePath, OSError, ValueError, subprocess.SubprocessError, ET.ParseError) as exc: print(f"FAIL: {exc}", file=sys.stderr) return 1 print(json.dumps(report, sort_keys=True, indent=2)) diff --git a/tests/test_evidence.py b/tests/test_evidence.py index 0d0fbee..b66af30 100644 --- a/tests/test_evidence.py +++ b/tests/test_evidence.py @@ -4,11 +4,13 @@ import json import os import tempfile +import stat import unittest from pathlib import Path from unittest.mock import patch from scripts.evidence import EvidenceError, inventory, seal, verify +from scripts.safe_fs import UnsafePath class EvidenceTests(unittest.TestCase): @@ -47,7 +49,7 @@ def test_added_file_fails(self) -> None: verify(self.data, self.manifest) def test_output_inside_input_fails(self) -> None: - with self.assertRaises(EvidenceError): + with self.assertRaises(UnsafePath): seal(self.data, self.data / "manifest.json") def test_existing_manifest_is_not_overwritten(self) -> None: @@ -64,7 +66,7 @@ def test_symlinked_evidence_is_rejected(self) -> None: def test_symlinked_root_is_rejected(self) -> None: alias = self.base / "alias" alias.symlink_to(self.data, target_is_directory=True) - with self.assertRaises(EvidenceError): + with self.assertRaises(NotADirectoryError): inventory(alias) def test_modified_manifest_fails(self) -> None: @@ -90,8 +92,8 @@ def test_unreadable_subdirectory_blocks_seal(self) -> None: real_scandir = os.scandir def deny(path): - if Path(path) == blocked: - raise PermissionError(f"cannot enumerate {path}") + if isinstance(path, int) and Path(os.readlink(f"/proc/self/fd/{path}")) == blocked: + raise PermissionError(f"cannot enumerate {blocked}") return real_scandir(path) with patch("scripts.evidence.os.scandir", side_effect=deny): @@ -109,8 +111,8 @@ def test_unreadable_subdirectory_blocks_verify(self) -> None: real_scandir = os.scandir def deny(path): - if Path(path) == blocked: - raise PermissionError(f"cannot enumerate {path}") + if isinstance(path, int) and Path(os.readlink(f"/proc/self/fd/{path}")) == blocked: + raise PermissionError(f"cannot enumerate {blocked}") return real_scandir(path) with patch("scripts.evidence.os.scandir", side_effect=deny): @@ -132,5 +134,67 @@ def test_symlinked_directory_is_rejected(self) -> None: + def test_sealed_manifest_is_private_even_with_permissive_umask(self) -> None: + original = os.umask(0o022) + try: + seal(self.data, self.manifest) + finally: + os.umask(original) + self.assertEqual(stat.S_IMODE(self.manifest.stat().st_mode), 0o600) + + def test_public_manifest_parent_is_rejected(self) -> None: + public = self.base / "public" + public.mkdir(mode=0o755) + with self.assertRaises(UnsafePath): + seal(self.data, public / "manifest.json") + + def test_raced_symlink_never_hashes_outside_file(self) -> None: + victim = self.data / "a.log" + outside = self.base / "outside-secret" + outside.write_bytes(b"secret outside evidence") + real_open = os.open + triggered = False + + def swap(name, flags, *args, **kwargs): + nonlocal triggered + if name == "a.log" and kwargs.get("dir_fd") is not None and not triggered: + triggered = True + victim.unlink() + victim.symlink_to(outside) + return real_open(name, flags, *args, **kwargs) + + with patch("scripts.evidence.os.open", side_effect=swap): + with self.assertRaises(OSError): + inventory(self.data) + self.assertTrue(triggered) + + def test_output_parent_swap_keeps_pinned_destination(self) -> None: + original_inventory = inventory(self.data) + original = self.base / "dest" + original.mkdir(mode=0o700) + moved = self.base / "moved" + def swap(fd): + original.rename(moved) + original.symlink_to(self.data, target_is_directory=True) + return original_inventory + with patch("scripts.evidence._inventory_fd", side_effect=swap): + seal(self.data, original / "manifest.json") + self.assertTrue((moved / "manifest.json").is_file()) + self.assertFalse((self.data / "manifest.json").exists()) + + def test_terminal_control_in_rejected_filename_is_escaped(self) -> None: + from contextlib import redirect_stderr + from io import StringIO + from scripts.evidence import main + (self.data / "bad\x1b[2J\nname").symlink_to(self.data / "a.log") + errors = StringIO() + with redirect_stderr(errors): + status = main(["seal", "--input", str(self.data), "--output", str(self.manifest)]) + self.assertEqual(status, 1) + self.assertNotIn("\x1b", errors.getvalue()) + self.assertNotIn("\nname", errors.getvalue()) + self.assertFalse(self.manifest.exists()) + + if __name__ == "__main__": unittest.main() diff --git a/tests/test_testbed.py b/tests/test_testbed.py index b42c0de..6351f05 100644 --- a/tests/test_testbed.py +++ b/tests/test_testbed.py @@ -10,6 +10,7 @@ from unittest.mock import patch from scripts import testbed as t +from scripts import safe_fs class TestbedTests(unittest.TestCase): @@ -157,7 +158,7 @@ def test_prepare_requires_operator_approval(self): self.assertFalse(self.root.exists()) def test_prepare_never_defines_or_boots_vm(self): - def fake_qemu(args, timeout=30): + def fake_qemu(args, timeout=30, pass_fds=()): self.assertEqual(args[:4], ["qemu-img", "create", "-f", "qcow2"]) Path(args[4]).write_bytes(b"simulated image") return "" @@ -202,5 +203,73 @@ def fake_command(args, timeout=30): self.assertNotIn("--inactive", calls[1]) + def test_untrusted_parent_writable_by_other_users_is_refused(self): + shared = self.base / "shared" + shared.mkdir(mode=0o700) + shared.chmod(0o777) + with self.assertRaises(safe_fs.UnsafePath): + t.state_dir(str(shared / "rhel-lab-attacker"), must_exist=False) + + def test_prepare_pins_created_directory_across_parent_swap(self): + moved = self.base / "moved" + attacker = self.base / "outside" + attacker.mkdir(mode=0o700) + + def raced_qemu(args, timeout=30, pass_fds=()): + self.assertEqual(args[:4], ["qemu-img", "create", "-f", "qcow2"]) + self.assertEqual(len(pass_fds), 1) + self.root.rename(moved) + self.root.symlink_to(attacker, target_is_directory=True) + Path(args[4]).write_bytes(b"simulated image") + return "" + + with patch.object(t, "need"), patch.object(t, "local_command", + side_effect=raced_qemu): + t.prepare(self.cfg, self.root, self.iso, t.PREPARE_TOKEN) + self.assertTrue((moved / "domain.xml").is_file()) + self.assertTrue((moved / "disk.qcow2").is_file()) + self.assertFalse((attacker / "domain.xml").exists()) + self.assertFalse((attacker / "disk.qcow2").exists()) + + def test_snapshot_source_symlink_is_refused(self): + self.root.mkdir(mode=0o700) + outside = self.base / "outside.qcow2" + outside.write_bytes(b"secret") + (self.root / "disk.qcow2").symlink_to(outside) + with patch.object(t, "need"): + with self.assertRaises(OSError): + t.snapshot(self.cfg, self.root, self.iso, "baseline", "a" * 40, + t.SNAPSHOT_TOKEN) + + def test_offline_snapshot_receipt_is_private(self): + self.root.mkdir(mode=0o700) + (self.root / "disk.qcow2").write_bytes(b"fake disk") + + def fake_command(args, timeout=30, pass_fds=()): + if args[:2] == ["virsh", "-c"]: + return "shut off" + if args[:2] == ["qemu-img", "info"]: + self.assertTrue(pass_fds) + return '{"format":"qcow2"}' + if args[:2] == ["qemu-img", "convert"]: + self.assertEqual(len(pass_fds), 2) + Path(args[-1]).write_bytes(b"converted evidence") + return "" + self.fail(f"unexpected command: {args}") + + with patch.object(t, "need"), patch.object(t, "audit_defined"), \ + patch.object(t, "local_command", side_effect=fake_command): + result = t.snapshot(self.cfg, self.root, self.iso, "baseline", + "a" * 40, t.SNAPSHOT_TOKEN) + receipt = Path(result["receipt"]) + image = Path(result["image"]) + self.assertTrue(image.is_file()) + self.assertEqual(image.read_bytes(), b"converted evidence") + self.assertEqual(os.stat(receipt).st_mode & 0o777, 0o600) + self.assertEqual(json.loads(receipt.read_text())["sha256"], result["sha256"]) + self.assertEqual(json.loads(receipt.read_text())["claim"], "OFFLINE_DISK_COPY_ONLY") + + + if __name__ == "__main__": unittest.main()