diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml new file mode 100644 index 0000000..904588f --- /dev/null +++ b/.github/workflows/codeql.yml @@ -0,0 +1,52 @@ +name: CodeQL + +# M064: weekly code scanning for Rust and GitHub Actions workflow surfaces. +permissions: + contents: read + security-events: write + +on: + push: + branches: [main] + pull_request: + schedule: + - cron: "31 4 * * 1" + +concurrency: + group: codeql-${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + analyze: + name: CodeQL (${{ matrix.language }}) + timeout-minutes: 35 + runs-on: ubuntu-latest + strategy: + fail-fast: false + matrix: + include: + - language: rust + build_mode: none + - language: actions + build_mode: none + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - uses: dtolnay/rust-toolchain@df2a88e9fe4098bad09cb42c3dec7187f15861fc # stable (master 2026-11-15) + if: matrix.language == 'rust' + with: + toolchain: 1.89.0 + components: rust-analyzer + # Rust CodeQL uses its supported `none` build mode. This separate + # locked check still exercises the whole workspace with the pinned MSRV. + - name: Check Rust workspace with pinned toolchain + if: matrix.language == 'rust' + run: cargo check --workspace --all-targets --all-features --locked + - uses: github/codeql-action/init@33d7b85da1a04171e211befe2c739303b9a4c066 # v4.39.3 + with: + languages: ${{ matrix.language }} + build-mode: ${{ matrix.build_mode }} + - uses: github/codeql-action/analyze@33d7b85da1a04171e211befe2c739303b9a4c066 # v4.39.3 + with: + category: /language:${{ matrix.language }} diff --git a/AGENTS.md b/AGENTS.md index 0db036c..52bfd80 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -69,7 +69,7 @@ Qualification (release workflow): `release-smoke.sh` (fmt/clippy/test/doc/audit/ ## Planning state -M000–M062 are closed with no active, ready, or blocked milestone. M062 closed the v0.2.1 release from exact candidate `b0bc9b1c3aeac6855ea4b82ea71a78f141197828` with ordinary hosted CI `43516207980` (15/15), pre-tag release dispatch `43517314319` (7/7), and tag-triggered release `43520281822` (7/7). All eight Rust workspace crates and five qualified binary/checksum pairs are published, and a clean-cache CLI install reports `0.2.1`. M058 remains the historical v0.2.0 publication authority and M059 the pre-publication hardening authority. Language-registry publication remains separately gated per package; `eggchaos-native` remains deferred under M058. Full release evidence is in `plans/closure/M062-v0-2-1-patch-release-closure.md`. +M000–M062 are closed; M063 and M065 are active, while M064 is blocked by unavailable GitHub Free-plan security features (see `plans/registry.md`). M062 closed the v0.2.1 release from exact candidate `b0bc9b1c3aeac6855ea4b82ea71a78f141197828` with ordinary hosted CI `43516207980` (15/15), pre-tag release dispatch `43517314319` (7/7), and tag-triggered release `43520281822` (7/7). All eight Rust workspace crates and five qualified binary/checksum pairs are published, and a clean-cache CLI install reports `0.2.1`. M058 remains the historical v0.2.0 publication authority and M059 the pre-publication hardening authority. Language-registry publication remains separately gated per package; `eggchaos-native` remains deferred under M058. Full release evidence is in `plans/closure/M062-v0-2-1-patch-release-closure.md`. If the owner asks for new work: `plans/roadmap.md` is the architecture authority, `plans/reference/` holds parity/verification contracts (not status), ADRs live in `plans/adrs/`. Any new numbered plan needs objective, baseline/deps, scope + non-goals, affected crates, ordered work packages, invariants/failure semantics, test commands, acceptance criteria, stop conditions, closure evidence, and follow-on rules — and must update `plans/registry.md` in the same change. `plans/registry.md` is the sole hand-maintained milestone-status authority (vocabulary: `active`, `blocked`, `closed`, `ready`); the `Current planning state` blocks in AGENTS.md / `plans/README.md` / `plans/roadmap.md` / `architecture/overview.md` are generated projections, never independent authorities, and each numbered plan's own top-level `Status:` header is a checked projection that must agree with its registry row (M061). After any registry edit: 1. add/update the numbered plan; 2. update `registry.md`; 3. run `python3 scripts/check_planning_state.py --write`; 4. run `sh scripts/tests/test_planning_state.sh`. Never mark `closed` from source inspection; closure requires running the plan's tests on the exact candidate plus external/differential evidence where declared. @@ -87,8 +87,15 @@ Prefer deterministic Tokio-time tests; wall-clock assertions need justified tole ## Current planning state +**Active (in flight):** +- `M063` (active; plan `063-control-plane-exposure-and-authentication-hardening.md`) +- `M065` (active; plan `065-residual-runtime-and-qualification-tooling-hardening.md`) + +**Blocked (waiting on a predecessor closure):** +- M064 + **Highest closed milestone:** `M062` (see registry for closure evidence). -**Execution order:** no active or ready milestones. +**Execution order:** `M063`, `M065` diff --git a/README.md b/README.md index e84d39c..2310c67 100644 --- a/README.md +++ b/README.md @@ -133,7 +133,11 @@ See [configuration](docs/configuration.md) for TOML fields, [control plane](docs | [Toxiproxy](docs/toxiproxy.md) | Compatibility profiles and differences | | [Eggfetch](docs/eggfetch.md) | In-process transport integration | -The admin listener binds to loopback by default. For non-loopback access, configure `public_admin = true` and a non-empty `auth_token` in `[admin]`. The listener uses HTTP, so protect remote access with a trusted TLS terminator and network controls. The CLI's `--admin-token` option and `EGGCHAOS_ADMIN_TOKEN` environment variable send credentials to an existing admin service; they do not configure the service listener. +## Security boundaries + +The native admin listener is unauthenticated on loopback by default; treat that as a same-user trust boundary. Non-loopback access requires `public_admin = true` and a bearer token with at least 32 non-whitespace bytes. Requests are checked against the bind-derived `Host` set or exact `[admin].allowed_hosts`; mutations also validate any present `Origin`, and non-empty bodies require JSON media type. The listener is cleartext HTTP, so protect remote access with a trusted TLS terminator and network controls. The CLI's `--admin-token` value may appear in local process listings; prefer `EGGCHAOS_ADMIN_TOKEN` or a protected secret mechanism and avoid shell history. The Toxiproxy compatibility API is unauthenticated and loopback-only unless the caller explicitly opts into public binding; that opt-in does not add TLS or authentication. See [admin configuration](docs/configuration.md#admin-listener), [control-plane security](docs/control-plane.md), and [Toxiproxy exposure](docs/toxiproxy.md). + +Repository governance uses active `main` and release-tag rulesets: `main` requires pull requests, current required checks, linear history, and resolved review threads, with a sole-maintainer bypass limited to pull requests; release tags are restricted to the release owner. Secret scanning, push protection, Dependabot alerts, and Dependabot security updates are enabled. Non-provider pattern scanning and validity checks are not available on the organization’s current GitHub Free plan. The pinned CodeQL workflow has been added to the candidate but still requires an exact-head hosted run before its analysis is considered verified. See [the security policy](SECURITY.md) for current readbacks and limitations. ## License diff --git a/SECURITY.md b/SECURITY.md index cb04900..a440979 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -44,6 +44,44 @@ unavailable on this repository, open a minimal public issue that describes only the affected area and asks for a private contact — never the vulnerability details themselves. +## Repository safeguards and dependency triage + +The repository requires pull requests for `main`, current required CI and +dependency-review checks, linear history, and resolved review conversations; +force-push and branch deletion are blocked. A `v*.*.*` release-tag ruleset +blocks creation, updates, and deletion except for the designated release +maintainer. The repository currently has one returned admin collaborator, so +an independent approval is not required or claimed. The maintainer's `main` +bypass is limited to pull requests; the tag bypass is limited to the release +maintainer. + +Dependabot vulnerability alerts and security updates are enabled. Secret +scanning and push protection are enabled. The GitHub API readback still reports +non-provider pattern scanning and validity checks as disabled after a +repository-settings update request. The organization API reports a `Free` plan; +GitHub documents non-provider pattern scanning for organization-owned +repositories with GitHub Team and Secret Protection, and validity checks for +GitHub Team or Enterprise accounts. These controls are not represented as +active. See [GitHub's non-provider pattern availability](https://docs.github.com/en/code-security/secret-scanning/using-advanced-secret-scanning-and-push-protection-features/non-provider-patterns) +and [supported secret-scanning patterns](https://docs.github.com/en/code-security/reference/secret-security/supported-secret-scanning-patterns). + +A pinned CodeQL workflow has been added to the current candidate, but has no +hosted run or code-scanning result yet; do not treat CodeQL analysis as active +until it runs successfully on the exact candidate SHA. The repository's +current active rulesets and security settings can be checked with +`scripts/check_repository_security_state.py` after that workflow is present on +GitHub. + +Triage every open dependency alert against the named manifest and committed +lockfile. Apply a compatible fix when available. If the dependency cannot be +reproduced from the lockfile, keep the alert open while recording the evidence +and investigating the GitHub alert metadata; do not dismiss an unreproduced +alert merely to clear the count. Rust advisories are additionally checked +against all four Cargo lockfiles by the scheduled audit workflow. The PR +dependency-review threshold remains `high`; Python clients are stdlib-only, +Python build/test tooling is exactly pinned, and the TypeScript client has no +runtime dependencies. + ## Scope notes Out-of-scope reports include: the documented developer-mode behavior diff --git a/api/openapi/eggchaos-v1.yaml b/api/openapi/eggchaos-v1.yaml index 4e606f5..060fd0e 100644 --- a/api/openapi/eggchaos-v1.yaml +++ b/api/openapi/eggchaos-v1.yaml @@ -727,7 +727,7 @@ components: code: type: string description: Stable machine code. - enum: [not_found, conflict, invalid, invalid_json, unauthorized, bind_failed, restart_failed, serialization] + enum: [not_found, conflict, invalid, invalid_json, unauthorized, invalid_host, invalid_origin, unsupported_media_type, bind_failed, restart_failed, serialization] message: type: string description: Bounded human detail; never echoes bearer tokens. diff --git a/architecture/overview.md b/architecture/overview.md index 555d7ba..959c424 100644 --- a/architecture/overview.md +++ b/architecture/overview.md @@ -62,7 +62,7 @@ work supersedes them: for that DAG — it closed without hosted CI on its exact implementation SHA, which is exactly why M057 exists. - **M061 is closed** as the M060 closure-evidence/plan-status consistency corrective, on exact candidate `9791375` with hosted run `37366364200` green 15/15. It changed planning/evidence guards only and reconciled the M060 hosted-CI lineage plus 24 divergent plan headers; production and release surfaces stayed frozen. -- **M062 closed** the `v0.2.1` patch release on exact candidate `b0bc9b1` (ordinary CI `43516207980`, 15/15; pre-tag dispatch `43517314319`, 7/7; tag release `43520281822`, 7/7). It published the eight Rust crates, attached the five tag-run binaries and checksums, verified a clean-cache CLI install, and reconciled current release documentation. M000–M062 are closed; no milestone is active or ready. +- **M062 closed** the `v0.2.1` patch release on exact candidate `b0bc9b1` (ordinary CI `43516207980`, 15/15; pre-tag dispatch `43517314319`, 7/7; tag release `43520281822`, 7/7). It published the eight Rust crates, attached the five tag-run binaries and checksums, verified a clean-cache CLI install, and reconciled current release documentation. M000–M062 are closed; M063 and M065 are active, and M064 is blocked by unavailable GitHub Free-plan security features (see `plans/registry.md`). - **M060 closed** the post-release documentation/status and drift-guard cleanup corrective (candidate `e897cc4`). It changed no Rust source, manifest, lockfile, OpenAPI, generated contract, or package version; it added @@ -329,8 +329,15 @@ python3 scripts/check_version_coherence.py --check # M055 version coherence (ch ## Current planning state +**Active (in flight):** +- `M063` (active; plan `063-control-plane-exposure-and-authentication-hardening.md`) +- `M065` (active; plan `065-residual-runtime-and-qualification-tooling-hardening.md`) + +**Blocked (waiting on a predecessor closure):** +- M064 + **Highest closed milestone:** `M062` (see registry for closure evidence). -**Execution order:** no active or ready milestones. +**Execution order:** `M063`, `M065` diff --git a/architecture/tooling-distribution.md b/architecture/tooling-distribution.md index 3113b1c..eb1b499 100644 --- a/architecture/tooling-distribution.md +++ b/architecture/tooling-distribution.md @@ -215,6 +215,55 @@ candidate (see §3). (typescript-client), and pip (`.github/python-ci`, python-native, python-client) with weekly updates and bounded PR counts. +### M064 repository security controls + +The repository-scoped `main-protection` ruleset is active. It requires a PR, +linear history, resolved review conversations, and the successful check +contexts observed on the latest green `main` CI run plus the observed +Dependency review job (`review`); it blocks force-push and deletion. The only +returned admin collaborator is `dbowm91`, so the required approval count is +zero rather than implying independent review. That user is the sole configured +`main` bypass actor, restricted to pull requests. The active +`release-tag-protection` ruleset covers `refs/tags/v*.*.*` and blocks creation, +update, and deletion except for the same release maintainer. + +Repository API readbacks report secret scanning, push protection, Dependabot +vulnerability alerts, and Dependabot security updates enabled. The +vulnerability-alert endpoint returns `204`, GitHub's documented enabled +response. The Dependabot open-alert list is empty; the four committed Cargo +lockfiles passed `cargo audit --deny warnings` during M064 triage, so no alert +was dismissed. The earlier three-vulnerability push-metadata count remains +unreproduced by the committed lockfiles or the enabled open-alert list. + +Non-provider pattern scanning and validity checks remain disabled: the +repository API left both disabled after repository-admin updates. GitHub +currently gates non-provider scanning and validity checks on an organization +Secret Protection entitlement (Team/Enterprise, depending on feature). No +organization-wide setting was changed; these are an explicit plan/entitlement +blocker, not enabled controls. + +`.github/workflows/codeql.yml` analyzes Rust and Actions workflow surfaces on +`main` pushes, pull requests, and a weekly schedule. It pins +`github/codeql-action` v4.39.3 (`33d7b85da1a04171e211befe2c739303b9a4c066`), +uses only `contents: read` and `security-events: write`, checks out without +persisted credentials, and separately runs the full workspace `cargo check` +under Rust 1.89. CodeQL's Rust database uses its documented `none` build mode; +GitHub-hosted analysis and the resulting check contexts have not yet run from +this local uncommitted workflow. The ruleset therefore contains only observed +check names; add the exact CodeQL contexts after the first hosted run rather +than predicting them. + +The dependency-review threshold remains `high`: `cargo audit --deny warnings` +and `cargo-deny` cover Rust advisory severities across committed lockfiles. +No separate `pip-audit` tool was added: Python clients are stdlib-only and +build/test requirements are pinned and Dependabot-managed; the TypeScript +client has no runtime dependencies, and its lockfile/tooling changes remain +covered by Dependabot and PR dependency review. The manual, read-only API +readback is `python3 scripts/check_repository_security_state.py --repo +eggstack/eggchaos`; run it with an authenticated `gh` session after the +CodeQL workflow is present on GitHub. It is intentionally not wired into PR CI +with a privileged token. + ## 3. Release qualification (`.github/workflows/release.yml`) - Triggers: `workflow_dispatch` (manual) and `push` tags `v*.*.*`. diff --git a/crates/eggchaos-cli/src/main.rs b/crates/eggchaos-cli/src/main.rs index 0a33db5..23c0204 100644 --- a/crates/eggchaos-cli/src/main.rs +++ b/crates/eggchaos-cli/src/main.rs @@ -916,7 +916,7 @@ fn build_kind( } async fn serve(path: PathBuf) -> Result<(), Box> { - let config = NativeConfig::load(path).await?; + let (config, allowed_hosts) = NativeConfig::load_with_admin_allowed_hosts(path).await?; let proxies = config.compile_proxies()?; let datagram_proxies = config.compile_datagram_proxies()?; let runtime = config.runtime; @@ -943,13 +943,14 @@ async fn serve(path: PathBuf) -> Result<(), Box> { ) .build()?; let handle = service.start().await?; - let mut admin = NativeAdmin::start( + let mut admin = NativeAdmin::start_with_allowed_hosts( AdminConfig { bind: config.admin.bind, public_admin: config.admin.public_admin, auth_token: config.admin.auth_token, }, handle.control_state(), + allowed_hosts, ) .await?; eprintln!("eggchaos listening; admin={}", admin.local_addr()); diff --git a/crates/eggchaos-server/src/admin.rs b/crates/eggchaos-server/src/admin.rs index a25662d..b8a0191 100644 --- a/crates/eggchaos-server/src/admin.rs +++ b/crates/eggchaos-server/src/admin.rs @@ -1,4 +1,10 @@ -use std::{io, net::SocketAddr, sync::Arc}; +use std::{ + collections::{HashMap, HashSet}, + io, + net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr}, + sync::{Arc, Mutex}, + time::{Duration, Instant}, +}; use eggserve_primitives::{Request, RequestBodyPolicy, Response, ResponseBody, StatusCode}; use eggserve_server::{service_fn_with_policy, RuntimeConfig, Server, ServerHandle, ServiceError}; @@ -65,6 +71,214 @@ pub enum AdminError { Invalid(String), } +const MAX_ALLOWED_HOSTS: usize = 64; +const AUTH_FAILURE_BURST: u8 = 5; +const AUTH_FAILURE_REFILL: Duration = Duration::from_secs(1); +const AUTH_FAILURE_PEER_CAPACITY: usize = 1024; +const AUTH_FAILURE_PEER_TTL: Duration = Duration::from_secs(300); +const AUTH_FAILURE_FALLBACK_DELAY: Duration = Duration::from_millis(50); + +#[derive(Debug)] +struct PeerFailureState { + tokens: u8, + last_refill: Instant, + last_seen: Instant, +} + +#[derive(Debug, Default)] +struct AuthFailureBudget { + peers: HashMap, +} + +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +enum AuthFailureDisposition { + Reject, + Throttled, + FallbackDelay, +} + +impl AuthFailureBudget { + fn record_failure(&mut self, peer: Option) -> AuthFailureDisposition { + let Some(peer) = peer else { + return AuthFailureDisposition::FallbackDelay; + }; + let now = Instant::now(); + if !self.peers.contains_key(&peer) { + if self.peers.len() >= AUTH_FAILURE_PEER_CAPACITY { + self.peers.retain(|_, state| { + now.saturating_duration_since(state.last_seen) < AUTH_FAILURE_PEER_TTL + }); + } + if self.peers.len() >= AUTH_FAILURE_PEER_CAPACITY { + return AuthFailureDisposition::FallbackDelay; + } + self.peers.insert( + peer, + PeerFailureState { + tokens: AUTH_FAILURE_BURST, + last_refill: now, + last_seen: now, + }, + ); + } + let state = self.peers.get_mut(&peer).expect("peer was inserted"); + let elapsed = now.saturating_duration_since(state.last_refill); + let refill = u8::try_from(elapsed.as_secs().min(u64::from(AUTH_FAILURE_BURST))) + .unwrap_or(AUTH_FAILURE_BURST); + if refill > 0 { + state.tokens = state.tokens.saturating_add(refill).min(AUTH_FAILURE_BURST); + state.last_refill += AUTH_FAILURE_REFILL * u32::from(refill); + } + state.last_seen = now; + if state.tokens == 0 { + AuthFailureDisposition::Throttled + } else { + state.tokens -= 1; + AuthFailureDisposition::Reject + } + } +} + +/// Returns whether a token contains at least 32 non-whitespace bytes. +pub(crate) fn has_public_token_strength(token: &str) -> bool { + token + .bytes() + .filter(|byte| !byte.is_ascii_whitespace()) + .count() + >= 32 +} + +/// Validate the optional explicit host allowlist at both config and startup boundaries. +pub(crate) fn validate_allowed_hosts(hosts: Option<&[String]>) -> Result<(), String> { + let Some(hosts) = hosts else { + return Ok(()); + }; + if hosts.is_empty() { + return Err("must contain at least one authority when specified".into()); + } + if hosts.len() > MAX_ALLOWED_HOSTS { + return Err(format!( + "must contain at most {MAX_ALLOWED_HOSTS} authorities" + )); + } + for host in hosts { + if normalize_authority(host).is_none() { + return Err( + "entries must be valid host authorities without wildcards, schemes, or paths" + .into(), + ); + } + } + Ok(()) +} + +fn normalize_authority(value: &str) -> Option { + if value.is_empty() + || value.len() > 512 + || !value.is_ascii() + || value.bytes().any(|byte| { + byte.is_ascii_whitespace() + || byte.is_ascii_control() + || matches!(byte, b'/' | b'\\' | b'?' | b'#' | b'@' | b'*' | b'%') + }) + { + return None; + } + + let (host, port) = if let Some(rest) = value.strip_prefix('[') { + let close = rest.find(']')?; + let address = rest[..close].parse::().ok()?; + let suffix = &rest[close + 1..]; + let port = if suffix.is_empty() { + None + } else { + Some(parse_authority_port(suffix.strip_prefix(':')?)?) + }; + (format!("[{address}]"), port) + } else { + if value.contains('[') || value.contains(']') { + return None; + } + let (host, port) = match value.rsplit_once(':') { + Some((host, port)) => { + if host.contains(':') { + return None; + } + (host, Some(parse_authority_port(port)?)) + } + None => (value, None), + }; + if host.is_empty() { + return None; + } + let normalized_host = if let Ok(address) = host.parse::() { + address.to_string() + } else { + if host.len() > 253 + || host.starts_with('.') + || host.ends_with('.') + || host + .bytes() + .all(|byte| byte.is_ascii_digit() || byte == b'.') + { + return None; + } + for label in host.split('.') { + if label.is_empty() + || label.len() > 63 + || label.starts_with('-') + || label.ends_with('-') + || !label + .bytes() + .all(|byte| byte.is_ascii_alphanumeric() || byte == b'-') + { + return None; + } + } + host.to_ascii_lowercase() + }; + (normalized_host, port) + }; + + Some(match port { + Some(port) => format!("{host}:{port}"), + None => host, + }) +} + +fn parse_authority_port(suffix: &str) -> Option { + let port = suffix.parse::().ok()?; + (port != 0).then_some(port) +} + +fn socket_authority(address: SocketAddr) -> String { + match address.ip() { + IpAddr::V4(ip) => format!("{ip}:{}", address.port()), + IpAddr::V6(ip) => format!("[{ip}]:{}", address.port()), + } +} + +fn default_allowed_hosts(address: SocketAddr) -> HashSet { + let port = address.port(); + let mut hosts = HashSet::from([socket_authority(address)]); + if address.ip().is_loopback() { + hosts.extend([ + format!("localhost:{port}"), + format!("127.0.0.1:{port}"), + format!("[::1]:{port}"), + ]); + } + hosts +} + +fn origin_authority(value: &str) -> Option { + let (scheme, authority) = value.split_once("://")?; + if !scheme.eq_ignore_ascii_case("http") && !scheme.eq_ignore_ascii_case("https") { + return None; + } + normalize_authority(authority) +} + /// EggServe-backed native admin server. pub struct NativeAdmin; @@ -99,15 +313,36 @@ impl NativeAdmin { config: AdminConfig, state: ControlState, ) -> Result { + Self::start_with_allowed_hosts(config, state, None).await + } + + /// Start the native admin API with additional accepted Host/Origin authorities. + /// + /// This additive entry point preserves the existing [`AdminConfig`] shape. + pub async fn start_with_allowed_hosts( + config: AdminConfig, + state: ControlState, + allowed_hosts: Option>, + ) -> Result { + validate_allowed_hosts(allowed_hosts.as_deref()) + .map_err(|message| AdminError::Invalid(format!("admin.allowed_hosts {message}")))?; if !config.bind.ip().is_loopback() && (!config.public_admin - || config + || !config .auth_token - .as_ref() - .is_none_or(std::string::String::is_empty)) + .as_deref() + .is_some_and(has_public_token_strength)) { return Err(AdminError::InsecurePublicBind); } + if config.bind.ip().is_loopback() + && config + .auth_token + .as_deref() + .is_some_and(|token| !has_public_token_strength(token)) + { + tracing::warn!("loopback admin bearer token is shorter than 32 non-whitespace bytes"); + } let listener = TcpListener::bind(config.bind).await?; let runtime = RuntimeConfig { max_request_body_bytes: 1024 * 1024, @@ -115,12 +350,20 @@ impl NativeAdmin { ..RuntimeConfig::default() }; let local_addr = listener.local_addr()?; + let mut allowed_host_set = default_allowed_hosts(local_addr); + for host in allowed_hosts.as_deref().unwrap_or_default() { + allowed_host_set.insert(normalize_authority(host).expect("allowlist was validated")); + } + let allowed_hosts = Arc::new(allowed_host_set); let auth = config.auth_token.map(Arc::::from); + let auth_failures = Arc::new(Mutex::new(AuthFailureBudget::default())); let service = service_fn_with_policy( move |request: Request| { let state = state.clone(); let auth = auth.clone(); - async move { handle_request(request, state, auth).await } + let allowed_hosts = allowed_hosts.clone(); + let auth_failures = auth_failures.clone(); + async move { handle_request(request, state, auth, allowed_hosts, auth_failures).await } }, RequestBodyPolicy::Buffer { max_bytes: 1024 * 1024, @@ -165,30 +408,95 @@ fn control_error_response(error: &ControlError) -> Response { ) } +fn host_rejection(host: Option<&str>, allowed_hosts: &HashSet) -> Option { + let host = host.and_then(normalize_authority); + host.as_ref() + .is_none_or(|host| !allowed_hosts.contains(host)) + .then(|| { + json_response( + StatusCode::FORBIDDEN, + &envelope("invalid_host", "request host is not allowed"), + ) + }) +} + +fn body_or_origin_rejection( + method: &str, + has_body: bool, + content_type: Option<&str>, + origin: Option<&str>, + origin_present: bool, + allowed_hosts: &HashSet, +) -> Option { + if has_body && !content_type.is_some_and(is_json_media_type) { + return Some(json_response( + StatusCode::new(415).expect("unsupported media type status"), + &envelope( + "unsupported_media_type", + "non-empty admin request bodies require application/json", + ), + )); + } + if !matches!(method, "GET" | "HEAD" | "OPTIONS") && origin_present { + let origin = origin.and_then(|origin| { + if origin.eq_ignore_ascii_case("null") { + None + } else { + origin_authority(origin) + } + }); + if origin + .as_ref() + .is_none_or(|origin| !allowed_hosts.contains(origin)) + { + return Some(json_response( + StatusCode::FORBIDDEN, + &envelope("invalid_origin", "request origin is not allowed"), + )); + } + } + None +} + async fn handle_request( request: Request, state: ControlState, auth: Option>, + allowed_hosts: Arc>, + auth_failures: Arc>, ) -> Result { - let (head, body, _) = request.into_parts(); + let (head, body, connection) = request.into_parts(); + if let Some(response) = host_rejection( + head.headers() + .get_first("host") + .and_then(|value| value.to_str().ok()), + &allowed_hosts, + ) { + return Ok(response); + } + if let Some(expected) = auth.as_deref() { let supplied = head .headers() .get_first("authorization") .and_then(|value| value.to_str().ok()); - let Some(token) = supplied.and_then(|value| value.strip_prefix("Bearer ")) else { - return Ok(json_response( - StatusCode::FORBIDDEN, - &envelope("unauthorized", "authorization required"), - )); - }; - if expected.is_empty() || !constant_time_equal(token.as_bytes(), expected.as_bytes()) { - return Ok(json_response( - StatusCode::FORBIDDEN, - &envelope("unauthorized", "authorization required"), + let token = supplied.and_then(parse_bearer_token); + if token.is_none_or(|token| { + expected.is_empty() || !constant_time_equal(token.as_bytes(), expected.as_bytes()) + }) { + let disposition = auth_failures + .lock() + .unwrap_or_else(std::sync::PoisonError::into_inner) + .record_failure(connection.remote_addr.map(|address| address.ip())); + if disposition == AuthFailureDisposition::FallbackDelay { + tokio::time::sleep(AUTH_FAILURE_FALLBACK_DELAY).await; + } + return Ok(authorization_failure_response( + disposition == AuthFailureDisposition::Throttled, )); } } + let method = head.method().as_str().to_owned(); let path = head.target().path().to_owned(); let body = body.read_all().await.map_err(|error| { @@ -200,6 +508,19 @@ async fn handle_request( ServiceError::rejected(400, error.to_string()) } })?; + let origin_header = head.headers().get_first("origin"); + if let Some(response) = body_or_origin_rejection( + &method, + !body.is_empty(), + head.headers() + .get_first("content-type") + .and_then(|value| value.to_str().ok()), + origin_header.and_then(|value| value.to_str().ok()), + origin_header.is_some(), + &allowed_hosts, + ) { + return Ok(response); + } let segments: Vec<&str> = path.split('/').filter(|part| !part.is_empty()).collect(); let decoded_id = if segments.len() == 5 && segments[0] == "v1" @@ -243,6 +564,45 @@ async fn handle_request( Ok(response) } +fn parse_bearer_token(value: &str) -> Option<&str> { + let separator = value.find(' ')?; + if !value[..separator].eq_ignore_ascii_case("bearer") { + return None; + } + Some(&value[separator + 1..]) +} + +fn is_json_media_type(value: &str) -> bool { + value + .split(';') + .next() + .is_some_and(|essence| essence.trim().eq_ignore_ascii_case("application/json")) +} + +fn authorization_failure_response(throttled: bool) -> Response { + let status = if throttled { + StatusCode::new(429).expect("too many requests status") + } else { + StatusCode::FORBIDDEN + }; + let body = serde_json::to_vec(&envelope("unauthorized", "authorization required")) + .unwrap_or_else(|_| b"{\"error\":{\"code\":\"unauthorized\"}}".to_vec()); + let builder = Response::builder() + .status(status) + .header("content-type", "application/json") + .expect("static header is valid"); + let builder = if throttled { + builder + .header("retry-after", "1") + .expect("static retry header is valid") + } else { + builder + }; + builder + .body(ResponseBody::Bytes(body)) + .expect("status and body are valid") +} + fn decode_path_component(input: &str) -> Result { let bytes = input.as_bytes(); let mut decoded = Vec::with_capacity(bytes.len()); @@ -734,6 +1094,99 @@ mod tests { use eggfetch_core::Client; use std::time::Duration; + #[test] + fn host_authorities_are_normalized_and_reject_ambiguous_forms() { + assert_eq!( + normalize_authority("LOCALHOST:08475"), + Some("localhost:8475".into()) + ); + assert_eq!( + normalize_authority("[0:0:0:0:0:0:0:1]:8475"), + Some("[::1]:8475".into()) + ); + for invalid in [ + "", + "*", + "https://localhost:8475", + "localhost/path", + "user@localhost:8475", + "localhost:0", + "[::1", + "127.0.0.999", + ] { + assert_eq!( + normalize_authority(invalid), + None, + "invalid authority {invalid:?}" + ); + } + } + + #[test] + fn allowlist_validation_bounds_and_rejects_invalid_entries() { + assert!(validate_allowed_hosts(None).is_ok()); + assert!(validate_allowed_hosts(Some(&["api.example:443".into()])).is_ok()); + assert!(validate_allowed_hosts(Some(&[])).is_err()); + assert!(validate_allowed_hosts(Some(&["https://api.example".into()])).is_err()); + let too_many = vec!["api.example".to_owned(); MAX_ALLOWED_HOSTS + 1]; + assert!(validate_allowed_hosts(Some(&too_many)).is_err()); + } + + #[test] + fn public_token_strength_counts_non_whitespace_bytes() { + assert!(!has_public_token_strength("short")); + assert!(!has_public_token_strength( + " " + )); + assert!(has_public_token_strength( + "12345678901234567890123456789012" + )); + assert!(has_public_token_strength( + "12345678901234567890123456789012 " + )); + } + + #[test] + fn auth_failure_budget_is_per_ip_bounded_and_has_no_shared_fallback_lockout() { + let peer: IpAddr = "198.51.100.1".parse().unwrap(); + let mut budget = AuthFailureBudget::default(); + for _ in 0..AUTH_FAILURE_BURST { + assert_eq!( + budget.record_failure(Some(peer)), + AuthFailureDisposition::Reject + ); + } + assert_eq!( + budget.record_failure(Some(peer)), + AuthFailureDisposition::Throttled + ); + assert_eq!( + budget.record_failure(None), + AuthFailureDisposition::FallbackDelay + ); + assert_eq!( + budget.record_failure(Some("198.51.100.2".parse().unwrap()),), + AuthFailureDisposition::Reject + ); + + let mut full = AuthFailureBudget::default(); + for index in 1..=AUTH_FAILURE_PEER_CAPACITY { + let peer = IpAddr::V4(Ipv4Addr::from( + u32::try_from(index).expect("test index fits in an IPv4 address"), + )); + assert_eq!( + full.record_failure(Some(peer)), + AuthFailureDisposition::Reject + ); + } + assert_eq!(full.peers.len(), AUTH_FAILURE_PEER_CAPACITY); + assert_eq!( + full.record_failure(Some("203.0.113.5".parse().unwrap())), + AuthFailureDisposition::FallbackDelay + ); + assert_eq!(full.peers.len(), AUTH_FAILURE_PEER_CAPACITY); + } + #[test] fn native_fault_path_components_decode_once_and_reject_malformed_input() { assert_eq!(decode_path_component("a%2Fb%25").unwrap(), "a/b%"); diff --git a/crates/eggchaos-server/src/config.rs b/crates/eggchaos-server/src/config.rs index 1679d32..5468ecd 100644 --- a/crates/eggchaos-server/src/config.rs +++ b/crates/eggchaos-server/src/config.rs @@ -188,29 +188,86 @@ pub enum NativeConfigError { }, } +fn take_admin_allowed_hosts( + value: &mut toml::Value, +) -> Result>, NativeConfigError> { + value + .as_table_mut() + .and_then(|root| root.get_mut("admin")) + .and_then(toml::Value::as_table_mut) + .and_then(|admin| admin.remove("allowed_hosts")) + .map(|value| { + value + .try_into() + .map_err(|error: toml::de::Error| NativeConfigError::Field { + field: "admin.allowed_hosts".into(), + message: error.to_string(), + }) + }) + .transpose() +} + +fn validate_admin_settings( + config: &NativeConfig, + allowed_hosts: Option<&[String]>, +) -> Result<(), NativeConfigError> { + if config.version != 1 { + return Err(NativeConfigError::Version(config.version)); + } + if !config.admin.bind.ip().is_loopback() + && (!config.admin.public_admin + || config + .admin + .auth_token + .as_ref() + .is_none_or(std::string::String::is_empty)) + { + return Err(NativeConfigError::Field { + field: "admin".into(), + message: "non-loopback admin requires public_admin=true and a non-empty auth_token" + .into(), + }); + } + crate::admin::validate_allowed_hosts(allowed_hosts).map_err(|message| { + NativeConfigError::Field { + field: "admin.allowed_hosts".into(), + message, + } + })?; + if !config.admin.bind.ip().is_loopback() + && !config + .admin + .auth_token + .as_deref() + .is_some_and(crate::admin::has_public_token_strength) + { + return Err(NativeConfigError::Field { + field: "admin.auth_token".into(), + message: "non-loopback admin tokens must contain at least 32 non-whitespace bytes" + .into(), + }); + } + Ok(()) +} + impl NativeConfig { /// Parse bounded TOML and compile all proxy plans through core validation. pub fn parse(text: &str) -> Result { - let config: Self = toml::from_str(text)?; - if config.version != 1 { - return Err(NativeConfigError::Version(config.version)); - } - // Fail fast for insecure admin binds instead of only at serve time: - // non-loopback requires explicit opt-in plus a non-empty token. - if !config.admin.bind.ip().is_loopback() - && (!config.admin.public_admin - || config - .admin - .auth_token - .as_ref() - .is_none_or(std::string::String::is_empty)) - { - return Err(NativeConfigError::Field { - field: "admin".into(), - message: "non-loopback admin requires public_admin=true and a non-empty auth_token" - .into(), - }); - } + Self::parse_with_admin_allowed_hosts(text).map(|(config, _)| config) + } + + /// Parse config plus the optional native-admin Host/Origin allowlist. + /// + /// The allowlist is returned separately to preserve the existing public + /// configuration DTO shapes; callers starting the listener should pass it + /// to `NativeAdmin::start_with_allowed_hosts`. + pub fn parse_with_admin_allowed_hosts( + text: &str, + ) -> Result<(Self, Option>), NativeConfigError> { + let mut value: toml::Value = toml::from_str(text)?; + let allowed_hosts = take_admin_allowed_hosts(&mut value)?; + let config: Self = value.try_into().map_err(NativeConfigError::Toml)?; + validate_admin_settings(&config, allowed_hosts.as_deref())?; if config.proxies.len() > 1024 { return Err(NativeConfigError::Field { field: "proxy".into(), @@ -287,10 +344,19 @@ impl NativeConfig { message: error.to_string(), })?; } - Ok(config) + Ok((config, allowed_hosts)) } /// Load and parse a TOML file. pub async fn load(path: impl AsRef) -> Result { + Self::load_with_admin_allowed_hosts(path) + .await + .map(|(config, _)| config) + } + + /// Load config plus the optional native-admin Host/Origin allowlist. + pub async fn load_with_admin_allowed_hosts( + path: impl AsRef, + ) -> Result<(Self, Option>), NativeConfigError> { const MAX_CONFIG_BYTES: u64 = 1_048_576; let metadata = tokio::fs::metadata(path.as_ref()).await?; if metadata.len() > MAX_CONFIG_BYTES { @@ -313,7 +379,7 @@ impl NativeConfig { message: "config file exceeds the 1 MiB limit".into(), }); } - Self::parse(&text) + Self::parse_with_admin_allowed_hosts(&text) } /// Compile service proxy definitions. pub fn compile_proxies(&self) -> Result, NativeConfigError> { @@ -702,6 +768,29 @@ burst_bytes = 0 assert!(format!("{config:?}").contains("[REDACTED]")); } + #[test] + fn admin_allowed_hosts_parse_as_separate_runtime_options() { + let (config, allowed_hosts) = NativeConfig::parse_with_admin_allowed_hosts( + "version = 1\n[admin]\nallowed_hosts = ['api.example:443']\n", + ) + .unwrap(); + assert_eq!(config.admin.bind, "127.0.0.1:8475".parse().unwrap()); + assert_eq!( + allowed_hosts.as_deref(), + Some(&["api.example:443".to_owned()][..]) + ); + assert!(NativeConfig::parse_with_admin_allowed_hosts( + "version = 1\n[admin]\nallowed_hosts = ['https://api.example']\n" + ) + .is_err()); + assert!(NativeConfig::parse_with_admin_allowed_hosts( + "version = 1\n[admin]\nallowed_hosts = 'api.example'\n" + ) + .unwrap_err() + .to_string() + .contains("admin.allowed_hosts")); + } + #[test] fn schema_v1_runtime_and_proxy_bounds_compile_with_omission_defaults() { let config = NativeConfig::parse( diff --git a/crates/eggchaos-server/src/runtime/control.rs b/crates/eggchaos-server/src/runtime/control.rs index 773fad6..3a5c1ea 100644 --- a/crates/eggchaos-server/src/runtime/control.rs +++ b/crates/eggchaos-server/src/runtime/control.rs @@ -7,6 +7,26 @@ use super::{ TcpListener, OUTCOME_CLASS_NAMES, }; +fn escape_prometheus_label_value(value: &str) -> std::borrow::Cow<'_, str> { + if value + .bytes() + .all(|byte| !matches!(byte, b'\\' | b'"' | b'\n')) + { + return std::borrow::Cow::Borrowed(value); + } + + let mut escaped = String::with_capacity(value.len()); + for character in value.chars() { + match character { + '\\' => escaped.push_str("\\\\"), + '"' => escaped.push_str("\\\""), + '\n' => escaped.push_str("\\n"), + _ => escaped.push(character), + } + } + std::borrow::Cow::Owned(escaped) +} + pub(super) fn map_datagram_error(error: DatagramRuntimeError) -> ControlError { match error { DatagramRuntimeError::Invalid(message) => ControlError::Invalid(message), @@ -85,15 +105,24 @@ impl ControlState { self.runtime.active.load(Ordering::Relaxed), ); for (index, name) in OUTCOME_CLASS_NAMES.iter().enumerate() { + let outcome = escape_prometheus_label_value(name); let _ = writeln!( text, - "eggchaos_connection_outcomes_total{{outcome=\"{name}\"}} {}", + "eggchaos_connection_outcomes_total{{outcome=\"{outcome}\"}} {}", self.runtime.metrics.outcomes[index].load(Ordering::Relaxed), ); } + let request_graceful = escape_prometheus_label_value("graceful"); + let request_hard_reset = escape_prometheus_label_value("hard_reset"); + let result_applied = escape_prometheus_label_value("applied"); + let result_unsupported = escape_prometheus_label_value("unsupported"); + let result_failed = escape_prometheus_label_value("failed"); + let flow_accepted = escape_prometheus_label_value("accepted"); + let flow_forwarded = escape_prometheus_label_value("forwarded"); + let flow_discarded = escape_prometheus_label_value("discarded"); let _ = writeln!( text, - "# HELP eggchaos_termination_requests_total Injected termination requests observed at close\n# TYPE eggchaos_termination_requests_total counter\neggchaos_termination_requests_total{{request=\"graceful\"}} {}\neggchaos_termination_requests_total{{request=\"hard_reset\"}} {}\n# HELP eggchaos_reset_results_total Abortive-close outcomes at the TCP edge\n# TYPE eggchaos_reset_results_total counter\neggchaos_reset_results_total{{result=\"applied\"}} {}\neggchaos_reset_results_total{{result=\"unsupported\"}} {}\neggchaos_reset_results_total{{result=\"failed\"}} {}\n# HELP eggchaos_bytes_total Bytes by flow across closed connections\n# TYPE eggchaos_bytes_total counter\neggchaos_bytes_total{{flow=\"accepted\"}} {}\neggchaos_bytes_total{{flow=\"forwarded\"}} {}\neggchaos_bytes_total{{flow=\"discarded\"}} {}\n# HELP eggchaos_policy_transitions_total Completed live-policy transitions\n# TYPE eggchaos_policy_transitions_total counter\neggchaos_policy_transitions_total {}\n# HELP eggchaos_schedule_v2_runs_total V2 schedule runs started\n# TYPE eggchaos_schedule_v2_runs_total counter\neggchaos_schedule_v2_runs_total {}\n# HELP eggchaos_schedule_v2_events_total V2 schedule events applied\n# TYPE eggchaos_schedule_v2_events_total counter\neggchaos_schedule_v2_events_total {}\n# HELP eggchaos_schedule_v2_late_events_total V2 schedule events applied after their deadline\n# TYPE eggchaos_schedule_v2_late_events_total counter\neggchaos_schedule_v2_late_events_total {}", + "# HELP eggchaos_termination_requests_total Injected termination requests observed at close\n# TYPE eggchaos_termination_requests_total counter\neggchaos_termination_requests_total{{request=\"{request_graceful}\"}} {}\neggchaos_termination_requests_total{{request=\"{request_hard_reset}\"}} {}\n# HELP eggchaos_reset_results_total Abortive-close outcomes at the TCP edge\n# TYPE eggchaos_reset_results_total counter\neggchaos_reset_results_total{{result=\"{result_applied}\"}} {}\neggchaos_reset_results_total{{result=\"{result_unsupported}\"}} {}\neggchaos_reset_results_total{{result=\"{result_failed}\"}} {}\n# HELP eggchaos_bytes_total Bytes by flow across closed connections\n# TYPE eggchaos_bytes_total counter\neggchaos_bytes_total{{flow=\"{flow_accepted}\"}} {}\neggchaos_bytes_total{{flow=\"{flow_forwarded}\"}} {}\neggchaos_bytes_total{{flow=\"{flow_discarded}\"}} {}\n# HELP eggchaos_policy_transitions_total Completed live-policy transitions\n# TYPE eggchaos_policy_transitions_total counter\neggchaos_policy_transitions_total {}\n# HELP eggchaos_schedule_v2_runs_total V2 schedule runs started\n# TYPE eggchaos_schedule_v2_runs_total counter\neggchaos_schedule_v2_runs_total {}\n# HELP eggchaos_schedule_v2_events_total V2 schedule events applied\n# TYPE eggchaos_schedule_v2_events_total counter\neggchaos_schedule_v2_events_total {}\n# HELP eggchaos_schedule_v2_late_events_total V2 schedule events applied after their deadline\n# TYPE eggchaos_schedule_v2_late_events_total counter\neggchaos_schedule_v2_late_events_total {}", self.runtime.metrics.graceful_requests.load(Ordering::Relaxed), self.runtime.metrics.hard_reset_requests.load(Ordering::Relaxed), self.runtime.metrics.reset_applied.load(Ordering::Relaxed), @@ -112,7 +141,9 @@ impl ControlState { ); text.push_str("# HELP eggchaos_stream_loss_chunks_evaluated_total Logical stream-loss chunks evaluated\n# TYPE eggchaos_stream_loss_chunks_evaluated_total counter\n# HELP eggchaos_stream_loss_chunks_dropped_total Logical stream-loss chunks dropped\n# TYPE eggchaos_stream_loss_chunks_dropped_total counter\n# HELP eggchaos_stream_loss_bytes_discarded_total Bytes discarded by stream-loss faults\n# TYPE eggchaos_stream_loss_bytes_discarded_total counter\n"); let write_stream_loss_samples = |text: &mut String, proxy: &str, samples: [[u64; 3]; 2]| { + let proxy = escape_prometheus_label_value(proxy); for (direction, index) in [("upstream", 0), ("downstream", 1)] { + let direction = escape_prometheus_label_value(direction); for (metric, value) in [ ( "eggchaos_stream_loss_chunks_evaluated_total", @@ -144,48 +175,56 @@ impl ControlState { let mut proxies: Vec<_> = tables.proxies.iter().collect(); proxies.sort_by_key(|(name, _)| *name); for (name, entry) in proxies { + let proxy = escape_prometheus_label_value(name); let _ = writeln!( text, - "eggchaos_proxy_connections_accepted_total{{proxy=\"{name}\"}} {}\neggchaos_proxy_connections_completed_total{{proxy=\"{name}\"}} {}", + "eggchaos_proxy_connections_accepted_total{{proxy=\"{proxy}\"}} {}\neggchaos_proxy_connections_completed_total{{proxy=\"{proxy}\"}} {}", entry.accepted, entry.completed, ); for (direction, index) in [("upstream", 0), ("downstream", 1)] { + let direction = escape_prometheus_label_value(direction); for (flow, value) in ["accepted", "forwarded", "discarded"] .iter() .zip(entry.bytes[index]) { + let flow = escape_prometheus_label_value(flow); let _ = writeln!( text, - "eggchaos_proxy_bytes_total{{proxy=\"{name}\",direction=\"{direction}\",flow=\"{flow}\"}} {value}", + "eggchaos_proxy_bytes_total{{proxy=\"{proxy}\",direction=\"{direction}\",flow=\"{flow}\"}} {value}", ); } } write_stream_loss_samples(&mut text, name, entry.stream_loss); } if tables.overflow_proxy.accepted + tables.overflow_proxy.completed > 0 { + let overflow_proxy = escape_prometheus_label_value("_overflow"); let _ = writeln!( text, - "eggchaos_proxy_connections_accepted_total{{proxy=\"_overflow\"}} {}\neggchaos_proxy_connections_completed_total{{proxy=\"_overflow\"}} {}", + "eggchaos_proxy_connections_accepted_total{{proxy=\"{overflow_proxy}\"}} {}\neggchaos_proxy_connections_completed_total{{proxy=\"{overflow_proxy}\"}} {}", tables.overflow_proxy.accepted, tables.overflow_proxy.completed, ); write_stream_loss_samples( &mut text, - "_overflow", + &overflow_proxy, tables.overflow_proxy.stream_loss, ); } let mut activations: Vec<_> = tables.activations.iter().collect(); activations.sort(); for ((proxy, direction, fault_type), count) in activations { + let proxy = escape_prometheus_label_value(proxy); + let direction = escape_prometheus_label_value(direction); + let fault_type = escape_prometheus_label_value(fault_type); let _ = writeln!( text, "eggchaos_fault_activations_total{{proxy=\"{proxy}\",direction=\"{direction}\",fault_type=\"{fault_type}\"}} {count}", ); } if tables.overflow_activations > 0 { + let overflow = escape_prometheus_label_value("_overflow"); let _ = writeln!( text, - "eggchaos_fault_activations_total{{proxy=\"_overflow\",direction=\"_overflow\",fault_type=\"_overflow\"}} {}", + "eggchaos_fault_activations_total{{proxy=\"{overflow}\",direction=\"{overflow}\",fault_type=\"{overflow}\"}} {}", tables.overflow_activations, ); } @@ -218,11 +257,14 @@ impl ControlState { } for name in names { let entry = &map[name]; + let proxy = escape_prometheus_label_value(name); + let upstream_direction = escape_prometheus_label_value("upstream"); + let downstream_direction = escape_prometheus_label_value("downstream"); let upstream = entry.spec.upstream_policy.snapshot(); let downstream = entry.spec.downstream_policy.snapshot(); let _ = writeln!( text, - "eggchaos_proxy_connections_active{{proxy=\"{name}\"}} {}\neggchaos_proxy_policy_generation{{proxy=\"{name}\",direction=\"upstream\"}} {}\neggchaos_proxy_policy_generation{{proxy=\"{name}\",direction=\"downstream\"}} {}\neggchaos_proxy_queue_bytes{{proxy=\"{name}\",direction=\"upstream\"}} {}\neggchaos_proxy_queue_bytes{{proxy=\"{name}\",direction=\"downstream\"}} {}", + "eggchaos_proxy_connections_active{{proxy=\"{proxy}\"}} {}\neggchaos_proxy_policy_generation{{proxy=\"{proxy}\",direction=\"{upstream_direction}\"}} {}\neggchaos_proxy_policy_generation{{proxy=\"{proxy}\",direction=\"{downstream_direction}\"}} {}\neggchaos_proxy_queue_bytes{{proxy=\"{proxy}\",direction=\"{upstream_direction}\"}} {}\neggchaos_proxy_queue_bytes{{proxy=\"{proxy}\",direction=\"{downstream_direction}\"}} {}", entry.active.load(Ordering::Relaxed), upstream.generation, downstream.generation, @@ -241,10 +283,11 @@ impl ControlState { text.push_str("# HELP eggchaos_datagram_proxy_drops Proxy-level UDP admission/drop observations\n# TYPE eggchaos_datagram_proxy_drops gauge\n"); text.push_str("# HELP eggchaos_datagram_administrative_discards Queued datagrams discarded by operator lifecycle actions\n# TYPE eggchaos_datagram_administrative_discards gauge\n"); for proxy in &datagram_proxies { + let proxy_name = escape_prometheus_label_value(&proxy.name); let _ = writeln!( text, - "eggchaos_datagram_associations_active{{proxy=\"{}\"}} {}", - proxy.name, proxy.active_associations + "eggchaos_datagram_associations_active{{proxy=\"{proxy_name}\"}} {}", + proxy.active_associations ); for (kind, value) in [ ("oversize", proxy.oversize_datagrams), @@ -255,10 +298,10 @@ impl ControlState { proxy.association_setup_failures, ), ] { + let kind = escape_prometheus_label_value(kind); let _ = writeln!( text, - "eggchaos_datagram_proxy_drops{{proxy=\"{}\",kind=\"{kind}\"}} {value}", - proxy.name + "eggchaos_datagram_proxy_drops{{proxy=\"{proxy_name}\",kind=\"{kind}\"}} {value}", ); } let administrative_discards = datagram_evidence @@ -267,8 +310,9 @@ impl ControlState { .fold(0u64, |total, association| { total.saturating_add(association.administrative_discards) }); - let _ = writeln!(text, "eggchaos_datagram_administrative_discards{{proxy=\"{}\"}} {administrative_discards}", proxy.name); + let _ = writeln!(text, "eggchaos_datagram_administrative_discards{{proxy=\"{proxy_name}\"}} {administrative_discards}"); for direction in ["upstream", "downstream"] { + let direction_label = escape_prometheus_label_value(direction); let mut totals = [0u64; 12]; let mut activations = [0u64; 6]; for association in datagram_evidence @@ -313,13 +357,15 @@ impl ControlState { .into_iter() .zip(totals) { - let _ = writeln!(text, "eggchaos_datagram_evidence{{proxy=\"{}\",direction=\"{direction}\",kind=\"{kind}\"}} {value}", proxy.name); + let kind = escape_prometheus_label_value(kind); + let _ = writeln!(text, "eggchaos_datagram_evidence{{proxy=\"{proxy_name}\",direction=\"{direction_label}\",kind=\"{kind}\"}} {value}"); } for (fault_type, value) in eggchaos_core::DATAGRAM_FAULT_TYPE_NAMES .into_iter() .zip(activations) { - let _ = writeln!(text, "eggchaos_datagram_fault_activations{{proxy=\"{}\",direction=\"{direction}\",fault_type=\"{fault_type}\"}} {value}", proxy.name); + let fault_type = escape_prometheus_label_value(fault_type); + let _ = writeln!(text, "eggchaos_datagram_fault_activations{{proxy=\"{proxy_name}\",direction=\"{direction_label}\",fault_type=\"{fault_type}\"}} {value}"); } } } @@ -1717,3 +1763,20 @@ impl ControlState { .collect() } } + +#[cfg(test)] +mod prometheus_label_tests { + use super::escape_prometheus_label_value; + + #[test] + fn escapes_backslash_quote_and_newline_without_allocating_for_plain_values() { + assert!(matches!( + escape_prometheus_label_value("plain"), + std::borrow::Cow::Borrowed("plain") + )); + assert_eq!( + escape_prometheus_label_value("backslash\\ quote\" newline\n"), + "backslash\\\\ quote\\\" newline\\n" + ); + } +} diff --git a/crates/eggchaos-server/src/runtime/tests.rs b/crates/eggchaos-server/src/runtime/tests.rs index 477ba77..24dd029 100644 --- a/crates/eggchaos-server/src/runtime/tests.rs +++ b/crates/eggchaos-server/src/runtime/tests.rs @@ -2018,6 +2018,42 @@ async fn stream_loss_prometheus_exposition_is_unique_and_well_formed() { origin_task.abort(); } +#[tokio::test] +async fn prometheus_metrics_escape_synthetic_label_values() { + let control = test_control(); + let label = "synthetic\"quote\nand\\slash"; + { + let mut tables = control.runtime.metrics.tables.lock().expect("metrics lock"); + tables.record_accept(label); + tables + .activations + .insert((label.to_owned(), label.to_owned(), label.to_owned()), 1); + } + + let metrics = control.metrics_text().await; + let escaped_label = r#"synthetic\"quote\nand\\slash"#; + let accepted_sample = + format!(r#"eggchaos_proxy_connections_accepted_total{{proxy="{escaped_label}"}} 1"#); + let accepted_samples: Vec<_> = metrics + .lines() + .filter(|line| line.starts_with("eggchaos_proxy_connections_accepted_total{proxy=")) + .collect(); + assert_eq!(accepted_samples.len(), 1); + assert_eq!(accepted_samples[0], accepted_sample); + + let activation_sample = format!( + r#"eggchaos_fault_activations_total{{proxy="{escaped_label}",direction="{escaped_label}",fault_type="{escaped_label}"}} 1"# + ); + let activation_samples: Vec<_> = metrics + .lines() + .filter(|line| line.starts_with("eggchaos_fault_activations_total{proxy=")) + .collect(); + assert_eq!(activation_samples.len(), 1); + assert_eq!(activation_samples[0], activation_sample); + + control.shutdown_and_join().await; +} + #[tokio::test] async fn connection_evidence_contains_no_payload_bytes() { let (origin_addr, origin_task) = echo_server().await; diff --git a/crates/eggchaos-server/tests/admin_auth.rs b/crates/eggchaos-server/tests/admin_auth.rs index 98a0ffe..0be3ab7 100644 --- a/crates/eggchaos-server/tests/admin_auth.rs +++ b/crates/eggchaos-server/tests/admin_auth.rs @@ -85,7 +85,8 @@ async fn bearer_authorization_matrix_enforces_configured_token() { ("Basic b3BlcmF0b3I=", 403), ("Bearer wrong-token", 403), ("Bearer ", 403), - ("bearer m059-baseline-operator-token", 403), + ("bearer m059-baseline-operator-token", 200), + ("BEARER m059-baseline-operator-token", 200), ("Bearer m059-baseline-operator-token", 200), ]; for (header, expected) in cases { @@ -119,6 +120,79 @@ async fn bearer_authorization_matrix_enforces_configured_token() { handle.wait().await; } +#[tokio::test] +async fn auth_failures_are_throttled_per_peer_and_valid_tokens_are_not_counted() { + let token = "01234567890123456789012345678901"; + let mut handle = NativeAdmin::start( + AdminConfig { + bind: "127.0.0.1:0".parse().unwrap(), + auth_token: Some(token.to_owned()), + ..AdminConfig::default() + }, + ControlState::default(), + ) + .await + .expect("loopback admin starts"); + let url = format!("http://{}/v1/health", handle.local_addr()); + let client = eggfetch_core::Client::builder().build(); + + for attempt in 0..5 { + let mut response = client + .get(&url) + .unwrap() + .header("authorization", "Bearer wrong-token") + .send() + .await + .unwrap(); + assert_eq!(response.status(), 403, "failure {attempt} should use burst"); + let _ = response.bytes().await.unwrap(); + } + + let authorization = format!("Bearer {token}"); + let mut valid = client + .get(&url) + .unwrap() + .header("authorization", authorization.as_str()) + .send() + .await + .unwrap(); + assert_eq!(valid.status(), 200, "valid tokens are never throttled"); + let _ = valid.bytes().await.unwrap(); + + let mut response = client + .get(&url) + .unwrap() + .header("authorization", "Bearer wrong-token") + .send() + .await + .unwrap(); + assert_eq!(response.status(), 429); + assert_eq!( + response + .headers() + .get("retry-after") + .and_then(|value| value.to_str().ok()), + Some("1") + ); + let _ = response.bytes().await.unwrap(); + + handle.shutdown(); + handle.wait().await; +} + +#[tokio::test] +async fn short_public_token_is_rejected_again_at_startup() { + let result = NativeAdmin::start( + public_config(true, Some("short-token")), + ControlState::default(), + ) + .await; + let Err(error) = result else { + panic!("non-loopback admin with a short token must not start") + }; + assert!(error.to_string().contains("auth_token")); +} + #[test] fn file_config_rejects_insecure_public_admin_bind() { let missing = @@ -132,13 +206,18 @@ fn file_config_rejects_insecure_public_admin_bind() { "version = 1\n[admin]\nbind = '192.0.2.1:8475'\nauth_token = 'operator-token'\n", ); assert!(no_opt_in.is_err(), "public bind without opt-in must fail"); - let secured = NativeConfig::parse( + let weak = NativeConfig::parse( "version = 1\n[admin]\nbind = '192.0.2.1:8475'\npublic_admin = true\nauth_token = 'operator-token'\n", - ) - .expect("secured public bind parses"); + ); + assert!(weak.is_err(), "short public tokens must fail config parse"); + let token = "01234567890123456789012345678901"; + let secured = NativeConfig::parse(&format!( + "version = 1\n[admin]\nbind = '192.0.2.1:8475'\npublic_admin = true\nauth_token = '{token}'\n" + )) + .expect("secured public bind with a strong token parses"); let debug = format!("{secured:?}"); assert!( - !debug.contains("operator-token"), + !debug.contains(token), "file config Debug must redact token material" ); assert!(debug.contains("[REDACTED]")); diff --git a/crates/eggchaos-server/tests/admin_origin.rs b/crates/eggchaos-server/tests/admin_origin.rs new file mode 100644 index 0000000..b08c791 --- /dev/null +++ b/crates/eggchaos-server/tests/admin_origin.rs @@ -0,0 +1,155 @@ +//! M063 regression tests for Host/Origin and JSON media-type policy. + +use std::{fmt::Write as _, time::Duration}; + +use eggchaos_server::{AdminConfig, ControlState, NativeAdmin}; +use tokio::{ + io::{AsyncReadExt, AsyncWriteExt}, + net::TcpStream, + time::timeout, +}; + +async fn send_request( + address: std::net::SocketAddr, + host: &str, + method: &str, + path: &str, + headers: &[(&str, &str)], + body: &str, +) -> (u16, String) { + let mut request = format!( + "{method} {path} HTTP/1.1\r\nHost: {host}\r\nContent-Length: {}\r\nConnection: close\r\n", + body.len() + ); + for (name, value) in headers { + write!(request, "{name}: {value}\r\n").expect("write request header"); + } + request.push_str("\r\n"); + request.push_str(body); + + let mut stream = TcpStream::connect(address).await.expect("connect to admin"); + stream + .write_all(request.as_bytes()) + .await + .expect("write raw request"); + let mut response = Vec::new(); + timeout(Duration::from_secs(2), stream.read_to_end(&mut response)) + .await + .expect("admin response closes promptly") + .expect("read response"); + let response = String::from_utf8_lossy(&response).into_owned(); + let status = response + .lines() + .next() + .and_then(|line| line.split_whitespace().nth(1)) + .and_then(|status| status.parse().ok()) + .expect("HTTP status line"); + (status, response) +} + +#[tokio::test] +async fn host_origin_and_media_type_guards_reject_audit_shapes_before_mutation() { + let state = ControlState::default(); + let mut admin = NativeAdmin::start_with_allowed_hosts( + AdminConfig { + bind: "127.0.0.1:0".parse().unwrap(), + ..AdminConfig::default() + }, + state.clone(), + Some(vec!["api.example".into()]), + ) + .await + .expect("start loopback admin"); + let address = admin.local_addr(); + let local_host = format!("127.0.0.1:{}", address.port()); + let proxy_body = r#"{"name":"csrf-proof","listen":"127.0.0.1:0","upstream":"127.0.0.1:9"}"#; + + let (status, _) = send_request( + address, + &format!("evil.example:{}", address.port()), + "GET", + "/v1/health", + &[("Origin", "https://evil.example")], + "", + ) + .await; + assert_eq!(status, 403, "foreign Host must be rejected on reads"); + + let (status, _) = send_request( + address, + &local_host, + "POST", + "/v1/proxies", + &[ + ("Origin", "https://evil.example"), + ("Content-Type", "application/json"), + ], + proxy_body, + ) + .await; + assert_eq!(status, 403, "foreign Origin must be rejected on mutations"); + assert!( + state.list().await.is_empty(), + "foreign Origin must not mutate state" + ); + + let (status, _) = send_request( + address, + &local_host, + "POST", + "/v1/reset", + &[("Origin", "null")], + "", + ) + .await; + assert_eq!(status, 403, "null Origin must be rejected on mutations"); + + // The audit's text/plain JSON probe is rejected as unsupported media type. + // Media type is checked before Origin so the probe's documented 415 stays stable. + let (status, _) = send_request( + address, + &local_host, + "POST", + "/v1/proxies", + &[ + ("Origin", "https://evil.example"), + ("Content-Type", "text/plain"), + ], + proxy_body, + ) + .await; + assert_eq!(status, 415, "non-JSON body must be rejected"); + assert!( + state.list().await.is_empty(), + "bad media type must not mutate state" + ); + + let (status, _) = + send_request(address, &local_host, "POST", "/v1/proxies", &[], proxy_body).await; + assert_eq!(status, 415, "missing media type must be rejected"); + assert!( + state.list().await.is_empty(), + "missing media type must not mutate state" + ); + + let (status, _) = send_request( + address, + "api.example", + "POST", + "/v1/proxies", + &[ + ("Origin", "https://api.example"), + ("Content-Type", "application/json"), + ], + proxy_body, + ) + .await; + assert_eq!( + status, 201, + "explicit reverse-proxy host and origin should work" + ); + assert_eq!(state.list().await.len(), 1); + + admin.shutdown(); + admin.wait().await; +} diff --git a/crates/eggchaos-toxiproxy/examples/compat_server.rs b/crates/eggchaos-toxiproxy/examples/compat_server.rs index 7309e51..9062efb 100644 --- a/crates/eggchaos-toxiproxy/examples/compat_server.rs +++ b/crates/eggchaos-toxiproxy/examples/compat_server.rs @@ -5,6 +5,7 @@ //! ```text //! cargo run -p eggchaos-toxiproxy --example compat_server -- 127.0.0.1:8474 //! cargo run -p eggchaos-toxiproxy --example compat_server -- 127.0.0.1:8475 post-v2.12-2026-09-25 +//! cargo run -p eggchaos-toxiproxy --example compat_server -- --allow-public 0.0.0.0:8474 //! ``` //! //! The first positional argument is the bind address (default @@ -17,28 +18,46 @@ //! profile. Adds `packet_loss` and reports `{"version":"git"}` from //! the source-build oracle. //! -//! Loopback only unless an explicit bind address is given. +//! The compatibility API has no authentication or TLS. Non-loopback binding +//! requires the explicit `--allow-public` flag and separate network/TLS controls. use eggchaos_server::ControlState; use eggchaos_toxiproxy::{CompatProfile, ToxiproxyAdapter, ToxiproxyHttp}; #[tokio::main] async fn main() { - let bind: std::net::SocketAddr = std::env::args() - .nth(1) - .unwrap_or_else(|| "127.0.0.1:8474".into()) + let mut args: Vec = std::env::args().skip(1).collect(); + let allow_public = args + .iter() + .position(|argument| argument == "--allow-public") + .is_some_and(|index| { + args.remove(index); + true + }); + let bind: std::net::SocketAddr = args + .first() + .map_or("127.0.0.1:8474", String::as_str) .parse() .expect("bind address parses"); - let profile = match std::env::args().nth(2).as_deref() { + let profile = match args.get(1).map(String::as_str) { None => CompatProfile::default(), Some("strict-v2.12") => CompatProfile::StrictV2_12, Some("post-v2.12-2026-09-25") => CompatProfile::PostV2_12_2026_09_25, Some(other) => panic!("unknown profile {other:?}: strict-v2.12 or post-v2.12-2026-09-25"), }; + assert!(args.len() <= 2, "unexpected extra argument"); + assert!( + bind.ip().is_loopback() || allow_public, + "non-loopback compatibility binds require --allow-public" + ); + let adapter = ToxiproxyAdapter::with_profile(ControlState::default(), profile.clone()); - let handle = ToxiproxyHttp::start(bind, adapter) - .await - .expect("compat server starts"); + let handle = if allow_public { + ToxiproxyHttp::start_with_public_bind(bind, adapter).await + } else { + ToxiproxyHttp::start(bind, adapter).await + } + .expect("compat server starts"); println!( "compat server on {} (profile={})", handle.local_addr(), diff --git a/crates/eggchaos-toxiproxy/src/lib.rs b/crates/eggchaos-toxiproxy/src/lib.rs index 279025f..4bbb433 100644 --- a/crates/eggchaos-toxiproxy/src/lib.rs +++ b/crates/eggchaos-toxiproxy/src/lib.rs @@ -1140,10 +1140,37 @@ impl ToxiproxyHttpHandle { } impl ToxiproxyHttp { - /// Start the compatibility route family on a loopback-by-default listener. + /// Start the unauthenticated compatibility API on a loopback listener. + /// + /// Non-loopback binds are refused; use [`Self::start_with_public_bind`] + /// only after explicitly deciding how this unauthenticated API is protected. pub async fn start( bind: std::net::SocketAddr, adapter: ToxiproxyAdapter, + ) -> Result { + if !bind.ip().is_loopback() { + return Err(CompatError::new( + 500, + "non-loopback Toxiproxy binds require explicit start_with_public_bind opt-in", + )); + } + Self::start_inner(bind, adapter).await + } + + /// Start the unauthenticated compatibility API with explicit public-bind intent. + /// + /// This API adds no authentication or encryption. Protect non-loopback + /// exposure with network controls and a trusted TLS terminator. + pub async fn start_with_public_bind( + bind: std::net::SocketAddr, + adapter: ToxiproxyAdapter, + ) -> Result { + Self::start_inner(bind, adapter).await + } + + async fn start_inner( + bind: std::net::SocketAddr, + adapter: ToxiproxyAdapter, ) -> Result { let listener = tokio::net::TcpListener::bind(bind) .await diff --git a/crates/eggchaos-toxiproxy/tests/listener_security.rs b/crates/eggchaos-toxiproxy/tests/listener_security.rs new file mode 100644 index 0000000..549eaef --- /dev/null +++ b/crates/eggchaos-toxiproxy/tests/listener_security.rs @@ -0,0 +1,25 @@ +//! Regression tests for the Toxiproxy listener exposure guard. + +use eggchaos_server::ControlState; +use eggchaos_toxiproxy::{ToxiproxyAdapter, ToxiproxyHttp}; + +#[tokio::test] +async fn default_start_refuses_non_loopback_before_binding() { + let adapter = ToxiproxyAdapter::new(ControlState::default()); + let result = ToxiproxyHttp::start("192.0.2.1:0".parse().unwrap(), adapter).await; + let Err(error) = result else { + panic!("non-loopback bind must require explicit opt-in") + }; + assert!(error.to_string().contains("start_with_public_bind")); +} + +#[tokio::test] +async fn explicit_public_bind_constructor_remains_additive_on_loopback() { + let adapter = ToxiproxyAdapter::new(ControlState::default()); + let handle = ToxiproxyHttp::start_with_public_bind("127.0.0.1:0".parse().unwrap(), adapter) + .await + .expect("explicit constructor can start a loopback listener"); + assert!(handle.local_addr().ip().is_loopback()); + handle.shutdown(); + handle.wait().await; +} diff --git a/docs/configuration.md b/docs/configuration.md index 58a2675..01c7edc 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -4,16 +4,19 @@ Eggchaos reads schema-versioned TOML. Set `version = 1`; omitted optional fields ## Admin listener -The default listener is `127.0.0.1:8475` and is unauthenticated unless you configure a token. To bind beyond loopback, set `public_admin = true` and a non-empty `auth_token`: +The default listener is `127.0.0.1:8475` and is unauthenticated. Treat loopback access as a same-user trust boundary. To bind beyond loopback, set `public_admin = true` and configure a bearer token containing at least 32 non-whitespace bytes: ```toml [admin] bind = "0.0.0.0:8475" public_admin = true auth_token = "render-this-value-from-your-secret-store" +allowed_hosts = ["admin.example.com:8475"] ``` -Eggchaos reads `auth_token` as a literal TOML string. It does not expand environment variables. Do not commit a real token. The admin listener uses HTTP, so protect non-loopback access with a trusted TLS terminator and network controls. The CLI's `--admin-token` option and `EGGCHAOS_ADMIN_TOKEN` variable supply credentials for client requests; they do not configure the server listener. +Eggchaos reads `auth_token` as a literal TOML string; it does not expand environment variables. Do not commit a real token. A short token on a loopback listener is allowed but emits a startup warning. `allowed_hosts` is optional, accepts at most 64 exact ASCII host authorities, and does not accept wildcards, schemes, or paths. With no explicit list, the listener accepts only its bound address and the documented loopback names/literals for that port. Configure the public hostname (and port, when present in requests) when a reverse proxy is used. Forwarded host headers are not trusted. + +The native API validates `Host` on every route. For state-changing methods, a present `Origin` must be `http` or `https` and match an allowed authority; `Origin: null` is rejected, while an absent Origin remains valid for non-browser clients. Non-empty request bodies require `Content-Type: application/json` (parameters are allowed). These checks do not encrypt the connection: the admin listener is cleartext HTTP, so protect non-loopback access with a trusted TLS terminator and network controls. The CLI's `--admin-token` and `EGGCHAOS_ADMIN_TOKEN` supply credentials for client requests; they do not configure the server listener. ## Stream proxy example @@ -55,6 +58,12 @@ The optional `[runtime]` table controls service-wide limits. Defaults preserve t Each `[[proxy]]` may set `connect_timeout_ms` (default `5000`, range `1..=300000`), `seed` (default `0`), `enabled` (default `true`), and `max_connections` (optional). The global connection limit still applies. Latency faults may set `max_buffer_bytes` from `1` through `67108864` bytes. Invalid values fail configuration with a field-specific error. +### Connection memory and idle-timeout limits + +A latency buffer is a per-direction byte cap, not a preallocated reservation. For a conservative upper-bound estimate, multiply the configured latency-buffer cap by the number of active connections and by the number of directions that have latency buffering. At the maximum `64 MiB` cap in both directions and the default `1024` global connections, the possible buffered payload is about `128 GiB`; actual use depends on traffic and configured plans, and process memory also includes sockets, queues, and metadata. Lower `max_buffer_bytes` and set a per-proxy `max_connections` appropriate to the service; `global_connections` remains the workspace-wide ceiling. + +Stream connections have no idle timeout. Eggress `eggress-relay` 1.0.12 exposes no no-progress timeout option, and Eggchaos does not fork its copy/half-close behavior to add one. For long-lived or untrusted clients, limit exposure at the network layer and use `max_connections` (and, where appropriate, an external connection-lifetime policy) to bound resource occupancy. Datagram associations separately support `association_idle_timeout_ms`. + The service half-close policy is not configurable in schema v1. The runtime uses its `Drain` policy. ## Datagram proxies diff --git a/docs/control-plane.md b/docs/control-plane.md index edc38b7..2e7fe22 100644 --- a/docs/control-plane.md +++ b/docs/control-plane.md @@ -1,15 +1,36 @@ # Native control plane -The native API uses `/v1` and binds to loopback by default. A non-loopback -bind requires `public_admin = true` and a non-empty bearer token in the TOML -`[admin]` table. See [configuration](configuration.md#admin-listener). Failed -authentication returns a bounded JSON error without echoing the token. Request -bodies are limited to 1 MiB. +The native API uses `/v1` and binds to loopback by default. Unauthenticated +loopback access is a same-user trust boundary. A non-loopback bind requires +`public_admin = true` and a bearer token containing at least 32 non-whitespace +bytes in the TOML `[admin]` table. See +[configuration](configuration.md#admin-listener). The listener remains +cleartext HTTP; use a trusted TLS terminator and network controls for remote +access. + +Every request must use a `Host` authority matching the bind-derived defaults +or the optional exact `[admin].allowed_hosts` list. Forwarded host headers are +not trusted. State-changing methods reject `Origin: null` and any present +origin that is not `http`/`https` with an allowed authority; non-browser +clients may omit Origin. Non-empty request bodies require +`Content-Type: application/json` (optional parameters such as `charset` are +accepted). These checks run before route dispatch. Bodies remain capped at +1 MiB. + +When authentication is configured, failed or missing credentials return a +bounded JSON error without echoing token material. Bearer scheme casing is +ignored, but credential bytes are compared exactly. Failures are budgeted per +peer IP (five-failure burst, one token per second); exhausted peers receive +`429` with `Retry-After: 1`. Missing peer metadata uses a small fixed delay, +not a shared lockout. This throttle does not replace network-level controls. For CLI requests to a secured admin endpoint, pass `--admin-token ` or set `EGGCHAOS_ADMIN_TOKEN`. The command-line value takes precedence. The CLI -omits the authorization header when neither is set. Tokens are redacted from -native configuration debug output. +omits the authorization header when neither is set. A token passed with +`--admin-token` can be visible in local process listings; prefer the +environment variable or a protected configuration/secret mechanism, and do +not put tokens in shell history. Native configuration debug output redacts +tokens. The CLI is an HTTP client for the native API. It supports JSON output and returns a nonzero exit status when a command fails. diff --git a/docs/toxiproxy.md b/docs/toxiproxy.md index 57c4514..67ddc24 100644 --- a/docs/toxiproxy.md +++ b/docs/toxiproxy.md @@ -57,11 +57,22 @@ two opt-in compatibility profiles: Under both profiles the adapter remains stream/TCP-only; UDP datagram resources are a separate native API. -Run a standalone compat server with the strict profile with +Run a standalone compat server with the strict profile using `cargo run -p eggchaos-toxiproxy --example compat_server -- 127.0.0.1:8474` -(loopback by default). The example accepts an explicit profile as the -second positional argument (`strict-v2.12` or `post-v2.12-2026-09-25`). -Native fixed-target UDP datagram resources are a separate API and do not extend -Toxiproxy v2.12; the compatibility adapter remains stream/TCP-only. Contributor -oracle setup and qualification commands are documented in +(loopback by default). The example accepts an explicit profile as the second +positional argument (`strict-v2.12` or `post-v2.12-2026-09-25`). The existing +`ToxiproxyHttp::start` API refuses non-loopback binds; intentional exposure +requires the additive `start_with_public_bind` API. The example likewise +requires `--allow-public`, for example: + +```sh +cargo run -p eggchaos-toxiproxy --example compat_server -- --allow-public 0.0.0.0:8474 +``` + +This compatibility API has no authentication or TLS; the opt-in flag only +records explicit exposure intent. Do not expose it publicly without separate +network controls and a trusted TLS terminator. Native fixed-target UDP +datagram resources are a separate API and do not extend Toxiproxy v2.12; the +compatibility adapter remains stream/TCP-only. Contributor oracle setup and +qualification commands are documented in [verification and qualification](../architecture/verification-qualification.md). diff --git a/plans/063-control-plane-exposure-and-authentication-hardening.md b/plans/063-control-plane-exposure-and-authentication-hardening.md new file mode 100644 index 0000000..ca7dbea --- /dev/null +++ b/plans/063-control-plane-exposure-and-authentication-hardening.md @@ -0,0 +1,412 @@ +# M063 — Control-Plane Exposure and Authentication Hardening + +Status: active +Depends on: M062 closed; 2026-11-17 read-only security audit at `62682d9` +Role: security corrective for the native admin and Toxiproxy compatibility +control listeners; no data-plane, route-removal, or deployment redesign +Registration baseline: `60c28a48c2375d20c0cf793372423751967f2b9a` (`main`) +Audit evidence: `62682d955c802f8caedc43ec66f7100ca1af9dbb` +(`deps/update-dependencies`; no crate source differs from `main`) + +## Objective + +Close the control-plane exposure findings from the 2026-11-17 security audit +without weakening the local developer workflow or removing any native route, +CLI command, SDK operation, or Toxiproxy semantics: + +1. make the native admin listener reject browser-originated cross-site + requests and DNS-rebinding `Host` values while keeping the documented + unauthenticated loopback workflow usable by local tools; +2. make bearer credentials for non-loopback administration resistant to + trivial guessing and make failed authentication observably throttled; +3. make bearer parsing RFC 7235-compatible without changing the accepted + token bytes; +4. refuse non-loopback Toxiproxy compatibility binds unless the caller + explicitly opts in, mirroring the native admin guard; +5. document the loopback trust model, the reverse-proxy contract, and the + remaining cleartext-transport limitation; +6. prove all of the above with integration tests, a manual browser-style + probe, the full local gate, and exact-head hosted CI. + +This milestone corrects an exposure and credential-hardening defect class. It +does not add TLS to the admin listener, does not introduce a second +authentication scheme, and does not treat `Origin` as an authentication +factor. + +## Research baseline + +At the registration baseline, the audit established: + +- the native admin default is `127.0.0.1:8475` and is unauthenticated unless + `[admin].auth_token` is configured (`docs/configuration.md:7`); +- non-loopback operation already requires `public_admin = true` plus a + non-empty token, checked at config parse (`crates/eggchaos-server/src/ + config.rs:200-213`) and again before bind (`crates/eggchaos-server/src/ + admin.rs:102-110`), with regression tests in + `crates/eggchaos-server/tests/admin_auth.rs`; +- token comparison hashes both inputs to SHA-256 before an XOR fold + (`admin.rs:683-689`), so the comparison itself is fixed-width; +- the request handler authenticates and then routes without inspecting + `Host`, `Origin`, `Sec-Fetch-Site`, or the request `Content-Type` + (`admin.rs:168-232`); +- `POST /v1/reset` ignores the request body entirely (`admin.rs:302`); +- proxy creation parses JSON regardless of the declared media type + (`admin.rs:463`); +- a live probe at the audit revision returned `200` for + `GET /v1/health` with `Host: evil.example:38475` and + `Origin: https://evil.example`, `200` for `POST /v1/reset` with + `Content-Type: text/plain`, and `201` for `POST /v1/proxies` with a + `text/plain` JSON body; +- a configured token is accepted only as `Bearer ` with an exact + case-sensitive scheme: `bearer ` is currently pinned to `403` in + `admin_auth.rs`, which is stricter than RFC 7235; +- `ToxiproxyHttp::start(bind, adapter)` binds any `SocketAddr` with no + loopback guard and no authentication + (`crates/eggchaos-toxiproxy/src/lib.rs:1143-1150`); the docs only say + "loopback by default" (`docs/toxiproxy.md:62`); +- the CLI and generated SDKs set `Content-Type: application/json` whenever + they send a body (`eggfetch-core` `Request::json`; Python `client.py` + `_request`; TypeScript `client.ts`), so a native-admin JSON media-type + requirement is compatible with first-party clients; +- EggServe preserves `ConnectionInfoExt` in request extensions, so the + admin handler can obtain the peer address for a bounded failure budget + without a new dependency; +- EggServe already bounds header read (10 s), body read (30 s), total + connection (60 s), and handler time (30 s); this milestone does not + duplicate those limits. + +The defect is not missing authentication by default on loopback. Loopback +without a token is a documented same-user trust boundary. The defect is that +a browser origin is not the same trust boundary as a local process: simple +requests, form navigations, and DNS rebinding can reach a loopback listener +that never intended to accept browser-originated control traffic. + +## Scope + +### In scope + +1. Add an admin request-origin policy that validates the `Host` authority for + every native route and rejects `Host` values outside the configured set + before routing. +2. Add an `Origin` policy for state-changing methods: a present non-null + `Origin` must use `http` or `https` and carry an allowed authority, so a + TLS-terminated deployment can accept its own `https` origin; `null` and + foreign origins are rejected. +3. Require `application/json` for native-admin requests that carry a + non-empty body; return `415` otherwise. Bodyless mutations such as + `POST /v1/reset` remain bodyless and rely on `Host`/`Origin` validation. +4. Add optional `[admin].allowed_hosts` entries for reverse-proxy and + public-host deployments. With the field absent, allow only the bind + literal, `localhost`, and the loopback literals that apply to the bind. + Reject wildcards, schemes, paths, and empty entries. +5. Require a non-loopback `auth_token` to be at least 32 bytes of + non-whitespace material. Keep loopback tokens optional and unrestricted in + length, but emit a startup warning when a loopback token is shorter than + 32 bytes. +6. Accept the bearer scheme case-insensitively while preserving the exact + credential bytes after the scheme separator. +7. Add a bounded per-peer failed-authentication budget (for example a + five-failure burst with a one-per-second refill and a bounded peer map) + that returns `429` with `Retry-After: 1`. If peer metadata is absent, + apply a small fixed failure delay instead of a shared lockout. +8. Keep `403` for missing or wrong credentials, and never echo token + material, the supplied header, or the configured token. +9. Make `ToxiproxyHttp::start` refuse a non-loopback bind with a clear + startup error, and add an explicitly named additive constructor or + options value for intentional public binds. Update the `compat_server` + example to require an explicit `--allow-public` flag or equivalent before + it will bind beyond loopback. +10. Update `docs/control-plane.md`, `docs/configuration.md`, + `docs/toxiproxy.md`, the OpenAPI error descriptions if needed, and the + README security note so operators can see the trust model and the + reverse-proxy host contract. +11. Add regression tests for every rejected and accepted shape, including + the exact audit probes, first-party CLI/SDK traffic, and the Toxiproxy + compatibility path. +12. Re-run the full local gate, the pinned Toxiproxy v2.12 differential, the + language-client qualification, and exact-head hosted CI. + +### Non-goals + +- no TLS listener, certificate management, or automatic TLS termination; +- no replacement of bearer authentication with mTLS, OAuth, signed + requests, or CSRF tokens stored in server state; +- no change to the native `/v1` route set, request/response DTOs, status + codes for successful operations, or CLI command inventory; +- no change to Toxiproxy strict-v2.12 or post-v2.12 wire semantics; +- no change to proxy data-plane behavior, fault semantics, RNG, scheduling, + evidence, or persistence; +- no removal of the documented unauthenticated loopback default; +- no new runtime dependency for host parsing or throttling; +- no change to the admin body limit (1 MiB) or connection limit (128); +- no publication, tag, or release workflow change; +- no rewrite of M059's native-auth corrective record; this plan builds on it. + +## Affected surfaces + +Expected implementation surfaces: + +- `crates/eggchaos-server/src/admin.rs` — origin policy, media-type policy, + bearer parsing, failure budget, config-derived allowlist; +- `crates/eggchaos-server/src/config.rs` — optional `allowed_hosts`, token + strength validation, field errors; +- `crates/eggchaos-server/src/lib.rs` if a public type must be re-exported; +- `crates/eggchaos-server/tests/admin_auth.rs` and a new focused integration + test file for origin/media-type behavior; +- `crates/eggchaos-toxiproxy/src/lib.rs` — loopback guard and explicit public + constructor/options; +- `crates/eggchaos-toxiproxy/examples/compat_server.rs` — explicit exposure + flag; +- `crates/eggchaos-toxiproxy/tests/` as needed for guard and public opt-in; +- `docs/control-plane.md`, `docs/configuration.md`, `docs/toxiproxy.md`, + `README.md`, and `api/openapi/eggchaos-v1.yaml` if error descriptions + change; +- `plans/registry.md` and the generated planning-state projections; +- a closure record under `plans/closure/` at closure. + +Expected non-surfaces: `eggchaos-core`, `eggchaos-experiment`, +`eggchaos-protocol` wire DTOs, `eggchaos-embed`, `eggchaos-eggfetch`, the +Python/TypeScript client source, Cargo manifests/lockfiles, and release +workflows. Any change there needs an explicit recorded reason. + +## Ordered work packages + +### WP1 — Freeze the trust model and write failing tests + +1. Record the registration baseline and the audit probe transcript. +2. Add table-driven tests that currently fail: + - foreign `Host` on `GET /v1/health` and `/metrics`; + - foreign `Origin` on `POST /v1/reset`, `POST /v1/proxies`, and + `PATCH`/`DELETE` mutations; + - `Origin: null`; + - `Content-Type: text/plain` with a JSON body; + - missing `Content-Type` with a non-empty body; + - `bearer`/`BEARER` scheme acceptance; + - duplicate `authorization` headers and the documented first-value + behavior; + - short non-loopback token rejection; + - Toxiproxy non-loopback bind rejection. +3. Add positive tests for the CLI, Python client, TypeScript client, and + loopback no-token workflow so the security policy cannot silently break + first-party consumers. + +### WP2 — Host and Origin policy + +1. Derive the default authority set from the bind (`127.0.0.1`, `localhost`, + `[::1]` as applicable) plus the literal bind address and port. +2. Parse the `Host` header without trusting proxy forwarding headers. + Reject absent, malformed, userinfo-bearing, scheme-bearing, wildcard, or + out-of-set values before route dispatch. +3. Add `[admin].allowed_hosts` as an optional bounded list for reverse-proxy + and public-host deployments. Validate entries at config parse and at + startup; do not accept `*`. +4. For state-changing methods, validate a present `Origin`: require an + `http` or `https` scheme and an authority in the allowed set; reject + `null`; allow an absent `Origin` for non-browser clients. +5. Keep `GET`/`HEAD` usable by local scrapers with the correct `Host`; do not + require `Origin` for reads. +6. Return a bounded `403` error envelope with a stable code; do not include + the offending value in the message or in logs. + +### WP3 — Media-type policy + +1. For native-admin methods that carry a body, require a media type whose + essence is `application/json` (parameters allowed). +2. Return `415` with a bounded error envelope for a missing or different + media type; read no body beyond the existing 1 MiB cap. +3. Leave bodyless mutations and bodyless `DELETE` requests unchanged. +4. Do not apply this policy to the Toxiproxy compatibility listener; parity + with upstream clients takes precedence there, and the loopback/public + guard is the compatibility control. + +### WP4 — Bearer parsing and failure budget + +1. Parse the scheme case-insensitively, require at least one separator space, + and preserve the remainder exactly for the constant-time comparison. +2. Keep SHA-256 fixed-width comparison and redaction behavior unchanged. +3. Enforce `>= 32` bytes and no whitespace-only content for non-loopback + tokens at both config parse and `NativeAdmin::start`; keep the existing + `InsecurePublicBind` failure class or add a clearly documented field + error. +4. Add a bounded per-peer failure budget using `ConnectionInfoExt` when + present; otherwise apply a fixed small delay. Do not add a process-global + lockout that a remote attacker could use to deny valid operators. +5. Add tests proving a valid token is never delayed or counted, failed + attempts are bounded, and the peer map cannot grow without limit. + +### WP5 — Toxiproxy exposure guard + +1. Make the existing `ToxiproxyHttp::start` reject a non-loopback bind with a + clear error before binding. +2. Add an additive explicit-public API (`start_with_options`, a policy + struct, or an equivalent named constructor); do not remove or rename the + existing entry point. +3. Update `examples/compat_server.rs` so a non-loopback argument fails + unless `--allow-public` (or an equivalent explicit flag) is present. +4. Add tests for the refusal path using a documentation address and for the + opt-in path on loopback. +5. Update `docs/toxiproxy.md` to state that the compatibility API has no + authentication and must not be exposed without an explicit decision. + +### WP6 — Documentation and contract reconciliation + +1. `docs/control-plane.md`: document the loopback trust model, the + Host/Origin policy, the media-type requirement, the failure-budget + behavior, and the reverse-proxy `allowed_hosts` contract. +2. `docs/configuration.md`: document `allowed_hosts`, the 32-byte + non-loopback token minimum, and the fact that the listener remains + cleartext HTTP and still requires a trusted TLS terminator. +3. `docs/toxiproxy.md` and the README security paragraph: document the + compatibility guard and the no-authentication warning. +4. If error codes or status descriptions are added to OpenAPI, update the + specification and re-run the drift check; do not add routes. +5. Update the registry row and plan header only through the normal planning + workflow. + +### WP7 — Qualification and closure + +1. Run the focused suites and the full local gate. +2. Run the audit probe commands against a fresh loopback daemon and record + the rejected statuses. +3. Run the pinned Toxiproxy v2.12 differential and the language-client + qualification. +4. Obtain exact-head hosted CI on the final candidate. +5. Write the closure record with the exact SHA, run ID, probe transcript, + test commands, and any residual limitations. + +## Invariants and failure semantics + +- No native mutation may execute for a request whose `Host` is outside the + configured set, regardless of method or body. +- A present, non-null `Origin` must match an allowed authority for + state-changing methods; `null` is always rejected for those methods. +- A body-bearing native mutation without a JSON media type never reaches + route dispatch. +- The bearer comparison remains constant-time over fixed-width digests; no + token, header value, or configured secret appears in a response, error, + trace, metric label, or test fixture that ships. +- The default loopback no-token workflow remains functional for the CLI, + Python client, TypeScript client, and local `curl` with the correct + `Host`. +- The `public_admin` guard still requires both explicit opt-in and a + non-empty token; this milestone tightens rather than relaxes it. +- Toxiproxy non-loopback binds fail before a socket is bound unless the + caller passed the explicit public option. +- Existing body, connection, header, and timeout bounds are unchanged. +- No new dependency, no `unsafe`, and no change to deterministic data-plane + behavior. +- A malformed `Host`, `Origin`, or media type yields a bounded error and + never a panic. + +## Test commands + +Focused: + +```sh +cargo test -p eggchaos-server --all-features +cargo test -p eggchaos-toxiproxy --all-features +cargo test -p eggchaos-cli --all-features +cargo test -p eggchaos-protocol --all-features +``` + +Full local gate: + +```sh +./scripts/check.sh +``` + +Language clients (using the repository's pinned Python environment): + +```sh +uv run --with-requirements .github/python-ci/requirements.txt -- sh -c ' + ./scripts/check_python_client.sh + ./scripts/check_typescript_client.sh + ./scripts/qualify_language_clients.sh +' +``` + +Pinned compatibility oracle: + +```sh +TOXIPROXY_SERVER="$(./scripts/fetch_toxiproxy_v2_12.sh)" \ +EGGCHAOS_REQUIRE_TOXIPROXY_ORACLE=1 \ +./scripts/qualify_toxiproxy_v2_12.sh +``` + +Manual audit probe (expected: `403`, `403`, `415`): + +```sh +curl -sS -i http://127.0.0.1:8475/v1/health \ + -H 'Host: evil.example:8475' -H 'Origin: https://evil.example' +curl -sS -i -X POST http://127.0.0.1:8475/v1/reset \ + -H 'Host: evil.example:8475' -H 'Origin: https://evil.example' \ + -H 'Content-Type: text/plain' --data 'x' +curl -sS -i -X POST http://127.0.0.1:8475/v1/proxies \ + -H 'Origin: https://evil.example' -H 'Content-Type: text/plain' \ + --data '{"name":"probe","listen":"127.0.0.1:0","upstream":"127.0.0.1:9"}' +``` + +Planning and contract guards: + +```sh +python3 scripts/check_planning_state.py --check +sh scripts/tests/test_planning_state.sh +python3 scripts/check_release_state_docs.py --check +./scripts/check_openapi.sh +python3 scripts/check_action_pins.py --check +``` + +## Acceptance criteria + +1. Every audit probe above returns the documented rejection status; no + mutation occurs for a foreign `Host` or `Origin`. +2. A correct `Host` and JSON body still produce the existing success status + and body for CLI and SDK requests. +3. `bearer`, `Bearer`, and `BEARER` schemes all authenticate the same exact + token; a wrong token still returns `403`. +4. Non-loopback configuration with a token shorter than 32 bytes fails at + parse and at startup; a 32-byte token succeeds. +5. `ToxiproxyHttp::start` refuses `192.0.2.1:0` before bind; the explicit + public option is required for any non-loopback bind. +6. The pinned Toxiproxy differential remains 50/50 and the language-client + qualification remains green. +7. `./scripts/check.sh`, the planning guards, and exact-head hosted CI are + green on the final candidate. +8. Documentation states the trust model and reverse-proxy contract without + claiming the listener is encrypted. + +## Stop conditions + +- Stop if `Host` validation cannot be made compatible with a reverse-proxy + deployment without a new configuration surface that the project rejects. +- Stop if JSON media-type enforcement breaks a first-party client or the + Toxiproxy differential; scope the media-type rule to the native admin only + before proceeding. +- Stop if Toxiproxy public-bind support requires removing or renaming the + existing `start` entry point; the change must be additive. +- Stop if the failure budget can be repurposed as a global denial of service + against a valid operator. +- Stop if any test requires weakening constant-time comparison, token + redaction, or the non-loopback opt-in guard. +- Do not mark the milestone closed on source inspection alone; closure needs + the probe transcript, the test evidence, and the exact-head hosted run. + +## Closure evidence + +The closure record under `plans/closure/` must include: + +- the exact candidate SHA and the exact hosted run ID with job results; +- the audit probe transcript showing the before/after behavior; +- focused and full-gate test output; +- the pinned oracle differential result and language-client result; +- the final `allowed_hosts`/token-strength documentation diff; +- residual limitations (cleartext HTTP, loopback same-user trust, any + reverse-proxy configuration requirement). + +## Follow-on rules + +M063 activates no successor. M064 (repository governance) and M065 +(residual runtime/tooling hardening) were registered as independent plans; see +`plans/registry.md` for their current execution states. A future TLS-admin +feature requires a separate ADR and plan; it must not be smuggled into this +corrective. diff --git a/plans/064-repository-security-governance-and-release-integrity.md b/plans/064-repository-security-governance-and-release-integrity.md new file mode 100644 index 0000000..9baaa3b --- /dev/null +++ b/plans/064-repository-security-governance-and-release-integrity.md @@ -0,0 +1,412 @@ +# M064 — Repository Security Governance and Release-Integrity Guardrails + +Status: blocked +Depends on: M062 closed; 2026-11-17 read-only security audit at `62682d9` +Role: repository-governance and supply-chain corrective; no production-code +change +Registration baseline: `60c28a48c2375d20c0cf793372423751967f2b9a` (`main`) +Audit evidence: `62682d955c802f8caedc43ec66f7100ca1af9dbb` + +## Current execution status (2026-11-18) + +M064 is blocked, not closed. GitHub readback confirms active rulesets +`main-protection` (ID `27505299`) and `release-tag-protection` (ID +`27505300`), enabled secret scanning and push protection, enabled vulnerability +alerts (`GET /vulnerability-alerts` returned `204`), enabled Dependabot +security updates, and zero open Dependabot alerts. The previous three +push-metadata vulnerability findings were not reproduced in the committed +Cargo lockfiles or the audited lockfile set; no advisory was dismissed. + +The organization API reports the `eggstack` plan as `Free`. Repository-settings +update requests for non-provider pattern scanning and secret-scanning validity +checks returned successfully, but subsequent readbacks still report both as +disabled. GitHub’s documented plan requirements make these controls unavailable +under the current plan; WP3 therefore remains incomplete under this plan’s +acceptance criteria and stop condition. The pinned CodeQL workflow is present +only in the local candidate: there is no hosted run or analysis result for the +candidate, and the code-scanning-alert endpoint has no analysis to return. +Exact-head hosted CI and ruleset behavior on a test PR are also unverified. + +Do not mark M064 closed unless the required plan features become available and +the remaining exact-head hosted evidence is obtained. The repository-security +readback and current limitations are recorded in `SECURITY.md`. + +## Objective + +Close the repository-governance findings from the 2026-11-17 security audit +so the project's published crates and attested binaries are protected by the +same discipline the code already applies: + +1. protect `main` with a ruleset that requires pull requests and the + qualified status checks, and blocks force-push and deletion; +2. protect `v*.*.*` release tags against creation, update, and deletion by + anyone other than the release owner; +3. enable the GitHub security features that are currently disabled: + secret scanning, push protection, non-provider pattern scanning, + validity checks, Dependabot alerts, and Dependabot security updates; +4. add a pinned, least-privilege CodeQL workflow for Rust and the workflow + surfaces, or record a supported fallback if CodeQL cannot analyse the + pinned toolchain; +5. reconcile the three default-branch vulnerabilities reported in earlier + push metadata, using the enabled alerting path rather than inference; +6. decide and document the dependency-review failure threshold and any + additional Python/npm advisory coverage; +7. record reproducible API readbacks so the enabled state is evidence, not a + claim. + +This milestone changes repository settings and CI configuration. It does not +change crate source, the release workflow DAG, package versions, or the +published-release record. + +## Research baseline + +At the registration baseline, the audit established: + +- `GET /repos/eggstack/eggchaos/branches/main/protection` returns `404` + "Branch not protected"; +- `GET /repos/eggstack/eggchaos/rulesets` returns `[]`, so neither branch nor + tag rulesets are active; +- `security_and_analysis` reports `secret_scanning`, + `secret_scanning_push_protection`, + `secret_scanning_non_provider_patterns`, + `secret_scanning_validity_checks`, and + `dependabot_security_updates` all `disabled`; +- `GET /repos/eggstack/eggchaos/vulnerability-alerts` returns `204`, the + documented response when vulnerability alerts are enabled; `404` means they + are not enabled; +- `GET /repos/eggstack/eggchaos/code-scanning/alerts` returns `404`, so code + scanning is not configured; +- `.github/dependabot.yml` already covers Cargo (all four workspaces), + GitHub Actions, npm, and the pinned Python CI requirements, but version + updates are not the same control as security alerts or security updates; +- every existing workflow already uses full-length action SHAs, + `permissions: contents: read`, and `persist-credentials: false`; the + release artifact job alone adds `id-token: write` and + `attestations: write`; +- `.github/workflows/dependency-review.yml` fails on `high` severity only; +- `.github/workflows/security.yml` audits all four Cargo lockfiles daily and + runs the `cargo-deny` policy, which is the current Rust advisory path; +- `cargo audit --deny warnings` reports no advisories on the four lockfiles + at the audit revision, and also none on `main`'s lockfiles; +- earlier push metadata reported three default-branch vulnerabilities that + could not be reproduced from any committed Cargo lockfile; because + Dependabot alerts are disabled, the GitHub-side count could not be + triaged through the API; +- `release.yml` builds and attests binaries from `v*.*.*` tags, so tag + integrity is a release-integrity control, not a convenience setting; +- `SECURITY.md` already documents private vulnerability reporting and the + supported release line. + +The defect class is missing repository guardrails, not a code vulnerability. +The repository is public, so secret scanning and push protection are +available without a paid plan; rulesets and CodeQL are available to public +repositories as well. Enabling these settings is an owner-authorized +operation; this plan cannot execute it by itself. + +## Scope + +### In scope + +1. Create a `main` ruleset with: + - pull request required before merge; + - the qualified status checks required and up to date (the exact contexts + are enumerated from a green run, not guessed: at minimum the Rust + `check`, `language-clients`, `python-native`, `api-gate`, and + `performance-provenance` families, plus the dependency-review check and + the new CodeQL check); + - non-fast-forward (force-push) blocked; + - deletion blocked; + - linear history and conversation resolution required; + - a documented, minimal bypass for the repository owner so an emergency + release is not permanently locked out. If the account is a solo + maintainer, state the review limitation explicitly rather than + pretending independent review exists. +2. Create a `v*.*.*` tag ruleset that restricts creation, update, and + deletion to the release owner, with the same documented bypass. +3. Enable secret scanning, push protection, non-provider patterns, and + validity checks through the repository security settings. +4. Enable vulnerability alerts and Dependabot security updates; keep the + existing version-update configuration and grouping. +5. Add `.github/workflows/codeql.yml`: + - triggers on `push` to `main`, `pull_request`, and a bounded schedule; + - `permissions: contents: read` plus `security-events: write` only; + - SHA-pinned `actions/checkout`, the pinned Rust toolchain action, and a + resolved, pinned `github/codeql-action` release SHA with a version + comment; + - a Rust analysis that builds the workspace under the pinned 1.89 + toolchain, or a documented supported build mode if CodeQL requires a + different one; + - the same `persist-credentials: false` discipline as the other + workflows. +6. If CodeQL Rust cannot analyse the pinned toolchain, record the attempted + configuration and use a supported fallback (for example a pinned + `cargo-clippy` SARIF upload or an equivalent static-analysis job) without + claiming CodeQL coverage that does not exist. +7. Enable the Dependabot alert path and triage every open alert: + - reproduce each advisory against the committed lockfile; + - fix it by a compatible dependency update where a fixed version exists; + - otherwise dismiss with an explicit, recorded reason and scope; + - reconcile the earlier three-vulnerability report, or record that it + cannot be reproduced and why. +8. Decide the dependency-review threshold with evidence: + - keep `high` and document that `cargo audit --deny warnings` covers all + Rust severities; or + - lower it to `moderate` if the resulting signal is actionable and does + not create noise the project will ignore. +9. Evaluate Python/npm advisory coverage. The Python clients are stdlib-only + and the TypeScript client has no runtime dependencies; the remaining + surface is pinned build/test tooling. Add a pinned `pip-audit`-style check + only if it does not introduce an unpinned runtime dependency, and record + the decision either way. +10. Add a reproducible repository-settings readback (a small stdlib script + or a documented command set) that asserts rulesets, security features, + alerts, and CodeQL state from the GitHub API. The readback must not be + wired into pull-request CI with a privileged token; run it manually or in + an owner-controlled job. +11. Update `SECURITY.md`, `architecture/tooling-distribution.md`, and the + README security section with the enabled controls, the owner bypass, the + release-tag policy, and the alert-triage expectations. +12. Obtain exact-head hosted CI plus a green CodeQL run and record the + evidence. + +### Non-goals + +- no crate source, Cargo manifest, lockfile, MSRV, package-version, API, + wire, CLI, SDK, fault, scenario, Toxiproxy, or Eggfetch change; +- no change to the release workflow's jobs, permissions, artifact set, + attestation scope, or publication sequence; +- no tag, crates.io/PyPI/npm publication, or GitHub Release; +- no organization-wide policy change outside `eggstack/eggchaos`; +- no claim that branch protection provides independent review when the + repository has a single maintainer; +- no weakening of an existing workflow permission to make a new feature + easier; +- no secret, token, or credential written into the repository or a workflow + file; +- no rewrite of M059's security-hardening closure record; this plan extends + its repository-governance layer. + +## Affected surfaces + +Expected implementation surfaces: + +- `.github/workflows/codeql.yml` (new); +- `.github/workflows/dependency-review.yml` if the threshold changes; +- `.github/dependabot.yml` only if grouping or coverage needs correction; +- `SECURITY.md`; +- `architecture/tooling-distribution.md`; +- `README.md` security paragraph if the operator-facing controls change; +- `scripts/` for an optional settings-readback helper and its test; +- `plans/registry.md`, this plan, and the generated planning-state + projections; +- a closure record under `plans/closure/` at closure. + +GitHub repository settings are not files in this repository. Their evidence +belongs in the closure record with API readbacks, not in a fabricated local +configuration file. + +## Ordered work packages + +### WP1 — Snapshot the current state + +1. Record the registration baseline and the exact API responses for branch + protection, rulesets, `security_and_analysis`, vulnerability alerts, and + code scanning. +2. Enumerate the actual required check-run contexts from the most recent + green run on `main` or on the qualification candidate. Do not guess check + names in the ruleset. +3. Confirm the authenticated GitHub identity can administer the repository; + record the permission used. If it cannot, stop at this package and record + the owner action required. + +### WP2 — Branch and tag rulesets + +1. Create the `main` ruleset in evaluate mode first if available, then + active, with the enumerated checks. +2. Verify a test pull request cannot merge while a required check is failing + or missing, and that direct force-push/deletion is rejected. +3. Create the release-tag ruleset for `refs/tags/v*.*.*`; verify a + non-owner token cannot create or move a matching tag. +4. Record the ruleset IDs and the exact readback JSON in the closure + evidence. Do not leave an evaluate-mode ruleset as the final state. + +### WP3 — Secret scanning and Dependabot + +1. Enable secret scanning, push protection, non-provider patterns, and + validity checks. +2. Enable vulnerability alerts and Dependabot security updates. +3. Verify with readbacks, including the `204`/`200` distinction where the + API uses it. +4. Open the Dependabot alert list and triage every open alert under WP6. + +### WP4 — CodeQL + +1. Resolve the current `github/codeql-action` release SHA and record its + version comment; do not use a moving tag. +2. Add the workflow with least-privilege permissions and the same + `persist-credentials: false` discipline. +3. Verify the Rust analysis actually builds and analyses the workspace on + the pinned 1.89 toolchain; if it cannot, implement and document the + fallback rather than leaving a permanently red workflow. +4. Confirm the workflow is accepted by `scripts/check_action_pins.py` and + that a pull request produces a code-scanning result. +5. Record the first green CodeQL run ID and the analysed commit. + +### WP5 — Alert and advisory reconciliation + +1. Query the enabled Dependabot alert path and list every open alert. +2. Reproduce each advisory against the committed lockfile with the pinned + audit tooling; record the path, package, advisory ID, and fixed version. +3. Fix what is fixable within the existing compatibility line; do not use + this milestone for a major migration. +4. Dismiss only with a recorded reason and scope; never dismiss an + unreproduced alert merely to make the count zero. +5. Reconcile the earlier three-vulnerability push report: either identify + and address the same advisories, or record that the current lockfiles + audit clean and that the GitHub-side count cannot be reproduced. Do not + claim a fix that was not verified. +6. Decide and document the dependency-review threshold and Python/npm + advisory coverage. + +### WP6 — Documentation and readback + +1. Update `SECURITY.md` with the enabled reporting/alerting controls and the + supported release line. +2. Update `architecture/tooling-distribution.md` with the ruleset, tag, + secret-scanning, Dependabot, CodeQL, and readback controls. +3. Add a README security note that points operators at the policy and the + supported line without implying a bug bounty or guaranteed SLA. +4. Add the optional reusable readback helper; keep it stdlib-only or use the + already-authenticated `gh` CLI, and do not add a dependency to the + production crates. +5. Run the planning, version, release-state, and action-pin guards. + +### WP7 — Qualification and closure + +1. Obtain exact-head hosted CI on the final candidate and a green CodeQL + analysis for that SHA. +2. Verify the ruleset/check behavior on a real pull request. +3. Write the closure record with API readbacks, ruleset IDs, alert triage, + run IDs, and any owner-only settings that could not be verified from the + repository. + +## Invariants and failure semantics + +- `main` cannot be force-pushed or deleted once the ruleset is active; the + only bypass is the documented owner path. +- A `v*.*.*` tag cannot be created, moved, or deleted by a non-owner token. +- Existing workflows keep `contents: read` unless they already require a + narrower write scope; the CodeQL job adds only `security-events: write`. +- No new secret is introduced; the readback uses the operator's existing + authenticated `gh` session and records no token material. +- If a setting is unavailable on the repository plan or requires an + organization owner, the plan records the blocker and does not mark the + work package complete. +- If an alert cannot be reproduced, it is recorded as unreproduced, not + silently dismissed. +- No production behavior changes, so the runtime and data-plane test matrix + remains a regression check rather than a new-feature gate. +- The release workflow's permissions, jobs, and artifact contract remain + byte-identical except for the additive CodeQL workflow. + +## Test commands + +Repository guards: + +```sh +python3 scripts/check_action_pins.py --check +python3 scripts/check_planning_state.py --check +sh scripts/tests/test_planning_state.sh +python3 scripts/check_release_state_docs.py --check +python3 scripts/check_version_coherence.py --check +python3 scripts/check_lock_coherence.py --check +``` + +Workflow syntax and action-pin validation: + +```sh +# If the repository's pinned Python environment is available: +uv run --with-requirements .github/python-ci/requirements.txt -- \ + python3 -c 'import yaml, pathlib; [yaml.safe_load(p.read_text()) for p in pathlib.Path(".github/workflows").glob("*.yml")]' +python3 scripts/check_action_pins.py --check +``` + +Settings readback (owner-authenticated; exact helper name may change): + +```sh +gh api repos/eggstack/eggchaos/rulesets +gh api repos/eggstack/eggchaos/branches/main/protection +gh api repos/eggstack/eggchaos --jq '.security_and_analysis' +gh api repos/eggstack/eggchaos/vulnerability-alerts +gh api 'repos/eggstack/eggchaos/dependabot/alerts?state=open' +gh api repos/eggstack/eggchaos/code-scanning/alerts +``` + +Live checks: + +```sh +cargo audit --deny warnings +for dir in . bindings/python-native benchmarks fuzz; do + (cd "$dir" && cargo audit --deny warnings) +done +cargo deny check advisories licenses bans sources +``` + +## Acceptance criteria + +1. `main` has an active ruleset requiring a pull request, the enumerated + status checks, linear history, and conversation resolution, with + force-push and deletion blocked; a failing-check PR cannot merge. +2. A `v*.*.*` tag cannot be created, updated, or deleted by a non-owner + token. +3. Secret scanning, push protection, non-provider patterns, validity + checks, vulnerability alerts, and Dependabot security updates all read + back as enabled. +4. CodeQL is either green on the exact candidate for Rust and the workflow + surfaces, or a documented supported fallback is green and the CodeQL gap + is recorded. A permanently failing workflow is not acceptable. +5. Every open Dependabot alert is fixed or dismissed with a recorded reason; + the earlier three-vulnerability report is reconciled or explicitly marked + unreproduced with the evidence. +6. The dependency-review threshold and Python/npm advisory coverage are + documented decisions, not accidental omissions. +7. `SECURITY.md`, `architecture/tooling-distribution.md`, and the README + describe the enabled controls and the owner bypass. +8. All repository guards and exact-head hosted CI are green; the closure + record contains the API readback evidence and run IDs. + +## Stop conditions + +- Stop if the authenticated account lacks repository-admin permission; record + the exact owner action instead of fabricating enabled state. +- Stop if the repository plan does not offer a required feature (for example + private-repository-only secret scanning); record the plan limitation. +- Stop if the `main` ruleset would lock the sole maintainer out of an + emergency release without a documented bypass. +- Stop if CodeQL cannot build the pinned 1.89 workspace and no supported + fallback exists; record the gap rather than claiming coverage. +- Stop if enabling Dependabot alerts requires a broader token scope than the + operator is willing to grant; record the blocker. +- Do not close on "settings changed" alone; closure needs readback and live + behavior evidence. + +## Closure evidence + +The closure record under `plans/closure/` must include: + +- the exact candidate SHA and exact hosted run IDs; +- ruleset IDs, target refs, required contexts, bypass actors, and readback + JSON; +- the `security_and_analysis` readback and vulnerability-alert state; +- the CodeQL run ID and the analysed SHA, or the documented fallback; +- the Dependabot alert list with per-alert disposition and evidence; +- the dependency-review threshold and Python/npm coverage decision; +- the documentation diff and guard outputs; +- any remaining owner-only action or unverifiable setting. + +## Follow-on rules + +M064 activates no successor. M063 and M065 are independently ready. A future +organization-wide policy, signed-commit requirement, or release-environment +approval gate needs a separate plan; it must not be inferred from this +milestone's ruleset. diff --git a/plans/065-residual-runtime-and-qualification-tooling-hardening.md b/plans/065-residual-runtime-and-qualification-tooling-hardening.md new file mode 100644 index 0000000..bc4f59e --- /dev/null +++ b/plans/065-residual-runtime-and-qualification-tooling-hardening.md @@ -0,0 +1,351 @@ +# M065 — Residual Runtime and Qualification-Tooling Hardening + +Status: active +Depends on: M062 closed; 2026-11-17 read-only security audit at `62682d9` +Role: low-risk hardening of qualification tooling, metrics exposition, and +documented runtime resource limits; no protocol or default-behavior change +Registration baseline: `60c28a48c2375d20c0cf793372423751967f2b9a` (`main`) +Audit evidence: `62682d955c802f8caedc43ec66f7100ca1af9dbb` + +## Objective + +Close the residual low-severity findings from the 2026-11-17 security audit +without expanding the runtime's ownership boundaries or changing any default: + +1. remove predictable `/tmp` paths and unrestricted redirects from the + external-oracle fetch and qualification scripts, while preserving their + documented stdout and checksum contracts; +2. make Prometheus label serialization escape label values even though + proxy-name validation currently prevents hostile names from reaching it; +3. document the per-connection memory amplification envelope and the + `max_connections` mitigation for proxy listeners that are intentionally + exposed beyond loopback; +4. evaluate an optional stream idle timeout through the existing + `eggress-relay` boundary. If the pinned relay cannot express it without + forking relay semantics, record the residual risk and an upstream request + instead of copying the relay loop; +5. document the `--admin-token` process-argument exposure and the environment + alternative; +6. prove the script and metrics changes with focused tests and the full gate. + +M065 is deliberately additive. It changes no default timeout, no default +connection limit, no wire format, and no release workflow. + +## Research baseline + +At the registration baseline, the audit established: + +- `scripts/fetch_toxiproxy_v2_12.sh` downloads to a caller/default destination + under `${TMPDIR:-/tmp}`, runs `mkdir -p`, downloads with + `curl --location`, then verifies SHA-256 (lines 15-28); +- `scripts/fetch_toxiproxy_post_v2_12.sh` uses a fixed + `${TMPDIR:-/tmp}/eggchaos-toxiproxy-post-v2-12-40f7fd31` destination, + `mkdir -p`, `curl --location`, a committed source-archive SHA-256, and a + `mkdir`/`tar` extraction path (lines 65-108); +- `scripts/qualify_toxiproxy_post_v2_12.sh` writes a fixed + `/tmp/post-v212.log` (lines 56-58); +- both fetchers verify content checksums, so the residual risk is local + file clobbering/symlink behavior on shared hosts and a cleartext redirect + downgrade, not substituted upstream content; +- `metrics_text` interpolates stream and datagram proxy names, directions, + fault types, and kinds directly into label strings + (`crates/eggchaos-server/src/runtime/control.rs:132,149,159,182,225,246, + 260,270,316,322`); +- proxy names are validated to `[A-Za-z0-9._-]+` and 1..=128 bytes + (`crates/eggchaos-server/src/runtime/mod.rs:135-148`, + `runtime/datagram/model.rs:133-140`), so the current validation prevents a + hostile name from reaching the unescaped writer; escaping is + defense-in-depth, not a live injection fix; +- a latency fault may configure `max_buffer_bytes` up to 67,108,864 bytes + (`docs/configuration.md:56`), and the default global connection limit is + 1024; the worst-case buffered envelope is therefore an operator-visible + multiplication that is not currently documented; +- stream connections have no idle timeout; datagram associations do have an + `association_idle_timeout_ms` bound; +- the proxy data-plane copy and half-close behavior are owned by the pinned + `eggress-relay` crate; the workspace forbids forking its semantics, and the + pinned `1.0.12` source exposes no idle-timeout knob (only shutdown drain + timeouts); +- the CLI exposes `--admin-token` with an `EGGCHAOS_ADMIN_TOKEN` fallback + (`crates/eggchaos-cli/src/main.rs:26-28`), and the docs already prefer the + environment variable; +- EggServe bounds admin header/body/total/handler time, so this plan does + not add duplicate HTTP timeouts. + +## Scope + +### In scope + +1. Harden `scripts/fetch_toxiproxy_v2_12.sh`: + - create a private temporary directory with a portable `mktemp -d` + template and mode `0700`; + - download into the temporary directory, verify the committed SHA-256, + and only then move/install the executable at the requested destination; + - use `--proto '=https' --proto-redir '=https'` with `curl --fail + --location`; + - install a cleanup trap that removes only the temporary directory and + preserves the existing stdout contract (one executable path); + - keep the version assertion and the checksum-mismatch failure behavior. +2. Harden `scripts/fetch_toxiproxy_post_v2_12.sh` equivalently: + - private temporary archive/extraction/build directory; no fixed + destination until verification succeeds; + - preserve the committed source-archive checksum and the Go toolchain + identity assertions; + - preserve `--path-only`/`--json`/default stdout contracts and the + one-record JSON shape; + - clean temporary state on exit/signal and never leave a partial + executable at the final destination. +3. Harden `scripts/qualify_toxiproxy_post_v2_12.sh`: + - use `mktemp` for the differential log and a cleanup trap; + - keep the existing failure-tail behavior and summary grep. +4. Add a Prometheus label-escaping helper in the server metrics writer: + - escape backslash, double quote, and newline per the Prometheus text + exposition format; + - apply it to every label value inserted by `metrics_text`, including + proxy names, directions, fault types, outcome/result/flow constants, and + datagram kinds; + - leave the existing name validation and cardinality bounds unchanged. +5. Add unit tests for the escaping helper and a metrics-output assertion + using a synthetic label value that would otherwise break the exposition + (the test may call the helper directly because the public API correctly + rejects such names). +6. Document the resource envelope in `docs/configuration.md`: + - `max_buffer_bytes` per latency fault multiplied by the global and + per-proxy connection bounds; + - the recommendation to set per-proxy `max_connections` and to keep + listeners on loopback unless exposure is intentional; + - the fact that stream connections have no idle timeout and that + `max_connections` is the current bound. +7. Evaluate stream idle-timeout support at the `eggress-relay` boundary: + - if the pinned relay exposes a supported no-progress timeout, add an + optional `[runtime] stream_idle_timeout_ms` with `0`/absent meaning + disabled, bounded to a documented range, and implement it through the + relay API; + - if it does not, do not fork or reimplement the relay copy loop; record + the residual risk, document the mitigation, and open an upstream + request against Eggress. This outcome is an accepted documented gap, + not a code change. +8. Document the CLI token-argument exposure in `README.md` or + `docs/control-plane.md`: `--admin-token` is visible in a local process + listing; prefer `EGGCHAOS_ADMIN_TOKEN` or a protected config file, and do + not paste tokens into shell history. +9. Run the focused script tests, the server tests, the full local gate, and + exact-head hosted CI. + +### Non-goals + +- no change to any default timeout, connection limit, buffer bound, route, + fault semantic, RNG, scenario, evidence, or payload handling; +- no fork or copy of `eggress-relay`'s bidirectional copy/half-close logic; +- no new runtime dependency; +- no change to the fetch scripts' checksum values, toolchain identity + assertions, or stdout contracts; +- no change to release workflows or artifact names; +- no TLS or admin-listener work (M063 owns that); +- no repository-settings work (M064 owns that); +- no metrics label cardinality or naming change; +- no performance-threshold retuning. + +## Affected surfaces + +Expected implementation surfaces: + +- `scripts/fetch_toxiproxy_v2_12.sh`; +- `scripts/fetch_toxiproxy_post_v2_12.sh`; +- `scripts/qualify_toxiproxy_post_v2_12.sh`; +- `scripts/tests/test_fetch_toxiproxy_post_v2_12_contract.sh` and any + existing cleanup-trap test that covers these scripts; +- `crates/eggchaos-server/src/runtime/control.rs` (escaping helper and + call sites); +- `crates/eggchaos-server/src/config.rs` only if the optional idle timeout is + supported by the pinned relay; +- `docs/configuration.md`, `docs/control-plane.md`, `README.md`; +- `plans/registry.md`, this plan, and the generated planning-state + projections; +- a closure record under `plans/closure/` at closure. + +## Ordered work packages + +### WP1 — Freeze the script contracts + +1. Record the current stdout shapes: + - v2.12 fetcher: one executable path; + - post-v2.12 fetcher: one path by default/`--path-only`, one JSON record + with `--json`; + - failure paths: diagnostics on stderr, nonzero exit, no path on stdout. +2. Run the existing contract tests once to confirm the baseline. +3. Add failing assertions for the new temporary-path and redirect behavior + without changing the expected stdout. + +### WP2 — Fetch-script hardening + +1. Replace fixed paths with `mktemp -d` directories created under + `${TMPDIR:-/tmp}` with a template that works on macOS and Linux. +2. Download to the temporary directory; verify the checksum there; only then + install the executable at the requested destination with the expected + mode. +3. Add `--proto '=https' --proto-redir '=https'` to every `curl` invocation. +4. Add `trap` cleanup for `EXIT HUP INT TERM`; ensure a checksum mismatch + removes temporary artifacts and leaves no executable at the destination. +5. Keep the existing version/toolchain assertions and all stdout contracts. +6. Update the qualification wrapper to use a temporary log and cleanup trap. + +### WP3 — Metrics label escaping + +1. Add a small pure helper that escapes `\`, `"`, and newline and returns a + borrowed value when no escaping is needed. +2. Apply it at every label insertion in `metrics_text`; do not escape metric + names, HELP text, or numeric samples. +3. Add unit tests for the helper and an assertion that a synthetic + quote/newline value produces one valid exposition line per sample. +4. Confirm existing metric names, labels, and values are byte-identical for + normal names. + +### WP4 — Idle-timeout evaluation + +1. Inspect the pinned `eggress-relay` public API for a no-progress or idle + timeout configuration. +2. If present, add the optional `[runtime] stream_idle_timeout_ms` field, + validate the range, thread it through the existing relay boundary, and + test expiry with paused time, half-close, and byte conservation. +3. If absent, do not modify the relay loop. Record the exact API gap, add the + documentation mitigation, and create a bounded upstream request against + Eggress. Treat this as the accepted outcome for this milestone. +4. Either outcome must leave the default behavior unchanged. + +### WP5 — Resource and token documentation + +1. Add the memory-envelope section to `docs/configuration.md` with the + worst-case multiplication and the per-proxy `max_connections` guidance. +2. Document the no-idle-timeout residual and the loopback/exposure guidance. +3. Document the `--admin-token` process-listing exposure and the environment + alternative. +4. Keep the existing TLS-terminator warning and the public-admin token rules + unchanged except for the M063 cross-reference. + +### WP6 — Qualification and closure + +1. Run the focused script tests and `sh -n` on every changed script. +2. Run `cargo test -p eggchaos-server --all-features` and the full local + gate. +3. Verify the fetchers still produce their documented stdout on the pinned + hosts and that a checksum mismatch fails closed. +4. Obtain exact-head hosted CI. +5. Write the closure record with the exact SHA, run ID, script contract + transcript, metrics test evidence, and the idle-timeout disposition + (implemented or documented upstream gap). + +## Invariants and failure semantics + +- The fetchers print no executable path to stdout on failure, and a checksum + mismatch leaves no executable at the requested destination. +- Temporary directories are private, unique, and removed on normal exit and + on `HUP`/`INT`/`TERM`. +- HTTPS is required for the initial request and every redirect. +- Existing checksum values and toolchain identity assertions are unchanged. +- The metrics writer emits syntactically valid Prometheus text for any label + value; normal labels remain byte-identical. +- No default runtime timeout or connection limit changes. If the optional + idle timeout is added, `0`/absent preserves today's behavior exactly. +- If the idle timeout is implemented, it must close gracefully without + discarding already-forwarded bytes, must respect half-close, and must not + run a second copy loop. +- No new dependency and no `unsafe`. +- No script writes a secret or token to a log or stdout. + +## Test commands + +Script contracts and shell syntax: + +```sh +sh -n scripts/fetch_toxiproxy_v2_12.sh +sh -n scripts/fetch_toxiproxy_post_v2_12.sh +sh -n scripts/qualify_toxiproxy_post_v2_12.sh +sh scripts/tests/test_fetch_toxiproxy_post_v2_12_contract.sh +sh scripts/tests/test_cleanup_traps.sh +``` + +Server and metrics: + +```sh +cargo test -p eggchaos-server --all-features +cargo test -p eggchaos-core --all-features +``` + +Full local gate: + +```sh +./scripts/check.sh +``` + +Oracle smoke (only if the host supports it): + +```sh +TOXIPROXY_SERVER="$(./scripts/fetch_toxiproxy_v2_12.sh)" \ +EGGCHAOS_REQUIRE_TOXIPROXY_ORACLE=1 \ +./scripts/qualify_toxiproxy_v2_12.sh +``` + +Planning and sign-off guards: + +```sh +python3 scripts/check_planning_state.py --check +sh scripts/tests/test_planning_state.sh +python3 scripts/check_release_state_docs.py --check +python3 scripts/check_action_pins.py --check +git diff --check +``` + +## Acceptance criteria + +1. Every fetcher downloads through a private temporary directory, verifies + its checksum before installing, uses HTTPS-only redirects, and cleans up + on exit and signals. +2. The stdout contracts and failure behavior are unchanged; the existing + contract tests pass with added temporary-path assertions. +3. The qualification wrapper no longer uses a fixed `/tmp` log. +4. The metrics writer escapes label values; unit tests cover backslash, + quote, newline, and a synthetic mixed value; normal output is unchanged. +5. `docs/configuration.md` documents the memory envelope, the no-idle-timeout + residual, and the `max_connections` mitigation. +6. The idle-timeout disposition is explicit: implemented through the relay + API with paused-time tests, or recorded as an upstream gap with no relay + fork and a documented mitigation. +7. `./scripts/check.sh` and exact-head hosted CI are green; no default + behavior or release-workflow change is present in the diff. + +## Stop conditions + +- Stop if a portable `mktemp -d` template cannot be found for the supported + hosts; use the narrowest documented fallback rather than a fixed path. +- Stop if installing the verified executable at the caller's destination + requires deleting an existing user file without confirmation; preserve the + existing overwrite contract only where it is already documented. +- Stop if metrics escaping changes normal output or a snapshot test; fix the + helper rather than updating fixtures. +- Stop if idle-timeout work requires modifying `eggress-relay` semantics or + copying its copy loop; take the documentation/upstream-request path. +- Stop if the optional timeout would change default half-close or + byte-conservation behavior. +- Do not close on script inspection alone; closure needs the contract + transcript, the mismatch failure, and the hosted run. + +## Closure evidence + +The closure record under `plans/closure/` must include: + +- the exact candidate SHA and exact hosted run ID; +- before/after stdout and failure-path transcripts for both fetchers; +- the checksum-mismatch and signal-cleanup evidence; +- the metrics escaping unit output and a normal-output byte comparison; +- the idle-timeout disposition and, if deferred, the pinned relay API gap and + the upstream request; +- the documentation diff and guard outputs; +- confirmation that no default timeout, limit, or release workflow changed. + +## Follow-on rules + +M065 activates no successor. M063 and M064 are independently ready. Any +future idle-timeout implementation that requires relay changes must be +registered against Eggress or a separate plan; it must not fork +`eggress-relay` semantics inside Eggchaos. diff --git a/plans/README.md b/plans/README.md index 86aa626..68d4864 100644 --- a/plans/README.md +++ b/plans/README.md @@ -8,7 +8,7 @@ This directory holds the project's architecture decisions, milestone plans, stat | --- | --- | | `roadmap.md` | Architecture, invariants, non-goals, and future directions. | | `registry.md` | Sole hand-maintained source of milestone status and dependencies. | -| `000-*.md`–`062-*.md` | Scoped milestone plans. All milestones through M062 are closed; retain their plans as historical handoffs. | +| `000-*.md`–`065-*.md` | Scoped milestone plans. M000–M062 are closed; M063 and M065 are active, while M064 is blocked by GitHub plan limitations. Retain closed plans as historical handoffs. | | `adrs/` | Durable architecture decisions. | | `reference/` | Parity and verification contracts, not status. | | `closure/` | Exact-candidate milestone closure evidence. | @@ -24,12 +24,18 @@ This directory holds the project's architecture decisions, milestone plans, stat ## Current planning state +**Active (in flight):** +- `M063` (active; plan `063-control-plane-exposure-and-authentication-hardening.md`) +- `M065` (active; plan `065-residual-runtime-and-qualification-tooling-hardening.md`) + +**Blocked (waiting on a predecessor closure):** +- M064 + **Highest closed milestone:** `M062` (see registry for closure evidence). -**Execution order:** no active or ready milestones. +**Execution order:** `M063`, `M065` - ## Status and closure rules - `registry.md` is the only status authority. Its `active`, `blocked`, `closed`, and `ready` states are projected into the generated blocks in `AGENTS.md`, this file, `roadmap.md`, and `architecture/overview.md`. diff --git a/plans/registry.md b/plans/registry.md index 62e8406..6a6383c 100644 --- a/plans/registry.md +++ b/plans/registry.md @@ -1,6 +1,6 @@ # Eggchaos Plan Registry -Last reconciled: 2026-11-13 (M000–M062 closed; no active or ready milestones) +Last reconciled: 2026-11-18 (M000–M062 closed; M063 and M065 active; M064 blocked by unavailable GitHub plan features) This file is the compact source of truth for active milestone state. Detailed scope lives in the numbered plans. Historical closure evidence belongs in `plans/closure/`. @@ -69,6 +69,9 @@ This file is the compact source of truth for active milestone state. Detailed sc | M060 | `060-post-v0-2-0-documentation-status-and-drift-guard-cleanup-corrective.md` | **closed** | M058, M059 | Closed on exact candidate `e897cc4767f0bb2c10feaae46232ab2e52666d90`; evidence in `plans/closure/M060-post-v0-2-0-documentation-status-and-drift-guard-cleanup-corrective-closure.md`. M059 plan header closed; `SECURITY.md` support table and `docs/release-notes-v0.2.0.md` reflect the published `v0.2.0`; architecture deep-dives carry the M058 (published) / M059 (pre-publication hardening) / M057 (historical hosted qualification) authority layers and the narrowed PyO3 unsafe boundary; `architecture/tooling-distribution.md` documents `npm ci --ignore-scripts --no-audit --no-fund` and the historicalized 0.2.0 baseline; `.github/workflows/release.yml` retains only the comment-level cleanup; `plans/registry.md` narrative reconciled. New stdlib-only `scripts/check_release_state_docs.py` + `scripts/tests/test_release_state_docs.sh` (six named deliberate-drift negative tests + registry-state + duplicate-detection wiring) wired into `scripts/check.sh` and the `language-clients` CI job. `git diff b6a277d..HEAD` proves no Rust source, Cargo manifest, lockfile, OpenAPI, generated SDK contract, release artifact, package version, or MSRV change. M058/M059 closure records untouched. M060 activates no automatic successor. **M061 reconciliation:** hosted CI never ran on the exact M060 implementation candidate `e897cc4` (no Actions run exists for that SHA); the M060 closure record's WP6 hosted paragraph was closed with an unfilled `` placeholder. Runs `37028684309@4742206` and `37266737795@3ebee30` are later descendant evidence and do **not** qualify `e897cc4`. `e897cc4` remains M060's implementation/local-qualification candidate and is preserved unchanged; the hosted exact-head evidence gap is reconciled additively by M061 (see M061 row and the "M061 reconciliation and erratum" section of the M060 closure record). | | M061 | `061-m060-closure-evidence-and-plan-status-consistency-corrective.md` | **closed** | M060 historical closure + post-M060 docs audit at `3ebee30` | Closed on exact candidate `97913754c125864dbbccb4a269e5ee51102c3de8`; evidence in `plans/closure/M061-m060-closure-evidence-and-plan-status-consistency-corrective-closure.md`. Hosted run `37366364200` is green 15/15 on the exact candidate (`success`, exact `head_sha` match, all eight `language-clients` legs independently executing the bare planning guard). Records that no Actions run exists for the M060 implementation candidate `e897cc4` and that `37028684309@4742206` / `37266737795@3ebee30` are descendant evidence only. Reconciles all 24 registered plan headers that had diverged from their registry row (M026, M035–M039, M041–M057, M060) using the established single-line suffix form with each as-written status preserved, and extends `scripts/check_planning_state.py` so registry ↔ plan-header status agreement is enforced (`plan-status-missing` / `-duplicate` / `-unparseable` / `-mismatch`). `plans/registry.md` remains the sole hand-maintained status authority. No production/dependency/package/API/release-workflow change; M058/M059 closure records byte-identical. M061 activates no successor. | | M062 | `062-v0-2-1-patch-release.md` | **closed** | M061, M058, M059 | Published `v0.2.1` from exact candidate `b0bc9b1c3aeac6855ea4b82ea71a78f141197828`: ordinary CI `43516207980` 15/15, pre-tag dispatch `43517314319` 7/7, tag release `43520281822` 7/7; annotated tag object `27e7af53f78abdc08489bb2681e4b31f93af6b25`, eight crates.io packages, five binary/checksum pairs, clean-cache CLI install. Closure evidence: `plans/closure/M062-v0-2-1-patch-release-closure.md`. No successor; language registries remain deferred under M058. | +| M063 | `063-control-plane-exposure-and-authentication-hardening.md` | active | M062 + security audit at `62682d9` | Implementation and `./scripts/check.sh` pass on the local candidate; fresh-daemon audit probes returned 403/403/415, the pinned v2.12 differential passed 50/50, and Python/TypeScript plus cross-language qualification passed using existing Node 20.20.2. Exact-head hosted CI/CodeQL is pending because the candidate is uncommitted and no PR exists. No closure record. | +| M064 | `064-repository-security-governance-and-release-integrity.md` | blocked | M062 + security audit at `62682d9` | Rulesets `27505299` and `27505300` are active; secret scanning, push protection, vulnerability alerts (GET returns 204), Dependabot security updates, and the zero-open-alert readback are confirmed. Non-provider pattern scanning and validity checks remain disabled on the organization’s Free plan, so WP3 and acceptance criterion 3 are unmet. Local CodeQL workflow has no hosted exact-candidate run; see the plan’s execution-status section. No closure record. | +| M065 | `065-residual-runtime-and-qualification-tooling-hardening.md` | active | M062 + security audit at `62682d9` | Implementation and full local gate pass; fetcher/cleanup fixtures pass, strict v2.12 differential is 50/50, pinned post-v2.12 JSON stdout passed with Go 1.23.0, and language-client qualification is green. Upstream relay request filed as [eggstack/eggress#10](https://github.com/eggstack/eggress/issues/10). Exact-head hosted CI is pending. No closure record. | A post-M048 repository audit registered a bounded correctness/maintenance corrective chain: @@ -92,6 +95,10 @@ Determined at M061 closure, as required before any new milestone is registered: M061 activated no automatic successor by design, and nothing in the M060/M061 closure evidence created an unblocked obligation: the M060 hosted-CI gap is reconciled by M061's own exact-head run, and no language-registry publication, release, or runtime obligation was pending at M061 closure. The downstream `ready downstream` rows in the post-release roadmap table (EggReplay, EggProbe) are owned by those projects and are not eggchaos milestones. M062 was subsequently registered to carry out the owner's explicit v0.2.1 release request and is now closed with publication evidence in `plans/closure/M062-v0-2-1-patch-release-closure.md`; any future feature, patch release, dependency migration, language publication, or runtime work requires a new evidence-backed milestone registered here. +A 2026-11-17 read-only security audit at `62682d9` (the dependency-audit branch; no crate source differs from `main` at `60c28a4`) registered three ready correctives and no code changes. The audit found no high/critical code vulnerability and no Rust advisory in any of the four lockfiles, but confirmed two medium gaps: the default loopback admin listener accepted foreign `Host`/`Origin` values and bodyless or `text/plain` mutations, and the repository had no branch/tag rulesets while secret scanning, push protection, Dependabot security updates, and code scanning were disabled. The vulnerability-alert endpoint returned `204`; GitHub documents that as enabled, so the audit’s initial interpretation of that response as disabled was incorrect. It also recorded low-severity findings in non-loopback token strength, the unguarded Toxiproxy compatibility bind, predictable oracle-script temporary paths, missing stream idle timeout, and a theoretical memory-amplification envelope. + +M063 owns the control-plane exposure and authentication correction. M064 owns the repository settings, alerting, CodeQL, and release-tag integrity correction; it requires owner repository-admin authorization and cannot verify owner-only settings from repository files. M065 owns the residual tooling, metrics-escaping, and documented resource-envelope correction. M063 and M065 are active; M064 is blocked by GitHub Free-plan feature availability. The plans remain independent; none depends on another. Each must close on its own exact candidate with the evidence named in its plan. No tag, publication, or release workflow change is part of any of them. + ## Execution state The earlier corrective implementation chain is complete: @@ -189,13 +196,17 @@ The completed UDP/datagram tranche is listed below; the remaining items are post Completed work: M000–M062 are closed (M008 closed as historical work alongside the main chain). M058 is closed as the historical v0.2.0 publication; M059 is closed as the pre-publication hardening corrective; M060 remains the historical documentation/status cleanup closure, with its hosted exact-head evidence gap reconciled additively by M061; M061 is closed as the additive closure-evidence/plan-status consistency corrective on exact candidate `9791375` (hosted run `37366364200`, 15/15); M062 is closed as the current v0.2.1 publication (ordinary CI `43516207980`, pre-tag dispatch `43517314319`, tag release `43520281822`; all green). The eight Rust crates and five binary/checksum pairs are published, and the clean-cache CLI install passed. -Active: none. +Active: +- M063 — control-plane exposure and authentication hardening (`063-control-plane-exposure-and-authentication-hardening.md`); +- M065 — residual runtime and qualification-tooling hardening (`065-residual-runtime-and-qualification-tooling-hardening.md`). Ready: none. -Blocked: none. No plan can be unblocked: every milestone that previously carried a `ready` or `blocked` header is `closed` in both this registry and its own plan header. M062 is an explicitly registered successor for the owner's v0.2.1 release request. +M063–M065 were registered from the 2026-11-17 security audit at `62682d9`. They are independent; no plan depends on another. M063 and M065 are active, while M064 is blocked by unavailable GitHub Free-plan secret-scanning features. + +Blocked: M064 — the current organization plan leaves required non-provider pattern scanning and secret-scanning validity checks disabled after settings update attempts; see the plan’s current execution status. The eleven plans that previously carried a `blocked` header (M037, M038, M039, M043, M044, M045, M050, M051, M052, M053, M054) are closed in both this registry and their own headers. -Release/planning evidence order: `M055 (closed) -> M056 (closed implementation) -> M057 (closed historical hosted qualification authority for the M056 DAG) -> M059 (closed security/dependency/maintenance corrective, exact candidate 1409d0f) -> M058 (closed publication, tag v0.2.0 on b6a277d) -> M060 (historical documentation/status cleanup closure; hosted exact-head gap reconciled by M061) -> M061 (closed additive M060 closure-evidence/plan-status consistency corrective, exact candidate 9791375, hosted run 37366364200 15/15) -> M062 (closed v0.2.1 publication, tag v0.2.1 on b0bc9b1, tag release run 43520281822 7/7)`. `v0.2.1` is the current published release; M062 activates no successor. +Release/planning evidence order: `M055 (closed) -> M056 (closed implementation) -> M057 (closed historical hosted qualification authority for the M056 DAG) -> M059 (closed security/dependency/maintenance corrective, exact candidate 1409d0f) -> M058 (closed publication, tag v0.2.0 on b6a277d) -> M060 (historical documentation/status cleanup closure; hosted exact-head gap reconciled by M061) -> M061 (closed additive M060 closure-evidence/plan-status consistency corrective, exact candidate 9791375, hosted run 37366364200 15/15) -> M062 (closed v0.2.1 publication, tag v0.2.1 on b0bc9b1, tag release run 43520281822 7/7)`. `v0.2.1` is the current published release; M062 activates no successor. Security-audit remediation was registered as M063–M065 from the 2026-11-17 audit at `62682d9`; current execution states are M063 active, M064 blocked, and M065 active, each requiring its own closure evidence. Current performance execution order: `M042 (closed) -> M043 (closed) -> M044 (closed) -> M045 (closed) -> M046 (closed historical provenance) -> M047 (closed artifact-provenance hardening) -> M048 (closed hosted qualification/CI integration)`. M048 adds hosted enforcement for M047 without reopening optimization conclusions. diff --git a/plans/roadmap.md b/plans/roadmap.md index 468cb99..72f60b9 100644 --- a/plans/roadmap.md +++ b/plans/roadmap.md @@ -1,6 +1,6 @@ # Eggchaos Long-Term Roadmap -Status: M000–M062 are closed. M058 closed the historical v0.2.0 publication (tag `v0.2.0` on `b6a277d`, eight crates.io publishes, GitHub Release with five binaries + checksums, fresh-install verification green). M055 owns the historical 0.2.0 development-version baseline, M056 the release-contract implementation, M057 the historical exact-head qualification authority for the M056 DAG, and M059 the pre-publication hardening corrective. M060 remains the historical post-release documentation/status cleanup closure, with its hosted exact-head evidence gap reconciled additively by M061. M061 is closed as the M060 closure-evidence/plan-status consistency corrective on exact candidate `9791375` (hosted run `37366364200`, 15/15). M062 closed the current v0.2.1 publication on exact candidate `b0bc9b1` (ordinary CI `43516207980`, 15/15; pre-tag dispatch `43517314319`, 7/7; tag release `43520281822`, 7/7), with all eight Rust crates and five qualified binaries published. `v0.2.1` is current; there are no active or ready milestones. +Status: M000–M062 are closed. M058 closed the historical v0.2.0 publication (tag `v0.2.0` on `b6a277d`, eight crates.io publishes, GitHub Release with five binaries + checksums, fresh-install verification green). M055 owns the historical 0.2.0 development-version baseline, M056 the release-contract implementation, M057 the historical exact-head qualification authority for the M056 DAG, and M059 the pre-publication hardening corrective. M060 remains the historical post-release documentation/status cleanup closure, with its hosted exact-head evidence gap reconciled additively by M061. M061 is closed as the M060 closure-evidence/plan-status consistency corrective on exact candidate `9791375` (hosted run `37366364200`, 15/15). M062 closed the current v0.2.1 publication on exact candidate `b0bc9b1` (ordinary CI `43516207980`, 15/15; pre-tag dispatch `43517314319`, 7/7; tag release `43520281822`, 7/7), with all eight Rust crates and five qualified binaries published. `v0.2.1` is current. M063 and M065 are active from the 2026-11-17 security audit at `62682d9`; M064 is blocked because the organization’s current GitHub Free plan does not expose required secret-scanning features. M063–M065 have no closure records. ## 1. Mission @@ -859,8 +859,15 @@ publication remain deferred under M058. ## Current planning state +**Active (in flight):** +- `M063` (active; plan `063-control-plane-exposure-and-authentication-hardening.md`) +- `M065` (active; plan `065-residual-runtime-and-qualification-tooling-hardening.md`) + +**Blocked (waiting on a predecessor closure):** +- M064 + **Highest closed milestone:** `M062` (see registry for closure evidence). -**Execution order:** no active or ready milestones. +**Execution order:** `M063`, `M065` diff --git a/scripts/check_repository_security_state.py b/scripts/check_repository_security_state.py new file mode 100644 index 0000000..23f97e4 --- /dev/null +++ b/scripts/check_repository_security_state.py @@ -0,0 +1,341 @@ +#!/usr/bin/env python3 +"""Read-only M064 GitHub settings readback; requires an authenticated `gh` CLI. + +Run manually with repository-admin read access. This script is deliberately +not wired into pull-request CI and never changes GitHub state. +""" + +from __future__ import annotations + +import argparse +import json +import re +import subprocess +import sys +from typing import Any + + +class ApiError(RuntimeError): + """A failed GitHub API read, with credential-free CLI diagnostics.""" + + +def gh_json(endpoint: str) -> Any: + result = subprocess.run( + ["gh", "api", endpoint], + check=False, + capture_output=True, + text=True, + ) + if result.returncode != 0: + detail = (result.stderr or result.stdout).strip() + raise ApiError(f"gh api {endpoint} failed: {detail or 'unknown error'}") + if not result.stdout.strip(): + return None + try: + return json.loads(result.stdout) + except json.JSONDecodeError as error: + raise ApiError(f"gh api {endpoint} returned invalid JSON") from error + + +def vulnerability_alerts_enabled(repo: str) -> bool: + endpoint = f"repos/{repo}/vulnerability-alerts" + try: + gh_json(endpoint) + except ApiError as error: + if re.search(r"HTTP\s+404\b", str(error)): + return False + raise + # GitHub returns 204 with no response body when alerts are enabled. + return True + + +def latest_successful_run( + repo: str, workflow_id: int, branch: str | None = None +) -> dict[str, Any] | None: + query = "status=success&per_page=1" + if branch is not None: + query += f"&branch={branch}" + payload = gh_json( + f"repos/{repo}/actions/workflows/{workflow_id}/runs?{query}" + ) + runs = payload.get("workflow_runs", []) if isinstance(payload, dict) else [] + return runs[0] if runs else None + + +def latest_workflow_run( + repo: str, workflow_id: int, branch: str +) -> dict[str, Any] | None: + payload = gh_json( + f"repos/{repo}/actions/workflows/{workflow_id}/runs?branch={branch}&per_page=1" + ) + runs = payload.get("workflow_runs", []) if isinstance(payload, dict) else [] + return runs[0] if runs else None + + +def workflow_job_names(repo: str, run: dict[str, Any] | None) -> list[str]: + if run is None: + return [] + payload = gh_json(f"repos/{repo}/actions/runs/{run['id']}/jobs?per_page=100") + jobs = payload.get("jobs", []) if isinstance(payload, dict) else [] + return sorted({job["name"] for job in jobs if job.get("name")}) + + +def read_snapshot(repo: str) -> dict[str, Any]: + repository = gh_json(f"repos/{repo}") + if not isinstance(repository, dict): + raise ApiError("repository API response was not an object") + + workflow_payload = gh_json(f"repos/{repo}/actions/workflows?per_page=100") + workflows = ( + workflow_payload.get("workflows", []) + if isinstance(workflow_payload, dict) + else [] + ) + by_path = {workflow.get("path"): workflow for workflow in workflows} + + ci = by_path.get(".github/workflows/ci.yml") + dependency_review = by_path.get(".github/workflows/dependency-review.yml") + codeql = by_path.get(".github/workflows/codeql.yml") + branch = repository.get("default_branch", "main") + + ci_run = ( + latest_successful_run(repo, ci["id"], branch) + if ci and ci.get("state") == "active" + else None + ) + dependency_review_run = ( + latest_successful_run(repo, dependency_review["id"]) + if dependency_review and dependency_review.get("state") == "active" + else None + ) + codeql_run = ( + latest_workflow_run(repo, codeql["id"], branch) + if codeql and codeql.get("state") == "active" + else None + ) + + open_alerts = gh_json( + f"repos/{repo}/dependabot/alerts?state=open&per_page=100" + ) + ruleset_summaries = gh_json(f"repos/{repo}/rulesets?per_page=100") + rulesets = [ + gh_json(f"repos/{repo}/rulesets/{ruleset['id']}") + for ruleset in (ruleset_summaries if isinstance(ruleset_summaries, list) else []) + ] + current_user = gh_json("user") + + return { + "repo": repo, + "default_branch": branch, + "current_user": current_user, + "security_and_analysis": repository.get("security_and_analysis") or {}, + "vulnerability_alerts_enabled": vulnerability_alerts_enabled(repo), + "open_dependabot_alerts": open_alerts if isinstance(open_alerts, list) else [], + "rulesets": rulesets if isinstance(rulesets, list) else [], + "ci": { + "active": bool(ci and ci.get("state") == "active"), + "run": ci_run, + "jobs": workflow_job_names(repo, ci_run), + }, + "dependency_review": { + "active": bool( + dependency_review and dependency_review.get("state") == "active" + ), + "run": dependency_review_run, + "jobs": workflow_job_names(repo, dependency_review_run), + }, + "codeql": { + "active": bool(codeql and codeql.get("state") == "active"), + "run": codeql_run, + "jobs": workflow_job_names(repo, codeql_run), + }, + } + + +def matching_ruleset( + rulesets: list[dict[str, Any]], target: str, ref_pattern: str +) -> dict[str, Any] | None: + for ruleset in rulesets: + refs = ruleset.get("conditions", {}).get("ref_name", {}).get("include", []) + if ( + ruleset.get("target") == target + and ruleset.get("enforcement") == "active" + and ref_pattern in refs + ): + return ruleset + return None + + +def validate_snapshot(snapshot: dict[str, Any]) -> list[str]: + errors: list[str] = [] + security = snapshot.get("security_and_analysis", {}) + expected_settings = { + "secret_scanning": "Secret scanning", + "secret_scanning_push_protection": "Secret scanning push protection", + "secret_scanning_non_provider_patterns": "Secret scanning non-provider patterns", + "secret_scanning_validity_checks": "Secret scanning validity checks", + "dependabot_security_updates": "Dependabot security updates", + } + for key, label in expected_settings.items(): + status = security.get(key, {}).get("status") + if status != "enabled": + errors.append(f"{label} is {status or 'not reported'}, not enabled") + if not snapshot.get("vulnerability_alerts_enabled"): + errors.append("Dependabot vulnerability alerts are disabled") + for alert in snapshot.get("open_dependabot_alerts", []): + advisory = alert.get("security_advisory", {}) + dependency = alert.get("dependency", {}).get("package", {}).get("name", "?") + errors.append( + "Open Dependabot alert " + f"#{alert.get('number', '?')} {advisory.get('ghsa_id', '?')} " + f"for {dependency}; triage against its manifest lockfile" + ) + + user_id = snapshot.get("current_user", {}).get("id") + branch_ruleset = matching_ruleset( + snapshot.get("rulesets", []), "branch", "refs/heads/main" + ) + tag_ruleset = matching_ruleset( + snapshot.get("rulesets", []), "tag", "refs/tags/v*.*.*" + ) + if branch_ruleset is None: + errors.append("No active ruleset applies to refs/heads/main") + else: + rules = branch_ruleset.get("rules", []) + rule_by_type = {rule.get("type"): rule for rule in rules} + required_types = { + "deletion", + "non_fast_forward", + "required_linear_history", + "pull_request", + "required_status_checks", + } + missing_types = sorted(required_types - set(rule_by_type)) + if missing_types: + errors.append(f"main ruleset missing rules: {', '.join(missing_types)}") + pr_parameters = rule_by_type.get("pull_request", {}).get("parameters", {}) + if pr_parameters.get("required_review_thread_resolution") is not True: + errors.append("main ruleset does not require resolved review conversations") + if pr_parameters.get("required_approving_review_count") != 0: + errors.append("main ruleset review count differs from documented solo-maintainer policy") + bypass = branch_ruleset.get("bypass_actors", []) + if not any( + actor.get("actor_type") == "User" + and actor.get("actor_id") == user_id + and actor.get("bypass_mode") == "pull_request" + for actor in bypass + ): + errors.append("main ruleset does not grant the authenticated user PR-only bypass") + status_rule = rule_by_type.get("required_status_checks", {}).get("parameters", {}) + if status_rule.get("strict_required_status_checks_policy") is not True: + errors.append("main ruleset does not require checks to be up to date") + required_contexts = { + check.get("context") + for check in status_rule.get("required_status_checks", []) + } + expected_contexts = set(snapshot.get("ci", {}).get("jobs", [])) + expected_contexts.update(snapshot.get("dependency_review", {}).get("jobs", [])) + expected_contexts.update(snapshot.get("codeql", {}).get("jobs", [])) + missing_contexts = sorted(expected_contexts - required_contexts) + if missing_contexts: + errors.append( + "main ruleset does not require observed check contexts: " + + ", ".join(missing_contexts) + ) + + if tag_ruleset is None: + errors.append("No active ruleset applies to refs/tags/v*.*.*") + else: + rule_types = {rule.get("type") for rule in tag_ruleset.get("rules", [])} + missing = sorted({"creation", "update", "deletion"} - rule_types) + if missing: + errors.append(f"release tag ruleset missing rules: {', '.join(missing)}") + bypass = tag_ruleset.get("bypass_actors", []) + if not any( + actor.get("actor_type") == "User" + and actor.get("actor_id") == user_id + and actor.get("bypass_mode") == "always" + for actor in bypass + ): + errors.append("release tag ruleset lacks the authenticated release-owner bypass") + + for name in ("ci", "dependency_review", "codeql"): + if not snapshot.get(name, {}).get("active"): + errors.append(f"{name} workflow is not active on the repository") + run = snapshot.get(name, {}).get("run") + if not run: + errors.append(f"{name} has no successful hosted run to read back") + elif run.get("conclusion") != "success": + errors.append(f"{name} latest hosted run is not successful") + elif not run.get("head_sha"): + errors.append(f"{name} latest successful run has no head SHA") + + return errors + + +def summary(snapshot: dict[str, Any]) -> dict[str, Any]: + def brief_run(run: dict[str, Any] | None) -> dict[str, Any] | None: + if not run: + return None + return { + "id": run.get("id"), + "event": run.get("event"), + "head_sha": run.get("head_sha"), + "conclusion": run.get("conclusion"), + "html_url": run.get("html_url"), + } + + return { + "repo": snapshot.get("repo"), + "default_branch": snapshot.get("default_branch"), + "rulesets": [ + { + "id": ruleset.get("id"), + "name": ruleset.get("name"), + "target": ruleset.get("target"), + "enforcement": ruleset.get("enforcement"), + } + for ruleset in snapshot.get("rulesets", []) + ], + "security_and_analysis": snapshot.get("security_and_analysis"), + "vulnerability_alerts_enabled": snapshot.get("vulnerability_alerts_enabled"), + "open_dependabot_alerts": [ + { + "number": alert.get("number"), + "ghsa": alert.get("security_advisory", {}).get("ghsa_id"), + "package": alert.get("dependency", {}).get("package", {}).get("name"), + "manifest": alert.get("dependency", {}).get("manifest_path"), + } + for alert in snapshot.get("open_dependabot_alerts", []) + ], + "codeql": { + "active": snapshot.get("codeql", {}).get("active"), + "run": brief_run(snapshot.get("codeql", {}).get("run")), + "jobs": snapshot.get("codeql", {}).get("jobs", []), + }, + } + + +def main(argv: list[str] | None = None) -> int: + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("--repo", default="eggstack/eggchaos", help="OWNER/REPO") + args = parser.parse_args(argv) + if not re.fullmatch(r"[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+", args.repo): + parser.error("--repo must be OWNER/REPO") + try: + snapshot = read_snapshot(args.repo) + except ApiError as error: + print(f"FAIL: {error}", file=sys.stderr) + return 2 + print(json.dumps(summary(snapshot), indent=2, sort_keys=True)) + errors = validate_snapshot(snapshot) + if errors: + for error in errors: + print(f"FAIL: {error}", file=sys.stderr) + return 1 + print('{"repository_security_readback":"pass"}') + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/scripts/fetch_toxiproxy_post_v2_12.sh b/scripts/fetch_toxiproxy_post_v2_12.sh index b554b12..167528e 100755 --- a/scripts/fetch_toxiproxy_post_v2_12.sh +++ b/scripts/fetch_toxiproxy_post_v2_12.sh @@ -64,23 +64,30 @@ if [ "$#" -gt 0 ]; then fi default_dest="${TMPDIR:-/tmp}/eggchaos-toxiproxy-post-v2-12-40f7fd31/toxiproxy-server" if [ -z "$dest" ]; then dest="$default_dest"; fi -script_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd) -archive_dir=$(dirname "$dest") -archive="$archive_dir/toxiproxy-post-v2-12-${commit}.tar.gz" -# The codeload archive unpacks as a single directory named after the -# commit; use that explicit directory rather than relying on a glob. -sources="$archive_dir/toxiproxy-${commit}" # Committed source archive checksum. Pinned via M038; any change is a # reproduction break, not a fixture refresh. expected="26351cc70792f1c3391bdd1d376974a79a756b349ec1abfa8b8f1524c042b13d" +work_dir="$(mktemp -d "${TMPDIR:-/tmp}/eggchaos-toxiproxy-post-v2-12.XXXXXX")" +install_dir="" +cleanup() { + rm -rf "$work_dir" + if [ -n "$install_dir" ]; then rm -rf "$install_dir"; fi +} +trap cleanup EXIT +trap 'exit 129' HUP +trap 'exit 130' INT +trap 'exit 143' TERM +chmod 700 "$work_dir" -mkdir -p "$archive_dir" -if [ ! -f "$archive" ]; then - curl --fail --location --silent --show-error \ - "https://codeload.github.com/Shopify/toxiproxy/tar.gz/$commit" \ - --output "$archive" -fi +archive="$work_dir/toxiproxy-post-v2-12-${commit}.tar.gz" +# The codeload archive unpacks as a single directory named after the +# commit; use that explicit directory rather than relying on a glob. +sources="$work_dir/toxiproxy-${commit}" +staged_binary="$work_dir/toxiproxy-server" +curl --proto '=https' --proto-redir '=https' --fail --location --silent --show-error \ + "https://codeload.github.com/Shopify/toxiproxy/tar.gz/$commit" \ + --output "$archive" if command -v sha256sum >/dev/null 2>&1; then actual="$(sha256sum "$archive" | cut -d ' ' -f 1)" else @@ -90,9 +97,7 @@ if [ "$actual" != "$expected" ]; then echo "toxiproxy post-v2.12 source archive checksum mismatch: got $actual expected $expected" >&2 exit 1 fi -if [ ! -d "$sources" ]; then - tar -xzf "$archive" -C "$archive_dir" -fi +tar -xzf "$archive" -C "$work_dir" build_dir="$sources" if [ ! -d "$build_dir/cmd/server" ]; then echo "post-v2.12 source tree missing cmd/server: $build_dir" >&2 @@ -106,15 +111,26 @@ resolved_toolchain="$(GOTOOLCHAIN="$requested_toolchain" go env GOTOOLCHAIN 2>/d } case "$resolved_go" in "go version $requested_toolchain"*) ;; *) echo "Go toolchain mismatch: requested=$requested_toolchain resolved=$resolved_go" >&2; exit 1;; esac -( cd "$build_dir/cmd/server" && GOTOOLCHAIN="$requested_toolchain" go build -o "$dest" . ) -chmod +x "$dest" +( cd "$build_dir/cmd/server" && GOTOOLCHAIN="$requested_toolchain" go build -o "$staged_binary" . ) +chmod +x "$staged_binary" # Source-built upstream reports `version git`; assert the oracle identity # rather than a real release tag. -version_output="$("$dest" -version 2>&1 || true)" +version_output="$("$staged_binary" -version 2>&1 || true)" if ! printf '%s' "$version_output" | grep -q 'toxiproxy-server version'; then echo "post-v2.12 oracle -version output unexpected: $version_output" >&2 exit 1 fi +if [ -d "$dest" ]; then + echo "post-v2.12 oracle destination is a directory: $dest" >&2 + exit 1 +fi +dest_parent="$(dirname "$dest")" +mkdir -p "$dest_parent" +install_dir="$(mktemp -d "$dest_parent/.eggchaos-toxiproxy-post-v2-12.XXXXXX")" +chmod 700 "$install_dir" +install_binary="$install_dir/toxiproxy-server" +mv -f "$staged_binary" "$install_binary" +mv -f "$install_binary" "$dest" if [ "$mode" = "--json" ]; then # JSON output is the only metadata mode; the executable path must # never appear on stdout in this mode (M041). diff --git a/scripts/fetch_toxiproxy_v2_12.sh b/scripts/fetch_toxiproxy_v2_12.sh index 49d7c78..76fe011 100755 --- a/scripts/fetch_toxiproxy_v2_12.sh +++ b/scripts/fetch_toxiproxy_v2_12.sh @@ -13,24 +13,46 @@ case "$(uname -s):$(uname -m)" in esac expected="$("$script_dir/toxiproxy_v2_12_expected_sha256.sh")" -mkdir -p "$(dirname "$dest")" -curl --fail --location --silent --show-error \ +work_dir="$(mktemp -d "${TMPDIR:-/tmp}/eggchaos-toxiproxy-v2.12.0.XXXXXX")" +install_dir="" +cleanup() { + rm -rf "$work_dir" + if [ -n "$install_dir" ]; then rm -rf "$install_dir"; fi +} +trap cleanup EXIT +trap 'exit 129' HUP +trap 'exit 130' INT +trap 'exit 143' TERM +chmod 700 "$work_dir" + +staged_binary="$work_dir/$asset" +curl --proto '=https' --proto-redir '=https' --fail --location --silent --show-error \ "https://github.com/Shopify/toxiproxy/releases/download/v2.12.0/$asset" \ - --output "$dest" -chmod +x "$dest" + --output "$staged_binary" if command -v sha256sum >/dev/null 2>&1; then - actual="$(sha256sum "$dest" | cut -d ' ' -f 1)" + actual="$(sha256sum "$staged_binary" | cut -d ' ' -f 1)" else - actual="$(shasum -a 256 "$dest" | cut -d ' ' -f 1)" + actual="$(shasum -a 256 "$staged_binary" | cut -d ' ' -f 1)" fi if [ "$actual" != "$expected" ]; then echo "SHA-256 mismatch for $asset: expected $expected, got $actual" >&2 - rm -f "$dest" exit 1 fi -version="$("$dest" -version 2>&1 || true)" +chmod +x "$staged_binary" +version="$("$staged_binary" -version 2>&1 || true)" case "$version" in *'version 2.12.0'*) ;; - *) echo "unexpected oracle version: $version" >&2; rm -f "$dest"; exit 1 ;; + *) echo "unexpected oracle version: $version" >&2; exit 1 ;; esac +if [ -d "$dest" ]; then + echo "oracle destination is a directory: $dest" >&2 + exit 1 +fi +dest_parent="$(dirname "$dest")" +mkdir -p "$dest_parent" +install_dir="$(mktemp -d "$dest_parent/.eggchaos-toxiproxy-v2.12.0.XXXXXX")" +chmod 700 "$install_dir" +install_binary="$install_dir/$asset" +mv -f "$staged_binary" "$install_binary" +mv -f "$install_binary" "$dest" printf '%s\n' "$dest" diff --git a/scripts/qualify_toxiproxy_post_v2_12.sh b/scripts/qualify_toxiproxy_post_v2_12.sh index 938e4c3..9ce07d6 100755 --- a/scripts/qualify_toxiproxy_post_v2_12.sh +++ b/scripts/qualify_toxiproxy_post_v2_12.sh @@ -48,12 +48,19 @@ echo "$oracle_record" # read / update / remove, edge cases, statistical intent checks. The # strict v2.12 regression stays on its existing pinned oracle (M012 + # M013). +log_file="$(mktemp "${TMPDIR:-/tmp}/eggchaos-post-v212.XXXXXX")" +cleanup() { rm -f "$log_file"; } +trap cleanup EXIT +trap 'exit 129' HUP +trap 'exit 130' INT +trap 'exit 143' TERM +chmod 600 "$log_file" TOXIPROXY_POST_V2_12_SERVER="$oracle" \ TOXIPROXY_POST_V2_12_COMMIT="$commit" \ EGGCHAOS_REQUIRE_POST_V2_12_ORACLE=1 \ EGGCHAOS_POST_V2_12_GO_TOOLCHAIN="${EGGCHAOS_POST_V2_12_GO_TOOLCHAIN:-go1.23.0}" \ cargo test -p eggchaos-toxiproxy --all-features --test post_v212_differential -- --nocapture \ - > /tmp/post-v212.log 2>&1 || { tail -40 /tmp/post-v212.log >&2; exit 1; } -grep -q 'DIFFERENTIAL_SUMMARY.*"failed":0' /tmp/post-v212.log \ - || { echo "post-v2.12 differential failed" >&2; tail -20 /tmp/post-v212.log >&2; exit 1; } + > "$log_file" 2>&1 || { tail -40 "$log_file" >&2; exit 1; } +grep -q 'DIFFERENTIAL_SUMMARY.*"failed":0' "$log_file" \ + || { echo "post-v2.12 differential failed" >&2; tail -20 "$log_file" >&2; exit 1; } echo '{"translation":"pass","differential":"pass"}' diff --git a/scripts/tests/test_fetch_toxiproxy_post_v2_12_contract.sh b/scripts/tests/test_fetch_toxiproxy_post_v2_12_contract.sh index 4bf6aa7..2132735 100755 --- a/scripts/tests/test_fetch_toxiproxy_post_v2_12_contract.sh +++ b/scripts/tests/test_fetch_toxiproxy_post_v2_12_contract.sh @@ -49,6 +49,53 @@ fi if ! grep -q 'mode="--path-only"' "$fetcher"; then fail "fetcher must default to --path-only" fi + +# 2. Both fetchers stage privately, enforce HTTPS across redirects, and +# install only after verifying the committed checksum. +v212_fetcher="$script_dir/../fetch_toxiproxy_v2_12.sh" +assert_hardened_fetcher() { + script="$1" + label="$2" + grep -Fq 'work_dir="$(mktemp -d "${TMPDIR:-/tmp}/' "$script" \ + || fail "$label fetcher must use a unique mktemp staging directory" + grep -Fq 'chmod 700 "$work_dir"' "$script" \ + || fail "$label fetcher staging directory must be private" + grep -Fq 'install_dir="$(mktemp -d "$dest_parent/' "$script" \ + || fail "$label fetcher must stage the final install beside its destination" + grep -Fq 'chmod 700 "$install_dir"' "$script" \ + || fail "$label fetcher install staging directory must be private" + grep -Fq "curl --proto '=https' --proto-redir '=https' --fail --location" "$script" \ + || fail "$label fetcher must restrict initial and redirected URLs to HTTPS" + grep -Fq 'trap cleanup EXIT' "$script" \ + || fail "$label fetcher must clean staging on exit" + grep -Fq "trap 'exit 129' HUP" "$script" \ + || fail "$label fetcher must clean staging on HUP" + grep -Fq "trap 'exit 130' INT" "$script" \ + || fail "$label fetcher must clean staging on INT" + grep -Fq "trap 'exit 143' TERM" "$script" \ + || fail "$label fetcher must clean staging on TERM" + checksum_line=$(grep -nF 'if [ "$actual" != "$expected" ]; then' "$script" | cut -d: -f1 | head -n 1) + install_line=$(grep -nF 'mv -f "$install_binary" "$dest"' "$script" | cut -d: -f1 | head -n 1) + [ -n "$checksum_line" ] && [ -n "$install_line" ] \ + || fail "$label fetcher checksum/install steps are missing" + [ "$checksum_line" -lt "$install_line" ] \ + || fail "$label fetcher must verify its checksum before installation" +} +assert_hardened_fetcher "$v212_fetcher" "v2.12" +assert_hardened_fetcher "$fetcher" "post-v2.12" +if grep -Fq '/tmp/post-v212.log' "$qualifier"; then + fail "qualifier must not use the predictable /tmp/post-v212.log path" +fi +grep -Fq 'mktemp "${TMPDIR:-/tmp}/eggchaos-post-v212.XXXXXX"' "$qualifier" \ + || fail "qualifier must use a unique temporary differential log" +grep -Fq 'trap cleanup EXIT' "$qualifier" \ + || fail "qualifier must clean its temporary log on exit" +grep -Fq "trap 'exit 129' HUP" "$qualifier" \ + || fail "qualifier must clean its temporary log on HUP" +grep -Fq "trap 'exit 130' INT" "$qualifier" \ + || fail "qualifier must clean its temporary log on INT" +grep -Fq "trap 'exit 143' TERM" "$qualifier" \ + || fail "qualifier must clean its temporary log on TERM" echo "pattern checks ok" # 2. --help prints usage to stderr and exits 0 (no oracle needed). diff --git a/scripts/tests/test_fetcher_staging.sh b/scripts/tests/test_fetcher_staging.sh new file mode 100644 index 0000000..dc6a0b5 --- /dev/null +++ b/scripts/tests/test_fetcher_staging.sh @@ -0,0 +1,251 @@ +#!/usr/bin/env sh +# M065 behavior checks for private fetch staging, stdout contracts, +# checksum-before-install, HTTPS-only redirects, and cleanup. +set -eu + +fail() { echo "FAIL: $1" >&2; exit 1; } +count_lines() { wc -l < "$1" | tr -d ' '; } + +script_dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd) +repo_root=$(CDPATH= cd -- "$script_dir/../.." && pwd) +v212_fetcher="$repo_root/scripts/fetch_toxiproxy_v2_12.sh" +post_fetcher="$repo_root/scripts/fetch_toxiproxy_post_v2_12.sh" +base_tmp="${TMPDIR:-/tmp}" +[ -d "$base_tmp" ] || mkdir -p "$base_tmp" +test_root=$(mktemp -d "$base_tmp/eggchaos-fetch-staging-test.XXXXXX") +cleanup() { rm -rf "$test_root"; } +trap cleanup EXIT HUP INT TERM +staging="$test_root/tmp" +mock_bin="$test_root/mock-bin" +mkdir -p "$staging" "$mock_bin" + +export FETCH_CURL_ARGS_LOG="$test_root/curl-args.log" +export FETCH_CURL_OUTPUT_LOG="$test_root/curl-output.log" +export FETCH_CURL_MODE_LOG="$test_root/curl-mode.log" +export FETCH_V212_EXPECTED="$("$repo_root/scripts/toxiproxy_v2_12_expected_sha256.sh")" +export FETCH_POST_EXPECTED=26351cc70792f1c3391bdd1d376974a79a756b349ec1abfa8b8f1524c042b13d +: > "$FETCH_CURL_ARGS_LOG" +: > "$FETCH_CURL_OUTPUT_LOG" +: > "$FETCH_CURL_MODE_LOG" + +cat > "$mock_bin/curl" <<'MOCK_CURL' +#!/bin/sh +set -eu +request="$*" +printf '%s\n' "$request" >> "$FETCH_CURL_ARGS_LOG" +output="" +while [ "$#" -gt 0 ]; do + case "$1" in + --output) shift; output="$1" ;; + esac + shift +done +[ -n "$output" ] || exit 2 +printf '%s\n' "$output" >> "$FETCH_CURL_OUTPUT_LOG" +directory=${output%/*} +case "$(uname -s)" in + Darwin) mode=$(stat -f '%Lp' "$directory") ;; + *) mode=$(stat -c '%a' "$directory") ;; +esac +printf '%s\n' "$mode" >> "$FETCH_CURL_MODE_LOG" +if [ "${FETCH_CURL_BLOCK:-0}" = 1 ]; then + : > "$FETCH_CURL_BLOCK_MARKER" + sleep 2 + exit 0 +fi +case "$request" in + *codeload.github.com*) printf 'mock source archive\n' > "$output" ;; + *) + cat > "$output" <<'MOCK_V212_ORACLE' +#!/bin/sh +printf '%s\n' 'Toxiproxy version 2.12.0' +MOCK_V212_ORACLE + ;; +esac +MOCK_CURL + +cat > "$mock_bin/sha256sum" <<'MOCK_SHA256' +#!/bin/sh +set -eu +if [ "${FETCH_HASH_MODE:-valid}" = mismatch ]; then + hash=0000000000000000000000000000000000000000000000000000000000000000 +else + case "$1" in + *.tar.gz) hash="$FETCH_POST_EXPECTED" ;; + *) hash="$FETCH_V212_EXPECTED" ;; + esac +fi +printf '%s %s\n' "$hash" "$1" +MOCK_SHA256 + +cat > "$mock_bin/tar" <<'MOCK_TAR' +#!/bin/sh +set -eu +extract_to="" +while [ "$#" -gt 0 ]; do + case "$1" in + -C) shift; extract_to="$1" ;; + esac + shift +done +[ -n "$extract_to" ] || exit 2 +mkdir -p "$extract_to/toxiproxy-40f7fd31bee529d824116bd2a11a9e3425e904ec/cmd/server" +MOCK_TAR + +cat > "$mock_bin/go" <<'MOCK_GO' +#!/bin/sh +set -eu +case "$1" in + version) printf 'go version %s mock/host\n' "$GOTOOLCHAIN" ;; + env) printf '%s\n' "$GOTOOLCHAIN" ;; + build) + shift + output="" + while [ "$#" -gt 0 ]; do + case "$1" in + -o) shift; output="$1" ;; + esac + shift + done + [ -n "$output" ] || exit 2 + cat > "$output" <<'MOCK_POST_ORACLE' +#!/bin/sh +printf '%s\n' 'toxiproxy-server version git' +MOCK_POST_ORACLE + chmod +x "$output" + ;; + *) echo "unexpected mock go arguments: $*" >&2; exit 2 ;; +esac +MOCK_GO +chmod +x "$mock_bin"/* + +# v2.12 path mode succeeds only after the host checksum and version checks. +v212_dest="$test_root/install-v212/oracle" +if ! TMPDIR="$staging" PATH="$mock_bin:$PATH" FETCH_HASH_MODE=valid \ + "$v212_fetcher" "$v212_dest" > "$test_root/v212.out" 2> "$test_root/v212.err"; then + fail "v2.12 fetch failed: $(cat "$test_root/v212.err")" +fi +[ "$(count_lines "$test_root/v212.out")" = 1 ] || fail "v2.12 fetch must print one path" +[ "$(cat "$test_root/v212.out")" = "$v212_dest" ] || fail "v2.12 stdout path changed" +[ -x "$v212_dest" ] || fail "v2.12 fetch did not install an executable" +[ ! -s "$test_root/v212.err" ] || fail "v2.12 success wrote diagnostics" + +# Post-v2.12 default, --path-only, and --json stdout modes use the mocked +# pinned archive and the exact Go toolchain identity without network access. +post_default="$staging/eggchaos-toxiproxy-post-v2-12-40f7fd31/toxiproxy-server" +if ! TMPDIR="$staging" PATH="$mock_bin:$PATH" FETCH_HASH_MODE=valid \ + "$post_fetcher" > "$test_root/post-default.out" 2> "$test_root/post-default.err"; then + fail "post-v2.12 default fetch failed: $(cat "$test_root/post-default.err")" +fi +[ "$(count_lines "$test_root/post-default.out")" = 1 ] || fail "post default must print one path" +[ "$(cat "$test_root/post-default.out")" = "$post_default" ] || fail "post default stdout path changed" +[ -x "$post_default" ] || fail "post default did not install an executable" +[ ! -s "$test_root/post-default.err" ] || fail "post default wrote diagnostics" + +post_path="$test_root/path-only/oracle" +if ! TMPDIR="$staging" PATH="$mock_bin:$PATH" FETCH_HASH_MODE=valid \ + "$post_fetcher" --path-only "$post_path" > "$test_root/post-path.out" 2> "$test_root/post-path.err"; then + fail "post-v2.12 --path-only failed: $(cat "$test_root/post-path.err")" +fi +[ "$(count_lines "$test_root/post-path.out")" = 1 ] || fail "--path-only must print one path" +[ "$(cat "$test_root/post-path.out")" = "$post_path" ] || fail "--path-only stdout path changed" +[ -x "$post_path" ] || fail "--path-only did not install an executable" +[ ! -s "$test_root/post-path.err" ] || fail "--path-only wrote diagnostics" + +post_json="$test_root/json/oracle" +if ! TMPDIR="$staging" PATH="$mock_bin:$PATH" FETCH_HASH_MODE=valid \ + "$post_fetcher" --json "$post_json" > "$test_root/post-json.out" 2> "$test_root/post-json.err"; then + fail "post-v2.12 --json failed: $(cat "$test_root/post-json.err")" +fi +[ "$(count_lines "$test_root/post-json.out")" = 1 ] || fail "--json must print one record" +[ ! -s "$test_root/post-json.err" ] || fail "--json wrote diagnostics" +python3 -c ' +import json, sys +with open(sys.argv[1], encoding="utf-8") as stream: + obj = json.loads(stream.read()) +assert obj["requested_toolchain"] == "go1.23.0", obj +assert obj["resolved_go_version"].startswith("go version go1.23.0"), obj +assert obj["resolved_gotoolchain"] == "go1.23.0", obj +assert obj["source_commit"] == "40f7fd31bee529d824116bd2a11a9e3425e904ec", obj +assert obj["source_sha256"] == "26351cc70792f1c3391bdd1d376974a79a756b349ec1abfa8b8f1524c042b13d", obj +assert obj["oracle_path"] == sys.argv[2], obj +assert obj["oracle_version"].startswith("toxiproxy-server version"), obj +' "$test_root/post-json.out" "$post_json" +[ -x "$post_json" ] || fail "--json did not install an executable" +echo "fetcher stdout contracts ok (v2.12 path; post default/path-only/JSON)" + +# On checksum failure, neither fetcher may emit a path or create a partial +# destination (including its parent). The test writes only inside test_root. +for profile in v212 post; do + dest="$test_root/mismatch-$profile/oracle" + if [ "$profile" = v212 ]; then script="$v212_fetcher"; else script="$post_fetcher"; fi + set +e + TMPDIR="$staging" PATH="$mock_bin:$PATH" FETCH_HASH_MODE=mismatch \ + "$script" "$dest" > "$test_root/mismatch-$profile.out" 2> "$test_root/mismatch-$profile.err" + status=$? + set -e + [ "$status" -ne 0 ] || fail "$profile checksum mismatch unexpectedly succeeded" + [ ! -s "$test_root/mismatch-$profile.out" ] || fail "$profile checksum failure leaked stdout" + grep -qi 'mismatch' "$test_root/mismatch-$profile.err" \ + || fail "$profile checksum failure diagnostic missing" + [ ! -e "$dest" ] || fail "$profile checksum failure left a partial executable" + [ ! -e "$test_root/mismatch-$profile" ] \ + || fail "$profile checksum failure created its install parent" +done +echo "checksum mismatch is fail-closed with no partial install" + +# A TERM during a download exits with the documented signal status and removes +# private staging without creating the caller's destination parent. +signal_dest="$test_root/signal/oracle" +export FETCH_CURL_BLOCK_MARKER="$test_root/curl-blocked" +TMPDIR="$staging" PATH="$mock_bin:$PATH" FETCH_HASH_MODE=valid FETCH_CURL_BLOCK=1 \ + "$v212_fetcher" "$signal_dest" > "$test_root/signal.out" 2> "$test_root/signal.err" & +signal_pid=$! +attempt=0 +while [ ! -e "$FETCH_CURL_BLOCK_MARKER" ]; do + kill -0 "$signal_pid" 2>/dev/null || fail "fetcher exited before the signal probe started" + attempt=$((attempt + 1)) + [ "$attempt" -lt 100 ] || fail "fetcher did not reach the mocked download" + sleep 0.05 +done +kill -TERM "$signal_pid" +set +e +wait "$signal_pid" +signal_status=$? +set -e +[ "$signal_status" = 143 ] || fail "TERM exit status was $signal_status, expected 143" +[ ! -e "$signal_dest" ] || fail "TERM left a partial executable at the destination" +[ ! -e "${signal_dest%/*}" ] || fail "TERM created the destination parent before verification" +echo "TERM during download exits 143 and cleans private staging" + +# Confirm every download used a unique 0700 staging directory restricted to +# HTTPS, and that success and failure paths removed all of those directories. +while IFS= read -r artifact; do + case "$artifact" in + "$staging"/eggchaos-toxiproxy-v2.12.0.*/*|"$staging"/eggchaos-toxiproxy-post-v2-12.*/*) ;; + *) fail "artifact was not staged in a private temporary directory: $artifact" ;; + esac + [ ! -e "${artifact%/*}" ] || fail "staging directory survived: ${artifact%/*}" +done < "$FETCH_CURL_OUTPUT_LOG" +artifact_count=$(count_lines "$FETCH_CURL_OUTPUT_LOG") +unique_count=$(sort -u "$FETCH_CURL_OUTPUT_LOG" | wc -l | tr -d ' ') +[ "$artifact_count" = "$unique_count" ] || fail "temporary staging paths were reused" +while IFS= read -r mode; do + [ "$mode" = 700 ] || fail "staging directory mode was $mode, expected 700" +done < "$FETCH_CURL_MODE_LOG" +while IFS= read -r args; do + case "$args" in + *"--proto =https"*"--proto-redir =https"*) ;; + *) fail "curl did not restrict redirect protocol to HTTPS: $args" ;; + esac +done < "$FETCH_CURL_ARGS_LOG" +for parent in \ + "$test_root/install-v212" \ + "$staging/eggchaos-toxiproxy-post-v2-12-40f7fd31" \ + "$test_root/path-only" \ + "$test_root/json"; do + for install_dir in "$parent"/.eggchaos-toxiproxy-*.*; do + [ ! -e "$install_dir" ] || fail "install staging directory survived: $install_dir" + done +done +echo "private unique staging, HTTPS-only redirects, and cleanup ok" diff --git a/scripts/tests/test_repository_security_state.py b/scripts/tests/test_repository_security_state.py new file mode 100644 index 0000000..9064fde --- /dev/null +++ b/scripts/tests/test_repository_security_state.py @@ -0,0 +1,185 @@ +#!/usr/bin/env python3 +"""Stdlib fixture tests for the manual M064 repository-settings readback.""" + +from __future__ import annotations + +import sys +import unittest +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).resolve().parents[1])) +import check_repository_security_state as checker + + +CI_JOBS = [ + "check (ubuntu-latest)", + "check (macos-latest)", + "check (windows-latest)", + "performance-provenance", + "api-gate", + "python-native (ubuntu-latest, 3.12)", + "python-native (macos-latest, 3.12)", + "language-clients (macos-latest, 3.11, 20)", +] +DEPENDENCY_REVIEW_JOBS = ["review"] +CODEQL_JOBS = ["CodeQL (rust)", "CodeQL (actions)"] +ALL_CONTEXTS = CI_JOBS + DEPENDENCY_REVIEW_JOBS + CODEQL_JOBS + + +def fixture() -> dict: + return { + "repo": "eggstack/eggchaos", + "default_branch": "main", + "current_user": {"id": 262892073, "login": "dbowm91"}, + "security_and_analysis": { + key: {"status": "enabled"} + for key in ( + "secret_scanning", + "secret_scanning_push_protection", + "secret_scanning_non_provider_patterns", + "secret_scanning_validity_checks", + "dependabot_security_updates", + ) + }, + "vulnerability_alerts_enabled": True, + "open_dependabot_alerts": [], + "rulesets": [ + { + "id": 27505299, + "name": "main-protection", + "target": "branch", + "enforcement": "active", + "conditions": {"ref_name": {"include": ["refs/heads/main"]}}, + "bypass_actors": [ + { + "actor_id": 262892073, + "actor_type": "User", + "bypass_mode": "pull_request", + } + ], + "rules": [ + {"type": "deletion"}, + {"type": "non_fast_forward"}, + {"type": "required_linear_history"}, + { + "type": "pull_request", + "parameters": { + "required_approving_review_count": 0, + "required_review_thread_resolution": True, + }, + }, + { + "type": "required_status_checks", + "parameters": { + "strict_required_status_checks_policy": True, + "required_status_checks": [ + {"context": context, "integration_id": 15368} + for context in ALL_CONTEXTS + ], + }, + }, + ], + }, + { + "id": 27505300, + "name": "release-tag-protection", + "target": "tag", + "enforcement": "active", + "conditions": {"ref_name": {"include": ["refs/tags/v*.*.*"]}}, + "bypass_actors": [ + { + "actor_id": 262892073, + "actor_type": "User", + "bypass_mode": "always", + } + ], + "rules": [ + {"type": "creation"}, + {"type": "update"}, + {"type": "deletion"}, + ], + }, + ], + "ci": { + "active": True, + "run": {"id": 1, "conclusion": "success", "head_sha": "ci-sha"}, + "jobs": CI_JOBS, + }, + "dependency_review": { + "active": True, + "run": { + "id": 2, + "conclusion": "success", + "head_sha": "review-sha", + }, + "jobs": DEPENDENCY_REVIEW_JOBS, + }, + "codeql": { + "active": True, + "run": { + "id": 3, + "head_sha": "candidate-sha", + "conclusion": "success", + }, + "jobs": CODEQL_JOBS, + }, + } + + +class RepositorySecurityReadbackTests(unittest.TestCase): + def test_complete_state_passes(self) -> None: + self.assertEqual(checker.validate_snapshot(fixture()), []) + + def test_failed_latest_codeql_run_is_reported(self) -> None: + state = fixture() + state["codeql"]["run"]["conclusion"] = "failure" + errors = checker.validate_snapshot(state) + self.assertTrue( + any("codeql latest hosted run is not successful" in error for error in errors), + errors, + ) + + def test_disabled_security_setting_is_reported(self) -> None: + state = fixture() + state["security_and_analysis"]["secret_scanning_validity_checks"] = { + "status": "disabled" + } + errors = checker.validate_snapshot(state) + self.assertTrue(any("validity checks" in error for error in errors), errors) + + def test_open_alert_is_not_silently_accepted(self) -> None: + state = fixture() + state["open_dependabot_alerts"] = [ + { + "number": 4, + "security_advisory": {"ghsa_id": "GHSA-test-0000"}, + "dependency": { + "package": {"name": "example"}, + "manifest_path": "Cargo.lock", + }, + } + ] + errors = checker.validate_snapshot(state) + self.assertTrue(any("#4 GHSA-test-0000" in error for error in errors), errors) + + def test_missing_observed_codeql_context_is_reported(self) -> None: + state = fixture() + state["rulesets"][0]["rules"][-1]["parameters"]["required_status_checks"] = [ + check + for check in state["rulesets"][0]["rules"][-1]["parameters"][ + "required_status_checks" + ] + if check["context"] != "CodeQL (rust)" + ] + errors = checker.validate_snapshot(state) + self.assertTrue(any("CodeQL (rust)" in error for error in errors), errors) + + def test_missing_or_unreconciled_ruleset_is_reported(self) -> None: + state = fixture() + state["rulesets"] = state["rulesets"][:1] + errors = checker.validate_snapshot(state) + self.assertTrue(any("release-tag-protection" in error or "refs/tags" in error for error in errors), errors) + + +if __name__ == "__main__": + unittest.main()