Merge pull request #50 from BotCoder254/feat/event-driven-orchestration

Add toolchain catalog and image allowlist

Author: BotCoder254

backend/.env.example

@@ -76,13 +76,27 @@ RUNNER_JOB_SIGNING_KEY=
 # Node/npm/yarn, Python, git, build-essential etc. preinstalled
 # (~500 MB compressed). It does NOT ship every toolchain — notably no Rust
 # (`cargo: not found`) or Go — so a job needing one pins its own image in
-# workflow YAML with the GitHub `container:` key, e.g. `container: rust:1`,
-# `container: node:22`, `container: golang:1.23`. (`uses: actions/setup-*`
-# steps are not executed; overup emits a plan notice pointing at the
-# equivalent `container:` pin. `uses: actions/checkout` is a no-op — the
+# workflow YAML with the GitHub `container:` key. overup understands short
+# TOOLCHAIN ALIASES for the catthehacker specialized images: `container: rust`,
+# `container: js`, `container: go`, `container: dotnet`, `container: java`,
+# `container: pwsh`, `container: gh` (plus `act` and `full`). An alias pairs
+# with the job's Ubuntu version (`container: rust` + `runs-on: ubuntu-22.04`
+# → the rust-22.04 image). Full references like `container: node:22` still
+# work. See the Toolchains page in the UI for the full catalog. (`uses:
+# actions/setup-*` steps are not executed; overup emits a plan notice pointing
+# at the equivalent toolchain alias. `uses: actions/checkout` is a no-op — the
 # runner checks the repository out into /workspace automatically.)
 DEFAULT_JOB_IMAGE=catthehacker/ubuntu:act-latest
 
+# Optional hardening: restrict which images a job `container:` may run.
+# Comma-separated; each entry is an exact image reference or a trailing-`*`
+# prefix glob (e.g. `catthehacker/*`, `node:*`, `ghcr.io/acme/*`). UNSET =
+# allow any syntactically valid reference (the default). When set, a
+# `container:` image outside this list (toolchain-catalog images are always
+# allowed) is rejected at plan time and the job falls back to DEFAULT_JOB_IMAGE
+# with a visible plan notice — it never fails the job.
+#RUNNER_IMAGE_ALLOWLIST=catthehacker/*
+
 # --- Secrets Management (optional but recommended) ---------------------------
 # Master key for envelope-encrypting workspace/repository secrets (exactly
 # 32 bytes, hex- or base64-encoded). Generate with: openssl rand -hex 32
@@ -127,8 +141,11 @@ DEFAULT_JOB_IMAGE=catthehacker/ubuntu:act-latest
 # failures are warn-only and never affect hosted-runner availability.
 # NOTE: this is the way to "bake" job images into a deployment — the backend
 # Dockerfile cannot do it (images live in the host daemon's store, not
-# inside the backend image).
-#RUNNER_PREPULL_IMAGES=catthehacker/ubuntu:act-latest
+# inside the backend image). To warm the language toolchains surfaced on the
+# UI Toolchains page, list the ones your workflows use (they show as
+# "Prewarmed"; capped at 20 entries, and the ~60 GB `full-*` image is best
+# left out):
+#RUNNER_PREPULL_IMAGES=catthehacker/ubuntu:act-latest,catthehacker/ubuntu:rust-latest,catthehacker/ubuntu:js-latest,catthehacker/ubuntu:go-latest
 # DOCKER_HOST passed through to runner containers so they can execute jobs.
 # SECURITY: leave unset to mount /var/run/docker.sock into runner containers
 # instead — that mount is root-equivalent on the host, so prefer a

backend/src/config.rs

@@ -46,6 +46,13 @@ pub struct Config {
     /// Container image used when a job declares no container and no known
     /// runs-on label.
     pub default_job_image: String,
+    /// Optional allow-list of images a job's `container:` may run. Empty =
+    /// allow any syntactically valid reference (default). When non-empty, a
+    /// `container:` image outside this list (and outside the toolchain
+    /// catalog) is rejected at plan time and the job falls back to the
+    /// default image with a notice. Entries support a trailing `*` prefix
+    /// glob (e.g. `catthehacker/*`, `node:*`).
+    pub image_allowlist: Vec<String>,
     pub job_timeout_seconds: i32,
     pub pipeline_timeout_seconds: i32,
     pub max_log_bytes_per_job: i64,
@@ -277,6 +284,12 @@ impl Config {
         // no toolchains, so real workflows die on `npm: not found`.
         let default_job_image = optional("DEFAULT_JOB_IMAGE", "catthehacker/ubuntu:act-latest");
 
+        // Optional hardening: restrict which images a job `container:` may run.
+        // Unset = allow any valid reference (the historical behavior). Parsed
+        // with the same caps as the prepull list so a malformed deployment
+        // fails loudly at startup.
+        let image_allowlist = parse_image_list("RUNNER_IMAGE_ALLOWLIST")?;
+
         // Hosted-runner provisioning is opt-in: the server needs Docker
         // access and a URL that provisioned containers can reach it on.
         let runner_provisioner = match optional("RUNNER_PROVISIONER", "").as_str() {
@@ -431,6 +444,7 @@ impl Config {
                 .context("GITHUB_CHECKS_ENABLED must be true or false")?,
             runner_job_signing_key,
             default_job_image,
+            image_allowlist,
             job_timeout_seconds: optional("JOB_TIMEOUT_SECONDS", "3600")
                 .parse()
                 .context("JOB_TIMEOUT_SECONDS must be an integer")?,
@@ -556,6 +570,30 @@ fn optional(key: &str, default: &str) -> String {
     std::env::var(key).unwrap_or_else(|_| default.to_string())
 }
 
+/// Parse a comma-separated image-reference env var (unset/empty = empty list),
+/// applying the same caps as the prepull list. Entries may end in `*` for a
+/// prefix glob, so the length cap is generous enough for a registry path.
+fn parse_image_list(key: &str) -> anyhow::Result<Vec<String>> {
+    let raw = optional(key, "");
+    let mut images: Vec<String> = Vec::new();
+    for entry in raw.split(',') {
+        let entry = entry.trim();
+        if entry.is_empty() {
+            continue;
+        }
+        if entry.len() > 256 {
+            anyhow::bail!("{key} entries must be at most 256 characters (got one of {} characters)", entry.len());
+        }
+        if !images.iter().any(|existing| existing == entry) {
+            images.push(entry.to_string());
+        }
+    }
+    if images.len() > 50 {
+        anyhow::bail!("{key} supports at most 50 entries (got {})", images.len());
+    }
+    Ok(images)
+}
+
 /// Parse the comma-separated RUNNER_PREPULL_IMAGES value: trim entries, drop
 /// empties, dedupe preserving order, and enforce sane caps so a malformed
 /// deployment fails at startup instead of spraying pull warnings forever.

backend/src/handlers/mod.rs

@@ -19,6 +19,7 @@ pub mod search;
 pub mod runners;
 pub mod secrets;
 pub mod sessions;
+pub mod toolchains;
 pub mod workflows;
 pub mod workspaces;
 pub mod ws_tickets;

backend/src/handlers/toolchains.rs

@@ -0,0 +1,39 @@
+//! Toolchains API: a read-only catalog of the language-toolchain images
+//! overup understands (`services::toolchain_images`), tagged with the
+//! deployment's default image, prewarm state, and whether an image allow-list
+//! is active. Rides `content.read` like the other workspace read surfaces.
+//! Static strings only — no mutation surface, no user/runner text.
+
+use axum::Json;
+use axum::extract::{Path, State};
+use uuid::Uuid;
+
+use crate::error::AppResult;
+use crate::middleware::auth::CurrentUser;
+use crate::models::toolchain::ToolchainsResponse;
+use crate::services::authz;
+use crate::state::AppState;
+
+/// GET /api/workspaces/{workspace_id}/toolchains
+pub async fn list(
+    State(state): State<AppState>,
+    CurrentUser(user): CurrentUser,
+    Path(workspace_id): Path<Uuid>,
+) -> AppResult<Json<ToolchainsResponse>> {
+    authz::require_permission(&state.pool, user.id, workspace_id, authz::CONTENT_READ).await?;
+
+    // Prewarm state comes from the provisioner's prepull list (only present
+    // when hosted provisioning is configured); otherwise nothing is prewarmed.
+    let prepull: &[String] = state
+        .config
+        .runner_provisioner
+        .as_ref()
+        .map(|p| p.prepull_images.as_slice())
+        .unwrap_or(&[]);
+
+    Ok(Json(ToolchainsResponse::build(
+        state.config.default_job_image.clone(),
+        prepull,
+        !state.config.image_allowlist.is_empty(),
+    )))
+}

backend/src/models/mod.rs

@@ -8,6 +8,7 @@ pub mod repository;
 pub mod runner;
 pub mod search;
 pub mod secret;
+pub mod toolchain;
 pub mod user;
 pub mod workflow;
 pub mod workspace;

backend/src/models/toolchain.rs

@@ -0,0 +1,63 @@
+//! API shapes for the language-toolchain catalog (`GET …/toolchains`). The
+//! catalog itself is static (`services::toolchain_images`); these DTOs project
+//! it, tagging each entry with whether its `-latest` image is prewarmed by the
+//! deployment's `RUNNER_PREPULL_IMAGES`. Static strings only — no user or
+//! runner text ever reaches here.
+
+use serde::Serialize;
+
+use crate::services::toolchain_images;
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ToolchainResponse {
+    pub key: &'static str,
+    pub label: &'static str,
+    pub language: &'static str,
+    pub description: &'static str,
+    pub tools: Vec<&'static str>,
+    pub image_latest: &'static str,
+    pub image2204: &'static str,
+    pub image2404: &'static str,
+    /// Very large image (`full-*`) — the UI warns against prewarming it.
+    pub large: bool,
+    /// The `-latest` image is in `RUNNER_PREPULL_IMAGES` (warmed on connect).
+    pub prewarmed: bool,
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ToolchainsResponse {
+    pub toolchains: Vec<ToolchainResponse>,
+    /// Image a job falls back to (`DEFAULT_JOB_IMAGE`).
+    pub default_image: String,
+    /// Whether `RUNNER_IMAGE_ALLOWLIST` restricts which images may run.
+    pub allowlist_enabled: bool,
+}
+
+impl ToolchainsResponse {
+    /// Build the response from the static catalog plus the deployment's
+    /// prepull list and default image.
+    pub fn build(default_image: String, prepull: &[String], allowlist_enabled: bool) -> Self {
+        let toolchains = toolchain_images::all()
+            .iter()
+            .map(|t| ToolchainResponse {
+                key: t.key,
+                label: t.label,
+                language: t.language,
+                description: t.description,
+                tools: t.tools.to_vec(),
+                image_latest: t.image_latest,
+                image2204: t.image_2204,
+                image2404: t.image_2404,
+                large: t.large,
+                prewarmed: prepull.iter().any(|p| p == t.image_latest),
+            })
+            .collect();
+        Self {
+            toolchains,
+            default_image,
+            allowlist_enabled,
+        }
+    }
+}

backend/src/routes/mod.rs

@@ -18,8 +18,8 @@ use crate::error::AppError;
 use crate::handlers::{
     activity, artifacts, auth, browser_ws, dashboard, dashboard_ws, environments,
     github_installations, github_webhooks, health, jobs, me, notification_ws, notifications,
-    pipelines, repositories, runner_ws, runners, search, secrets, sessions, workflows,
-    workspaces, ws_tickets,
+    pipelines, repositories, runner_ws, runners, search, secrets, sessions, toolchains,
+    workflows, workspaces, ws_tickets,
 };
 use crate::middleware::{csrf, security_headers};
 use crate::services::session;
@@ -371,6 +371,10 @@ pub fn build_router(state: AppState) -> anyhow::Result<Router> {
                 .patch(environments::update)
                 .delete(environments::remove),
         )
+        .route(
+            "/workspaces/{workspace_id}/toolchains",
+            get(toolchains::list),
+        )
         .route(
             "/workspaces/{workspace_id}/runners",
             get(runners::list).post(runners::create),

backend/src/services/mod.rs

@@ -25,6 +25,7 @@ pub mod scheduler;
 pub mod search_indexer;
 pub mod secrets_crypto;
 pub mod session;
+pub mod toolchain_images;
 pub mod trigger_eval;
 pub mod webhook_processor;
 pub mod webhook_stats;