refactor(backup)!: run argv lists, never a shell

The backup built command strings and handed them to shell=True, so four interpolated values per dump - user, password, container, database - were each a way out of the command. validate_database covered one of them since the previous commit; now there is nothing to cover: every command is an argv list, and a value can only ever be an argument.

execute_to_file absorbs the atomic dump write. The shell redirect into <file>.tmp and the separate mv process become a Python file handle and os.replace, and a failing dump deletes its partial file instead of leaving it. PGPASSWORD moves out of the command string into the child's environment, where a process listing does not show it.

docker exec is built in one place, docker_exec_argv; db.py's three hand-built copies and the probe use it. The dead docker_volume_exists goes - never called, and the restore side owns the living twin. The rsync quoting in --link-dest falls away: inside an argv it would have become part of the path.

The snapshot module's injected runner changes type with it, which the three e2e drivers implement - the first conversion missed them, btrfs ran with no arguments, and the e2e caught it. Marked breaking for that contract: any external runner injected into volume_snapshot must now accept a list.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

tests/unit/backup/test_db_mariadb_dump.py

@@ -13,16 +13,16 @@ def _df(rows):
     )
 
 
-def _capture_commands(*, db_type, rows, container, dump_tool="mariadb-dump"):
+def _capture_dumps(*, db_type, rows, container, dump_tool="mariadb-dump"):
+    """Every (argv, env) the dump path would have run."""
     captured = []
 
-    def _capture(cmd):
-        captured.append(cmd)
-        return []
+    def _capture(command, out_file, *, env=None):
+        captured.append((list(command), env))
 
     with (
         tempfile.TemporaryDirectory() as td,
-        patch.object(db_mod, "execute_shell_command", side_effect=_capture),
+        patch.object(db_mod, "execute_to_file", side_effect=_capture),
     ):
         db_mod.backup_database(
             container=container,
@@ -41,45 +41,64 @@ class TestMariaDBDumpUsesTCP(unittest.TestCase):
     # the connection is auth-matched against '%' instead of socket->localhost.
 
     def test_mariadb_dump_forces_tcp_loopback(self):
-        captured = _capture_commands(
+        captured = _capture_dumps(
             db_type="mariadb",
             rows=[("mariadb", "appdb", "appuser", "s3cret")],
             container="mariadb",
         )
-        dump_cmds = [c for c in captured if "mariadb-dump" in c]
-        self.assertEqual(
-            len(dump_cmds), 1, f"expected one dump command, got: {captured}"
-        )
+        self.assertEqual(len(captured), 1, f"expected one dump, got: {captured}")
 
-        cmd = dump_cmds[0]
-        self.assertIn("-h 127.0.0.1", cmd)
-        self.assertIn("--protocol=tcp", cmd)
-        self.assertIn("-u appuser", cmd)
-        self.assertIn("-ps3cret", cmd)
-        self.assertIn(" appdb", cmd)
+        argv, env = captured[0]
+        self.assertEqual(argv[:3], ["docker", "exec", "mariadb"])
+        self.assertIn("--protocol=tcp", argv)
+        self.assertEqual(argv[argv.index("-h") + 1], "127.0.0.1")
+        self.assertEqual(argv[argv.index("-u") + 1], "appuser")
+        self.assertIn("-ps3cret", argv)
+        self.assertEqual(argv[-1], "appdb")
+        self.assertIsNone(env)
 
     def test_the_probed_client_is_the_one_invoked(self):
-        captured = _capture_commands(
+        captured = _capture_dumps(
             db_type="mariadb",
             rows=[("mariadb", "appdb", "appuser", "s3cret")],
             container="mariadb",
             dump_tool="mysqldump",
         )
-        dump_cmds = [c for c in captured if "mysqldump" in c]
-        self.assertEqual(
-            len(dump_cmds), 1, f"expected one dump command, got: {captured}"
-        )
-        self.assertNotIn("mariadb-dump", dump_cmds[0])
+        argv, _env = captured[0]
+        self.assertIn("mysqldump", argv)
+        self.assertNotIn("mariadb-dump", argv)
 
     def test_postgres_dump_unaffected(self):
-        captured = _capture_commands(
+        captured = _capture_dumps(
             db_type="postgres",
             rows=[("pg", "appdb", "appuser", "s3cret")],
             container="pg",
         )
-        dump_cmds = [c for c in captured if "pg_dump" in c and "pg_dumpall" not in c]
-        self.assertEqual(len(dump_cmds), 1)
-        self.assertNotIn("--protocol=tcp", dump_cmds[0])
+        argv, _env = captured[0]
+        self.assertIn("pg_dump", argv)
+        self.assertNotIn("--protocol=tcp", argv)
+
+    def test_the_password_travels_in_the_environment_not_the_argv(self):
+        """A process listing shows argv; PGPASSWORD must not be in it."""
+        captured = _capture_dumps(
+            db_type="postgres",
+            rows=[("pg", "appdb", "appuser", "s3cret")],
+            container="pg",
+        )
+        argv, env = captured[0]
+        self.assertEqual(env, {"PGPASSWORD": "s3cret"})
+        self.assertNotIn("s3cret", argv)
+
+
+class TestNoShellReachesTheDump(unittest.TestCase):
+    def test_a_hostile_database_name_never_reaches_a_command(self):
+        """validate_database refuses it, so no argv is built at all."""
+        with self.assertRaises(ValueError):
+            _capture_dumps(
+                db_type="postgres",
+                rows=[("pg", "app;rm -rf /", "appuser", "s3cret")],
+                container="pg",
+            )
 
 
 if __name__ == "__main__":

tests/unit/backup/test_docker_tool_probe.py

@@ -35,7 +35,9 @@ class TestHasTool(unittest.TestCase):
         with patch.object(docker_mod, "execute_shell_command", side_effect=_capture):
             docker_mod.has_tool("c1", "pg_dumpall")
 
-        self.assertEqual(captured, ["docker exec c1 pg_dumpall --version"])
+        self.assertEqual(
+            captured, [["docker", "exec", "c1", "pg_dumpall", "--version"]]
+        )
 
 
 if __name__ == "__main__":

tests/unit/backup/test_snapshot.py

@@ -10,13 +10,13 @@ from baudolo.backup.snapshot import SnapshotError, volume_snapshot
 
 class Runner:
     def __init__(self, replies: dict[str, list[str]] | None = None) -> None:
-        self.calls: list[str] = []
+        self.calls: list[list[str]] = []
         self.replies = replies or {}
 
-    def __call__(self, command: str) -> list[str]:
-        self.calls.append(command)
+    def __call__(self, command: list[str]) -> list[str]:
+        self.calls.append(list(command))
         for prefix, reply in self.replies.items():
-            if command.startswith(prefix):
+            if " ".join(command).startswith(prefix):
                 return reply
         return []
 
@@ -28,7 +28,14 @@ class TestBtrfs(unittest.TestCase):
             pass
         self.assertEqual(
             run.calls[0],
-            "btrfs subvolume snapshot -r /var/lib/docker /var/lib/docker/.baudolo-20260731",
+            [
+                "btrfs",
+                "subvolume",
+                "snapshot",
+                "-r",
+                "/var/lib/docker",
+                "/var/lib/docker/.baudolo-20260731",
+            ],
         )
 
     def test_it_removes_the_snapshot_afterwards(self) -> None:
@@ -36,7 +43,8 @@ class TestBtrfs(unittest.TestCase):
         with volume_snapshot("btrfs", "/var/lib/docker", "20260731", run=run):
             pass
         self.assertEqual(
-            run.calls[-1], "btrfs subvolume delete /var/lib/docker/.baudolo-20260731"
+            run.calls[-1],
+            ["btrfs", "subvolume", "delete", "/var/lib/docker/.baudolo-20260731"],
         )
 
     def test_it_maps_a_volume_path_into_the_snapshot(self) -> None:
@@ -66,7 +74,7 @@ class TestBtrfs(unittest.TestCase):
             volume_snapshot("btrfs", "/var/lib/docker", "20260731", run=run),
         ):
             raise ZeroDivisionError
-        self.assertTrue(run.calls[-1].startswith("btrfs subvolume delete"))
+        self.assertEqual(run.calls[-1][:3], ["btrfs", "subvolume", "delete"])
 
 
 class TestZfs(unittest.TestCase):
@@ -77,13 +85,15 @@ class TestZfs(unittest.TestCase):
         run = self._run()
         with volume_snapshot("zfs", "/var/lib/docker", "20260731", run=run):
             pass
-        self.assertIn("zfs snapshot tank/docker@baudolo-20260731", run.calls)
+        self.assertIn(["zfs", "snapshot", "tank/docker@baudolo-20260731"], run.calls)
 
     def test_it_destroys_the_snapshot_afterwards(self) -> None:
         run = self._run()
         with volume_snapshot("zfs", "/var/lib/docker", "20260731", run=run):
             pass
-        self.assertEqual(run.calls[-1], "zfs destroy tank/docker@baudolo-20260731")
+        self.assertEqual(
+            run.calls[-1], ["zfs", "destroy", "tank/docker@baudolo-20260731"]
+        )
 
     def test_it_maps_a_volume_path_through_the_dot_zfs_directory(self) -> None:
         run = self._run()
@@ -131,8 +141,8 @@ class TestRejections(unittest.TestCase):
 
 
 class Busy(Runner):
-    def __call__(self, command: str) -> list[str]:
-        if command.startswith("btrfs subvolume delete"):
+    def __call__(self, command: list[str]) -> list[str]:
+        if command[:3] == ["btrfs", "subvolume", "delete"]:
             raise BackupException("target is busy")
         return super().__call__(command)
 

tests/unit/backup/test_volume.py

@@ -48,7 +48,7 @@ class TestBackupVolume(unittest.TestCase):
 
     def test_it_keeps_no_twin_of_what_the_second_pass_replaces(self) -> None:
         command = self.copy(authoritative=True)
-        self.assertIn("rsync -aP ", command)
+        self.assertEqual(command[:2], ["rsync", "-aP"])
         self.assertNotIn("--backup", command)
 
     def test_it_creates_the_destination(self) -> None: