diff --git a/.github/workflows/shipped-image.yml b/.github/workflows/shipped-image.yml new file mode 100644 index 0000000..372bb03 --- /dev/null +++ b/.github/workflows/shipped-image.yml @@ -0,0 +1,111 @@ +# The shipped team-server image, built and started. +# +# This file exists because of a measurement, not a policy. The first time +# anyone built `software/c2/Dockerfile` on a machine that was not the one +# it was written on, it failed six different ways. Four of those failures +# hit every architecture, and they had been there long enough that the +# image's own base had changed Debian release underneath it. Nothing in +# this repository ever built it, so nothing ever said so. +# +# A separate workflow rather than a job inside ci.yml, deliberately: this +# guards one artefact, it is the only thing that needs Docker and a long +# apt step, and a reader looking at a red run should be able to tell from +# the name alone that the image is what broke. +# +# It builds AND starts. Defect 5 built cleanly and then died at import +# with "No module named 'software'", so a job that stopped at a green +# build would have reported success over an image that could not run. +# That is the whole reason for the second step. +name: Shipped image + +on: + push: + branches: ["**"] + paths: + - "software/c2/Dockerfile" + - "software/c2/docker-compose.yml" + - "software/c2/docker-entrypoint.sh" + - "software/c2/server.py" + - "software/c2/beacon.py" + - ".github/workflows/shipped-image.yml" + pull_request: + workflow_dispatch: + +permissions: + contents: read + +jobs: + image: + name: build and start (docker, linux) + runs-on: ubuntu-latest + # The apt step alone pulls ~140 MB and the NetExec install compiles, + # so this is not a two-minute job. Measured locally at 8-14 minutes + # from a cold cache. + timeout-minutes: 40 + steps: + - uses: actions/checkout@v4 + + - name: What docker is here + run: | + docker --version + echo "runner arch: $(uname -m)" + + # The context is the repository root, because the image needs the + # software/ package: server.py imports software.c2.listeners and + # software.c2.stagers. Building with a context of software/c2 is + # exactly what made the image unable to start. + - name: Build software/c2/Dockerfile + run: | + docker build \ + -f software/c2/Dockerfile \ + -t raccoon-c2:ci \ + . + + # Not a smoke test of the entrypoint: this runs the module the way + # the entrypoint runs it, so every top-level import in server.py is + # executed. --help returns 0 and exits, which is all that is needed + # to prove the imports resolve inside the image. + - name: The server starts inside the image + run: | + docker run --rm --entrypoint python3 raccoon-c2:ci \ + -m software.c2.server --help > /tmp/help.txt + echo "--- first lines of --help:" + head -5 /tmp/help.txt + grep -q -- "--operator-port" /tmp/help.txt + + # Reported, not asserted. Which tools resolve depends on the + # runner's architecture -- NetExec has no aarch64 wheel and is + # allowed to be absent -- so this prints the truth rather than + # demanding a particular answer. The entrypoint's banner is built + # the same way for the same reason. + - name: What the image actually carries + run: | + docker run --rm --entrypoint sh raccoon-c2:ci -c ' + for t in nmap xfreerdp xfreerdp3 vncviewer responder \ + relayking nxc secretsdump.py; do + if command -v "$t" >/dev/null 2>&1; then + printf " %-18s %s\n" "$t" "$(command -v "$t")" + else + printf " %-18s absent\n" "$t" + fi + done + python3 - </dev/null` on the pip call hid which of the two branches had run. RUN git clone --depth 1 https://github.com/depthsecurity/RelayKing-Depth.git /opt/RelayKing \ && cd /opt/RelayKing && pip install --no-cache-dir -e . 2>/dev/null \ || pip install --no-cache-dir -r /opt/RelayKing/requirements.txt \ - && ln -s /opt/RelayKing/relayking.py /usr/local/bin/relayking \ + && ln -sf /opt/RelayKing/relayking.py /usr/local/bin/relayking \ && chmod +x /opt/RelayKing/relayking.py WORKDIR /opt/raccoon-c2 -COPY server.py . -COPY beacon.py . -COPY __init__.py . +# The whole package, not three flat files. +# +# This used to be `COPY server.py .` and two siblings, while server.py +# imports `software.c2.listeners` and `software.c2.stagers`. The image +# built and then died at start-up with "No module named 'software'" -- so +# the shipped team server could not run at all, on any architecture. The +# build context is the repository root (see docker-compose.yml), which is +# what the listener image already used. +COPY software/__init__.py ./software/ +COPY software/c2/ ./software/c2/ +ENV PYTHONPATH=/opt/raccoon-c2 RUN mkdir -p /data/raccoon-c2 @@ -52,7 +90,7 @@ EXPOSE 8443 VOLUME ["/data/raccoon-c2"] -COPY docker-entrypoint.sh /entrypoint.sh +COPY software/c2/docker-entrypoint.sh /entrypoint.sh RUN chmod +x /entrypoint.sh ENTRYPOINT ["/entrypoint.sh"] diff --git a/software/c2/docker-compose.yml b/software/c2/docker-compose.yml index 8fad57d..4a2a56f 100644 --- a/software/c2/docker-compose.yml +++ b/software/c2/docker-compose.yml @@ -1,6 +1,14 @@ services: raccoon-c2: - build: . + build: + # The repository root, because the image needs the `software/` + # package: server.py imports `software.c2.listeners` and + # `software.c2.stagers`, and a context of this directory cannot + # COPY them. With the old context the image built and then died at + # start-up with "No module named 'software'". The listener service + # below has always used this context for the same reason. + context: ../.. + dockerfile: software/c2/Dockerfile container_name: raccoon-c2 restart: unless-stopped network_mode: host diff --git a/software/c2/docker-entrypoint.sh b/software/c2/docker-entrypoint.sh index 9482768..682d600 100644 --- a/software/c2/docker-entrypoint.sh +++ b/software/c2/docker-entrypoint.sh @@ -23,13 +23,57 @@ echo -e "${D} ───────────────────── echo "" # Tool versions +# +# `_tool` reports what is actually there. The three lines below used to +# read `$(nxc --version 2>/dev/null || echo 'installed')`, which printed +# the word "installed" under a green tick for a tool that was absent -- +# it claimed NetExec in an image deliberately built without it. A banner +# that cannot be wrong is worth more than one that is always green. +_tool() { + # $1 label, $2 command that must be on PATH, $3.. how to ask for a version + if ! command -v "$2" >/dev/null 2>&1; then + printf "%b [ ]%b %b%-13s%b %bnot installed%b\n" "$D" "$N" "$W" "$1" \ + "$N" "$D" "$N" + return + fi + # The version is dug out, not trusted. Measured: `relayking --version` + # exits 1 and prints six lines of ASCII art before the version, and + # `responder --version` prints nothing at all -- so a plain `cmd | head + # -1 || echo unknown` showed an empty string for both, because head + # exits 0 whatever it read. Pull the first version-shaped token out of + # the output, strip the colour codes, and say "installed" when there is + # none rather than printing a blank. + local out ver + out="$("${@:3}" 2>/dev/null | sed 's/\x1b\[[0-9;]*m//g')" + ver="$(printf '%s' "$out" | grep -oE '[0-9]+\.[0-9]+(\.[0-9]+)?' | head -1)" + printf "%b [✓]%b %b%-13s%b %b%s%b\n" "$G" "$N" "$W" "$1" "$N" "$D" \ + "${ver:-installed}" "$N" +} + +_pymod() { + # $1 label, $2 distribution name. The three module lines below used to + # print a hardcoded green tick beside this, so an absent package would + # have read "[✓] Lsassy not installed" -- the same defect as the one + # above, left in place by the first version of this fix. + local ver + ver="$(python3 -c "import importlib.metadata as m; print(m.version('$2'))" \ + 2>/dev/null)" + if [ -n "$ver" ]; then + printf "%b [✓]%b %b%-13s%b %b%s%b\n" "$G" "$N" "$W" "$1" "$N" "$D" \ + "$ver" "$N" + else + printf "%b [ ]%b %b%-13s%b %bnot installed%b\n" "$D" "$N" "$W" "$1" \ + "$N" "$D" "$N" + fi +} + echo -e "${G} [✓]${N} ${W}Python${N} ${D}$(python3 --version 2>&1)${N}" -echo -e "${G} [✓]${N} ${W}Flask${N} ${D}$(python3 -c 'import importlib.metadata; print(importlib.metadata.version("flask"))')${N}" -echo -e "${G} [✓]${N} ${W}Impacket${N} ${D}$(python3 -c 'import importlib.metadata; print(importlib.metadata.version("impacket"))')${N}" -echo -e "${G} [✓]${N} ${W}NetExec${N} ${D}$(nxc --version 2>/dev/null || echo 'installed')${N}" -echo -e "${G} [✓]${N} ${W}Lsassy${N} ${D}$(python3 -c 'import importlib.metadata; print(importlib.metadata.version("lsassy"))')${N}" -echo -e "${G} [✓]${N} ${W}RelayKing${N} ${D}$(python3 /opt/RelayKing/relayking.py --version 2>/dev/null || echo 'installed')${N}" -echo -e "${G} [✓]${N} ${W}Responder${N} ${D}$(python3 /opt/Responder/Responder.py --version 2>/dev/null || echo 'installed')${N}" +_pymod "Flask" flask +_pymod "Impacket" impacket +_tool "NetExec" nxc nxc --version +_pymod "Lsassy" lsassy +_tool "RelayKing" relayking python3 /opt/RelayKing/relayking.py --version +_tool "Responder" responder python3 /opt/Responder/Responder.py --version echo "" # RACCOON_HOST/PORT: the beacon socket. RACCOON_OPERATOR_HOST/PORT: the GUI @@ -41,7 +85,7 @@ OPERATOR_PORT="${RACCOON_OPERATOR_PORT:-8444}" OPERATOR_HOST="${RACCOON_OPERATOR_HOST:-127.0.0.1}" DATA="${RACCOON_DATA:-/data/raccoon-c2}" -CMD=(python3 /opt/raccoon-c2/server.py +CMD=(python3 -m software.c2.server --host "$HOST" --port "$PORT" --operator-host "$OPERATOR_HOST" @@ -65,7 +109,15 @@ echo -e "${D} ┌──────────────────── echo -e "${D} │${N} ${C}Beacons${N} ${W}http://${HOST}:${PORT}${N}" echo -e "${D} │${N} ${C}GUI${N} ${W}http://${OPERATOR_HOST}:${OPERATOR_PORT}${N}" echo -e "${D} │${N} ${C}Data${N} ${W}${DATA}${N}" -echo -e "${D} │${N} ${C}Tools${N} ${W}impacket nxc lsassy relayking responder nmap${N}" +# Built from what is on PATH, not from a list written once. The fixed +# list claimed `nxc` in an image that had none. +_present="" +for _t in nmap nxc responder relayking xfreerdp xfreerdp3 vncviewer; do + command -v "$_t" >/dev/null 2>&1 && _present="${_present} ${_t}" +done +python3 -c "import impacket" 2>/dev/null && _present="${_present} impacket" +python3 -c "import lsassy" 2>/dev/null && _present="${_present} lsassy" +echo -e "${D} │${N} ${C}Tools${N} ${W}${_present# }${N}" echo -e "${D} └──────────────────────────────────────────────┘${N}" echo "" diff --git a/software/c2/server.py b/software/c2/server.py index 01fcc1a..371db0c 100644 --- a/software/c2/server.py +++ b/software/c2/server.py @@ -1761,7 +1761,19 @@ def api_server_rdp(): return jsonify({"error": "target required"}), 400 if mode == "xfreerdp": - cmd_parts = ["xfreerdp"] + # Looked up, not assumed. freerdp2 ships `xfreerdp` and + # freerdp3 ships `xfreerdp3`; this used to hardcode the former, + # so moving the image's Debian base -- which happened once + # already, unnoticed -- would leave the RDP button failing at + # runtime for an operator to discover. The VNC branch below + # has always probed its viewer names; this now matches it. + client = next( + (name for name in ("xfreerdp", "xfreerdp3") + if shutil.which(name)), None) + if client is None: + return jsonify({"error": "No RDP client found (install " + "freerdp2-x11 or freerdp3-x11)"}), 400 + cmd_parts = [client] cmd_parts.append(f"/v:{target}") if port: cmd_parts.append(f"/port:{port}") diff --git a/software/tests/test_docs.py b/software/tests/test_docs.py index 8f054bc..51f8692 100644 --- a/software/tests/test_docs.py +++ b/software/tests/test_docs.py @@ -546,11 +546,21 @@ def _nothing_is_pinned(): _read("software", "tests", "requirements.txt")] image = _read("software", "c2", "Dockerfile") pip_block = image.split("RUN pip install", 1)[1].split("\n\n", 1)[0] + # The third clause used to be `re.search(r"NetExec\s*$", image, re.M)`: + # the NetExec line happening to end the line was read as "its git ref + # carries no tag". Adding a `\` continuation to that line defeated the + # probe without changing a thing about pinning, and the suite reported + # this finding as fixed. So ask the question the finding actually + # asks -- are the three source builds pulling a moving ref? -- which a + # reformat cannot answer differently. + sources = re.findall(r"(?:git\+https://|https://)github\.com/\S+", image) + moving = [url for url in sources + if "@" not in url.split("github.com/", 1)[1]] return (not any("==" in line for text in reqs for line in text.splitlines() if not line.lstrip().startswith("#")) and not re.search(r"[<>=]", pip_block) - and re.search(r"NetExec\s*$", image, re.M) is not None) + and len(moving) >= 3) def _the_old_dependencies_are_still_declared(): diff --git a/software/tests/test_shipped_image.py b/software/tests/test_shipped_image.py new file mode 100644 index 0000000..d3c0215 --- /dev/null +++ b/software/tests/test_shipped_image.py @@ -0,0 +1,253 @@ +#!/usr/bin/env python3 +"""The shipped team-server image: that it can be built, and can then run. + +Six defects were found in `software/c2/Dockerfile` the first time anyone +tried to build it on this project's own development machine. Four of them +broke the build on *every* architecture, and one of those four had been +hidden by a `2>/dev/null`. A fifth let the image build and then crash at +import. None of it was caught, because nothing in this repository ever +built the image. + +These tests need no Docker: they read the Dockerfile, the compose file and +the entrypoint, and they assert the properties whose absence produced each +defect. The build itself is CI's job -- see .github/workflows/ci.yml -- +because only a build proves a build. +""" + +import re +import unittest +from pathlib import Path + +REPO = Path(__file__).resolve().parents[2] +C2 = REPO / "software" / "c2" +DOCKERFILE = C2 / "Dockerfile" +COMPOSE = C2 / "docker-compose.yml" +ENTRYPOINT = C2 / "docker-entrypoint.sh" +SERVER = C2 / "server.py" + + +def _text(path): + return path.read_text() + + +def _instructions(path): + """The file without its comments: what Docker actually runs.""" + return "\n".join(line for line in _text(path).splitlines() + if not line.lstrip().startswith("#")) + + +class TheBaseIsPinned(unittest.TestCase): + def test_the_base_image_names_a_debian_release(self): + # Measured: `python:3.12-slim` moved from Debian 12 to Debian 13, + # where freerdp2-x11 no longer exists, and the build died at step 3 + # of 20 for everyone. An unpinned base means the image's contents + # change under it without a commit. + base = re.search(r"^FROM\s+(\S+)", _instructions(DOCKERFILE), re.M) + self.assertIsNotNone(base, "no FROM line") + self.assertRegex( + base.group(1), r":.+-(bookworm|trixie|bullseye)\b", + "the base image does not name a Debian release, so apt can " + "stop carrying a package without anything here changing") + + +class TheBuildHasWhatItCompilesWith(unittest.TestCase): + def test_python_headers_are_installed(self): + # arc4, a NetExec dependency, publishes no Linux aarch64 wheel, so + # pip compiles it from source there and needs Python.h. Measured: + # without python3-dev the build dies on arm64 and succeeds on + # amd64, which is why nobody saw it. + self.assertTrue(re.search(r"\bpython3-dev\b", _instructions(DOCKERFILE)), + "python3-dev is not installed, so a dependency " + "without a wheel cannot compile") + + def test_a_tool_without_a_wheel_cannot_fail_the_whole_build(self): + # aardwolf, NetExec's RDP library, has no aarch64 wheel either and + # needs a Rust toolchain. Adding Rust to a slim image for one + # optional tool is the wrong trade, so the install is allowed to + # fail -- and the entrypoint then reports the tool as missing + # rather than claiming it (see TheBannerDoesNotLie). + netexec = [line for line in _instructions(DOCKERFILE).splitlines() + if "NetExec" in line] + self.assertTrue(netexec, "the NetExec install vanished entirely") + self.assertTrue( + any("||" in line for line in netexec), + "a tool that cannot build on one architecture must not fail " + "the image for every architecture") + + +class LinksDoNotFightWhatPipInstalled(unittest.TestCase): + def test_every_console_script_link_is_forced(self): + # `pip install -e .` installs its own console script at the same + # path, so a plain `ln -s` fails with "File exists" -- meaning the + # step could only succeed when pip FAILED. The `2>/dev/null` on the + # pip call hid which of the two had happened. + plain = re.findall(r"&&\s*ln -s\s+(?!-)", _instructions(DOCKERFILE)) + self.assertEqual( + plain, [], + "a bare `ln -s` into /usr/local/bin breaks as soon as pip " + "installs its own entry point at that path") + + +class TheImageCanActuallyRunTheServer(unittest.TestCase): + def test_server_py_imports_from_the_package(self): + # The premise of the next test. If this stops being true the next + # one is no longer proving anything. + self.assertTrue(re.search(r"^from software\.c2\.", _text(SERVER), re.M), + "server.py no longer imports from the package, so " + "the next test proves nothing") + + def test_the_build_context_can_see_the_package(self): + # The image copied three flat files into /opt/raccoon-c2 while + # server.py imports `software.c2.listeners` and + # `software.c2.stagers`. So the server died at import with + # ModuleNotFoundError: No module named 'software' -- the image + # built and could not start. The listener service already builds + # from the repository root; the team server now does too. + import yaml + + with open(COMPOSE) as handle: + doc = yaml.safe_load(handle) + build = doc["services"]["raccoon-c2"]["build"] + context = build["context"] if isinstance(build, dict) else build + self.assertNotEqual( + context, ".", + "a context of software/c2 cannot COPY the software/ package, " + "and server.py imports from it") + + def test_the_package_is_copied_into_the_image(self): + copied = re.findall(r"^COPY\s+(\S+)", _instructions(DOCKERFILE), re.M) + self.assertTrue( + any(part.startswith("software/") for part in copied), + "nothing copies the software/ package, so every `from " + "software.c2...` import in server.py fails at start-up") + + + def test_every_copy_source_exists_in_the_build_context(self): + # Moving the context to the repository root broke `COPY + # docker-entrypoint.sh`, which had been written against the old + # one: the build died at step 17 of 19. A COPY path is only + # meaningful together with the context, and nothing checked the + # two against each other. + missing = [] + for line in _instructions(DOCKERFILE).splitlines(): + match = re.match(r"^COPY\s+(?!--)(.+)$", line) + if not match: + continue + parts = match.group(1).split() + for source in parts[:-1]: + if not list(REPO.glob(source.rstrip("/"))): + missing.append(source) + self.assertEqual( + missing, [], + "these COPY sources do not exist relative to the build " + "context (the repository root), so the build cannot reach " + "step 19") + + + def test_the_entrypoint_launches_the_package_not_a_loose_file(self): + # Defect 7, and I made this one myself: once the image copied the + # package instead of three flat files, the entrypoint's + # `python3 /opt/raccoon-c2/server.py` pointed at a path that no + # longer existed. The banner printed perfectly and then the + # container died with "can't open file". Running it as a module is + # also what the CI step runs, so the two cannot drift apart. + launch = [line for line in _instructions(ENTRYPOINT).splitlines() + if "CMD=(" in line or line.strip().startswith("exec ")] + self.assertTrue(launch, "the entrypoint no longer launches anything") + self.assertTrue( + any("-m software.c2.server" in line for line in launch), + "the entrypoint must launch the installed package; a path to " + "a loose server.py breaks whenever the COPY layout changes") + + +class TheBannerDoesNotLie(unittest.TestCase): + def test_no_tool_is_reported_as_installed_without_being_found(self): + # `$(nxc --version 2>/dev/null || echo 'installed')` prints + # "installed" for a tool that is absent, under a green [✓]. It told + # me NetExec was installed in an image I had deliberately built + # without it. Three tools did this. + # Instructions, not comments. The first version of this read the + # whole file and caught the comment above the fix, which quotes the + # broken line on purpose -- a test that forbids describing a defect + # is a test that makes the code harder to understand. + self.assertNotIn( + "echo 'installed'", _instructions(ENTRYPOINT), + "a missing tool must not be reported as installed") + + def test_no_green_tick_is_printed_beside_a_value_it_cannot_vouch_for(self): + # The first version of this fix routed NetExec, RelayKing and + # Responder through a helper and left Flask, Impacket and Lsassy + # printing a literal green tick beside a version lookup that could + # return "not installed" -- so an absent package would have read + # "[✓] Lsassy not installed". Same defect, three lines over. + offenders = [] + for line in _instructions(ENTRYPOINT).splitlines(): + if "[✓]" not in line or "$(" not in line: + continue + if "python3 --version" in line: + continue # the interpreter running this script, always there + offenders.append(line.strip()[:60]) + self.assertEqual( + offenders, [], + "these lines print a fixed green tick next to a value looked " + "up at run time, so they claim a tool the image may not have") + + def test_the_tool_summary_is_not_a_hardcoded_list(self): + # The summary line read `impacket nxc lsassy relayking responder + # nmap` as fixed text, so it claimed every tool whatever the image + # held. + self.assertNotIn("impacket nxc lsassy relayking responder nmap", + _instructions(ENTRYPOINT)) + + +class RdpDoesNotHardcodeOneBinaryName(unittest.TestCase): + def test_the_rdp_client_is_looked_up_not_assumed(self): + # freerdp2 ships `xfreerdp`, freerdp3 ships `xfreerdp3`. server.py + # hardcoded `xfreerdp`, so the next base-image move would leave the + # RDP button failing at runtime for an operator to discover. The + # VNC path twenty lines below already probes several names; this + # makes RDP match it. + text = _text(SERVER) + i = text.index('mode == "xfreerdp"') + block = text[i:i + 900] + self.assertIn( + "xfreerdp3", block, + "only the freerdp2 binary name is known, so the image cannot " + "move to freerdp3 without breaking RDP silently") + + +class CiBuildsAndStartsTheImage(unittest.TestCase): + """Some workflow must build this image. Which file is not the point. + + These tests read every workflow rather than naming one, because the + repository's main CI file arrives in a different branch and a test + that hardcoded its path would turn an ordinary merge order into a + failure. + """ + + def setUp(self): + workflows = REPO / ".github" / "workflows" + self.files = sorted(workflows.glob("*.yml")) + \ + sorted(workflows.glob("*.yaml")) + self.assertTrue(self.files, "no workflows at all") + self.ci = "\n".join(_text(path) for path in self.files) + + def test_a_job_builds_the_shipped_image(self): + self.assertTrue( + re.search(r"software/c2/(Dockerfile|docker-compose\.yml)", + self.ci), + "no workflow builds the shipped image, which is how it came to " + "be broken on every architecture without anyone noticing") + + def test_the_build_job_also_starts_the_server(self): + # Defect 5 built cleanly and crashed at import. A job that only + # builds would have reported green over an image that cannot run, + # so the job runs the server far enough to execute its imports. + self.assertTrue( + re.search(r"software\.c2\.server[^\n]*--help", self.ci), + "the image is built but never started, so an import error " + "would pass unnoticed -- which is defect 5 exactly") + + +if __name__ == "__main__": + unittest.main()