fix: switch linux builds to musl for glibc compatibility

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.github/workflows/release.yml

@@ -19,12 +19,12 @@ jobs:
           - target: x86_64-apple-darwin
             os: macos-latest
             name: ectf-tools-x86_64-apple-darwin
-          - target: x86_64-unknown-linux-gnu
+          - target: x86_64-unknown-linux-musl
             os: ubuntu-latest
-            name: ectf-tools-x86_64-unknown-linux-gnu
-          - target: aarch64-unknown-linux-gnu
+            name: ectf-tools-x86_64-unknown-linux-musl
+          - target: aarch64-unknown-linux-musl
             os: ubuntu-latest
-            name: ectf-tools-aarch64-unknown-linux-gnu
+            name: ectf-tools-aarch64-unknown-linux-musl
 
     runs-on: ${{ matrix.os }}
 
@@ -37,14 +37,18 @@ jobs:
           targets: ${{ matrix.target }}
 
       - name: Install cross-compilation tools
-        if: matrix.target == 'aarch64-unknown-linux-gnu'
+        if: contains(matrix.target, 'linux-musl')
         run: |
           sudo apt-get update
-          sudo apt-get install -y gcc-aarch64-linux-gnu
+          sudo apt-get install -y musl-tools
+          if [ "${{ matrix.target }}" = "aarch64-unknown-linux-musl" ]; then
+            sudo apt-get install -y gcc-aarch64-linux-gnu
+          fi
 
       - name: Build
         env:
-          CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER: aarch64-linux-gnu-gcc
+          CARGO_TARGET_AARCH64_UNKNOWN_LINUX_MUSL_LINKER: aarch64-linux-gnu-gcc
+          CC_aarch64_unknown_linux_musl: aarch64-linux-gnu-gcc
         run: cargo build --release --target ${{ matrix.target }}
 
       - name: Package

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "ectf-tools"
-version = "0.1.0"
+version = "0.2.0"
 edition = "2024"
 
 [dependencies]
@@ -13,4 +13,6 @@ hmac = "0.12"
 sha2 = "0.10"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
+serde_yaml = "0.9"
 clap_complete = "4"
+reqwest = { version = "0.12", default-features = false, features = ["blocking", "multipart", "json", "rustls-tls"] }

README.md

@@ -4,12 +4,20 @@
 
 Drop-in replacement for MITRE's `uvx ectf` CLI, rewritten in Rust with reliable serial I/O. Uses raw termios instead of pyserial to avoid macOS CDC-ACM data corruption bugs.
 
-## Usage
+## Install
+
+```bash
+brew install taciturnaxolotl/tap/ectf-tools
+```
+
+Or build from source:
 
 ```bash
 cargo build --release
 ```
 
+## Usage
+
 ### HSM Host Tools
 
 ```bash

src/api.rs

@@ -0,0 +1,649 @@
+use std::io::{Read as _, Write as _};
+use std::net::TcpStream;
+use std::path::PathBuf;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::Arc;
+use std::time::{Duration, Instant};
+
+use anyhow::{Context, Result, bail};
+
+use crate::config::Config;
+use crate::log;
+use crate::protocol::{HSMIntf, Opcode};
+use crate::serial;
+
+// ─── Types ───
+
+#[derive(Debug, serde::Deserialize)]
+#[allow(dead_code)]
+pub struct Flow {
+    pub id: String,
+    pub submit_time: String,
+    pub name: String,
+    pub completed: bool,
+    pub params: serde_json::Value,
+    pub jobs: Vec<Job>,
+}
+
+#[derive(Debug, serde::Deserialize)]
+#[allow(dead_code)]
+pub struct Job {
+    pub name: String,
+    pub id: String,
+    pub has_artifacts: bool,
+    pub private: bool,
+    pub status: String,
+}
+
+fn status_color(s: &str) -> &'static str {
+    match s {
+        "succeeded" | "completed" => "\x1b[38;5;114m",
+        "queued" | "running" | "pending" => "\x1b[38;5;221m",
+        "canceled" => "\x1b[38;5;242m",
+        "failed" => "\x1b[38;5;203m",
+        _ => "",
+    }
+}
+
+fn titlecase(s: &str) -> String {
+    let mut c = s.chars();
+    match c.next() {
+        None => String::new(),
+        Some(f) => f.to_uppercase().collect::<String>() + c.as_str(),
+    }
+}
+
+fn relative_time(iso: &str) -> String {
+    // Parse ISO 8601 timestamp and compute relative time
+    let ts = iso
+        .split('T')
+        .next()
+        .and_then(|d| {
+            let parts: Vec<&str> = d.split('-').collect();
+            if parts.len() == 3 {
+                let y: i64 = parts[0].parse().ok()?;
+                let m: i64 = parts[1].parse().ok()?;
+                let d: i64 = parts[2].parse().ok()?;
+                Some(y * 365 + m * 30 + d)
+            } else {
+                None
+            }
+        });
+
+    let now = {
+        let output = std::process::Command::new("date")
+            .arg("+%Y-%m-%d")
+            .output()
+            .ok();
+        output.and_then(|o| {
+            let s = String::from_utf8(o.stdout).ok()?;
+            let parts: Vec<&str> = s.trim().split('-').collect();
+            if parts.len() == 3 {
+                let y: i64 = parts[0].parse().ok()?;
+                let m: i64 = parts[1].parse().ok()?;
+                let d: i64 = parts[2].parse().ok()?;
+                Some(y * 365 + m * 30 + d)
+            } else {
+                None
+            }
+        })
+    };
+
+    match (ts, now) {
+        (Some(t), Some(n)) => {
+            let days = n - t;
+            if days < 0 {
+                "in the future".to_string()
+            } else if days == 0 {
+                "today".to_string()
+            } else if days == 1 {
+                "yesterday".to_string()
+            } else if days < 7 {
+                format!("{days} days ago")
+            } else if days < 14 {
+                "a week ago".to_string()
+            } else if days < 30 {
+                format!("{} weeks ago", days / 7)
+            } else if days < 60 {
+                "a month ago".to_string()
+            } else if days < 365 {
+                format!("{} months ago", days / 30)
+            } else {
+                format!("{} years ago", days / 365)
+            }
+        }
+        _ => iso.to_string(),
+    }
+}
+
+const RESET: &str = "\x1b[0m";
+const BOLD: &str = "\x1b[1m";
+const UNDERLINE: &str = "\x1b[4m";
+const CYAN: &str = "\x1b[36m";
+const YELLOW: &str = "\x1b[33m";
+const GREEN: &str = "\x1b[32m";
+const RED: &str = "\x1b[31m";
+const BLUE: &str = "\x1b[34m";
+const DIM: &str = "\x1b[38;5;242m";
+
+/// Auto-highlight a value like Rich's highlighter:
+/// UUIDs/hashes → yellow, booleans → green/red, URLs → blue, else → cyan
+fn highlight(val: &str) -> String {
+    if val.eq_ignore_ascii_case("true") {
+        format!("{GREEN}{val}{RESET}")
+    } else if val.eq_ignore_ascii_case("false") {
+        format!("{RED}{val}{RESET}")
+    } else if val.starts_with("http://") || val.starts_with("https://") || val.starts_with("ssh://") || val.starts_with("git@") {
+        format!("{BLUE}{val}{RESET}")
+    } else if val.contains('-') && val.len() >= 32 && val.chars().all(|c| c.is_ascii_hexdigit() || c == '-') {
+        // UUIDs → yellow
+        format!("{YELLOW}{val}{RESET}")
+    } else if val.len() >= 32 && val.chars().all(|c| c.is_ascii_hexdigit()) {
+        // Commit hashes → blue
+        format!("{BLUE}{val}{RESET}")
+    } else {
+        format!("{CYAN}{val}{RESET}")
+    }
+}
+
+// ─── Client ───
+
+pub struct ApiClient {
+    pub config: Config,
+    client: reqwest::blocking::Client,
+}
+
+impl ApiClient {
+    pub fn new() -> Result<Self> {
+        let config = Config::load()?;
+        let client = reqwest::blocking::Client::new();
+        Ok(Self { config, client })
+    }
+
+    fn url(&self, path: &str) -> String {
+        // Trailing slash must come before query string
+        if let Some((base, query)) = path.split_once('?') {
+            format!("{}/api/{base}/?{query}", self.config.api_url)
+        } else {
+            format!("{}/api/{path}/", self.config.api_url)
+        }
+    }
+
+    fn get(&self, path: &str) -> Result<reqwest::blocking::Response> {
+        let resp = self
+            .client
+            .get(self.url(path))
+            .bearer_auth(&self.config.token)
+            .send()?;
+        check_status(resp)
+    }
+
+    fn post_json(
+        &self,
+        path: &str,
+        body: &serde_json::Value,
+    ) -> Result<reqwest::blocking::Response> {
+        let resp = self
+            .client
+            .post(self.url(path))
+            .bearer_auth(&self.config.token)
+            .json(body)
+            .send()?;
+        check_status(resp)
+    }
+
+    fn post_file(
+        &self,
+        path: &str,
+        name: &str,
+        data: Vec<u8>,
+    ) -> Result<reqwest::blocking::Response> {
+        let part = reqwest::blocking::multipart::Part::bytes(data).file_name(name.to_string());
+        let form = reqwest::blocking::multipart::Form::new().part("file", part);
+        let resp = self
+            .client
+            .post(self.url(path))
+            .bearer_auth(&self.config.token)
+            .multipart(form)
+            .send()?;
+        check_status(resp)
+    }
+
+    // ─── Flow operations ───
+
+    pub fn flow_list(&self, flow: &str, count: usize) -> Result<Vec<Flow>> {
+        let resp = self.get(&format!("flow/{flow}?num={count}"))?;
+        Ok(resp.json()?)
+    }
+
+    pub fn flow_info(&self, flow: &str, id: &str) -> Result<Flow> {
+        let resp = self.get(&format!("flow/{flow}/{id}"))?;
+        Ok(resp.json()?)
+    }
+
+    pub fn flow_submit(&self, flow: &str, body: &serde_json::Value) -> Result<String> {
+        let resp = self.post_json(&format!("flow/{flow}"), body)?;
+        Ok(resp.text()?)
+    }
+
+    pub fn flow_cancel(&self, flow: &str, id: &str) -> Result<()> {
+        let resp = self
+            .client
+            .post(self.url(&format!("flow/{flow}/{id}/cancel")))
+            .bearer_auth(&self.config.token)
+            .send()?;
+        check_status(resp)?;
+        Ok(())
+    }
+
+    pub fn flow_pull(&self, flow: &str, job_id: &str) -> Result<Vec<u8>> {
+        let resp = self.get(&format!("flow/{flow}/job/{job_id}"))?;
+        Ok(resp.bytes()?.to_vec())
+    }
+
+    // ─── Package operations ───
+
+    pub fn list_packages(&self) -> Result<Vec<String>> {
+        let resp = self.get("package")?;
+        Ok(resp.json()?)
+    }
+
+    pub fn get_package(&self, package: &str) -> Result<Vec<u8>> {
+        let resp = self.get(&format!("package/{package}"))?;
+        Ok(resp.bytes()?.to_vec())
+    }
+
+    // ─── Flag operations ───
+
+    pub fn submit_flag(&self, flag: &str, body: &serde_json::Value) -> Result<String> {
+        let resp = self.post_json(&format!("flag/{flag}"), body)?;
+        Ok(resp.text()?)
+    }
+
+    pub fn submit_flag_file(&self, flag: &str, name: &str, data: Vec<u8>) -> Result<String> {
+        let resp = self.post_file(&format!("flag/{flag}"), name, data)?;
+        Ok(resp.text()?)
+    }
+}
+
+fn check_status(resp: reqwest::blocking::Response) -> Result<reqwest::blocking::Response> {
+    let status = resp.status();
+    let url = resp.url().to_string();
+    if status.is_success() {
+        return Ok(resp);
+    }
+    let code = status.as_u16();
+    let text = resp.text().unwrap_or_default();
+    log::debug(&format!("API {code} from {url}: {text}"));
+    // Try to extract {"detail": "..."} from JSON responses
+    let detail = serde_json::from_str::<serde_json::Value>(&text)
+        .ok()
+        .and_then(|v| v["detail"].as_str().map(|s| s.to_string()))
+        .unwrap_or(text);
+    match code {
+        401 => bail!("Authentication failed. Check your API token."),
+        _ => bail!("{detail}"),
+    }
+}
+
+// ─── Command implementations ───
+
+fn flow_overall_status(f: &Flow) -> String {
+    // Derive status from jobs like the Python tool does
+    if f.jobs.iter().any(|j| j.status == "failed") {
+        "Failed".to_string()
+    } else if f.completed {
+        "Succeeded".to_string()
+    } else if f.jobs.iter().any(|j| j.status == "running") {
+        "Running".to_string()
+    } else {
+        "Queued".to_string()
+    }
+}
+
+pub fn cmd_flow_list(flow: &str, count: usize) -> Result<()> {
+    let api = ApiClient::new()?;
+    let flows = api.flow_list(flow, count)?;
+    if flows.is_empty() {
+        log::info("No flows found");
+        return Ok(());
+    }
+
+    let flow_title = titlecase(flow);
+    let id_header = format!("{flow_title} ID");
+
+    // Calculate column widths
+    let id_w = flows.iter().map(|f| f.id.len()).max().unwrap_or(36).max(id_header.len());
+    let time_w = 14; // "When Submitted"
+    let status_w = 9;
+
+    let total = id_w + time_w + status_w + 10; // 10 for borders + padding
+    let title = format!("Submitted {flow_title} Flows");
+    let pad = total.saturating_sub(title.len()) / 2;
+
+    // Title
+    println!("{BOLD}{:>pad$}{title}{RESET}", "");
+    // Top border
+    println!("┏{:━<id_w$}━━┳{:━<time_w$}━━┳{:━<status_w$}━━┓", "", "", "");
+    // Header
+    println!(
+        "┃ {BOLD}{:<id_w$}{RESET} ┃ {BOLD}{:<time_w$}{RESET} ┃ {BOLD}{:<status_w$}{RESET} ┃",
+        id_header, "When Submitted", "Status"
+    );
+    // Header separator
+    println!("┡{:━<id_w$}━━╇{:━<time_w$}━━╇{:━<status_w$}━━┩", "", "", "");
+
+    for f in &flows {
+        let status = flow_overall_status(f);
+        let sc = status_color(&status.to_lowercase());
+        let when = relative_time(&f.submit_time);
+        println!(
+            "│ {:<id_w$} │ {:<time_w$} │ {sc}{:<status_w$}{RESET} │",
+            f.id, when, status
+        );
+    }
+
+    // Bottom border
+    println!("└{:─<id_w$}──┴{:─<time_w$}──┴{:─<status_w$}──┘", "", "", "");
+
+    Ok(())
+}
+
+pub fn cmd_flow_info(flow: &str, id: &str) -> Result<()> {
+    let api = ApiClient::new()?;
+    let f = api.flow_info(flow, id)?;
+    let status = flow_overall_status(&f);
+    let sc = status_color(&status.to_lowercase());
+    let when = relative_time(&f.submit_time);
+
+    println!("{BOLD}{UNDERLINE}Flow {flow}{RESET}");
+    println!("├── ID: {}", highlight(&f.id));
+    // Format like Python: "2026-02-11 22:05:47+00:00"
+    let display_time = f.submit_time
+        .replace('T', " ")
+        .split('.')
+        .next()
+        .unwrap_or(&f.submit_time)
+        .to_string()
+        + "+00:00";
+    println!("├── Submitted: {} ({when})", highlight(&display_time));
+    println!("├── Status: {sc}{status}{RESET}");
+
+    // Parameters
+    if let Some(obj) = f.params.as_object() {
+        if !obj.is_empty() {
+            println!("├── Parameters");
+            let params: Vec<_> = obj.iter().collect();
+            for (i, (k, v)) in params.iter().enumerate() {
+                let connector = if i == params.len() - 1 { "└" } else { "├" };
+                let fallback = v.to_string();
+                let val = v.as_str().unwrap_or(&fallback);
+                println!("│   {connector}── {k}: {}", highlight(val));
+            }
+        }
+    }
+
+    // Jobs
+    if !f.jobs.is_empty() {
+        println!("└── Jobs");
+        for (i, job) in f.jobs.iter().enumerate() {
+            let is_last = i == f.jobs.len() - 1;
+            let branch = if is_last { "└" } else { "├" };
+            let prefix = if is_last { " " } else { "│" };
+            let jsc = status_color(&job.status);
+            println!("    {branch}── {BOLD}{}{RESET}", job.name);
+            println!("    {prefix}   ├── ID: {}", highlight(&job.id));
+            println!("    {prefix}   ├── Has Output: {}", highlight(&titlecase(&job.has_artifacts.to_string())));
+            println!("    {prefix}   ├── Private: {}", highlight(&titlecase(&job.private.to_string())));
+            println!("    {prefix}   └── Status: {jsc}{}{RESET}", titlecase(&job.status));
+        }
+    }
+
+    Ok(())
+}
+
+pub fn cmd_flow_submit(flow: &str, commit: &str, url: Option<&str>) -> Result<()> {
+    let api = ApiClient::new()?;
+    let git_url = url
+        .map(|s| s.to_string())
+        .unwrap_or_else(|| api.config.git_url.clone());
+    let body = serde_json::json!({
+        "git_url": git_url,
+        "commit_hash": commit,
+    });
+    let id = api.flow_submit(flow, &body)?;
+    log::success(&format!("Submitted {flow} flow: {id}"));
+    Ok(())
+}
+
+pub fn cmd_flow_cancel(flow: &str, id: &str) -> Result<()> {
+    let api = ApiClient::new()?;
+    api.flow_cancel(flow, id)?;
+    log::success(&format!("Cancelled flow {id}"));
+    Ok(())
+}
+
+pub fn cmd_flow_get(flow: &str, job_id: &str, out: &PathBuf) -> Result<()> {
+    let api = ApiClient::new()?;
+    let data = api.flow_pull(flow, job_id)?;
+    std::fs::write(out, &data)?;
+    log::success(&format!("Downloaded to {}", out.display()));
+    Ok(())
+}
+
+pub fn cmd_submit(commit: &str) -> Result<()> {
+    cmd_flow_submit("submit", commit, None)
+}
+
+pub fn cmd_photo(file: &PathBuf) -> Result<()> {
+    let api = ApiClient::new()?;
+    let data = std::fs::read(file).context("Failed to read file")?;
+    let name = file
+        .file_name()
+        .context("No filename")?
+        .to_str()
+        .context("Invalid filename")?;
+    let resp = api.submit_flag_file("photo", name, data)?;
+    log::success(&format!("Photo submitted: {resp}"));
+    Ok(())
+}
+
+pub fn cmd_design(file: &PathBuf) -> Result<()> {
+    let api = ApiClient::new()?;
+    let data = std::fs::read(file).context("Failed to read file")?;
+    let name = file
+        .file_name()
+        .context("No filename")?
+        .to_str()
+        .context("Invalid filename")?;
+    let resp = api.submit_flag_file("design", name, data)?;
+    log::success(&format!("Design doc submitted: {resp}"));
+    Ok(())
+}
+
+pub fn cmd_steal(team: &str, digest: &str) -> Result<()> {
+    let api = ApiClient::new()?;
+    let body = serde_json::json!({
+        "team": team,
+        "digest": digest,
+    });
+    let resp = api.submit_flag("steal", &body)?;
+    log::success(&format!("Steal submitted: {resp}"));
+    Ok(())
+}
+
+pub fn cmd_list_packages() -> Result<()> {
+    let api = ApiClient::new()?;
+    let packages = api.list_packages()?;
+    if packages.is_empty() {
+        log::info("No packages available");
+    } else {
+        for p in &packages {
+            log::info(p);
+        }
+    }
+    Ok(())
+}
+
+pub fn cmd_get_package(package: &str, out: Option<&PathBuf>, force: bool) -> Result<()> {
+    let api = ApiClient::new()?;
+    let data = api.get_package(package)?;
+    let path = out.cloned().unwrap_or_else(|| PathBuf::from(package));
+    if !force && path.exists() {
+        bail!(
+            "File {} already exists (use --force to overwrite)",
+            path.display()
+        );
+    }
+    std::fs::write(&path, &data)?;
+    log::success(&format!("Downloaded {} to {}", package, path.display()));
+    Ok(())
+}
+
+// ─── Remote scenario ───
+
+const REMOTE_HOST: &str = "54.163.176.58";
+
+pub fn cmd_remote_connect(
+    mgmt_port: &str,
+    transfer_port: &str,
+    team: &str,
+    timeout: u64,
+) -> Result<()> {
+    let api = ApiClient::new()?;
+
+    // Submit remote flow
+    let body = serde_json::json!({"team": team});
+    let flow_id = api.flow_submit("remote", &body)?;
+    log::info(&format!("Submitted remote flow: {flow_id}"));
+
+    // Poll for get_ports job
+    log::info("Waiting for port assignment...");
+    let port: u16 = loop {
+        std::thread::sleep(Duration::from_secs(3));
+        let flow = api.flow_info("remote", &flow_id)?;
+        if let Some(job) = flow.jobs.iter().find(|j| j.name == "get_ports") {
+            match job.status.as_str() {
+                "succeeded" => {
+                    let data = api.flow_pull("remote", &job.id)?;
+                    let port_str = String::from_utf8(data)?.trim().to_string();
+                    break port_str.parse().context("Invalid port number")?;
+                }
+                "canceled" | "failed" => bail!("Port assignment failed"),
+                _ => continue,
+            }
+        }
+    };
+
+    log::info(&format!("Assigned port {port}, connecting..."));
+
+    // Connect to remote server
+    let tcp = TcpStream::connect((REMOTE_HOST, port)).context("Failed to connect to remote")?;
+    tcp.set_nodelay(true)?;
+    log::success("Connected to remote server");
+
+    // Open serial ports
+    let transfer_file = serial::open_serial(transfer_port, None)?;
+    let mgmt_port_str = mgmt_port.to_string();
+
+    let done = Arc::new(AtomicBool::new(false));
+
+    // Bridge: TCP → transfer serial
+    let tcp_r = tcp.try_clone()?;
+    let mut transfer_w = transfer_file.try_clone()?;
+    let done1 = done.clone();
+    let h1 = std::thread::spawn(move || {
+        let mut reader = tcp_r;
+        let mut buf = [0u8; 4096];
+        while !done1.load(Ordering::Relaxed) {
+            match reader.read(&mut buf) {
+                Ok(0) => break,
+                Ok(n) => {
+                    if transfer_w.write_all(&buf[..n]).is_err() {
+                        break;
+                    }
+                }
+                Err(_) => break,
+            }
+        }
+    });
+
+    // Bridge: transfer serial → TCP
+    let mut tcp_w = tcp.try_clone()?;
+    let done2 = done.clone();
+    let h2 = std::thread::spawn(move || {
+        let mut reader = transfer_file;
+        let mut buf = [0u8; 4096];
+        while !done2.load(Ordering::Relaxed) {
+            match reader.read(&mut buf) {
+                Ok(0) => continue,
+                Ok(n) => {
+                    if tcp_w.write_all(&buf[..n]).is_err() {
+                        break;
+                    }
+                }
+                Err(_) => break,
+            }
+        }
+    });
+
+    // HSM listen on management port
+    let done3 = done.clone();
+    let h3 = std::thread::spawn(move || {
+        if done3.load(Ordering::Relaxed) {
+            return;
+        }
+        match HSMIntf::open(&mgmt_port_str) {
+            Ok(mut hsm) => {
+                let _ = hsm.send_respond(Opcode::Listen, &[]);
+            }
+            Err(e) => log::warning(&format!("Management port error: {e}")),
+        }
+    });
+
+    // Poll flow status with timeout
+    let start = Instant::now();
+    let timeout_dur = Duration::from_secs(timeout);
+    loop {
+        std::thread::sleep(Duration::from_secs(3));
+        if start.elapsed() > timeout_dur {
+            log::warning("Remote scenario timed out");
+            break;
+        }
+        match api.flow_info("remote", &flow_id) {
+            Ok(flow) => {
+                if let Some(job) = flow
+                    .jobs
+                    .iter()
+                    .find(|j| j.name == "run_remote_scenario")
+                {
+                    match job.status.as_str() {
+                        "succeeded" => {
+                            log::success("Remote scenario completed successfully");
+                            break;
+                        }
+                        "canceled" | "failed" => {
+                            log::error("Remote scenario failed");
+                            break;
+                        }
+                        _ => {
+                            log::debug(&format!("Scenario status: {}", job.status));
+                        }
+                    }
+                }
+            }
+            Err(e) => log::warning(&format!("Failed to check status: {e}")),
+        }
+    }
+
+    done.store(true, Ordering::Relaxed);
+
+    // Shutdown TCP to unblock threads
+    let _ = tcp.shutdown(std::net::Shutdown::Both);
+
+    let _ = h1.join();
+    let _ = h2.join();
+    let _ = h3.join();
+
+    Ok(())
+}

src/config.rs

@@ -0,0 +1,46 @@
+use anyhow::{Context, Result};
+use serde::{Deserialize, Serialize};
+use std::path::PathBuf;
+
+pub const DEFAULT_API_URL: &str = "https://api.ectf.mitre.org";
+
+#[derive(Debug, Serialize, Deserialize)]
+pub struct Config {
+    pub token: String,
+    pub git_url: String,
+    #[serde(default = "default_api_url")]
+    pub api_url: String,
+}
+
+fn default_api_url() -> String {
+    DEFAULT_API_URL.to_string()
+}
+
+impl Config {
+    pub fn path() -> Result<PathBuf> {
+        let home = std::env::var("HOME").context("HOME not set")?;
+        Ok(PathBuf::from(home).join(".ectf-config"))
+    }
+
+    pub fn exists() -> bool {
+        Self::path().map(|p| p.exists()).unwrap_or(false)
+    }
+
+    pub fn load() -> Result<Self> {
+        let path = Self::path()?;
+        let contents = std::fs::read_to_string(&path).with_context(|| {
+            format!(
+                "Config not found at {}. Run `ectf-tools config` first.",
+                path.display()
+            )
+        })?;
+        serde_yaml::from_str(&contents).context("Failed to parse config file")
+    }
+
+    pub fn save(&self) -> Result<()> {
+        let path = Self::path()?;
+        let contents = serde_yaml::to_string(self)?;
+        std::fs::write(&path, contents)?;
+        Ok(())
+    }
+}

src/main.rs

@@ -1,3 +1,5 @@
+mod api;
+mod config;
 mod fthr;
 mod log;
 mod protocol;
@@ -68,6 +70,164 @@ enum TopLevel {
         /// Shell to generate completions for
         shell: Shell,
     },
+    /// Create or update the configuration file
+    Config {
+        /// Team API token
+        #[arg(long)]
+        token: Option<String>,
+        /// Git repository URL
+        #[arg(long)]
+        git_url: Option<String>,
+        /// API URL
+        #[arg(long)]
+        api_url: Option<String>,
+        /// Overwrite existing config
+        #[arg(short, long)]
+        force: bool,
+    },
+    /// Open the API documentation website
+    Docs,
+    /// Open the eCTF rules website
+    Rules,
+    /// Interact with the API
+    #[command(arg_required_else_help = true)]
+    Api {
+        #[command(subcommand)]
+        command: ApiCmd,
+    },
+}
+
+// ─── API subcommands ───
+
+#[derive(Subcommand)]
+enum ApiCmd {
+    /// Submit your design to Handoff
+    Submit {
+        /// Git commit hash
+        commit: String,
+    },
+    /// Submit a PNG for the Team Photo flag
+    Photo {
+        /// PNG file to submit
+        file: PathBuf,
+    },
+    /// Submit a PDF for the Design Doc flag
+    Design {
+        /// PDF file to submit
+        file: PathBuf,
+    },
+    /// Submit a digest for the Steal Design flag
+    Steal {
+        /// Target team identifier
+        team: String,
+        /// Hex digest string
+        digest: String,
+    },
+    /// Get the list of available packages
+    List,
+    /// Download an Attack Package
+    Get {
+        /// Package name
+        package: String,
+        /// Output path
+        #[arg(short, long)]
+        out: Option<PathBuf>,
+        /// Overwrite if file exists
+        #[arg(short, long)]
+        force: bool,
+    },
+    /// Test that your design can be cloned by the API
+    #[command(arg_required_else_help = true)]
+    Clone {
+        #[command(subcommand)]
+        command: FlowCmd,
+    },
+    /// Test your design with the API
+    #[command(arg_required_else_help = true)]
+    Test {
+        #[command(subcommand)]
+        command: FlowCmd,
+    },
+    /// Submit to the remote attack scenario
+    #[command(arg_required_else_help = true)]
+    Remote {
+        #[command(subcommand)]
+        command: RemoteCmd,
+    },
+}
+
+#[derive(Subcommand)]
+enum FlowCmd {
+    /// List recent flows
+    Ls {
+        /// Number of flows to show (0 for all)
+        #[arg(short, long, default_value = "5")]
+        number: usize,
+    },
+    /// Get flow details
+    Info {
+        /// Flow ID
+        id: String,
+    },
+    /// Submit a commit
+    Submit {
+        /// Git commit hash
+        commit: String,
+        /// Override git URL
+        #[arg(short, long)]
+        url: Option<String>,
+    },
+    /// Cancel a flow
+    Cancel {
+        /// Flow ID
+        id: String,
+    },
+    /// Download job output
+    Get {
+        /// Job ID
+        job_id: String,
+        /// Output file path
+        out: PathBuf,
+    },
+}
+
+#[derive(Subcommand)]
+enum RemoteCmd {
+    /// Connect to the remote attack scenario
+    Connect {
+        /// HSM management serial port
+        management_port: String,
+        /// Transfer interface UART port
+        transfer_port: String,
+        /// Target team identifier
+        team: String,
+        /// Timeout in seconds
+        #[arg(short, long, default_value = "120")]
+        timeout: u64,
+    },
+    /// List recent remote flows
+    Ls {
+        /// Number of flows to show (0 for all)
+        #[arg(short, long, default_value = "5")]
+        number: usize,
+    },
+    /// Get remote flow details
+    Info {
+        /// Flow ID
+        id: String,
+    },
+    /// Cancel a remote flow
+    Cancel {
+        /// Flow ID
+        id: String,
+    },
+    /// Download remote job output
+    Get {
+        /// Job ID
+        job_id: String,
+        /// Output file path
+        out: PathBuf,
+    },
 }
 
 // ─── Tools subcommands ───
@@ -273,14 +433,169 @@ fn main() {
     }
 }
 
+fn open_url(url: &str) -> Result<()> {
+    #[cfg(target_os = "macos")]
+    {
+        std::process::Command::new("open").arg(url).spawn()?;
+    }
+    #[cfg(not(target_os = "macos"))]
+    {
+        std::process::Command::new("xdg-open").arg(url).spawn()?;
+    }
+    Ok(())
+}
+
 fn run(cli: Cli) -> Result<()> {
     match cli.command {
         TopLevel::Tools { port, command } => run_tools(&port, command),
         TopLevel::Hw { port, command } => run_hw(&port, command),
         TopLevel::Completions { shell } => {
-            clap_complete::generate(shell, &mut Cli::command(), "ectf-tools", &mut std::io::stdout());
+            clap_complete::generate(
+                shell,
+                &mut Cli::command(),
+                "ectf-tools",
+                &mut std::io::stdout(),
+            );
             Ok(())
         }
+        TopLevel::Config {
+            token,
+            git_url,
+            api_url,
+            force,
+        } => run_config(token, git_url, api_url, force),
+        TopLevel::Docs => {
+            open_url("https://sb.ectf.mitre.org/")?;
+            log::success("Opened API documentation");
+            Ok(())
+        }
+        TopLevel::Rules => {
+            open_url("https://rules.ectf.mitre.org/")?;
+            log::success("Opened eCTF rules");
+            Ok(())
+        }
+        TopLevel::Api { command } => run_api(command),
+    }
+}
+
+// ─── Config ───
+
+fn prompt(label: &str, default: Option<&str>) -> Result<String> {
+    use std::io::Write;
+    match default {
+        Some(d) => eprint!("{label} [{d}]: "),
+        None => eprint!("{label}: "),
+    }
+    std::io::stderr().flush()?;
+    let mut input = String::new();
+    std::io::stdin().read_line(&mut input)?;
+    let input = input.trim().to_string();
+    if input.is_empty() {
+        default
+            .map(|d| d.to_string())
+            .context(format!("{label} is required"))
+    } else {
+        Ok(input)
+    }
+}
+
+fn run_config(
+    token: Option<String>,
+    git_url: Option<String>,
+    api_url: Option<String>,
+    force: bool,
+) -> Result<()> {
+    let has_args = token.is_some() || git_url.is_some() || api_url.is_some() || force;
+
+    // No args: print existing config or prompt for new one
+    if !has_args && config::Config::exists() {
+        let cfg = config::Config::load()?;
+        log::info(&format!("token:   {}", cfg.token));
+        log::info(&format!("git_url: {}", cfg.git_url));
+        log::info(&format!("api_url: {}", cfg.api_url));
+        return Ok(());
+    }
+
+    let existing = if config::Config::exists() && !force {
+        Some(config::Config::load()?)
+    } else {
+        None
+    };
+
+    let token = match token {
+        Some(t) => t,
+        None => prompt("Token", existing.as_ref().map(|c| c.token.as_str()))?,
+    };
+    let git_url = match git_url {
+        Some(g) => g,
+        None => prompt("Git URL", existing.as_ref().map(|c| c.git_url.as_str()))?,
+    };
+    let api_url = match api_url {
+        Some(a) => a,
+        None => prompt(
+            "API URL",
+            Some(
+                existing
+                    .as_ref()
+                    .map(|c| c.api_url.as_str())
+                    .unwrap_or(config::DEFAULT_API_URL),
+            ),
+        )?,
+    };
+
+    config::Config { token, git_url, api_url }.save()?;
+
+    log::success(&format!(
+        "Config saved to {}",
+        config::Config::path()?.display()
+    ));
+    Ok(())
+}
+
+// ─── API commands ───
+
+fn run_api(cmd: ApiCmd) -> Result<()> {
+    match cmd {
+        ApiCmd::Submit { commit } => api::cmd_submit(&commit),
+        ApiCmd::Photo { file } => api::cmd_photo(&file),
+        ApiCmd::Design { file } => api::cmd_design(&file),
+        ApiCmd::Steal { team, digest } => api::cmd_steal(&team, &digest),
+        ApiCmd::List => api::cmd_list_packages(),
+        ApiCmd::Get {
+            package,
+            out,
+            force,
+        } => api::cmd_get_package(&package, out.as_ref(), force),
+        ApiCmd::Clone { command } => run_flow("clone", command),
+        ApiCmd::Test { command } => run_flow("test", command),
+        ApiCmd::Remote { command } => run_remote(command),
+    }
+}
+
+fn run_flow(flow: &str, cmd: FlowCmd) -> Result<()> {
+    match cmd {
+        FlowCmd::Ls { number } => api::cmd_flow_list(flow, number),
+        FlowCmd::Info { id } => api::cmd_flow_info(flow, &id),
+        FlowCmd::Submit { commit, url } => {
+            api::cmd_flow_submit(flow, &commit, url.as_deref())
+        }
+        FlowCmd::Cancel { id } => api::cmd_flow_cancel(flow, &id),
+        FlowCmd::Get { job_id, out } => api::cmd_flow_get(flow, &job_id, &out),
+    }
+}
+
+fn run_remote(cmd: RemoteCmd) -> Result<()> {
+    match cmd {
+        RemoteCmd::Connect {
+            management_port,
+            transfer_port,
+            team,
+            timeout,
+        } => api::cmd_remote_connect(&management_port, &transfer_port, &team, timeout),
+        RemoteCmd::Ls { number } => api::cmd_flow_list("remote", number),
+        RemoteCmd::Info { id } => api::cmd_flow_info("remote", &id),
+        RemoteCmd::Cancel { id } => api::cmd_flow_cancel("remote", &id),
+        RemoteCmd::Get { job_id, out } => api::cmd_flow_get("remote", &job_id, &out),
     }
 }