"""Committed tests for the bash tool (stdlib unittest, offline, no network).
Covers the BashTools engine directly against a tmp-root FileState:
real exit codes, separate streams, stdin, env masking (stored and
streamed), truncation markers, timeout group kills, and the sandbox
boundary with and without yolo.
"""
# retoor <retoor@molodetz.nl>
import os
import sys
import tempfile
import time
import unittest
from blackcat.fstate import FileState
from blackcat.tools import BashTools
class EngineCase(unittest.IsolatedAsyncioTestCase):
def setUp(self):
self.tmp = tempfile.TemporaryDirectory()
self.addCleanup(self.tmp.cleanup)
self.root = os.path.join(self.tmp.name, "ws")
os.mkdir(self.root)
self.state = FileState(self.root)
self.bash = BashTools(self.state)
class TestRun(EngineCase):
async def test_stdout_stderr_exit_code(self):
out = await self.bash.run("printf out; printf err >&2")
self.assertTrue(out["ok"])
self.assertEqual(out["exit_code"], 0)
self.assertEqual(out["code"], "ok")
self.assertEqual(out["stdout"], "out")
self.assertEqual(out["stderr"], "err")
self.assertFalse(out["timed_out"])
self.assertFalse(out["truncated"])
self.assertEqual(out["stdout_bytes"], 3)
self.assertEqual(out["stderr_bytes"], 3)
self.assertEqual(out["cwd"], self.state.root)
self.assertEqual(out["redactions"], [])
async def test_nonzero_exit_is_data(self):
out = await self.bash.run("echo failing >&2; exit 3")
self.assertFalse(out["ok"])
self.assertEqual(out["exit_code"], 3)
self.assertEqual(out["code"], "nonzero_exit")
self.assertEqual(out["stderr"], "failing\n")
async def test_empty_command_refused(self):
for command in ("", " "):
out = await self.bash.run(command)
self.assertFalse(out["ok"])
self.assertEqual(out["code"], "bad_args")
async def test_unknown_shell_refused(self):
out = await self.bash.run("echo hi", shell="zsh")
self.assertFalse(out["ok"])
self.assertEqual(out["code"], "bad_args")
async def test_sh_shell(self):
out = await self.bash.run("echo hi", shell="sh")
self.assertTrue(out["ok"])
self.assertEqual(out["stdout"], "hi\n")
async def test_none_shell_splits_argv(self):
out = await self.bash.run("echo hi", shell="none")
self.assertTrue(out["ok"])
self.assertEqual(out["stdout"], "hi\n")
async def test_none_shell_missing_binary_is_io(self):
out = await self.bash.run("blackcat-no-such-bin-xyz", shell="none")
self.assertFalse(out["ok"])
self.assertEqual(out["code"], "io")
async def test_missing_binary_reports_nonzero(self):
out = await self.bash.run("blackcat-no-such-bin-xyz")
self.assertFalse(out["ok"])
self.assertNotEqual(out["exit_code"], 0)
async def test_stdin_piped_then_closed(self):
out = await self.bash.run("cat", stdin="hello in")
self.assertTrue(out["ok"])
self.assertEqual(out["stdout"], "hello in")
async def test_heredoc_and_quoting_survive(self):
out = await self.bash.run("cat <<'EOF'\nline $HOME `tick`\nEOF")
self.assertTrue(out["ok"])
self.assertEqual(out["stdout"], "line $HOME `tick`\n")
async def test_bad_env_and_stdin_types(self):
self.assertEqual(
(await self.bash.run("echo hi", env="nope"))["code"], "bad_args")
self.assertEqual(
(await self.bash.run("echo hi", env={"ok": 1}))["code"], "bad_args")
self.assertEqual(
(await self.bash.run("cat", stdin=123))["code"], "bad_args")
self.assertEqual(
(await self.bash.run("echo hi", timeout_ms="soon"))["code"],
"bad_args")
class TestSandbox(EngineCase):
async def test_cwd_inside_root(self):
os.mkdir(os.path.join(self.root, "sub"))
out = await self.bash.run("pwd", cwd="sub")
self.assertTrue(out["ok"])
self.assertTrue(out["stdout"].rstrip("\n").endswith("/sub"))
self.assertEqual(
out["cwd"], os.path.join(self.state.root, "sub"))
async def test_cwd_escape_refused(self):
for cwd in ("/tmp", "../..", "/etc"):
out = await self.bash.run("pwd", cwd=cwd)
self.assertFalse(out["ok"], cwd)
self.assertEqual(out["code"], "security", cwd)
async def test_cwd_symlink_out_refused(self):
os.symlink("/tmp", os.path.join(self.root, "link"))
out = await self.bash.run("pwd", cwd="link")
self.assertFalse(out["ok"])
self.assertEqual(out["code"], "security")
async def test_unsandboxed_runs_anywhere(self):
free = BashTools(FileState(self.root, sandbox=False))
out = await free.run("pwd", cwd="/tmp")
self.assertTrue(out["ok"])
self.assertEqual(out["cwd"], "/tmp")
async def test_read_only_session_refuses(self):
read_only = BashTools(FileState(self.root, write=False))
out = await read_only.run("echo hi")
self.assertFalse(out["ok"])
self.assertEqual(out["code"], "security")
async def test_missing_cwd_is_io(self):
out = await self.bash.run("echo hi", cwd="nope-dir")
self.assertFalse(out["ok"])
self.assertEqual(out["code"], "io")
class TestLimits(EngineCase):
async def test_truncation_is_announced(self):
program = "print('y' * 100000)"
out = await self.bash.run(sys.executable + " -c %r" % program,
shell="none", max_output_bytes=2048)
self.assertTrue(out["ok"])
self.assertTrue(out["truncated"])
self.assertGreaterEqual(out["stdout_bytes"], 100000)
self.assertLessEqual(len(out["stdout"].encode("utf-8")), 2052)
async def test_no_truncation_marker_on_small_output(self):
out = await self.bash.run("echo hi", max_output_bytes=1024)
self.assertFalse(out["truncated"])
self.assertEqual(out["stdout"], "hi\n")
async def test_timeout_reports_and_kills(self):
started = time.monotonic()
out = await self.bash.run("sleep 30", timeout_ms=1000)
elapsed = time.monotonic() - started
self.assertFalse(out["ok"])
self.assertTrue(out["timed_out"])
self.assertEqual(out["code"], "timed_out")
self.assertIn("SIGTERM", out["error"])
self.assertLess(elapsed, 12)
async def test_timeout_kills_the_group(self):
marker = os.path.join(self.root, "marker.txt")
out = await self.bash.run(
"(sleep 2; touch marker.txt) & wait", timeout_ms=1000)
self.assertTrue(out["timed_out"])
time.sleep(2.5)
self.assertFalse(os.path.exists(marker))
class TestSecrets(EngineCase):
async def test_env_values_masked_in_result(self):
secret = "hunter2-secret-value"
out = await self.bash.run(
"echo $BLACKCAT_TEST_SECRET",
env={"BLACKCAT_TEST_SECRET": secret})
self.assertTrue(out["ok"])
self.assertIn("***", out["stdout"])
self.assertNotIn(secret, out["stdout"])
self.assertNotIn(secret, out["stderr"])
self.assertEqual(out["redactions"], ["BLACKCAT_TEST_SECRET"])
async def test_env_values_masked_in_stream(self):
secret = "stream-secret-value-xyz"
chunks: list[str] = []
out = await self.bash.run(
"echo before; echo $BLACKCAT_TEST_SECRET; echo after",
env={"BLACKCAT_TEST_SECRET": secret},
on_chunk=lambda stream, text: chunks.append(text))
self.assertTrue(out["ok"])
streamed = "".join(chunks)
self.assertIn("before", streamed)
self.assertIn("***", streamed)
self.assertNotIn(secret, streamed)
async def test_env_values_masked_across_splits(self):
secret = "split-secret-value-0123456789abcdef"
program = ("import os, time; [ (print(end=c, flush=True), "
"time.sleep(0.005)) "
"for c in os.environ['BLACKCAT_SPLIT'] ]")
chunks: list[str] = []
out = await self.bash.run(
sys.executable + " -c %r" % program, shell="none",
env={"BLACKCAT_SPLIT": secret},
on_chunk=lambda stream, text: chunks.append(text))
self.assertTrue(out["ok"])
streamed = "".join(chunks)
self.assertNotIn(secret, streamed)
for width in range(4, len(secret)):
self.assertNotIn(secret[:width], streamed.replace("*", ""))
self.assertIn("*", streamed)
class TestStreaming(EngineCase):
async def test_chunks_arrive_with_content(self):
chunks: list[tuple[str, str]] = []
out = await self.bash.run(
"for i in 1 2 3; do echo line$i; sleep 0.2; done",
on_chunk=lambda stream, text: chunks.append((stream, text)))
self.assertTrue(out["ok"])
self.assertEqual(out["stdout"], "line1\nline2\nline3\n")
self.assertGreaterEqual(len(chunks), 1)
self.assertEqual(
"".join(text for _stream, text in chunks), out["stdout"])
self.assertTrue(
all(stream == "stdout" for stream, _text in chunks))
async def test_first_chunk_arrives_long_before_exit(self):
moments: list[float] = []
start = time.monotonic()
out = await self.bash.run(
"echo first; sleep 0.6; echo last",
on_chunk=lambda stream, text: moments.append(
time.monotonic() - start))
end = time.monotonic() - start
self.assertTrue(out["ok"])
self.assertTrue(moments)
self.assertLess(moments[0], end - 0.3)
async def test_exploding_chunk_handler_cannot_break_run(self):
def _boom(stream: str, text: str) -> None:
raise RuntimeError("listener blew up")
out = await self.bash.run("echo hi", on_chunk=_boom)
self.assertTrue(out["ok"])
self.assertEqual(out["stdout"], "hi\n")
if __name__ == "__main__":
unittest.main()