Skip to content

Commit 1a8e819

Browse files
committed
chore: merge main into PR 4697 branch
Signed-off-by: Taylor Mutch <[email protected]>
2 parents 91ff960 + 56d2350 commit 1a8e819

474 files changed

Lines changed: 136734 additions & 15774 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.agents/skills/create-security-advisory/SKILL.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,9 @@ metadata:
1010
Prepare every report with the required [advisory template](assets/advisory-template.md);
1111
keep GitHub metadata separate from its description.
1212

13+
Keep the [private reporting form](../../../.github/VULNERABILITY_REPORT.yml) and
14+
the template aligned when changing report requirements.
15+
1316
## Scope and privacy
1417

1518
Follow the repository's current [SECURITY.md](../../../SECURITY.md). This contributor

‎.agents/skills/create-security-advisory/assets/advisory-template.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,8 +28,9 @@ revision. State who verified what and any failed attempts or limitations.}}
2828
## Additional details
2929

3030
{{Optional: include supported details that help review, such as the root cause,
31-
severity rationale and CVSS/CWE, a proposed fix or verified workaround, known
32-
unaffected deployments, or a related private PR. Omit this section if none are available.}}
31+
severity rationale and CVSS/CWE, existing CVE identifiers, disclosure deadlines,
32+
a proposed fix or verified workaround, known unaffected deployments, or a related
33+
private PR. Omit this section if none are available.}}
3334

3435
## Open questions
3536

‎.agents/skills/helm-dev-environment/SKILL.md‎

Lines changed: 40 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -195,6 +195,17 @@ every member one at a time. The PID must survive each case, while an open
195195
replacement confirmed within the recovery timeout, so the runtime terminated
196196
the workload.
197197

198+
For RFC 0017 app-listener validation, enable the listener and supply the app TLS
199+
Secret on the shared Deployment, plus a separate NetworkPolicy allowing the test
200+
client/proxy to reach its app port. Runtime-port access does not grant app access.
201+
Discovery returns the acknowledged owner's Pod IP and app port; no headless app
202+
Service is needed. Exercise HTTP/WebSocket reconnection through graceful downscale
203+
and abrupt loss, preserving workload generation/PID/in-memory state and the public
204+
hostname. Verify stale-owner rejection independently of the replacement's success.
205+
Shared serving leases expire within fifteen seconds of issuance and do not renew
206+
from configuration alone. Do not claim seamless socket migration or infer external
207+
ingress readiness from an advertisement.
208+
198209
### 2. Deploy OpenShell
199210

200211
**Iterative dev** (rebuilds on file changes, recommended during active development):
@@ -255,8 +266,9 @@ task running while using those endpoints.
255266
### Viewing local traces
256267

257268
The gateway exports OTLP/gRPC to
258-
`http://openshell-collector.observability.svc.cluster.local:4317` through the
259-
default Skaffold values. Forward OTLP/gRPC and the trace UI to the host:
269+
`http://openshell-collector.observability.svc.cluster.local:4317` through
270+
`ci/values-local-tracing.yaml`, which only `skaffold.yaml` layers. The Kubernetes
271+
E2E wrapper omits it, so E2E clusters export no traces. Forward OTLP/gRPC and the trace UI to the host:
260272

261273
```bash
262274
mise run helm:k3s:forward
@@ -267,9 +279,10 @@ Kubernetes compute-driver spans under their distinct service names, along with
267279
Agent Sandbox controller reconciliation spans linked through the Sandbox
268280
trace-context annotation. The same command exposes OTLP/gRPC on
269281
`http://127.0.0.1:4317` and, when deployed, the Kubernetes gateway on
270-
`http://127.0.0.1:8090`. The local `gateway:docker`, `gateway:podman`, and
271-
`gateway:vm` tasks detect the collector listener at startup and enable trace
272-
export, OCSF log export, and the agent trace relay only while it is reachable.
282+
`http://127.0.0.1:8090`. The local `gateway`, `gateway:docker`,
283+
`gateway:podman`, and `gateway:vm` tasks enable trace export, OCSF log export,
284+
and the agent trace relay only when `OPENSHELL_DEV_OTLP_ENDPOINT` is set, for
285+
example `OPENSHELL_DEV_OTLP_ENDPOINT=http://127.0.0.1:4317`.
273286
Spans an agent exports from inside a sandbox arrive through the supervisor's
274287
relay with `openshell.telemetry.source=agent` and share `openshell.sandbox.id`
275288
with that sandbox's supervisor spans.
@@ -445,6 +458,16 @@ public `SandboxStatus` image fields. Resume a pending operation with
445458
`SandboxUpdates.UpdateSandbox`, the current resource version, and no selected
446459
fields, following the documented request-ID semantics.
447460

461+
462+
For the opt-in application listener, build/import matching branch images and run
463+
`mise run e2e:kubernetes:app-listener`; see `e2e/kubernetes/app-listener/README.md`
464+
for image, topology, delivery-mode and takeover inputs. The task owns an isolated
465+
Helm release/namespace, temporary TLS material, in-cluster clients, teardown and
466+
evidence under `results/app-listener/`. It checks policy denial, Pod-IP ingress without app Services, shared-owner takeover, gateway-outage expiry and disabled-listener
467+
gateway compatibility, without discovery or a proxy. CI runs four cases under
468+
`test:e2e` and includes them in `Core E2E result`. Its reusable kind setup installs
469+
pinned Calico only for this lane; other jobs retain kindnet. Local k3s already
470+
enforces policy. The lower-level `verify.py` can target a predeployed release.
448471
The kube e2e wrapper creates only one port-forward, to `svc/openshell`; it no
449472
longer forwards the unauthenticated health listener or runs a `/readyz` e2e
450473
target. `/readyz` remains covered by server unit/integration tests.
@@ -621,6 +644,7 @@ for dependencies still declared in `Chart.yaml`.
621644
| `deploy/helm/openshell/skaffold.yaml` | Skaffold config — images, Helm releases, values overlays |
622645
| `deploy/helm/openshell/values.yaml` | Default Helm values |
623646
| `deploy/helm/openshell/ci/values-skaffold.yaml` | Dev overrides (image pull policy, TLS disabled for local Skaffold) |
647+
| `deploy/helm/openshell/ci/values-local-tracing.yaml` | OTLP export to the `helm:k3s:create` collector (Skaffold only) |
624648
| `deploy/helm/openshell/ci/values-cert-manager.yaml` | cert-manager PKI overlay (opt-in; disables pkiInitJob) |
625649
| `deploy/helm/openshell/ci/values-gateway.yaml` | Envoy Gateway GRPCRoute + Gateway overlay |
626650
| `deploy/helm/openshell/ci/values-high-availability.yaml` | HA test overlay (`replicaCount: 2` with external PostgreSQL Secret) |
@@ -645,3 +669,14 @@ identity and contents, command/environment changes, and request replay.
645669
`OPENSHELL_E2E_UPDATE_ORIGINAL_IMAGE` and `OPENSHELL_E2E_UPDATE_TARGET_IMAGE` can
646670
select mirrored Alpine 3.21 and 3.22 manifests. Defaults use the public registry
647671
cache; keep immutable digests when overriding them.
672+
673+
## App listener fixture
674+
675+
The opt-in `deploy/helm/openshell/ci/values-app-listener.yaml` enables the
676+
supervisor listener at port 9443 without discovery or a proxy. Provision the
677+
operator TLS Secret and an ingress-client NetworkPolicy first. Follow
678+
`e2e/kubernetes/app-listener/README.md` for direct in-cluster verification,
679+
shared-member selection, and the HA follow-up checks. Keep the fixture disabled
680+
in default profiles. Dedicated and shared supervisors expose app ports on their
681+
Pod IPs without app Services. Select the member owning the sandbox; automatic
682+
owner selection belongs to the later discovery API.

‎.agents/skills/release-captain/SKILL.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,11 @@ tag, or start a second `Pre-release` run for a tag; it has no concurrency guard.
4141
- `Release` (`release.yml`) is dispatched by hand with the stable version. It
4242
picks the highest `-pre.N` on `main` whose whole `Pre-release` run passed,
4343
creates the stable tag on that commit, and publishes without requalifying.
44+
- Stable releases publish public schemas to `buf.build/openshell/core` with
45+
the release tag as the label; prereleases skip Buf publication. The Buf
46+
repository must exist and Actions must have a `BUF_TOKEN` secret with write
47+
access. A failed Buf push fails the release run; follow Recovery before
48+
rerunning the failed publication job.
4449

4550
## Setup
4651

‎.agents/skills/release-openshell/SKILL.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,3 +83,18 @@ updating a Snap Store support track. Docs retain an
8383
immutable version and advance latest only for a newer version.
8484

8585
Watch the stable release run and report its result.
86+
87+
## PyPI publishing
88+
89+
Stable releases publish the Python wheel to PyPI from `wheel-publish.yml`, which the `publish-pypi` job in `release-publish.yml` calls after the GitHub Release is created. The workflow downloads the wheel from the stable GitHub Release, not a run's build artifact, and checks the stable tag's source commit and the wheel's release checksum. It uses Trusted Publishing with the `pypi` GitHub environment. PyPI matches the workflow file that contains the publishing job, so configure the `openshell` PyPI project's GitHub publisher with owner `NVIDIA`, repository `OpenShell`, workflow `wheel-publish.yml`, and environment `pypi`. No PyPI API token or GitLab trigger credentials are required.
90+
91+
The environment must allow the branch used to dispatch Release or `wheel-publish.yml`. For a support release, explicitly allow its support branch before dispatching. Required reviewers, if configured, must approve the PyPI job. An existing wheel on PyPI is skipped; PyPI does not allow replacing a published wheel.
92+
93+
If a stable release did not reach PyPI, publish the wheel without rerunning Release:
94+
95+
```shell
96+
gh workflow run wheel-publish.yml -R NVIDIA/OpenShell --ref main \
97+
-f release-tag=vX.Y.Z -f source-sha=<tag commit> -f python-version=X.Y.Z
98+
```
99+
100+
Development and prerelease wheels remain GitHub Release assets and do not publish to PyPI.

‎.agents/skills/sync-agent-infra/SKILL.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ Run after adding, removing, or renaming a skill or crate; changing issue or PR c
2828
| TUI behavior | `tui-development` |
2929
| Release artifacts or smoke coverage | `test-release-canary` |
3030
| Release cadence, tagging, or qualification workflows | `release-captain` |
31+
| Release workflows or publishers | `release-openshell`, `release-captain`; keep the Release workflows table and the manual-trigger rule in `CI.md` current |
3132
| CI diagnostics | `watch-github-actions` |
3233
| Native Windows builds, runtime, or release branch guidance | `build-openshell-mxc-windows`; keep Windows implementation links on `windows` even in docs merged to `main` |
3334
| Gator supervision | `launch-openshell-gator` |

‎.agents/skills/watch-github-actions/SKILL.md‎

Lines changed: 23 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -125,29 +125,42 @@ gh run list --json databaseId,status,headBranch,url --jq '.[] | {id: .databaseId
125125

126126
## View Job Logs
127127

128-
For tmachine Kubernetes conformance failures, inspect the `e2e-results-conformance-sandbox-ubuntu-k3s-*` artifact. Its `diagnostics/` holds the K3s report with Agent Sandbox controller state, leader leases, events, and current and previous controller logs. The k3s installers check reconciliation after guest boot with a temporary scheduling-gated Sandbox probe, so a failed probe fails provisioning before any test runs. Distinguish a failed controller probe from a failed conformance scenario; gateway connectivity and controller Deployment availability do not prove reconciliation works.
128+
For Kubernetes app-listener E2E failures during kind setup, inspect the uploaded
129+
`results/app-listener/cni-setup/` evidence. It includes node and Calico pod
130+
descriptions, events, and current/previous container logs. A CNI rollout timeout
131+
occurs before the listener tests run; use these diagnostics to distinguish image
132+
pulls, init failures, and readiness failures.
133+
134+
For tmachine Kubernetes conformance failures, inspect the `e2e-results-conformance-conformance-ubuntu-k3s-*` artifact. Its `diagnostics/` holds the K3s report with Agent Sandbox controller state, leader leases, events, and current and previous controller logs. The k3s installers check reconciliation after guest boot with a temporary scheduling-gated Sandbox probe, so a failed probe fails provisioning before any test runs. Distinguish a failed controller probe from a failed conformance scenario; gateway connectivity and controller Deployment availability do not prove reconciliation works.
129135

130136
For the `e2e-suites` lane (`.github/workflows/e2e-suites.yml`), the last lines of the job log give the runner's result: PASS, FAIL (exit 1) after the end of the nextest log (which names the failed tests), or ERROR (exit 2) with the step that broke. FAIL and ERROR also appear as annotations on the run's summary page. Then inspect the `e2e-results-<family>-<package>-<environment>-<installer>` artifact, which holds `junit.xml`, `nextest.log` and, after a failure, the guest's `diagnostics/`.
131137

132-
`Pre-release` temporarily omits Codex Security from its `Security Scan` job.
133-
`Release` uses the passing prerelease qualification result. Other scanners and
134-
qualification gates still run. Use the standalone
135-
`Codex Security Release Qualification` workflow for manual investigation.
138+
`Pre-release` runs Codex Security as a separate advisory qualification job.
139+
It scans the exact prerelease tag against the previous stable release. Findings
140+
and scanner execution failures do not affect qualification or publication;
141+
failed steps and warnings remain visible. `Release` uses the passing prerelease
142+
qualification result. Codex Security has no schedule or manual trigger.
136143

137-
For `Codex Security`, an exit code of 2 with partial coverage is an incomplete
138-
scan, not a HIGH/CRITICAL threshold failure. Check the execution diagnostics in
139-
the job summary and the `codex-security-diagnostics-<run>-<attempt>` artifact on
144+
For Codex Security `0.8.3`, exit code 2 means an execution or required-output
145+
failure. Deferred investigations no longer cause that exit code. Check the
146+
execution diagnostics in the job summary and the
147+
`codex-security-diagnostics-<run>-<attempt>` artifact on
140148
scan failure. It contains fixed status values, aggregate coverage counts, and
141149
disk space before, after, and the minimum sampled every five seconds. Missing
142150
coverage or manifest documents indicate no readable final report was available;
143-
deferred items or surfaces needing follow-up can explain partial coverage.
151+
deferred items or surfaces needing follow-up describe coverage limitations.
152+
Current reports omit the legacy completeness field, so the diagnostic's
153+
`coverage` value is `unknown`; use `scan_status` and the exit code for execution.
144154
Sampling cannot rule out a disk spike between samples.
145155

146156
Artifacts and logs in this public repository are public. Never upload the raw
147157
scan directory, `report.md`, `coverage.json`, findings, agent state, or scanner
148158
logs. Coverage reasons and notes are free text and may disclose vulnerabilities.
149159
The public diagnostic intentionally omits them; detailed review needs an
150-
approved private destination. Helpers must come from the workflow revision,
160+
approved private destination. Setting the repository variable
161+
`CODEX_SECURITY_DIAGNOSTICS_PUBLIC_KEY` enables bounded scanner logging and
162+
encrypted report retention. Only ciphertext is uploaded; the private key stays
163+
local. See `CI.md` for decryption. Helpers must come from the workflow revision,
151164
not from the candidate under scan.
152165

153166
`setup-nix` retries development-shell preparation once when `prepare-shell`

‎.config/nextest.toml‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -32,11 +32,11 @@ kubernetes-shared-supervisor-pool = { max-threads = 1 }
3232
filter = "test(/gateway_(scale_and_rollout|pod_rolls)$/)"
3333
test-group = "kubernetes-ha"
3434

35-
# Both change the shared supervisor pool of the release they run against: one
36-
# kills a member, the other scales the pool. Never run them at once. Test
37-
# names, not binary(), for the reason above.
35+
# These change the shared supervisor pool of the release they run against:
36+
# they kill members or gateways, or scale the pool. Never run them at once.
37+
# Test names, not binary(), for the reason above.
3838
[[profile.e2e-kubernetes.overrides]]
39-
filter = "test(/^(losing_a_supervisor_pod_moves_its_sandboxes_without_restarting_them|scaling_a_supervisor_pool_up_and_down_keeps_its_sandboxes_running)$/)"
39+
filter = "test(/^(losing_a_supervisor_pod_moves_its_sandboxes_without_restarting_them|scaling_a_supervisor_pool_up_and_down_keeps_its_sandboxes_running|pool_sessions_follow_their_supervisors_gateway)$/)"
4040
test-group = "kubernetes-shared-supervisor-pool"
4141

4242
# Scaling the pool runs two bounded Helm upgrades (up to 6 minutes each), waits
@@ -46,6 +46,11 @@ test-group = "kubernetes-shared-supervisor-pool"
4646
filter = "test(/^scaling_a_supervisor_pool_up_and_down_keeps_its_sandboxes_running$/)"
4747
slow-timeout = { period = "60s", terminate-after = 20 }
4848

49+
# Three bounded rollouts (up to 5 minutes each) and four settle and exec rounds.
50+
[[profile.e2e-kubernetes.overrides]]
51+
filter = "test(/^pool_sessions_follow_their_supervisors_gateway$/)"
52+
slow-timeout = { period = "60s", terminate-after = 20 }
53+
4954
# Relative to the profile store dir (`e2e/rust/target/nextest/e2e-kubernetes/`).
5055
[profile.e2e-kubernetes.junit]
5156
path = "../../../../../results/e2e-kubernetes.xml"

‎.github/CODEOWNERS‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,11 @@
3131
/tasks/scripts/check_maintainer_approval_test.py @NVIDIA/openshell-codeowners @mrunalp @sjenning @derekwaynecarr
3232
/tasks/scripts/alert_maintainer_change_test.py @NVIDIA/openshell-codeowners @mrunalp @sjenning @derekwaynecarr
3333

34+
# Reviewer routing registry and helper
35+
/REVIEWERS.md @NVIDIA/openshell-codeowners @mrunalp @sjenning @derekwaynecarr
36+
/tasks/scripts/check_review_readiness.py @NVIDIA/openshell-codeowners @mrunalp @sjenning @derekwaynecarr
37+
/tasks/scripts/check_review_readiness_test.py @NVIDIA/openshell-codeowners @mrunalp @sjenning @derekwaynecarr
38+
3439
# PR issue acceptance checks
3540
/tasks/scripts/check_issue_acceptance.cjs @NVIDIA/openshell-codeowners @mrunalp @sjenning @derekwaynecarr
3641
/tasks/scripts/check_issue_acceptance.test.cjs @NVIDIA/openshell-codeowners @mrunalp @sjenning @derekwaynecarr

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,5 +15,5 @@ contact_links:
1515
url: https://github.com/NVIDIA/OpenShell/blob/main/SECURITY.md
1616
about: >
1717
Do not report security vulnerabilities through GitHub issues. Follow
18-
the disclosure process in SECURITY.md — report through the NVIDIA PSIRT
19-
web form or email [email protected].
18+
the disclosure process in SECURITY.md — use GitHub's private vulnerability
19+
reporting form.

0 commit comments

Comments
 (0)