zabbix-crontroller 0.0.1__py3-none-any.whl

zabbix_crontroller/__init__.py

@@ -0,0 +1,8 @@
+"""Monitor cron jobs while keeping the parser independently importable."""
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Delegate to the application without importing it during library use."""
+    from .app import main as app_main
+
+    return app_main(argv)

zabbix_crontroller/app.py

@@ -0,0 +1,596 @@
+"""Run cron commands with bounded evidence capture and validate installations.
+
+The application targets Linux with cron. It uses only the standard library and
+never submits data to Zabbix or reads system logs. Monitoring failures do not
+prevent a valid command from running or replace its exit status.
+"""
+
+import argparse
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+import fcntl
+import json
+import os
+from pathlib import Path
+import select
+import shutil
+import signal
+import stat
+import subprocess
+import sys
+import time
+from typing import BinaryIO
+import uuid
+
+from .invocation import JOB_IDENTIFIER
+from .parser import CronJob, ParseError, parse_crontab
+
+CAPTURE_LIMIT = 10 * 1024 * 1024
+RETAIN_RUNS = 20
+DRAIN_SECONDS = 2.0
+_CHUNK_SIZE = 64 * 1024
+
+
+def _now() -> str:
+    """Return a UTC timestamp suitable for a JSON run record."""
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _diagnostic(message: str) -> None:
+    """Attempt a stderr diagnostic without turning a broken sink into failure."""
+    flags = None
+    try:
+        flags = fcntl.fcntl(2, fcntl.F_GETFL)
+        fcntl.fcntl(2, fcntl.F_SETFL, flags | os.O_NONBLOCK)
+        os.write(
+            2, f"zabbix-crontroller: {message}\n".encode("utf-8", "backslashreplace")
+        )
+    except OSError:
+        pass
+    finally:
+        if flags is not None:
+            try:
+                fcntl.fcntl(2, fcntl.F_SETFL, flags)
+            except OSError:
+                pass
+
+
+def _problem(record: dict, message: str) -> None:
+    """Retain a monitoring error and attempt to report it to the operator."""
+    record["errors"].append(message)
+    _diagnostic(message)
+
+
+def _state_directory() -> Path:
+    """Resolve per-user storage without expanding variables in explicit values."""
+    if "ZC_STATE_DIR" in os.environ:
+        root = Path(os.environ["ZC_STATE_DIR"])
+        if not root.is_absolute():
+            raise ValueError("ZC_STATE_DIR must be an absolute path")
+        return root
+    state_home = os.environ.get("XDG_STATE_HOME", "")
+    if state_home and Path(state_home).is_absolute():
+        return Path(state_home) / "zabbix-crontroller"
+    return Path.home() / ".local" / "state" / "zabbix-crontroller"
+
+
+def _private_directory(path: Path) -> None:
+    """Create missing directories privately and reject an unsafe evidence root."""
+    missing = []
+    ancestor = path
+    while not ancestor.exists() and not ancestor.is_symlink():
+        missing.append(ancestor)
+        ancestor = ancestor.parent
+    for directory in reversed(missing):
+        try:
+            directory.mkdir(mode=0o700)
+            directory.chmod(0o700)
+        except FileExistsError:
+            pass
+    info = path.lstat()
+    if (
+        not stat.S_ISDIR(info.st_mode)
+        or info.st_uid != os.getuid()
+        or info.st_mode & 0o077
+    ):
+        raise OSError(
+            f"Evidence directory must be owned by this user with mode 0700: {path}"
+        )
+
+
+def _private_file(path: Path, *, exclusive: bool = True) -> BinaryIO:
+    """Open a private regular file without following a final-component symlink."""
+    flags = os.O_CREAT | os.O_RDWR | os.O_NOFOLLOW | os.O_NONBLOCK
+    if exclusive:
+        flags |= os.O_EXCL
+    descriptor = os.open(path, flags, 0o600)
+    try:
+        info = os.fstat(descriptor)
+        if (
+            not stat.S_ISREG(info.st_mode)
+            or info.st_uid != os.getuid()
+            or info.st_mode & 0o077
+        ):
+            raise OSError(
+                f"Evidence file must be private and owned by this user: {path}"
+            )
+        os.fchmod(descriptor, 0o600)
+        return os.fdopen(descriptor, "r+b", buffering=0)
+    except BaseException:
+        os.close(descriptor)
+        raise
+
+
+def _sync_directory(path: Path) -> None:
+    """Persist directory entries after creation or atomic record replacement."""
+    descriptor = os.open(path, os.O_RDONLY | os.O_DIRECTORY)
+    try:
+        os.fsync(descriptor)
+    finally:
+        os.close(descriptor)
+
+
+def _write_all(file: BinaryIO, data: bytes) -> int:
+    """Write all bytes to a local evidence file, including partial writes."""
+    view = memoryview(data)
+    written = 0
+    while written < len(view):
+        count = file.write(view[written:])
+        if not count:
+            raise OSError("Evidence write made no progress")
+        written += count
+    return written
+
+
+class _Store:
+    """Own one invocation's private directory and atomic status publication."""
+
+    def __init__(self, job_id: str, run_id: str) -> None:
+        """Create storage without changing the job's inherited umask."""
+        root = _state_directory()
+        _private_directory(root)
+        self.job_directory = root / job_id
+        _private_directory(self.job_directory)
+        self.directory = self.job_directory / run_id
+        self.directory.mkdir(mode=0o700)
+        self.directory.chmod(0o700)
+        _sync_directory(root)
+        _sync_directory(self.job_directory)
+
+    def save(self, record: dict) -> None:
+        """Publish a complete, durable JSON snapshot by atomic replacement."""
+        temporary = self.directory / f".run-{uuid.uuid4().hex}.tmp"
+        try:
+            with _private_file(temporary) as file:
+                _write_all(file, (json.dumps(record, indent=2) + "\n").encode("utf-8"))
+                os.fsync(file.fileno())
+            os.replace(temporary, self.directory / "run.json")
+            _sync_directory(self.directory)
+        finally:
+            temporary.unlink(missing_ok=True)
+
+    def prune(self) -> None:
+        """Serialise retention and remove only recognised, completed run folders."""
+        with _private_file(
+            self.job_directory / ".cleanup.lock", exclusive=False
+        ) as lock:
+            fcntl.flock(lock, fcntl.LOCK_EX)
+            completed = []
+            for directory in self.job_directory.iterdir():
+                if directory.is_symlink() or not directory.is_dir():
+                    continue
+                try:
+                    if uuid.UUID(directory.name).hex != directory.name:
+                        continue
+                    contents = list(directory.iterdir())
+                    if any(
+                        item.is_symlink() or not item.is_file() for item in contents
+                    ):
+                        continue
+                    if {item.name for item in contents} != {
+                        "run.json",
+                        "stdout.log",
+                        "stderr.log",
+                    }:
+                        continue
+                    record = json.loads(
+                        (directory / "run.json").read_text(encoding="utf-8")
+                    )
+                    if (
+                        not isinstance(record, dict)
+                        or record.get("schema_version") != 1
+                        or record.get("status") not in ("finished", "spawn_failed")
+                        or record.get("run_id") != directory.name
+                        or record.get("job_id") != self.job_directory.name
+                        or record.get("uid") != os.getuid()
+                        or not isinstance(record.get("finished_at"), str)
+                    ):
+                        continue
+                    finished = datetime.fromisoformat(record["finished_at"])
+                    if finished.tzinfo is None:
+                        continue
+                    completed.append((finished, directory.name, directory))
+                except OSError, ValueError, TypeError:
+                    continue
+            for _, _, directory in sorted(completed, reverse=True)[RETAIN_RUNS:]:
+                shutil.rmtree(directory)
+
+
+def _save(store: _Store | None, record: dict) -> bool:
+    """Attempt publication without affecting command execution."""
+    if store is None:
+        return False
+    try:
+        store.save(record)
+        return True
+    except OSError as error:
+        _problem(record, f"Cannot save run record: {error}")
+        return False
+
+
+@dataclass
+class _Stream:
+    """Track one child's byte stream, bounded forwarding buffer and capture."""
+
+    name: str
+    destination: int | None
+    capture: BinaryIO | None = None
+    source: BinaryIO | None = None
+    pending: bytearray = field(default_factory=bytearray)
+    seen: int = 0
+    saved: int = 0
+    forwarded: int = 0
+    eof: bool = False
+    capture_failed: bool = False
+    forwarding_failed: bool = False
+
+    def receive(self, data: bytes, record: dict) -> None:
+        """Save a bounded prefix, then queue bytes for their original destination."""
+        self.seen += len(data)
+        if self.capture is not None and self.saved < CAPTURE_LIMIT:
+            try:
+                self.saved += _write_all(
+                    self.capture, data[: CAPTURE_LIMIT - self.saved]
+                )
+            except OSError as error:
+                self.capture_failed = True
+                _problem(record, f"Cannot capture {self.name}: {error}")
+                self.close_capture(record)
+        if self.destination is not None:
+            self.pending.extend(data)
+
+    def close_capture(self, record: dict) -> None:
+        """Flush evidence and report delayed storage failures."""
+        if self.capture is None:
+            return
+        try:
+            self.saved = os.fstat(self.capture.fileno()).st_size
+            os.fsync(self.capture.fileno())
+        except OSError as error:
+            self.capture_failed = True
+            _problem(record, f"Cannot finalise {self.name}: {error}")
+        finally:
+            try:
+                self.capture.close()
+            except OSError as error:
+                self.capture_failed = True
+                _problem(record, f"Cannot close {self.name}: {error}")
+            self.capture = None
+
+    def summary(self) -> dict:
+        """Describe captured and forwarded byte counts without decoding output."""
+        return {
+            "bytes_seen": self.seen,
+            "bytes_saved": self.saved,
+            "bytes_forwarded": self.forwarded,
+            "truncated": self.seen > CAPTURE_LIMIT,
+            "eof": self.eof,
+            "capture_complete": self.eof
+            and not self.capture_failed
+            and self.seen <= CAPTURE_LIMIT,
+            "forwarding_complete": self.eof
+            and not self.forwarding_failed
+            and not self.pending,
+        }
+
+
+def _capture(child: subprocess.Popen, streams: list[_Stream], record: dict) -> int:
+    """Drain both pipes fairly with bounded buffers and a post-exit deadline.
+
+    Non-blocking forwarding prevents one stalled destination from blocking reads
+    of the other stream. Original descriptor flags are restored before returning.
+    Regular-file I/O remains subject to the underlying filesystem's latency.
+    """
+    original_flags = {}
+    for stream in streams:
+        try:
+            original_flags[stream.destination] = fcntl.fcntl(
+                stream.destination, fcntl.F_GETFL
+            )
+        except OSError as error:
+            _problem(record, f"Cannot forward {stream.name}: {error}")
+            stream.destination = None
+            stream.forwarding_failed = True
+    try:
+        for stream in streams:
+            if stream.destination is not None:
+                try:
+                    fcntl.fcntl(
+                        stream.destination,
+                        fcntl.F_SETFL,
+                        original_flags[stream.destination] | os.O_NONBLOCK,
+                    )
+                except OSError as error:
+                    _problem(
+                        record, f"Cannot configure {stream.name} forwarding: {error}"
+                    )
+                    stream.destination = None
+                    stream.forwarding_failed = True
+        deadline = None
+        while True:
+            returncode = child.poll()
+            if returncode is not None:
+                if deadline is None:
+                    deadline = time.monotonic() + DRAIN_SECONDS
+                if all(stream.eof and not stream.pending for stream in streams):
+                    return returncode
+                if time.monotonic() >= deadline:
+                    for stream in streams:
+                        if not stream.eof or stream.pending:
+                            _problem(
+                                record,
+                                f"{stream.name} drain deadline exceeded; output is incomplete",
+                            )
+                    return returncode
+            readable = [
+                stream.source
+                for stream in streams
+                if not stream.eof and not stream.pending
+            ]
+            writable = [
+                stream.destination
+                for stream in streams
+                if stream.pending and stream.destination is not None
+            ]
+            ready_read, ready_write, _ = select.select(readable, writable, [], 0.05)
+            for stream in streams:
+                if stream.source in ready_read:
+                    data = os.read(stream.source.fileno(), _CHUNK_SIZE)
+                    if data:
+                        stream.receive(data, record)
+                    else:
+                        stream.eof = True
+                if stream.destination in ready_write and stream.pending:
+                    try:
+                        count = os.write(stream.destination, stream.pending)
+                        if count == 0:
+                            raise OSError("Forwarding write made no progress")
+                        stream.forwarded += count
+                        del stream.pending[:count]
+                    except BlockingIOError:
+                        pass
+                    except OSError as error:
+                        stream.forwarding_failed = True
+                        stream.destination = None
+                        stream.pending.clear()
+                        _problem(record, f"Cannot forward {stream.name}: {error}")
+    finally:
+        for descriptor, flags in original_flags.items():
+            try:
+                fcntl.fcntl(descriptor, fcntl.F_SETFL, flags)
+            except OSError as error:
+                _problem(
+                    record, f"Cannot restore output descriptor {descriptor}: {error}"
+                )
+        for stream in streams:
+            stream.source.close()
+
+
+def run_job(job_id: str, command: str) -> int:
+    """Execute one foreground shell command and preserve its termination result.
+
+    The caller supplies an already decoded command argument. This function does
+    not read the crontab or repeat cron's percent preprocessing. Call it from the
+    main thread, as it temporarily owns the termination signal handlers.
+    """
+    if (
+        JOB_IDENTIFIER.fullmatch(job_id) is None
+        or not command.strip()
+        or "\x00" in command
+    ):
+        raise ValueError(
+            "A valid job identifier and non-empty, NUL-free command are required"
+        )
+    started = time.monotonic()
+    run_id = uuid.uuid4().hex
+    shell = os.environ.get("SHELL", "/bin/sh")
+    record = {
+        "schema_version": 1,
+        "job_id": job_id,
+        "run_id": run_id,
+        "uid": os.getuid(),
+        "command": command,
+        "shell": shell,
+        "wrapper_pid": os.getpid(),
+        "child_pid": None,
+        "started_at": _now(),
+        "finished_at": None,
+        "duration_seconds": None,
+        "status": "started",
+        "returncode": None,
+        "exit_code": None,
+        "signal": None,
+        "errors": [],
+        "streams": {},
+    }
+    store = None
+    try:
+        store = _Store(job_id, run_id)
+    except (OSError, ValueError, RuntimeError) as error:
+        _problem(record, f"Cannot initialise evidence storage: {error}")
+    _save(store, record)
+    streams = [_Stream("stdout", 1), _Stream("stderr", 2)]
+    for stream in streams:
+        if store is not None:
+            try:
+                stream.capture = _private_file(store.directory / f"{stream.name}.log")
+            except OSError as error:
+                _problem(record, f"Cannot open {stream.name} capture: {error}")
+        stream.capture_failed = stream.capture is None
+
+    child = None
+    pending_signals = []
+
+    def forward(signum: int, frame: object) -> None:
+        """Forward cancellation to the process group, including during startup."""
+        if child is None:
+            pending_signals.append(signum)
+            return
+        try:
+            os.killpg(child.pid, signum)
+        except ProcessLookupError:
+            pass
+        except OSError as error:
+            _problem(record, f"Cannot forward signal {signum}: {error}")
+
+    previous_handlers = {}
+    try:
+        for signum in (signal.SIGTERM, signal.SIGINT, signal.SIGHUP):
+            previous_handlers[signum] = signal.signal(signum, forward)
+        environment = os.environ.copy()
+        environment.update(ZC_JOB_ID=job_id, ZC_RUN_ID=run_id)
+        try:
+            child = subprocess.Popen(
+                [shell, "-c", command],
+                stdin=None,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                env=environment,
+                start_new_session=True,
+                bufsize=0,
+            )
+        except OSError as error:
+            exit_code = 127 if isinstance(error, FileNotFoundError) else 126
+            record["status"] = "spawn_failed"
+            record["spawn_error"] = str(error)
+            _diagnostic(f"Cannot execute shell {shell!r}: {error}")
+        else:
+            record["child_pid"] = child.pid
+            for signum in pending_signals:
+                forward(signum, None)
+            _save(store, record)
+            streams[0].source = child.stdout
+            streams[1].source = child.stderr
+            returncode = _capture(child, streams, record)
+            record["returncode"] = returncode
+            record["signal"] = -returncode if returncode < 0 else None
+            record["status"] = "finished"
+            exit_code = 128 - returncode if returncode < 0 else returncode
+    finally:
+        for signum, handler in previous_handlers.items():
+            signal.signal(signum, handler)
+        for stream in streams:
+            stream.close_capture(record)
+    record["exit_code"] = exit_code
+    record["finished_at"] = _now()
+    record["duration_seconds"] = time.monotonic() - started
+    record["streams"] = {stream.name: stream.summary() for stream in streams}
+    if _save(store, record):
+        try:
+            store.prune()
+        except OSError as error:
+            _problem(record, f"Cannot prune completed runs: {error}")
+            _save(store, record)
+    return exit_code
+
+
+def _check_executable(executable: str, job: CronJob) -> None:
+    """Check a literal executable using only an explicit, absolute cron PATH."""
+    if not executable:
+        raise ValueError("SHELL must not be empty")
+    if os.path.isabs(executable):
+        found = shutil.which(executable)
+    else:
+        if "/" in executable:
+            raise ValueError(
+                f"Use an absolute executable path instead of {executable!r}"
+            )
+        path = job.environment.get("PATH")
+        if path is None or any(
+            not os.path.isabs(part) for part in path.split(os.pathsep)
+        ):
+            raise ValueError(
+                "Bare executable names require an explicit cron PATH containing only absolute directories"
+            )
+        found = shutil.which(executable, path=path)
+    if found is None:
+        raise ValueError(
+            f"Executable {executable!r} is missing or not executable by this user"
+        )
+
+
+def validate(filename: str | None = None) -> int:
+    """Validate a complete user crontab and executable availability without running jobs."""
+    try:
+        if filename is None:
+            result = subprocess.run(["crontab", "-l"], capture_output=True, check=False)
+            if result.returncode:
+                raise ValueError(
+                    f"crontab -l failed ({result.returncode}): {result.stderr.decode('utf-8', 'replace').strip()}"
+                )
+            text = result.stdout.decode("utf-8")
+        else:
+            text = Path(filename).read_bytes().decode("utf-8")
+        crontab = parse_crontab(text)
+    except (OSError, ValueError, ParseError) as error:
+        _diagnostic(str(error))
+        return 1
+    failed = False
+    for job in crontab.jobs:
+        for executable in (
+            job.wrapper_executable,
+            job.environment.get("SHELL", "/bin/sh"),
+        ):
+            try:
+                _check_executable(executable, job)
+            except (OSError, ValueError) as error:
+                _diagnostic(
+                    f"line {job.line_number}; job {job.job_id!r}, opened at line {job.declaration_line_number}: {error}"
+                )
+                failed = True
+    return 1 if failed else 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Dispatch the standard-library CLI and return an operating-system exit code."""
+    parser = argparse.ArgumentParser(prog="zabbix-crontroller")
+    commands = parser.add_subparsers(dest="action", required=True)
+    run = commands.add_parser(
+        "run", help="Run a quoted command and capture its evidence"
+    )
+    run.add_argument("job")
+    run.add_argument("command", nargs=argparse.REMAINDER, metavar="-- COMMAND")
+    check = commands.add_parser(
+        "validate", help="Validate a file or the current user's crontab"
+    )
+    check.add_argument("file", nargs="?")
+    raw_arguments = list(sys.argv[1:] if argv is None else argv)
+    arguments = parser.parse_args(raw_arguments)
+    if arguments.action == "validate":
+        return validate(arguments.file)
+    if (
+        len(raw_arguments) != 4
+        or raw_arguments[2] != "--"
+        or len(arguments.command) != 1
+    ):
+        parser.error("run requires JOB -- followed by exactly one quoted COMMAND")
+    if JOB_IDENTIFIER.fullmatch(arguments.job) is None:
+        parser.error("JOB must match [a-z][a-z0-9_-]*")
+    command = arguments.command[0]
+    if not command.strip() or "\x00" in command:
+        parser.error("COMMAND must be non-empty and contain no NUL bytes")
+    return run_job(arguments.job, command)
+
+
+if __name__ == "__main__":
+    sys.exit(main())