Skip to content

armgit / Pulse

Public Imported from GitHub
0

Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.

18.0 KB
Raw Blame
#!/usr/bin/env python3
"""Exercise private-file auth recipes with synthetic credentials, not Docker.

The recorders verify file permissions, argument boundaries and failure stops.
They do not establish native container startup or a password-change outcome.
"""

from __future__ import annotations

import json
import os
from pathlib import Path
import re
import stat
import subprocess
import tempfile
import unittest


ROOT = Path(__file__).resolve().parents[2]
GUIDES = (
    "CONFIGURATION.md",
    "INSTALL.md",
    "DOCKER.md",
    "i18n/de/README.md",
    "i18n/es/README.md",
    "i18n/fr/README.md",
)
HASH = "$2a$12$" + "a" * 53  # Synthetic file/argv sentinel, not a real password.
CONTENT = f"PULSE_AUTH_USER=admin\nPULSE_AUTH_PASS={HASH}\n"


def recipe(needle: str) -> str:
    text = (ROOT / "docs/CONFIGURATION.md").read_text(encoding="utf-8")
    matches = [block for block in re.findall(r"```bash\n(.*?)```", text, re.S)
               if needle in block]
    if len(matches) != 1:
        raise AssertionError(f"expected one configuration recipe containing {needle!r}")
    return matches[0]


EDITOR = '''#!/usr/bin/env python3
import json, os, stat, sys
from pathlib import Path
p = Path(sys.argv[1])
assert p == Path.home() / '.config/pulse/docker-auth.env'
assert stat.S_IMODE(p.stat().st_mode) == 0o600
assert stat.S_IMODE(p.parent.stat().st_mode) == 0o700
(Path.home() / 'editor.json').write_text(json.dumps(sys.argv[1:]))
sys.exit(int(os.environ.get('EDITOR_EXIT', '0')))
'''

DOCKER = '''#!/usr/bin/env python3
import json, os, stat, sys
from pathlib import Path
args = sys.argv[1:]
p = Path(args[args.index('--env-file') + 1])
assert p == Path.home() / '.config/pulse/docker-auth.env'
assert p.read_text() == os.environ['EXPECTED_FILE']
assert stat.S_IMODE(p.stat().st_mode) == 0o600
assert stat.S_IMODE(p.parent.stat().st_mode) == 0o700
assert os.environ['FIXTURE_HASH'] not in ' '.join(args)
assert not any(a.startswith('PULSE_AUTH_PASS=') for a in args)
(Path.home() / 'docker.json').write_text(json.dumps(args))
sys.exit(int(os.environ.get('DOCKER_EXIT', '0')))
'''


def environment(home: Path, **overrides: str) -> dict[str, str]:
    tools = home / "tools"
    tools.mkdir(exist_ok=True)
    for name, body in (("vi", EDITOR), ("docker", DOCKER)):
        script = tools / name
        script.write_text(body, encoding="utf-8")
        script.chmod(0o700)
    return {**os.environ, "HOME": str(home), "PATH": f"{tools}:{os.environ['PATH']}",
            "FIXTURE_HASH": HASH, "EXPECTED_FILE": CONTENT, **overrides}


def private_file(home: Path, content: str = CONTENT) -> Path:
    path = home / ".config/pulse/docker-auth.env"
    path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
    path.write_text(content, encoding="utf-8")
    path.chmod(0o600)
    return path


class ConfigurationAuthDocsTest(unittest.TestCase):
    def test_deployment_template_is_inert_and_has_no_seeded_credentials(self):
        text = (ROOT / ".env.example").read_text(encoding="utf-8")
        # Copying the reference must not install a shared password or override
        # existing authentication. Even commented credentials invite reuse.
        self.assertTrue(all(not line.strip() or line.lstrip().startswith("#")
                            for line in text.splitlines()))
        self.assertNotRegex(text, r"(?m)^#\s*(?:PULSE_AUTH_(?:USER|PASS)|API_TOKENS?)\s*=")
        self.assertNotIn("super-secret-password", text)
        for expected in ("Never overwrite an existing authentication file",
                         "Do not source it", "leave PULSE_AUTH_USER and PULSE_AUTH_PASS unset",
                         "API_TOKEN and API_TOKENS are ignored in v6",
                         "Settings > API Access", "complete bcrypt hash",
                         "does not remove a", "plaintext password from Docker's environment"):
            self.assertIn(expected, text)
        # The template sends readers to existing, source-verified recipes;
        # do not introduce a second credential-file or bootstrap procedure.
        for target in ("docs/INSTALL.md#step-1-get-the-token",
                       "docs/CONFIGURATION.md#private-docker-authentication-file",
                       "SECURITY.md#api-token-authentication"):
            self.assertIn(target, text)
            path, anchor = target.split("#")
            headings = re.findall(r"^#{1,6}\s+(.+?)\s*$",
                                  (ROOT / path).read_text(encoding="utf-8"), re.M)
            slugs = {re.sub(r"[^\w\s-]", "", heading.lower()).strip().replace(" ", "-")
                     for heading in headings}
            self.assertIn(anchor, slugs)

    def test_deployment_template_distinguishes_compose_from_runtime_settings(self):
        text = (ROOT / ".env.example").read_text(encoding="utf-8")
        compose = (ROOT / "docker-compose.yml").read_text(encoding="utf-8")
        interpolation = text.split("# Compose interpolation", 1)[1].split(
            "# Pulse runtime settings", 1)[0]
        examples = set(re.findall(r"(?m)^#\s*([A-Z][A-Z0-9_]*)=", interpolation))
        # Tie the documented selectors to the actual bundled Compose file,
        # rather than implying every .env key reaches the Pulse process.
        consumed = set(re.findall(r"\$\{([A-Z][A-Z0-9_]*)(?::-[^}]*)?\}", compose))
        self.assertEqual(examples, consumed)
        for expected in ("interpolation, not the container's", "does not pass them to Pulse",
                         "not automatically forwarded by Compose", "data directory",
                         "/etc/pulse", "/data inside a container", "PULSE_DATA_DIR",
                         "Deployment-supplied environment values take precedence",
                         "not a Compose interpolation"):
            self.assertIn(expected, text)

    def test_no_shared_password_or_secret_in_command_arguments(self):
        for name in GUIDES:
            with self.subTest(guide=name):
                text = (ROOT / "docs" / name).read_text(encoding="utf-8")
                self.assertNotIn("secret123", text)
                shell = "\n".join(re.findall(r"```bash\n(.*?)```", text, re.S))
                self.assertNotRegex(shell, r"(?:-e|--env)\s+PULSE_AUTH_(?:PASS|USER)=")
                self.assertNotRegex(shell, r"\b(?:export\s+)?PULSE_AUTH_PASS=")
                if name != "CONFIGURATION.md":
                    self.assertNotRegex(text, r"PULSE_AUTH_PASS\s*[:=]")

    def test_mirrors_and_sensitive_runtime_limit(self):
        for name in GUIDES:
            self.assertEqual((ROOT / "docs" / name).read_bytes(),
                             (ROOT / "frontend-modern/public/docs" / name).read_bytes())
        text = (ROOT / "docs/CONFIGURATION.md").read_text(encoding="utf-8")
        for expected in ("not out of Docker's", "does not scrub its original value",
                         "Do not source the file", "Deployment-supplied environment values take precedence",
                         "complete bcrypt hash", "unquoted", "no `$$` substitution",
                         "this new-container example is not an upgrade procedure"):
            self.assertIn(expected, text)

    def test_install_quick_start_preserves_data_and_bootstrap_route(self):
        text = (ROOT / "docs/INSTALL.md").read_text(encoding="utf-8")
        compose = next(block for block in re.findall(r"```yaml\n(.*?)```", text, re.S)
                       if "services:" in block)
        for expected in ("image: ${PULSE_IMAGE:-rcourtman/pulse:vX.Y.Z}",
                         "pulse_data:/data", "PULSE_DEPLOYMENT_METHOD=docker_compose"):
            self.assertIn(expected, compose)
        self.assertNotRegex(compose, r"PULSE_AUTH_(?:USER|PASS)")
        for expected in ("[bootstrap-token setup](#step-1-get-the-token)",
                         "[authentication guide](CONFIGURATION.md#private-docker-authentication-file)",
                         "Leave authentication overrides unset for a new install",
                         "not a Compose interpolation recipe", "do not reset authentication",
                         "deployment-supplied password takes precedence"):
            self.assertIn(expected, text)

    def test_preparation_preserves_existing_file_and_protects_both_paths(self):
        for existing in (False, True):
            with self.subTest(existing=existing), tempfile.TemporaryDirectory(prefix="auth docs ") as temp:
                home = Path(temp)
                path = home / ".config/pulse/docker-auth.env"
                if existing:
                    private_file(home)
                    path.chmod(0o644)
                    path.parent.chmod(0o755)
                result = subprocess.run(["bash", "-c", recipe('vi "$auth_file"')],
                                        env=environment(home), capture_output=True, timeout=10)
                self.assertEqual(result.returncode, 0, result.stderr.decode())
                self.assertEqual(stat.S_IMODE(path.stat().st_mode), 0o600)
                self.assertEqual(stat.S_IMODE(path.parent.stat().st_mode), 0o700)
                self.assertEqual(path.read_text(), CONTENT if existing else "")
                self.assertEqual(json.loads((home / "editor.json").read_text()), [str(path)])
                self.assertNotIn(HASH.encode(), result.stdout + result.stderr)

    def test_preparation_refuses_symlink_without_touching_target(self):
        for linked in ("file", "directory"):
            with self.subTest(linked=linked), tempfile.TemporaryDirectory(prefix="auth docs ") as temp:
                home = Path(temp)
                target = home / "retained"
                target.mkdir()
                credential = target / "docker-auth.env"
                credential.write_text(CONTENT)
                credential.chmod(0o644)
                directory = home / ".config/pulse"
                directory.parent.mkdir()
                if linked == "directory":
                    directory.symlink_to(target, target_is_directory=True)
                else:
                    directory.mkdir()
                    (directory / "docker-auth.env").symlink_to(credential)
                result = subprocess.run(["bash", "-c", recipe('vi "$auth_file"')],
                                        env=environment(home), capture_output=True, timeout=10)
                self.assertNotEqual(result.returncode, 0)
                self.assertIn(b"Refusing a symlinked credential path", result.stderr)
                self.assertEqual(credential.read_text(), CONTENT)
                self.assertEqual(stat.S_IMODE(credential.stat().st_mode), 0o644)
                self.assertFalse((home / "editor.json").exists())

    def test_editor_failure_is_not_reported_as_preparation_success(self):
        with tempfile.TemporaryDirectory(prefix="auth docs ") as temp:
            home = Path(temp)
            path = private_file(home)
            result = subprocess.run(["bash", "-c", recipe('vi "$auth_file"')],
                                    env=environment(home, EDITOR_EXIT="23"), capture_output=True, timeout=10)
            self.assertEqual(result.returncode, 23)
            self.assertEqual(path.read_text(), CONTENT)

    def test_both_steps_reject_unsafe_paths_before_any_operation(self):
        for needle in ('vi "$auth_file"', "docker run -d"):
            for placement in (".config", ".config/pulse", ".config/pulse/docker-auth.env"):
                for kind in ("symlink", "dangling-symlink", "fifo", "wrong-type"):
                    with self.subTest(recipe=needle, path=placement, kind=kind), \
                            tempfile.TemporaryDirectory(prefix="auth paths ") as temp:
                        home = Path(temp)
                        path = home / placement
                        path.parent.mkdir(parents=True, exist_ok=True)
                        outside = home / "untouched"
                        outside.mkdir(mode=0o755)
                        witness = outside / "docker-auth.env"
                        witness.write_text(CONTENT)
                        witness.chmod(0o644)
                        before = (witness.stat(), outside.stat())
                        file_path = placement.endswith(".env")
                        if kind == "symlink":
                            path.symlink_to(witness if file_path else outside)
                        elif kind == "dangling-symlink":
                            path.symlink_to(home / "must-not-be-created")
                        elif kind == "fifo":
                            os.mkfifo(path)
                        elif file_path:
                            path.mkdir()
                        else:
                            path.write_text("not a directory")
                        original = path.lstat()
                        tools = home / "tools"
                        tools.mkdir()
                        receipt = home / "operation-called"
                        for name in ("mkdir", "chmod", "touch", "vi", "docker"):
                            tool = tools / name
                            tool.write_text('#!/bin/sh\nprintf called >> "$OPERATION_RECEIPT"\nexit 23\n')
                            tool.chmod(0o700)
                        env = {**os.environ, "HOME": str(home),
                               "PATH": f"{tools}:{os.environ['PATH']}",
                               "OPERATION_RECEIPT": str(receipt)}
                        result = subprocess.run(["bash", "-c", recipe(needle)],
                                                env=env, capture_output=True, timeout=10)
                        self.assertNotEqual(result.returncode, 0)
                        self.assertFalse(receipt.exists(), "must stop before mutation, editor or Docker")
                        self.assertEqual(path.lstat(), original)
                        self.assertEqual((witness.stat(), outside.stat()), before)
                        self.assertEqual(witness.read_text(), CONTENT)
                        self.assertFalse((home / "must-not-be-created").exists())
                        self.assertNotIn(HASH.encode(), result.stdout + result.stderr)

    def test_preparation_command_failures_stop_before_editor(self):
        for failed in ("mkdir", "chmod", "touch"):
            with self.subTest(failed=failed), tempfile.TemporaryDirectory() as temp:
                home = Path(temp)
                env = environment(home)
                tool = home / "tools" / failed
                tool.write_text('#!/bin/sh\nexit 23\n')
                tool.chmod(0o700)
                result = subprocess.run(["bash", "-c", recipe('vi "$auth_file"')],
                                        env=env, capture_output=True, timeout=10)
                self.assertEqual(result.returncode, 23)
                self.assertFalse((home / "editor.json").exists())

    def test_launch_protects_existing_file_and_stops_on_permission_failure(self):
        for fail in (False, True):
            with self.subTest(fail=fail), tempfile.TemporaryDirectory() as temp:
                home = Path(temp)
                path = private_file(home)
                path.chmod(0o644)
                path.parent.chmod(0o755)
                env = environment(home)
                if fail:
                    tool = home / "tools/chmod"
                    tool.write_text('#!/bin/sh\nexit 23\n')
                    tool.chmod(0o700)
                result = subprocess.run(["bash", "-c", recipe("docker run -d")],
                                        env=env, capture_output=True, timeout=10)
                self.assertEqual(result.returncode, 23 if fail else 0, result.stderr.decode())
                self.assertEqual((home / "docker.json").exists(), not fail)
                self.assertEqual(path.read_text(), CONTENT)
                self.assertEqual(stat.S_IMODE(path.stat().st_mode), 0o644 if fail else 0o600)
                self.assertEqual(stat.S_IMODE(path.parent.stat().st_mode), 0o755 if fail else 0o700)
                self.assertNotIn(HASH.encode(), result.stdout + result.stderr)

    def test_launch_passes_only_private_path_and_preserves_hash_bytes(self):
        with tempfile.TemporaryDirectory(prefix="auth docs ") as temp:
            home = Path(temp)
            path = private_file(home)
            result = subprocess.run(["bash", "-c", recipe("docker run -d")],
                                    env=environment(home), capture_output=True, timeout=10)
            self.assertEqual(result.returncode, 0, result.stderr.decode())
            argv = json.loads((home / "docker.json").read_text())
            self.assertEqual(argv, ["run", "-d", "--name", "pulse", "-p", "7655:7655",
                                   "-v", "pulse_data:/data", "--env-file", str(path), "-e",
                                   "PULSE_DEPLOYMENT_METHOD=docker_run", "--restart", "unless-stopped",
                                   "rcourtman/pulse:vX.Y.Z"])
            self.assertNotIn(HASH, json.dumps(argv))
            self.assertNotIn(HASH.encode(), result.stdout + result.stderr)
            self.assertEqual(path.read_text(), CONTENT)

    def test_absent_or_empty_file_prevents_docker_start(self):
        for empty in (False, True):
            with self.subTest(empty=empty), tempfile.TemporaryDirectory(prefix="auth docs ") as temp:
                home = Path(temp)
                if empty:
                    private_file(home, "")
                result = subprocess.run(["bash", "-c", recipe("docker run -d")],
                                        env=environment(home), capture_output=True, timeout=10)
                self.assertNotEqual(result.returncode, 0)
                self.assertIn(b"Prepare the private authentication file first", result.stderr)
                self.assertFalse((home / "docker.json").exists())

    def test_docker_failure_remains_failed(self):
        with tempfile.TemporaryDirectory(prefix="auth docs ") as temp:
            home = Path(temp)
            path = private_file(home)
            result = subprocess.run(["bash", "-c", recipe("docker run -d")],
                                    env=environment(home, DOCKER_EXIT="31"), capture_output=True, timeout=10)
            self.assertEqual(result.returncode, 31)
            self.assertEqual(path.read_text(), CONTENT)


if __name__ == "__main__":
    unittest.main()