Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 52 additions & 0 deletions .github/workflows/codeql.yml
Original file line number Diff line number Diff line change
@@ -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 }}
11 changes: 9 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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`

<!-- END eggchaos:planning-state -->
6 changes: 5 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
38 changes: 38 additions & 0 deletions SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion api/openapi/eggchaos-v1.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
11 changes: 9 additions & 2 deletions architecture/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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`

<!-- END eggchaos:planning-state -->
49 changes: 49 additions & 0 deletions architecture/tooling-distribution.md
Original file line number Diff line number Diff line change
Expand Up @@ -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*.*.*`.
Expand Down
5 changes: 3 additions & 2 deletions crates/eggchaos-cli/src/main.rs
Original file line number Diff line number Diff line change
Expand Up @@ -916,7 +916,7 @@ fn build_kind(
}

async fn serve(path: PathBuf) -> Result<(), Box<dyn std::error::Error>> {
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;
Expand All @@ -943,13 +943,14 @@ async fn serve(path: PathBuf) -> Result<(), Box<dyn std::error::Error>> {
)
.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());
Expand Down
Loading
Loading