feat(suidhelper): self-checksum stamping + build-identity embedding (#30)

Author: markovejnovic

.gitignore

@@ -44,3 +44,7 @@ docs/superpowers/
 # gRPC bindings are generated from proto/hyper/grpc/v0/hyper.proto before compile
 # -- see the :grpc_gen Mix compiler in mix.exs.
 /lib/hyper/grpc/v0/
+
+# The expected suidhelper build identity (version + checksum) is captured from
+# the stamped binary's `version` output -- see the :suidhelper_stamp Mix compiler.
+/lib/hyper/suid_helper/expected.ex

config/config.exs

@@ -24,11 +24,7 @@ config :libcluster,
 config :hyper,
   cgroup_parent: "hyper",
   uid_gid_range: {900_000, 999_999},
-  layer_dir: "/srv/hyper/layers",
-  vmlinux: %{
-    x86_64: "/srv/hyper/vmlinux/vmlinux-x86_64",
-    aarch64: "/srv/hyper/vmlinux/vmlinux-aarch64"
-  }
+  layer_dir: "/srv/hyper/layers"
 
 if config_env() == :test do
   config :opentelemetry, traces_exporter: :none

lib/hyper/config.ex

@@ -22,7 +22,6 @@ defmodule Hyper.Config do
   @skopeo_path Application.compile_env(:hyper, :skopeo_path, "skopeo")
   @umoci_path Application.compile_env(:hyper, :umoci_path, nil)
   @mke2fs_path Application.compile_env(:hyper, :mke2fs_path, "mke2fs")
-  @vmlinux Application.compile_env(:hyper, :vmlinux, %{})
 
   @doc """
   Root work directory for this node. All firecracker paths derive from it.
@@ -156,5 +155,7 @@ defmodule Hyper.Config do
   `Hyper.Node.Vmlinux` resolves and validates them per node.
   """
   @spec vmlinux :: %{optional(Sys.Arch.t()) => Path.t()}
-  def vmlinux, do: @vmlinux
+  # Runtime read, not `compile_env`: an unset map would inline a literal `%{}`,
+  # which the type checker proves makes every `Map.fetch/2` on it return `:error`.
+  def vmlinux, do: Application.get_env(:hyper, :vmlinux, %{})
 end

lib/hyper/suid_helper.ex

@@ -16,7 +16,7 @@ defmodule Hyper.SuidHelper do
   self-test and reports the base path it was compiled against.
   """
 
-  alias Hyper.SuidHelper.{Blockdev, Dmsetup, Losetup}
+  alias Hyper.SuidHelper.{Blockdev, Dmsetup, Expected, Losetup}
 
   use OpenTelemetryDecorator
 
@@ -52,18 +52,43 @@ defmodule Hyper.SuidHelper do
 
   @doc """
   Check that the setuid helper and every tool it execs are usable on this
-  machine: the helper binary itself, then each tool submodule's own check.
+  machine: the helper binary is present, is the build this release expects
+  (`verify_version/0`), then each tool submodule's own check.
   """
   @spec test_system() :: :ok | {:error, term()}
   @decorate with_span("Hyper.SuidHelper.test_system")
   def test_system do
     with :ok <- helper_present(),
+         :ok <- verify_version(),
          :ok <- Losetup.test_system(),
          :ok <- Dmsetup.test_system() do
       Blockdev.test_system()
     end
   end
 
+  @doc """
+  Check the deployed helper is the one this build produced: its `version` output
+  must match `Hyper.SuidHelper.Expected` (the identity captured from the stamped
+  binary at compile time). Catches a stale or wrong binary at the configured path.
+
+  This compares the helper's *self-reported* identity, so it is a build-provenance
+  check, not an adversarial tamper proof -- a malicious binary could report any
+  value.
+  """
+  @spec verify_version() :: :ok | {:error, :version_mismatch | err()}
+  @decorate with_span("Hyper.SuidHelper.verify_version")
+  def verify_version do
+    case exec(["version"]) do
+      {:ok, %{"version" => v, "checksum_blake3" => c}} ->
+        if v == Expected.version() and c == Expected.checksum_blake3(),
+          do: :ok,
+          else: {:error, :version_mismatch}
+
+      {:error, _} = err ->
+        err
+    end
+  end
+
   @spec helper_present() :: :ok | {:error, :suid_helper_not_found}
   defp helper_present do
     if System.find_executable(Hyper.Config.suid_helper()),

mix.exs

@@ -14,7 +14,7 @@ defmodule Hyper.MixProject do
       # A Mix compiler (not a `compile` alias) is used because Mix honors a
       # dependency's `:compilers` but NOT its aliases or `config/` -- so this is
       # the only hook that also fires when hyper is compiled AS A DEPENDENCY.
-      compilers: [:firecracker_gen, :grpc_gen | Mix.compilers()],
+      compilers: [:suidhelper_stamp, :firecracker_gen, :grpc_gen | Mix.compilers()],
       deps: deps(),
       test_coverage: [tool: ExCoveralls],
       docs: docs(),
@@ -195,7 +195,9 @@ defmodule Hyper.MixProject do
       # Force a regeneration of the Firecracker bindings (ignores staleness).
       "firecracker.gen": ["compile.firecracker_gen --force"],
       # Force a regeneration of the gRPC bindings (ignores staleness).
-      "grpc.gen": ["compile.grpc_gen --force"]
+      "grpc.gen": ["compile.grpc_gen --force"],
+      # Rebuild + stamp the suidhelper and re-capture its expected identity.
+      "suidhelper.stamp": ["compile.suidhelper_stamp --force"]
     ]
   end
 end
@@ -325,3 +327,104 @@ defmodule Mix.Tasks.Compile.FirecrackerGen do
     not File.exists?(@out) or File.stat!(@spec_path).mtime > File.stat!(@out).mtime
   end
 end
+
+defmodule Mix.Tasks.Compile.SuidhelperStamp do
+  @moduledoc """
+  Mix compiler that builds and stamps the Rust setuid helper, then captures the
+  build identity it will report at runtime into a generated module,
+  `Hyper.SuidHelper.Expected` (gitignored, like the other generated bindings).
+
+  Steps, run before the Elixir compiler so the generated module compiles:
+
+    1. `cargo xtask stamp` (in `native/suidhelper`) builds the release binary and
+       writes its BLAKE3 self-checksum into the ELF `.note.sum` section.
+    2. The stamped binary's `version` subcommand is invoked; its JSON
+       (`{"version":..,"checksum_blake3":..}`) is the helper's self-reported
+       build identity.
+    3. Its version + checksum are baked into `lib/hyper/suid_helper/expected.ex`
+       so the BEAM can compare a deployed helper against the one this build made.
+
+  Always runs (no staleness gate): `cargo` is incremental, so a no-op rebuild is
+  cheap, and this keeps the embedded identity in lockstep with the binary. Like
+  the protoc compiler, a missing toolchain is a hard failure -- `cargo` and the
+  helper's nightly toolchain must be present wherever hyper is compiled.
+
+  Note: the checksum is *self-reported* by the binary, so the generated module is
+  a build-provenance / version-skew check, not an adversarial tamper proof (a
+  malicious binary could print any value). Real tamper detection would re-hash
+  the on-disk ELF with `.note.sum` zeroed and compare -- the embedded checksum is
+  the reference value that check would use.
+  """
+
+  use Mix.Task.Compiler
+
+  @helper_dir "native/suidhelper"
+  @binary "native/suidhelper/target/release/hyper-suidhelper"
+  @out "lib/hyper/suid_helper/expected.ex"
+
+  @impl Mix.Task.Compiler
+  def run(_argv) do
+    stamp!()
+    json = capture_version!()
+    generate(json)
+    {:ok, []}
+  end
+
+  defp stamp! do
+    case System.cmd("cargo", ["xtask", "stamp"], cd: @helper_dir, stderr_to_stdout: true) do
+      {_, 0} ->
+        :ok
+
+      {output, code} ->
+        Mix.raise("""
+        `cargo xtask stamp` failed (exit #{code}) building the suidhelper:
+
+        #{output}
+        Ensure `cargo` and the helper's toolchain (see #{@helper_dir}/rust-toolchain.toml)
+        are installed.
+        """)
+    end
+  end
+
+  defp capture_version! do
+    case System.cmd(Path.expand(@binary), ["version"], stderr_to_stdout: true) do
+      {out, 0} ->
+        String.trim(out)
+
+      {out, code} ->
+        Mix.raise("`hyper-suidhelper version` failed (exit #{code}): #{out}")
+    end
+  end
+
+  defp generate(json) do
+    # Jason and the app's deps are available once loadpaths runs.
+    Mix.Task.run("loadpaths")
+    %{"version" => version, "checksum_blake3" => checksum} = Jason.decode!(json)
+
+    File.mkdir_p!(Path.dirname(@out))
+
+    source = """
+    defmodule Hyper.SuidHelper.Expected do
+      @moduledoc false
+      # GENERATED by Mix.Tasks.Compile.SuidhelperStamp from the stamped
+      # `hyper-suidhelper version` output. Do not edit; gitignored.
+
+      @version #{inspect(version)}
+      @checksum_blake3 #{inspect(checksum)}
+
+      @doc "Expected helper version."
+      @spec version() :: String.t()
+      def version, do: @version
+
+      @doc "Expected BLAKE3 checksum (hex) of the stamped helper."
+      @spec checksum_blake3() :: String.t()
+      def checksum_blake3, do: @checksum_blake3
+    end
+    """
+
+    # Format the generated source directly rather than via `Mix.Task.run("format",
+    # ...)`: a Mix task runs once per session, so invoking it here would consume
+    # the single run and leave the later `:grpc_gen` compiler's format a no-op.
+    File.write!(@out, [Code.format_string!(source), "\n"])
+  end
+end

native/suidhelper/.cargo/config.toml

@@ -4,3 +4,6 @@
 # the host `cc`, so it's left at the default.
 [target.aarch64-unknown-linux-musl]
 linker = "rust-lld"
+
+[alias]
+xtask = "run --package xtask --"