From c69dd3f174cc269324e905b6713746b1e77a16c6 Mon Sep 17 00:00:00 2001 From: Jeff Whiteside Date: Tue, 6 Oct 2026 12:04:49 -0700 Subject: [PATCH] [docs] Move-only reorganization Move-only documentation reorganization. Groups backend, API reference, containment configuration, lifecycle, and developer docs without changing product behavior. --- .azure-pipelines/README.md | 2 +- .github/PULL_REQUEST_TEMPLATE.md | 8 ++-- .github/copilot-instructions.md | 24 +++++----- .../workflows/Dependency.Feed.Check.Job.yml | 4 +- CONTRIBUTING.md | 11 +++-- README.md | 44 ++++++++++--------- build-mac.sh | 4 +- docs/{reference => api-reference}/README.md | 2 +- .../dotnet/v1/README.md | 0 .../dotnet/v1/api.md | 0 .../dotnet/v1/types.md | 0 .../node/v1/README.md | 0 .../node/v1/api.md | 0 .../node/v1/types.md | 0 .../rust/v1/README.md | 0 .../rust/v1/api.md | 0 .../rust/v1/types.md | 0 .../bwrap}/bubblewrap-backend.md | 2 +- .../hyperlight/hyperlight-backend.md | 0 .../lxc}/lxc-backend.md | 2 +- .../nanvix}/nanvix.md | 2 +- .../process-container/UIPolicy_Schema.md | 0 .../examples/0.8.0-schema.md | 2 +- .../process-container}/host-prep.md | 0 .../process-container/networking.md | 4 +- .../process-container/os-version-support.md | 10 ++--- .../seatbelt/seatbelt-backend.md | 2 +- .../windows-sandbox-reference.md | 0 .../windows-sandbox/windows-sandbox.md | 2 +- .../wslc}/wsl-container-getting-started.md | 18 ++++---- .../wslc}/wslc-registry-allowlist-policy.md | 4 +- .../wslc}/wslc-state-aware.md | 4 +- ...api-overview.md => container-lifecycle.md} | 24 +++++----- .../0.7.0/policy.md | 14 +++--- .../0.8.0/networking/networking.md | 4 +- .../0.8.0/networking/schema-updates.md | 6 +-- .../0.8.0/policy.md | 0 docs/development/README.md | 39 ++++++++++++++++ .../backends}/isolation-session/oneshot.md | 0 .../isolation-session/state-aware-rust.md | 12 ++--- .../state-aware-typescript.md | 6 +-- .../architecture/container-lifecycle.md} | 10 ++--- .../architecture/repository-architecture.md} | 8 ++-- .../architecture}/telemetry-consent-design.md | 0 .../architecture}/telemetry.md | 0 .../architecture}/versioning.md | 10 ++--- .../ci-validation-infrastructure.md | 2 +- .../build-and-test}/fuzzing.md | 0 .../build-and-test}/pull-requests.md | 0 .../build-and-test}/schema-codegen.md | 0 .../build-and-test}/wslc-sdk-bindings.md | 0 .../guides}/authoring-a-new-feature.md | 8 ++-- docs/{ => development/guides}/diagnostics.md | 10 ++--- .../process-container-adding-os-features.md} | 8 ++-- .../plans/backend-support-probe-api.md} | 2 +- .../plans/bubblewrap-backend.md} | 6 +-- .../plans}/linux-wsl-roadmap-june-2026.md | 8 ++-- .../plans/nanvix-integration.md} | 4 +- docs/examples.md | 10 ++--- ...pabilities.md => logging-access-denied.md} | 2 +- docs/schema.md | 24 +++++----- ...-administrative-policy.md => telemetry.md} | 4 +- .../Microsoft.Mxc.Sdk/V1/MxcTelemetry.cs | 2 +- .../V1/TelemetryPolicyState.cs | 2 +- sdk/dotnet/README.md | 12 ++--- sdk/node/CHANGELOG.md | 2 +- sdk/node/README.md | 8 ++-- sdk/node/src/v1/types.ts | 2 +- src/ffi/mxc_ffi/tests/ffi.rs | 4 +- src/host/plm/readme.md | 2 +- src/mxc-sdk/README.md | 8 ++-- src/mxc-sdk/build/wslc_common/README.md | 2 +- .../bubblewrap/common/bwrap_command.rs | 6 +-- .../bubblewrap/common/bwrap_runner.rs | 2 +- .../bubblewrap/common/network_rules.rs | 2 +- src/mxc-sdk/src/backends/wslc/common/image.rs | 4 +- .../backends/wslc/common/registry_policy.rs | 2 +- .../network_parser_ingress_default_tests.rs | 4 +- .../src/core/mxc_common/telemetry/consent.rs | 4 +- .../src/core/mxc_common/telemetry/policy.rs | 8 ++-- src/mxc-sdk/src/core/plm/elevated.rs | 4 +- src/mxc-sdk/src/policy.rs | 2 +- src/mxc-sdk/src/telemetry.rs | 2 +- src/mxc-sdk/tests/sandbox.rs | 8 ++-- .../tests/streaming_processcontainer.rs | 4 +- src/mxc-sdk/tests/support/wxc_e2e_tests.rs | 2 +- ...s_e2e_processcontainer_characterization.rs | 2 +- src/testing/fuzz/README.md | 2 +- tests/examples/33_mac_local_dev_server.json | 2 +- .../playground}/playground-limitations.md | 2 +- .../lib/WinProcessContainer.Common.ps1 | 6 +-- .../run_lxc_network_no_network_test.sh | 4 +- .../run_processcontainer_all_tests.ps1 | 2 +- ...ocesscontainer_network_capability_test.ps1 | 2 +- ...n_processcontainer_network_egress_test.ps1 | 3 +- ...n_processcontainer_network_model3_test.ps1 | 3 +- ...un_processcontainer_network_proxy_test.ps1 | 3 +- ...n_processcontainer_ui_mitigations_test.ps1 | 2 +- ...processcontainer_ui_policy_matrix_test.ps1 | 2 +- tests/scripts/run_seatbelt_rejections_test.sh | 2 +- 100 files changed, 275 insertions(+), 232 deletions(-) rename docs/{reference => api-reference}/README.md (97%) rename docs/{reference => api-reference}/dotnet/v1/README.md (100%) rename docs/{reference => api-reference}/dotnet/v1/api.md (100%) rename docs/{reference => api-reference}/dotnet/v1/types.md (100%) rename docs/{reference => api-reference}/node/v1/README.md (100%) rename docs/{reference => api-reference}/node/v1/api.md (100%) rename docs/{reference => api-reference}/node/v1/types.md (100%) rename docs/{reference => api-reference}/rust/v1/README.md (100%) rename docs/{reference => api-reference}/rust/v1/api.md (100%) rename docs/{reference => api-reference}/rust/v1/types.md (100%) rename docs/{bwrap-support => backends/bwrap}/bubblewrap-backend.md (99%) rename docs/{ => backends}/hyperlight/hyperlight-backend.md (100%) rename docs/{lxc-support => backends/lxc}/lxc-backend.md (99%) rename docs/{nanvix-microvm => backends/nanvix}/nanvix.md (99%) rename docs/{ => backends}/process-container/UIPolicy_Schema.md (100%) rename docs/{ => backends}/process-container/examples/0.8.0-schema.md (97%) rename docs/{ => backends/process-container}/host-prep.md (100%) rename docs/{ => backends}/process-container/networking.md (98%) rename docs/{ => backends}/process-container/os-version-support.md (96%) rename docs/{ => backends}/seatbelt/seatbelt-backend.md (99%) rename docs/{ => backends}/windows-sandbox/windows-sandbox-reference.md (100%) rename docs/{ => backends}/windows-sandbox/windows-sandbox.md (98%) rename docs/{wsl => backends/wslc}/wsl-container-getting-started.md (96%) rename docs/{wsl => backends/wslc}/wslc-registry-allowlist-policy.md (93%) rename docs/{wsl => backends/wslc}/wslc-state-aware.md (98%) rename docs/{state-aware-lifecycle/mxc-state-aware-sandbox-api-overview.md => container-lifecycle.md} (82%) rename docs/{sandbox-policy => containment-configuration}/0.7.0/policy.md (96%) rename docs/{sandbox-policy => containment-configuration}/0.8.0/networking/networking.md (99%) rename docs/{sandbox-policy => containment-configuration}/0.8.0/networking/schema-updates.md (93%) rename docs/{sandbox-policy => containment-configuration}/0.8.0/policy.md (100%) create mode 100644 docs/development/README.md rename docs/{ => development/architecture/backends}/isolation-session/oneshot.md (100%) rename docs/{ => development/architecture/backends}/isolation-session/state-aware-rust.md (98%) rename docs/{ => development/architecture/backends}/isolation-session/state-aware-typescript.md (96%) rename docs/{state-aware-lifecycle/mxc-state-aware-sandbox-api.md => development/architecture/container-lifecycle.md} (99%) rename docs/{architecture.md => development/architecture/repository-architecture.md} (95%) rename docs/{telemetry => development/architecture}/telemetry-consent-design.md (100%) rename docs/{telemetry => development/architecture}/telemetry.md (100%) rename docs/{ => development/architecture}/versioning.md (98%) rename docs/{ => development/build-and-test}/ci-validation-infrastructure.md (99%) rename docs/{ => development/build-and-test}/fuzzing.md (100%) rename docs/{ => development/build-and-test}/pull-requests.md (100%) rename docs/{ => development/build-and-test}/schema-codegen.md (100%) rename docs/{wsl => development/build-and-test}/wslc-sdk-bindings.md (100%) rename docs/{ => development/guides}/authoring-a-new-feature.md (97%) rename docs/{ => development/guides}/diagnostics.md (97%) rename docs/{process-container/guide.md => development/guides/process-container-adding-os-features.md} (92%) rename docs/{backend-support-probe-api-plan.md => development/plans/backend-support-probe-api.md} (99%) rename docs/{bwrap-support/bubblewrap-backend-plan.md => development/plans/bubblewrap-backend.md} (98%) rename docs/{ => development/plans}/linux-wsl-roadmap-june-2026.md (99%) rename docs/{nanvix-microvm/nanvix-integration-plan.md => development/plans/nanvix-integration.md} (99%) rename docs/{learning-mode/capabilities.md => logging-access-denied.md} (99%) rename docs/{telemetry/telemetry-administrative-policy.md => telemetry.md} (97%) rename {docs => tests/playground}/playground-limitations.md (98%) diff --git a/.azure-pipelines/README.md b/.azure-pipelines/README.md index c1e7b0377..c091b2f11 100644 --- a/.azure-pipelines/README.md +++ b/.azure-pipelines/README.md @@ -56,5 +56,5 @@ setting `dryRun` to `false`. request β€” it mirrors the ADO build stages on native hardware for faster developer iteration. - The ADO pipeline can also be triggered on PRs via `/azp run` - (see [docs/pull-requests.md](../docs/pull-requests.md)) when reviewers want + (see [pull request builds](../docs/development/build-and-test/pull-requests.md)) when reviewers want to run the official build against a change before merge. \ No newline at end of file diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index e26edbb74..bcff9918c 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -13,8 +13,8 @@ - [ ] Signed the [Contributor License Agreement](https://cla.opensource.microsoft.com) - [ ] Linked to an issue - [ ] Updated documentation (if applicable) -- [ ] Updated [Copilot instructions](.github/copilot-instructions.md) (if build, architecture, or conventions changed) -- [ ] If this PR changes `Cargo.lock`, the `dependency-feed-check` check passes (see [docs/pull-requests.md](https://github.com/microsoft/mxc/blob/main/docs/pull-requests.md)) +- [ ] Updated [Copilot instructions](copilot-instructions.md) (if build, architecture, or conventions changed) +- [ ] If this PR changes `Cargo.lock`, the `dependency-feed-check` check passes (see [pull request builds](https://github.com/microsoft/mxc/blob/main/docs/development/build-and-test/pull-requests.md)) ## πŸ“‹ Issue Type @@ -27,8 +27,8 @@ GitHub Actions runs the PR validation build automatically. The ADO pipeline (`MXC-PR-Build`) is the Azure version of the PR pipeline, kept in parity with the GitHub Actions build; it runs on merge to `main`, and Microsoft reviewers with write access can trigger it -on a PR with `/azp run`. See [docs/pull-requests.md](https://github.com/microsoft/mxc/blob/main/docs/pull-requests.md). +on a PR with `/azp run`. See [pull request builds](https://github.com/microsoft/mxc/blob/main/docs/development/build-and-test/pull-requests.md). If the `dependency-feed-check` check fails on a new dependency, the crate must be added to -the feed before the PR can pass. See [docs/pull-requests.md](https://github.com/microsoft/mxc/blob/main/docs/pull-requests.md) +the feed before the PR can pass. See [pull request builds](https://github.com/microsoft/mxc/blob/main/docs/development/build-and-test/pull-requests.md) for the steps. \ No newline at end of file diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 11f9be3f1..dde7e2db2 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -25,9 +25,9 @@ MXC (Microsoft eXecution Container) is a cross-platform sandboxed code execution See: - [`docs/schema.md`](../docs/schema.md) -- [`docs/versioning.md`](../docs/versioning.md) -- [`docs/state-aware-lifecycle/mxc-state-aware-sandbox-api.md`](../docs/state-aware-lifecycle/mxc-state-aware-sandbox-api.md) -- [`docs/ci-validation-infrastructure.md`](../docs/ci-validation-infrastructure.md) +- [`docs/development/architecture/versioning.md`](../docs/development/architecture/versioning.md) +- [`docs/development/architecture/container-lifecycle.md`](../docs/development/architecture/container-lifecycle.md) +- [`docs/development/build-and-test/ci-validation-infrastructure.md`](../docs/development/build-and-test/ci-validation-infrastructure.md) - The relevant backend guide under `docs/` ## Build and validation @@ -71,7 +71,7 @@ npm run test:integration dotnet test --solution Microsoft.Mxc.Sdk.slnx ``` -Prefer the smallest test command covering the change. Host-dependent backend suites live under `tests/scripts/`; use the applicable backend guide and `docs/ci-validation-infrastructure.md` before running or changing them. +Prefer the smallest test command covering the change. Host-dependent backend suites live under `tests/scripts/`; use the applicable backend guide and `docs/development/build-and-test/ci-validation-infrastructure.md` before running or changing them. ## Schema and policy rules @@ -94,7 +94,7 @@ Prefer the smallest test command covering the change. Host-dependent backend sui serialize/deserialize check to `Microsoft.Mxc.Sdk.AotSmokeTest`; its CI AOT publish gate fails on any reflection-dependent path. -See [`docs/schema-codegen.md`](../docs/schema-codegen.md) for regeneration commands. +See [`docs/development/build-and-test/schema-codegen.md`](../docs/development/build-and-test/schema-codegen.md) for regeneration commands. ## Error and security behavior @@ -102,26 +102,26 @@ See [`docs/schema-codegen.md`](../docs/schema-codegen.md) for regeneration comma - Preserve panic containment across `mxc_ffi`; no panic may unwind through the C ABI. - Preserve exact resource ownership and cleanup contracts, especially for processes, jobs, traces, sessions, and native handles. - Do not weaken validation or convert failures into success-shaped fallbacks. -- Telemetry is Windows-only, requires explicit user consent, and fails closed. Administrative policy may restrict consent but may never grant it. See [`docs/telemetry/`](../docs/telemetry/). +- Telemetry is Windows-only, requires explicit user consent, and fails closed. Administrative policy may restrict consent but may never grant it. See [`docs/telemetry.md`](../docs/telemetry.md). ## Documentation Update documentation in the same change when behavior changes: - Schema or config fields: `docs/schema.md` and the applicable generated development artifacts. -- Experimental features: `docs/authoring-a-new-feature.md`. -- Versioning or promotion: `docs/versioning.md`. +- Experimental features: `docs/development/guides/authoring-a-new-feature.md`. +- Versioning or promotion: `docs/development/architecture/versioning.md`. - Backend behavior: the corresponding guide under `docs/`. -- SDK APIs: the affected SDK README and versioned references under `docs/reference/{rust,dotnet,node}/v*/`. -- Telemetry: `docs/telemetry/`. -- CI validation: `docs/ci-validation-infrastructure.md`. +- SDK APIs: the affected SDK README and versioned references under `docs/api-reference/{rust,dotnet,node}/v*/`. +- Telemetry: `docs/telemetry.md`. +- CI validation: `docs/development/build-and-test/ci-validation-infrastructure.md`. Do not duplicate detailed backend behavior here. Keep the canonical explanation in the subsystem documentation. ## SDK API consistency - Publish every SDK operation, type, probe, discovery API, telemetry API, and helper only through a supported versioned (V*) namespace/module/entrypoint. -- Before adding or changing an API or type, compare the corresponding Rust, .NET, and Node references under `docs/reference/`. Align names, field meanings, defaults, optional-field presence, input order, and result/ownership semantics across SDKs. +- Before adding or changing an API or type, compare the corresponding Rust, .NET, and Node references under `docs/api-reference/`. Align names, field meanings, defaults, optional-field presence, input order, and result/ownership semantics across SDKs. - Use language-idiomatic spelling and construction: Rust snake_case and enums, .NET PascalCase and closed SDK-owned classes, and TypeScript camelCase and discriminated unions. Do not force identical syntax or add convenience abstractions merely to imitate another language. - Keep authoring requests as typed data. Use consistent policy and backend configuration names; native adapters own wire mapping and the native engine owns semantic validation. - Keep API-specific controls in the API-specific options type. Creation takes request then options; existing-container execution takes identity, request, then options; .NET cancellation tokens come last. diff --git a/.github/workflows/Dependency.Feed.Check.Job.yml b/.github/workflows/Dependency.Feed.Check.Job.yml index 0ac1612eb..3166d9f73 100644 --- a/.github/workflows/Dependency.Feed.Check.Job.yml +++ b/.github/workflows/Dependency.Feed.Check.Job.yml @@ -1,6 +1,6 @@ # Resolves the locked dependency graph through the public MxcDependencies feed so a crate # not yet in the feed fails at PR time. On a 401, seed the crate by running the -# MXC-Update-Feed-Dependencies pipeline in shine-oss with the PR's number (see docs/pull-requests.md). +# MXC-Update-Feed-Dependencies pipeline in shine-oss with the PR's number (see docs/development/build-and-test/pull-requests.md). name: Dependency Feed Check @@ -46,7 +46,7 @@ jobs: if grep -qiE '401|failed to get successful HTTP response' fetch.log; then echo "::error title=Crate may be missing from the MxcDependencies feed::A locked crate could not be fetched through the feed (HTTP 401 above). If this PR adds a new crates.io dependency, it must be added to the feed before this check can pass." echo "To add it: someone with Contributor access to the shine-oss Mxc project runs the MXC-Update-Feed-Dependencies pipeline using the Run pipeline button, with prNumber set to the PR's number." - echo "Details: docs/pull-requests.md (Dependency feed check)." + echo "Details: docs/development/build-and-test/pull-requests.md (Dependency feed check)." else echo "::error title=cargo fetch failed::cargo fetch failed for a reason other than a feed 401 (see the log above)." fi diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5423e019c..9948f562a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -107,16 +107,21 @@ Human-facing Markdown documentation includes one visible audience marker immedia Do not add these markers to legal text, GitHub templates or workflow prompts, or agent instruction files. +Place developer-only documentation under the appropriate `docs/development/` +subdirectory. Keep consumer and mixed-audience documentation in the main +`docs/` tree, and keep implementation-specific READMEs beside the code or tests +they describe. + ### Experimental features New, in-development features use their permanent JSON locations in the mutable development contract. They may still require the binary's `--experimental` runtime authorization until graduation; that gate is independent of JSON placement. If you're adding a new feature, follow the step-by-step checklist in -[`docs/authoring-a-new-feature.md`](./docs/authoring-a-new-feature.md), which +[`docs/development/guides/authoring-a-new-feature.md`](./docs/development/guides/authoring-a-new-feature.md), which walks through the schema, Rust, and test-config changes required. The schema versioning model and promotion path from experimental to stable are described -in [`docs/versioning.md`](./docs/versioning.md). +in [`docs/development/architecture/versioning.md`](./docs/development/architecture/versioning.md). ### Help Wanted @@ -269,7 +274,7 @@ PowerShell and shell helper scripts that drive the executor end-to-end live unde When the change is ready, mark the Draft PR as **Ready for Review**. The PR template asks you to confirm CLA acceptance and to update [`.github/copilot-instructions.md`](./.github/copilot-instructions.md) if your change affects build commands, project architecture, or key conventions. -PR builds don't run automatically β€” Microsoft ADO policy requires a Microsoft employee to comment `/azp run` to start the `MXC-PR-Build` pipeline. See [`docs/pull-requests.md`](./docs/pull-requests.md) for details. +PR builds don't run automatically β€” Microsoft ADO policy requires a Microsoft employee to comment `/azp run` to start the `MXC-PR-Build` pipeline. See [pull request builds](./docs/development/build-and-test/pull-requests.md) for details. Reviewers will look for: diff --git a/README.md b/README.md index 4180468bc..1b3b69921 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,7 @@ backends** (`windows_sandbox`, `microvm`, and `hyperlight`) require `{ experimental: true }` in `SandboxSpawnOptions` or the `--experimental` CLI flag. -For which filesystem, network, and UI-restriction policy aspects the Windows `processcontainer` backend can enforce on each Windows 11 release (23H2 / 24H2 / 25H2 / 25H2+), see [Windows OS-version policy support](./docs/process-container/os-version-support.md). +For which filesystem, network, and UI-restriction policy aspects the Windows `processcontainer` backend can enforce on each Windows 11 release (23H2 / 24H2 / 25H2 / 25H2+), see [Windows OS-version policy support](./docs/backends/process-container/os-version-support.md). ### Requirements @@ -59,7 +59,7 @@ tests/ Test collateral (configs, examples, scripts) scripts/ Build and utility scripts ``` -See [Repository architecture](docs/architecture.md) for the Rust workspace +See [Repository architecture](docs/development/architecture/repository-architecture.md) for the Rust workspace layout, crate responsibilities, dependency direction, and execution surfaces. ### Full Build @@ -237,7 +237,7 @@ See the [SDK README](sdk/node/README.md) for full API documentation. Released, immutable stable schemas live in [`schemas/stable/`](schemas/stable); the in-progress dev schema (experimental backends, state-aware lifecycle) lives in [`schemas/dev/`](schemas/dev). The current stable and dev versions are tracked canonically in [`schemas/schema-version.json`](schemas/schema-version.json). -Pick the latest stable schema for new code on any supported platform. See [docs/versioning.md](docs/versioning.md) for the full versioning design. +Pick the latest stable schema for new code on any supported platform. See [versioning design](docs/development/architecture/versioning.md) for the full versioning design. ## Debugging @@ -249,7 +249,7 @@ By default, native binaries run in **silent mode** β€” stdin/stdout/stderr is co wxc-exec.exe --debug config.json ``` -See [docs/diagnostics.md](docs/diagnostics.md) for full diagnostics reference. +See [diagnostics](docs/development/guides/diagnostics.md) for the full developer reference. ### Request-aware ProcessContainer probe @@ -270,7 +270,7 @@ wxc-exec.exe --audit policy.json Successful non-dry-run audits require capture metadata, actionable denials JSON, its verbose diagnostic sibling, and a retained ETL. The CLI relocates the backend-selected paths to `denials.json`, `denials.verbose.json`, and `trace.etl` in the per-user audit directory, then generates a source-config snapshot and `Adjusted_*.json` from the actionable JSON without decoding the ETL again. Base64-only input keeps both JSON files and the ETL but has no source config to snapshot or adjust. Truncated analysis keeps both JSON files, the ETL, and the source snapshot but skips adjusted-config generation. Use `--audit-verbose` to print learned-policy details. -> **Warning:** `--audit` injects `permissiveLearningMode` β€” AppContainer restrictions are **not** enforced for the duration of the run. Use only for policy authoring. It cannot be combined with `processContainer.captureDenials`; use `captureDenials.mode: "allow"` for permissive application-driven capture. `learningModeLogging` and `permissiveLearningMode` are reserved internal capability names and are rejected in `processContainer.capabilities`. See [docs/learning-mode/capabilities.md](docs/learning-mode/capabilities.md) for the three learning-mode flows. +> **Warning:** `--audit` injects `permissiveLearningMode` β€” AppContainer restrictions are **not** enforced for the duration of the run. Use only for policy authoring. It cannot be combined with `processContainer.captureDenials`; use `captureDenials.mode: "allow"` for permissive application-driven capture. `learningModeLogging` and `permissiveLearningMode` are reserved internal capability names and are rejected in `processContainer.capabilities`. See [logging access denied](docs/logging-access-denied.md) for the three learning-mode flows. ## Telemetry @@ -322,27 +322,29 @@ Privacy information can be found at https://privacy.microsoft.com and in the Mic ## Documentation +Repository contributors can browse the [development documentation](docs/development/README.md). + | Document | Description | |----------|-------------| -| [docs/architecture.md](docs/architecture.md) | Repository layout, crate boundaries, and execution surfaces | +| [Repository architecture](docs/development/architecture/repository-architecture.md) | Repository layout, crate boundaries, and execution surfaces | | [docs/schema.md](docs/schema.md) | Full JSON configuration schema reference | -| [docs/versioning.md](docs/versioning.md) | Schema versioning and experimental feature lifecycle | +| [Versioning design](docs/development/architecture/versioning.md) | Schema versioning and experimental feature lifecycle | | [docs/examples.md](docs/examples.md) | Annotated configuration examples | -| [docs/ci-validation-infrastructure.md](docs/ci-validation-infrastructure.md) | Scheduled backend validation matrix and CI dispatch | +| [CI validation infrastructure](docs/development/build-and-test/ci-validation-infrastructure.md) | Scheduled backend validation matrix and CI dispatch | | [tests/scripts/README.md](tests/scripts/README.md) | Local and CI backend test suites | -| [docs/host-prep.md](docs/host-prep.md) | Windows host preparation (`wxc-host-prep.exe`) | -| [docs/diagnostics.md](docs/diagnostics.md) | Diagnostic logging and ETW | -| [docs/sandbox-policy/0.7.0/policy.md](docs/sandbox-policy/0.7.0/policy.md) | Sandbox policy 0.7.0 specification | -| [docs/process-container/guide.md](docs/process-container/guide.md) | Windows AppContainer / BaseContainer guide | -| [docs/lxc-support/lxc-backend.md](docs/lxc-support/lxc-backend.md) | LXC backend (Linux) | -| [docs/bwrap-support/bubblewrap-backend.md](docs/bwrap-support/bubblewrap-backend.md) | Bubblewrap backend (Linux) | -| [docs/seatbelt/seatbelt-backend.md](docs/seatbelt/seatbelt-backend.md) | Seatbelt backend (macOS) | -| [docs/windows-sandbox/windows-sandbox.md](docs/windows-sandbox/windows-sandbox.md) | Windows Sandbox backend | -| [docs/hyperlight/hyperlight-backend.md](docs/hyperlight/hyperlight-backend.md) | Hyperlight backend (Linux, Windows) | -| [docs/state-aware-lifecycle/mxc-state-aware-sandbox-api.md](docs/state-aware-lifecycle/mxc-state-aware-sandbox-api.md) | State-aware sandbox lifecycle API | -| [docs/telemetry/telemetry.md](docs/telemetry/telemetry.md) | TraceLogging telemetry architecture | -| [docs/telemetry/telemetry-consent-design.md](docs/telemetry/telemetry-consent-design.md) | Telemetry consent contract | -| [docs/telemetry/telemetry-administrative-policy.md](docs/telemetry/telemetry-administrative-policy.md) | Administrative telemetry controls | +| [Host preparation](docs/backends/process-container/host-prep.md) | Windows host preparation (`wxc-host-prep.exe`) | +| [Diagnostics](docs/development/guides/diagnostics.md) | Diagnostic logging and ETW | +| [Containment configuration 0.7.0](docs/containment-configuration/0.7.0/policy.md) | Containment configuration 0.7.0 specification | +| [Adding ProcessContainer OS features](docs/development/guides/process-container-adding-os-features.md) | Windows AppContainer / BaseContainer developer guide | +| [docs/backends/lxc/lxc-backend.md](docs/backends/lxc/lxc-backend.md) | LXC backend (Linux) | +| [docs/backends/bwrap/bubblewrap-backend.md](docs/backends/bwrap/bubblewrap-backend.md) | Bubblewrap backend (Linux) | +| [docs/backends/seatbelt/seatbelt-backend.md](docs/backends/seatbelt/seatbelt-backend.md) | Seatbelt backend (macOS) | +| [docs/backends/windows-sandbox/windows-sandbox.md](docs/backends/windows-sandbox/windows-sandbox.md) | Windows Sandbox backend | +| [docs/backends/hyperlight/hyperlight-backend.md](docs/backends/hyperlight/hyperlight-backend.md) | Hyperlight backend (Linux, Windows) | +| [Container lifecycle](docs/container-lifecycle.md) | Public container lifecycle API | +| [Telemetry architecture](docs/development/architecture/telemetry.md) | TraceLogging telemetry architecture | +| [Telemetry consent design](docs/development/architecture/telemetry-consent-design.md) | Telemetry consent contract | +| [docs/telemetry.md](docs/telemetry.md) | Administrative telemetry controls | ## Contributing diff --git a/build-mac.sh b/build-mac.sh index 88ddec784..16b4ab4f2 100755 --- a/build-mac.sh +++ b/build-mac.sh @@ -4,7 +4,7 @@ # TypeScript SDK. This is the macOS counterpart of build.sh. # # Codesigning + notarization are NOT performed here β€” those run later as a -# release-time step (see docs/seatbelt/seatbelt-backend.md). This script just +# release-time step (see docs/backends/seatbelt/seatbelt-backend.md). This script just # produces an unsigned binary suitable for local development. set -euo pipefail @@ -173,4 +173,4 @@ for triple in "${TARGETS[@]}"; do done echo "" echo "Note: this binary is unsigned. Codesigning + notarization happen at" -echo "release time (see docs/seatbelt/seatbelt-backend.md, codesign-notarize todo)." +echo "release time (see docs/backends/seatbelt/seatbelt-backend.md, codesign-notarize todo)." diff --git a/docs/reference/README.md b/docs/api-reference/README.md similarity index 97% rename from docs/reference/README.md rename to docs/api-reference/README.md index 34dea5fe7..8a8e0bed5 100644 --- a/docs/reference/README.md +++ b/docs/api-reference/README.md @@ -61,5 +61,5 @@ nullability, ownership, platform gates, and examples. Breaking changes to a published SDK API require a new versioned (V*) API surface and matching signature/type references under each affected SDK's -`docs/reference//v*/` directory. Preserve the published version's +`docs/api-reference//v*/` directory. Preserve the published version's references. diff --git a/docs/reference/dotnet/v1/README.md b/docs/api-reference/dotnet/v1/README.md similarity index 100% rename from docs/reference/dotnet/v1/README.md rename to docs/api-reference/dotnet/v1/README.md diff --git a/docs/reference/dotnet/v1/api.md b/docs/api-reference/dotnet/v1/api.md similarity index 100% rename from docs/reference/dotnet/v1/api.md rename to docs/api-reference/dotnet/v1/api.md diff --git a/docs/reference/dotnet/v1/types.md b/docs/api-reference/dotnet/v1/types.md similarity index 100% rename from docs/reference/dotnet/v1/types.md rename to docs/api-reference/dotnet/v1/types.md diff --git a/docs/reference/node/v1/README.md b/docs/api-reference/node/v1/README.md similarity index 100% rename from docs/reference/node/v1/README.md rename to docs/api-reference/node/v1/README.md diff --git a/docs/reference/node/v1/api.md b/docs/api-reference/node/v1/api.md similarity index 100% rename from docs/reference/node/v1/api.md rename to docs/api-reference/node/v1/api.md diff --git a/docs/reference/node/v1/types.md b/docs/api-reference/node/v1/types.md similarity index 100% rename from docs/reference/node/v1/types.md rename to docs/api-reference/node/v1/types.md diff --git a/docs/reference/rust/v1/README.md b/docs/api-reference/rust/v1/README.md similarity index 100% rename from docs/reference/rust/v1/README.md rename to docs/api-reference/rust/v1/README.md diff --git a/docs/reference/rust/v1/api.md b/docs/api-reference/rust/v1/api.md similarity index 100% rename from docs/reference/rust/v1/api.md rename to docs/api-reference/rust/v1/api.md diff --git a/docs/reference/rust/v1/types.md b/docs/api-reference/rust/v1/types.md similarity index 100% rename from docs/reference/rust/v1/types.md rename to docs/api-reference/rust/v1/types.md diff --git a/docs/bwrap-support/bubblewrap-backend.md b/docs/backends/bwrap/bubblewrap-backend.md similarity index 99% rename from docs/bwrap-support/bubblewrap-backend.md rename to docs/backends/bwrap/bubblewrap-backend.md index 374305b23..8a6c373ad 100644 --- a/docs/bwrap-support/bubblewrap-backend.md +++ b/docs/backends/bwrap/bubblewrap-backend.md @@ -14,7 +14,7 @@ requiring root privileges or a container runtime. > Versions before `0.9.0-alpha` are rejected; changing only the version of an > old config does not migrate its policy. Legacy `defaultPolicy`, > `enforcementMode`, host lists, `allowLocalNetwork`, and `network.proxy` -> are not accepted. See [schema migration](../schema.md). +> are not accepted. See [schema migration](../../schema.md). ## Prerequisites diff --git a/docs/hyperlight/hyperlight-backend.md b/docs/backends/hyperlight/hyperlight-backend.md similarity index 100% rename from docs/hyperlight/hyperlight-backend.md rename to docs/backends/hyperlight/hyperlight-backend.md diff --git a/docs/lxc-support/lxc-backend.md b/docs/backends/lxc/lxc-backend.md similarity index 99% rename from docs/lxc-support/lxc-backend.md rename to docs/backends/lxc/lxc-backend.md index fff330c41..f7d6cd7f6 100644 --- a/docs/lxc-support/lxc-backend.md +++ b/docs/backends/lxc/lxc-backend.md @@ -9,7 +9,7 @@ and `network.ingress`. LXC rejects `runtimeConfig.networkProxy`, so a v0.9 LXC request has no proxy surface at all β€” see [Proxy](#proxy) below. Legacy host lists and enforcement-mode fields in older examples are not accepted. Do not relabel an old request as v0.9 without migrating its policy. -See [the schema migration reference](../schema.md). +See [the schema migration reference](../../schema.md). ## Overview diff --git a/docs/nanvix-microvm/nanvix.md b/docs/backends/nanvix/nanvix.md similarity index 99% rename from docs/nanvix-microvm/nanvix.md rename to docs/backends/nanvix/nanvix.md index 88e0b4def..956ab738c 100644 --- a/docs/nanvix-microvm/nanvix.md +++ b/docs/backends/nanvix/nanvix.md @@ -192,7 +192,7 @@ JSON vocabulary. The exact cutover does not silently translate directional rules into this weaker contract. Legacy `defaultPolicy` and host-list interactions follow the -[backend-agnostic network policy semantics](../schema.md#legacy-network-host-list-semantics). +[backend-agnostic network policy semantics](../../schema.md#legacy-network-host-list-semantics). Invalid legacy combinations are rejected by shared policy validation: `blockedHosts` requires an `allowedHosts` exception set under a block default, and `allowedHosts` cannot be used under an allow default. diff --git a/docs/process-container/UIPolicy_Schema.md b/docs/backends/process-container/UIPolicy_Schema.md similarity index 100% rename from docs/process-container/UIPolicy_Schema.md rename to docs/backends/process-container/UIPolicy_Schema.md diff --git a/docs/process-container/examples/0.8.0-schema.md b/docs/backends/process-container/examples/0.8.0-schema.md similarity index 97% rename from docs/process-container/examples/0.8.0-schema.md rename to docs/backends/process-container/examples/0.8.0-schema.md index 0321161e1..5fd66df0f 100644 --- a/docs/process-container/examples/0.8.0-schema.md +++ b/docs/backends/process-container/examples/0.8.0-schema.md @@ -5,7 +5,7 @@ > Historical design reference: schema 0.8 is retired. For supported requests, > use [current ProcessContainer networking guidance](../networking.md). -See the shared [0.7-to-0.8 network schema comparison](../../sandbox-policy/0.8.0/networking/schema-updates.md) +See the shared [0.7-to-0.8 network schema comparison](../../../containment-configuration/0.8.0/networking/schema-updates.md) for egress, ingress, and proxy endpoint changes. This page covers the ProcessContainer-specific proxy peer. diff --git a/docs/host-prep.md b/docs/backends/process-container/host-prep.md similarity index 100% rename from docs/host-prep.md rename to docs/backends/process-container/host-prep.md diff --git a/docs/process-container/networking.md b/docs/backends/process-container/networking.md similarity index 98% rename from docs/process-container/networking.md rename to docs/backends/process-container/networking.md index 5fa77cbbb..2bbc2a153 100644 --- a/docs/process-container/networking.md +++ b/docs/backends/process-container/networking.md @@ -7,7 +7,7 @@ and `network.ingress` policy plus `runtimeConfig.networkProxy` and `processContainer.network.allowedProxyPeer` configuration. Implementation companion to the parent -[MXC Network Configuration, GA design](../sandbox-policy/0.8.0/networking/networking.md) +[MXC Network Configuration, GA design](../../containment-configuration/0.8.0/networking/networking.md) doc. The parent owns the shared policy schema, connectivity models, and GA goal. This doc covers only how the Windows ProcessContainer backend enforces them. @@ -128,7 +128,7 @@ complete implementation of the shared bidirectional `hostLoopback: "allow"` cont #### Identity-scoped proxy -Use the [supported proxy-policy example](../schema.md#directional-networking-supported-contracts), +Use the [supported proxy-policy example](../../schema.md#directional-networking-supported-contracts), which shows `runtimeConfig.networkProxy`, `processContainer.network.allowedProxyPeer`, and their relationship in one place. Use the installed Package Family Name for a packaged proxy, regardless of whether it has AppContainer isolation. Use diff --git a/docs/process-container/os-version-support.md b/docs/backends/process-container/os-version-support.md similarity index 96% rename from docs/process-container/os-version-support.md rename to docs/backends/process-container/os-version-support.md index da95948d1..b2a06dde2 100644 --- a/docs/process-container/os-version-support.md +++ b/docs/backends/process-container/os-version-support.md @@ -9,7 +9,7 @@ document are Windows 11**, and the minimum considered here is Windows 11 23H2. For the enforcement mechanisms themselves see the [UI policy schema](./UIPolicy_Schema.md) and the -[sandbox policy spec](../sandbox-policy/0.7.0/policy.md). +[containment configuration spec](../../containment-configuration/0.7.0/policy.md). ## Windows 11 releases @@ -20,8 +20,8 @@ For the enforcement mechanisms themselves see the | 25H2 | 26200 | | 25H2+ | 26600+ | -> **Product floor:** the [README](../../README.md#platforms) and -> [SDK README](../../sdk/node/README.md) state that `processcontainer`'s **minimum +> **Product floor:** the [README](../../../README.md#platforms) and +> [SDK README](../../../sdk/node/README.md) state that `processcontainer`'s **minimum > supported build is 26100 (24H2)**. The Rust code build-gates individual > capabilities down to 23H2 (build 22631); the **23H2** column below therefore > describes *what the code can enforce if run there* β€” it is below the @@ -198,5 +198,5 @@ and later (`MIN_BUILD_FOR_INJECTION_LIMIT`) and is therefore unavailable on `MIN_BUILD_FOR_INJECTION_LIMIT`, `supported_ui_limit_mask_for_build`): `src/mxc-sdk/src/backends/process_container/common/job_object.rs` - FlatBuffer contract: `external/windows-sdk/ProcessSecurityEnvironment.fbs` -- Product support floor: [README](../../README.md#platforms), - [SDK README](../../sdk/node/README.md) +- Product support floor: [README](../../../README.md#platforms), + [SDK README](../../../sdk/node/README.md) diff --git a/docs/seatbelt/seatbelt-backend.md b/docs/backends/seatbelt/seatbelt-backend.md similarity index 99% rename from docs/seatbelt/seatbelt-backend.md rename to docs/backends/seatbelt/seatbelt-backend.md index c115be864..b09cc3318 100644 --- a/docs/seatbelt/seatbelt-backend.md +++ b/docs/backends/seatbelt/seatbelt-backend.md @@ -183,7 +183,7 @@ Anything it hasn't declared is rejected up front. ### Fields (supported schema 0.9+) This is the cross-backend directional shape accepted by the registered exact -contracts. The original [0.8 networking design](../sandbox-policy/0.8.0/networking/networking.md) +contracts. The original [0.8 networking design](../../containment-configuration/0.8.0/networking/networking.md) is historical; schema 0.8 is no longer accepted. > **Omitting `network` entirely denies all IP networking.** Every field below diff --git a/docs/windows-sandbox/windows-sandbox-reference.md b/docs/backends/windows-sandbox/windows-sandbox-reference.md similarity index 100% rename from docs/windows-sandbox/windows-sandbox-reference.md rename to docs/backends/windows-sandbox/windows-sandbox-reference.md diff --git a/docs/windows-sandbox/windows-sandbox.md b/docs/backends/windows-sandbox/windows-sandbox.md similarity index 98% rename from docs/windows-sandbox/windows-sandbox.md rename to docs/backends/windows-sandbox/windows-sandbox.md index d1bfac152..9c9504961 100644 --- a/docs/windows-sandbox/windows-sandbox.md +++ b/docs/backends/windows-sandbox/windows-sandbox.md @@ -216,4 +216,4 @@ Both suites require a Windows host with the Windows Sandbox optional feature. ## Further Reading - [Windows Sandbox backend reference](windows-sandbox-reference.md) -- [State-aware lifecycle API](../state-aware-lifecycle/mxc-state-aware-sandbox-api.md) +- [Container lifecycle architecture](../../development/architecture/container-lifecycle.md) diff --git a/docs/wsl/wsl-container-getting-started.md b/docs/backends/wslc/wsl-container-getting-started.md similarity index 96% rename from docs/wsl/wsl-container-getting-started.md rename to docs/backends/wslc/wsl-container-getting-started.md index 964c657e1..bcf4442e1 100644 --- a/docs/wsl/wsl-container-getting-started.md +++ b/docs/backends/wslc/wsl-container-getting-started.md @@ -606,18 +606,18 @@ images β€” cannot be used. ## Example Configs -- [`tests/examples/wslc_hello_world.json`](../../tests/examples/wslc_hello_world.json) β€” Hello world with Alpine -- [`tests/configs/wslc_network_isolated.json`](../../tests/configs/wslc_network_isolated.json) β€” Network isolation -- [`tests/configs/wslc_network_proxy.json`](../../tests/configs/wslc_network_proxy.json) β€” In-container cooperative HTTP proxy (`runtimeConfig.networkProxy` at the container's `127.0.0.1`) -- [`tests/configs/wslc_custom_registry_ghcr.json`](../../tests/configs/wslc_custom_registry_ghcr.json) β€” Pull from GitHub Container Registry -- [`tests/configs/wslc_custom_registry_quay.json`](../../tests/configs/wslc_custom_registry_quay.json) β€” Pull from Quay.io -- [`tests/configs/wslc_tar_import_rootfs.json`](../../tests/configs/wslc_tar_import_rootfs.json) β€” Import rootfs tar -- [`tests/configs/wslc_tar_import_docker_save.json`](../../tests/configs/wslc_tar_import_docker_save.json) β€” Import Docker save archive -- [`tests/configs/wslc_timeout.json`](../../tests/configs/wslc_timeout.json) β€” Execution timeout enforcement +- [`tests/examples/wslc_hello_world.json`](../../../tests/examples/wslc_hello_world.json) β€” Hello world with Alpine +- [`tests/configs/wslc_network_isolated.json`](../../../tests/configs/wslc_network_isolated.json) β€” Network isolation +- [`tests/configs/wslc_network_proxy.json`](../../../tests/configs/wslc_network_proxy.json) β€” In-container cooperative HTTP proxy (`runtimeConfig.networkProxy` at the container's `127.0.0.1`) +- [`tests/configs/wslc_custom_registry_ghcr.json`](../../../tests/configs/wslc_custom_registry_ghcr.json) β€” Pull from GitHub Container Registry +- [`tests/configs/wslc_custom_registry_quay.json`](../../../tests/configs/wslc_custom_registry_quay.json) β€” Pull from Quay.io +- [`tests/configs/wslc_tar_import_rootfs.json`](../../../tests/configs/wslc_tar_import_rootfs.json) β€” Import rootfs tar +- [`tests/configs/wslc_tar_import_docker_save.json`](../../../tests/configs/wslc_tar_import_docker_save.json) β€” Import Docker save archive +- [`tests/configs/wslc_timeout.json`](../../../tests/configs/wslc_timeout.json) β€” Execution timeout enforcement ## Maintaining the SDK bindings The WSLC SDK FFI bindings (`wslcsdk_sys.rs`) are **generated by bindgen** from the SDK header and committed to the repo. For how they work and the exact procedure to follow on every SDK version bump, see -[`wslc-sdk-bindings.md`](./wslc-sdk-bindings.md). +[WSLC SDK bindings runbook](../../development/build-and-test/wslc-sdk-bindings.md). diff --git a/docs/wsl/wslc-registry-allowlist-policy.md b/docs/backends/wslc/wslc-registry-allowlist-policy.md similarity index 93% rename from docs/wsl/wslc-registry-allowlist-policy.md rename to docs/backends/wslc/wslc-registry-allowlist-policy.md index ddb8bbc1b..59a3ceb63 100644 --- a/docs/wsl/wslc-registry-allowlist-policy.md +++ b/docs/backends/wslc/wslc-registry-allowlist-policy.md @@ -22,7 +22,7 @@ explicitly to allow short names. The key sits under `SOFTWARE\Policies`, which only administrators can write, so a standard user cannot widen the list. It is the same key the telemetry policy uses; see -[`telemetry-administrative-policy.md`](../telemetry/telemetry-administrative-policy.md). +[`telemetry.md`](../../telemetry.md). ### Values @@ -91,4 +91,4 @@ the SDK is asked to pull at all. ## See also - [`wsl-container-getting-started.md`](wsl-container-getting-started.md) β€” running WSLC workloads -- [`telemetry-administrative-policy.md`](../telemetry/telemetry-administrative-policy.md) β€” the other policy under the same key +- [`telemetry.md`](../../telemetry.md) β€” the other policy under the same key diff --git a/docs/wsl/wslc-state-aware.md b/docs/backends/wslc/wslc-state-aware.md similarity index 98% rename from docs/wsl/wslc-state-aware.md rename to docs/backends/wslc/wslc-state-aware.md index 5be0197b8..0fa83af65 100644 --- a/docs/wsl/wslc-state-aware.md +++ b/docs/backends/wslc/wslc-state-aware.md @@ -9,8 +9,8 @@ cost. It complements: -- [`wslc-sdk-bindings.md`](wslc-sdk-bindings.md) β€” regenerating the SDK bindings. -- [`../state-aware-lifecycle/mxc-state-aware-sandbox-api.md`](../state-aware-lifecycle/mxc-state-aware-sandbox-api.md) β€” the cross-backend state-aware wire format, the Rust `StatefulSandboxBackend` trait, and the dispatcher contract. +- [WSLC SDK bindings runbook](../../development/build-and-test/wslc-sdk-bindings.md) β€” regenerating the SDK bindings. +- [Container lifecycle architecture](../../development/architecture/container-lifecycle.md) β€” the cross-backend state-aware wire format, the Rust `StatefulSandboxBackend` trait, and the dispatcher contract. The raw WSLc state-aware surface is available in published exact schemas beginning with `0.9.0-alpha`. The Rust, .NET, and Node high-level v1 lifecycle diff --git a/docs/state-aware-lifecycle/mxc-state-aware-sandbox-api-overview.md b/docs/container-lifecycle.md similarity index 82% rename from docs/state-aware-lifecycle/mxc-state-aware-sandbox-api-overview.md rename to docs/container-lifecycle.md index 33e048c4d..c8d7a321a 100644 --- a/docs/state-aware-lifecycle/mxc-state-aware-sandbox-api-overview.md +++ b/docs/container-lifecycle.md @@ -1,8 +1,8 @@ -# MXC State-Aware Sandbox API - Overview +# MXC Container Lifecycle > **Audience:** MXC consumers -Companion to [mxc-state-aware-sandbox-api.md](./mxc-state-aware-sandbox-api.md). +Companion to the [full lifecycle and wire contract](development/architecture/container-lifecycle.md). MXC separates container creation from persistent lifecycle operations. Creation runs a `ContainerRequest`; persistent execution provisions a @@ -44,9 +44,9 @@ Creation defaults to generic `Process` intent. Explicit PTY APIs return SDK-owned terminal process handles with interactive input, resize, wait, termination, and disposal. Use these for interactive workloads instead of attaching a workload to the host application's console. -See the launch-choice tables for [Rust](../reference/rust/v1/api.md#choosing-a-launch-operation), -[.NET](../reference/dotnet/v1/api.md#choosing-a-launch-operation), and -[Node](../reference/node/v1/api.md#choosing-a-launch-operation). +See the launch-choice tables for [Rust](api-reference/rust/v1/api.md#choosing-a-launch-operation), +[.NET](api-reference/dotnet/v1/api.md#choosing-a-launch-operation), and +[Node](api-reference/node/v1/api.md#choosing-a-launch-operation). Explicit validation APIs perform native dry-run validation and return no execution result. Backend policy and feature support remain native-engine @@ -73,16 +73,16 @@ warnings rather than converting failures into successful-looking output. ## Contributor and native integration details -The [full design](./mxc-state-aware-sandbox-api.md) documents engine dispatch, +The [full design](development/architecture/container-lifecycle.md) documents engine dispatch, backend interfaces, and native JSON contracts for contributors and direct executor/FFI integrations. These implementation details are not required to author typed SDK requests. ## References -- [Full lifecycle and wire contract](./mxc-state-aware-sandbox-api.md) -- [Rust SDK](../../src/core/mxc-sdk/README.md) -- [.NET SDK](../../sdk/dotnet/README.md) -- [Node SDK](../../sdk/node/README.md) -- [IsolationSession TypeScript guide](../isolation-session/state-aware-typescript.md) -- [WSLC lifecycle guide](../wsl/wslc-state-aware.md) +- [Full lifecycle and wire contract](development/architecture/container-lifecycle.md) +- [Rust SDK](../src/mxc-sdk/README.md) +- [.NET SDK](../sdk/dotnet/README.md) +- [Node SDK](../sdk/node/README.md) +- [IsolationSession TypeScript architecture](development/architecture/backends/isolation-session/state-aware-typescript.md) +- [WSLC lifecycle guide](backends/wslc/wslc-state-aware.md) diff --git a/docs/sandbox-policy/0.7.0/policy.md b/docs/containment-configuration/0.7.0/policy.md similarity index 96% rename from docs/sandbox-policy/0.7.0/policy.md rename to docs/containment-configuration/0.7.0/policy.md index dc7d8c36d..ff5d33e64 100644 --- a/docs/sandbox-policy/0.7.0/policy.md +++ b/docs/containment-configuration/0.7.0/policy.md @@ -80,7 +80,7 @@ the intent is the same. Fields that only apply to one backend live in ContainerC ### Principle 4: Version Is a Contract -> See [versioning.md](../../versioning.md) for the full versioning design. +> See [versioning design](../../development/architecture/versioning.md) for the full versioning design. The Policy version and ContainerConfig schema version are locked in step. A version number guarantees behavior. @@ -386,7 +386,7 @@ Only `"process"` is end-to-end implemented today. ## 8. Versioning -> See [versioning.md](../../versioning.md) for full details. +> See [versioning design](../../development/architecture/versioning.md) for full details. - Policy version = ContainerConfig schema version. Always bumped together. - SDK version is independent. SDK v5.0 can use policy/schema v2.1. @@ -396,10 +396,10 @@ Only `"process"` is end-to-end implemented today. ## 9. Development Guide -> See [authoring-a-new-feature.md](../../authoring-a-new-feature.md) for the full workflow and +> See [authoring a new feature](../../development/guides/authoring-a-new-feature.md) for the full workflow and > decision tree. > -> See [process-container/guide.md](../../process-container/guide.md) for OS-level implementation +> See [adding ProcessContainer OS features](../../development/guides/process-container-adding-os-features.md) for OS-level implementation > details. --- @@ -535,10 +535,10 @@ the ContainerConfig schema and translate it to OS-level Job Object UI restriction flags. > See -> [authoring-a-new-feature.md](../../authoring-a-new-feature.md) +> [Authoring a new feature](../../development/guides/authoring-a-new-feature.md) > for the full workflow. > See -> [process-container/guide.md](../../process-container/guide.md) for +> [Adding ProcessContainer OS features](../../development/guides/process-container-adding-os-features.md) for > the executor and OS implementation guide. --- @@ -548,7 +548,7 @@ Object UI restriction flags. ### "Where does my new feature go: Policy or ContainerConfig?" Use the decision tree in -[authoring-a-new-feature.md](../../authoring-a-new-feature.md). In short: if it is a +[Authoring a new feature](../../development/guides/authoring-a-new-feature.md). In short: if it is a cross-platform security intent that works on two or more platforms, it belongs in Policy. Backend-specific mechanisms belong in ContainerConfig. diff --git a/docs/sandbox-policy/0.8.0/networking/networking.md b/docs/containment-configuration/0.8.0/networking/networking.md similarity index 99% rename from docs/sandbox-policy/0.8.0/networking/networking.md rename to docs/containment-configuration/0.8.0/networking/networking.md index 8011989c0..f1d75d1d7 100644 --- a/docs/sandbox-policy/0.8.0/networking/networking.md +++ b/docs/containment-configuration/0.8.0/networking/networking.md @@ -317,7 +317,7 @@ sockets come with their own security questions and should be outlined in a separ **Elevation caveat:** Installing these filters (WFP on Windows, iptables on the Linux backends) generally requires elevation. Elevating on every sandbox launch is out of the question, so MXC applies them through a privileged broker/service rather than from the unelevated launch path. A per-platform, per-technology elevation story must be defined in a separate MXC elevation design doc and is a prerequisite for this enforcement. -> **Bubblewrap does not need this.** The caveat above holds only for filters installed on the *host*. Bubblewrap gives the sandbox its own network namespace and programs iptables inside it from a supervisor holding `CAP_NET_ADMIN` in an unprivileged user namespace β€” namespace-scoped capabilities are not host privilege, so the rules install with no elevation and no broker. The sandbox still cannot alter them, because it drops `CAP_NET_ADMIN` before the workload runs. Shipped at schema 0.8; see `docs/bwrap-support/bubblewrap-backend.md`. The elevation design remains a prerequisite for the host-filter backends only. +> **Bubblewrap does not need this.** The caveat above holds only for filters installed on the *host*. Bubblewrap gives the sandbox its own network namespace and programs iptables inside it from a supervisor holding `CAP_NET_ADMIN` in an unprivileged user namespace β€” namespace-scoped capabilities are not host privilege, so the rules install with no elevation and no broker. The sandbox still cannot alter them, because it drops `CAP_NET_ADMIN` before the workload runs. Shipped at schema 0.8; see `docs/backends/bwrap/bubblewrap-backend.md`. The elevation design remains a prerequisite for the host-filter backends only. ### D3: IP literals and CIDRs only (no DNS names) @@ -449,7 +449,7 @@ they cannot preserve either posture. | DNS | DNS queries follow same IP/CIDR allow/block rules as other traffic. No domain-based filtering. | If DNS resolver IP is blocked, DNS fails. If allowed, sandbox can resolve any domain. **For HTTP(S) via the proxy, DNS resolution happens in the proxy.** | | Bypass resistance | High. Kernel-enforced WFP filters. Bypass requires kernel compromise or AppContainer escape (elevation). | | -**Implementation doc:** [Process Container Networking Configuration, GA](../../../process-container/networking.md) +**Implementation doc:** [Process Container Networking Configuration, GA](../../../backends/process-container/networking.md) ### WSLc: GA enforcement diff --git a/docs/sandbox-policy/0.8.0/networking/schema-updates.md b/docs/containment-configuration/0.8.0/networking/schema-updates.md similarity index 93% rename from docs/sandbox-policy/0.8.0/networking/schema-updates.md rename to docs/containment-configuration/0.8.0/networking/schema-updates.md index 097fdcdd6..6eed3f815 100644 --- a/docs/sandbox-policy/0.8.0/networking/schema-updates.md +++ b/docs/containment-configuration/0.8.0/networking/schema-updates.md @@ -137,7 +137,7 @@ Backend-specific migration can require an additional acknowledgment without chan `ingress.default: "deny"` is rejected: no rule can carry the promised host-to-container grant. The reverse pair, `ingress.hostLoopback: "deny"` under `ingress.default: "allow"`, is accepted and enforces the container-to-host half only; the blanket inbound grant over-permits the host-to-container half, which is documented in the - [Seatbelt backend guide](../../../seatbelt/seatbelt-backend.md). + [Seatbelt backend guide](../../../backends/seatbelt/seatbelt-backend.md). - Isolation Session cannot enforce any network restriction. Its directional acknowledgment is reserved for the backend migration work; until that lands, callers must continue using the legacy unrestricted acknowledgment @@ -147,5 +147,5 @@ Backend-specific migration can require an additional acknowledgment without chan | Backend | Configuration | |---|---| -| ProcessContainer | [Schema 0.8 proxy configuration](../../../process-container/examples/0.8.0-schema.md) | -| Seatbelt (macOS) | [Schema 0.8 configuration](../../../seatbelt/seatbelt-backend.md#schema-08-network-shape-egress--ingress--runtimeconfignetworkproxy) +| ProcessContainer | [Schema 0.8 proxy configuration](../../../backends/process-container/examples/0.8.0-schema.md) | +| Seatbelt (macOS) | [Schema 0.8 configuration](../../../backends/seatbelt/seatbelt-backend.md#schema-08-network-shape-egress--ingress--runtimeconfignetworkproxy) diff --git a/docs/sandbox-policy/0.8.0/policy.md b/docs/containment-configuration/0.8.0/policy.md similarity index 100% rename from docs/sandbox-policy/0.8.0/policy.md rename to docs/containment-configuration/0.8.0/policy.md diff --git a/docs/development/README.md b/docs/development/README.md new file mode 100644 index 000000000..44cf90a23 --- /dev/null +++ b/docs/development/README.md @@ -0,0 +1,39 @@ +# MXC development documentation + +> **Audience:** MXC developers + +This section covers MXC architecture, implementation, validation, and planned +work. Consumer documentation remains under `docs/`; start with the +[project README](../../README.md). + +## Architecture + +- [Repository architecture](architecture/repository-architecture.md) +- [Container lifecycle architecture](architecture/container-lifecycle.md) +- [Versioning design](architecture/versioning.md) +- [Telemetry architecture](architecture/telemetry.md) +- [Telemetry consent design](architecture/telemetry-consent-design.md) +- [IsolationSession one-shot architecture](architecture/backends/isolation-session/oneshot.md) +- [IsolationSession state-aware Rust architecture](architecture/backends/isolation-session/state-aware-rust.md) +- [IsolationSession state-aware TypeScript architecture](architecture/backends/isolation-session/state-aware-typescript.md) + +## Build and test + +- [CI validation infrastructure](build-and-test/ci-validation-infrastructure.md) +- [Pull request builds](build-and-test/pull-requests.md) +- [Schema code generation](build-and-test/schema-codegen.md) +- [Fuzzing](build-and-test/fuzzing.md) +- [WSLC SDK bindings runbook](build-and-test/wslc-sdk-bindings.md) + +## Contributor guides + +- [Authoring a new feature](guides/authoring-a-new-feature.md) +- [Diagnostics](guides/diagnostics.md) +- [Adding ProcessContainer OS features](guides/process-container-adding-os-features.md) + +## Plans + +- [Backend support probe API](plans/backend-support-probe-api.md) +- [Bubblewrap backend feasibility](plans/bubblewrap-backend.md) +- [Linux and WSL roadmap](plans/linux-wsl-roadmap-june-2026.md) +- [Nanvix integration](plans/nanvix-integration.md) diff --git a/docs/isolation-session/oneshot.md b/docs/development/architecture/backends/isolation-session/oneshot.md similarity index 100% rename from docs/isolation-session/oneshot.md rename to docs/development/architecture/backends/isolation-session/oneshot.md diff --git a/docs/isolation-session/state-aware-rust.md b/docs/development/architecture/backends/isolation-session/state-aware-rust.md similarity index 98% rename from docs/isolation-session/state-aware-rust.md rename to docs/development/architecture/backends/isolation-session/state-aware-rust.md index 0b4c384b5..f7ac7d06c 100644 --- a/docs/isolation-session/state-aware-rust.md +++ b/docs/development/architecture/backends/isolation-session/state-aware-rust.md @@ -3,7 +3,7 @@ > **Audience:** MXC developers This document describes the IsolationSession backend's behaviour under the -state-aware lifecycle API ([design](../state-aware-lifecycle/mxc-state-aware-sandbox-api.md)). +state-aware lifecycle API ([design](../../container-lifecycle.md)). It is the per-backend specification required by Β§11.6 of that design and covers the five state-aware phases β€” provision, start, exec, stop, deprovision β€” plus the cross-cutting policy matrix, idempotence behaviour, @@ -45,7 +45,7 @@ For interactive execution, use lets the caller own input, output, resizing, and termination without binding the workload to the host application's global console streams. All Rust SDK launch operations take typed requests; see the -[launch-choice table](../reference/rust/v1/api.md#choosing-a-launch-operation). +[launch-choice table](../../../../api-reference/rust/v1/api.md#choosing-a-launch-operation). Backend runtime requirements: @@ -281,7 +281,7 @@ the optional `appId`, at provision. The matrix covers the full surface a caller can express, on both the one-shot and state-aware paths. Dispositions come from the closed set in Β§10.3 of the -[state-aware design](../state-aware-lifecycle/mxc-state-aware-sandbox-api.md), +[state-aware design](../../container-lifecycle.md), plus `required` for the network posture and `n/a` where a field has no meaning for this backend. @@ -469,7 +469,7 @@ the finer step is described in `message`. These values are **best-effort diagnostics, not a versioned contract**: they mirror the projected WinRT class and method names, which this repo does not own. Branch on `code`; treat `operation` as telemetry and log detail. See the -[cross-backend contract](../state-aware-lifecycle/mxc-state-aware-sandbox-api.md) Β§7.3. +[cross-backend contract](../../container-lifecycle.md) Β§7.3. `nativeCode` is the HRESULT rendered as lowercase hex, e.g. `0x80070490`. @@ -588,8 +588,8 @@ OS limitation. ## References -- [State-aware design (full)](../state-aware-lifecycle/mxc-state-aware-sandbox-api.md) -- [State-aware design (overview)](../state-aware-lifecycle/mxc-state-aware-sandbox-api-overview.md) +- [State-aware design (full)](../../container-lifecycle.md) +- [Container lifecycle overview](../../../../container-lifecycle.md) - [TypeScript spec](state-aware-typescript.md) β€” SDK companion to this doc; covers SDK API surface, types, and TS usage examples. - [One-shot bringup](oneshot.md) β€” the diff --git a/docs/isolation-session/state-aware-typescript.md b/docs/development/architecture/backends/isolation-session/state-aware-typescript.md similarity index 96% rename from docs/isolation-session/state-aware-typescript.md rename to docs/development/architecture/backends/isolation-session/state-aware-typescript.md index 93c3b2ed4..0253ab79f 100644 --- a/docs/isolation-session/state-aware-typescript.md +++ b/docs/development/architecture/backends/isolation-session/state-aware-typescript.md @@ -23,7 +23,7 @@ concurrency); this doc covers SDK API surface, types, and consumer usage pattern for the policy matrix, idempotence, concurrency, and error mapping. - The wire-format envelope β€” see the - [main design doc](../state-aware-lifecycle/mxc-state-aware-sandbox-api.md) Β§7. + [main design doc](../../container-lifecycle.md) Β§7. - Cross-backend lifecycle and error handling β€” see the SDK documentation and [Rust backend guide](state-aware-rust.md). @@ -162,7 +162,7 @@ describe('IsolationSession state-aware lifecycle E2E', { skip: skipReason }, () ## References -- [State-aware design (main)](../state-aware-lifecycle/mxc-state-aware-sandbox-api.md) -- [State-aware design (overview)](../state-aware-lifecycle/mxc-state-aware-sandbox-api-overview.md) +- [State-aware design (main)](../../container-lifecycle.md) +- [Container lifecycle overview](../../../../container-lifecycle.md) - [Rust spec](state-aware-rust.md) β€” runtime semantics - [One-shot bringup](oneshot.md) diff --git a/docs/state-aware-lifecycle/mxc-state-aware-sandbox-api.md b/docs/development/architecture/container-lifecycle.md similarity index 99% rename from docs/state-aware-lifecycle/mxc-state-aware-sandbox-api.md rename to docs/development/architecture/container-lifecycle.md index 338850c51..25f2b742d 100644 --- a/docs/state-aware-lifecycle/mxc-state-aware-sandbox-api.md +++ b/docs/development/architecture/container-lifecycle.md @@ -1,6 +1,6 @@ # MXC State-Aware Sandbox API -> **Audience:** MXC consumers and developers +> **Audience:** MXC developers *Detailed design proposal. Compiled 2026-04-28.* @@ -362,7 +362,7 @@ native engine. Persistent execution uses an already-provisioned identity and compose into supported request filesystem fields. Native enforcement remains backend-specific. -See the [Node SDK reference](../../sdk/node/README.md) for the supported +See the [Node SDK reference](../../../sdk/node/README.md) for the supported consumer API and the backend guides for policy requirements. ## 7. Wire contract @@ -1576,7 +1576,7 @@ cross-cutting field, a column per phase, with values from the closed set `applied` / `rejected` / `ignored`. Specific values per backend are documented in each backend's plan doc (Β§11.6). The IsolationSession row set below mirrors the shipped backend; the authoritative statement lives in -[`isolation-session/state-aware-rust.md`](../isolation-session/state-aware-rust.md): +[IsolationSession state-aware Rust architecture](backends/isolation-session/state-aware-rust.md): | Field | provision | start | exec | stop | deprovision | |---|---|---|---|---|---| @@ -1601,7 +1601,7 @@ unconditionally by the in-guest agent). > **Known gap (`deniedPaths`).** WindowsSandbox honors `deniedPaths` only as a > best-effort provision-time rejection (a `.wsb` mapped share cannot express a Deny > ACE), not as a hardened security boundary. See the "Known gap (`deniedPaths`)" -> caveat in [`docs/windows-sandbox/windows-sandbox.md`](../windows-sandbox/windows-sandbox.md). +> caveat in [`docs/backends/windows-sandbox/windows-sandbox.md`](../../backends/windows-sandbox/windows-sandbox.md). | Field | provision | start | exec | stop | deprovision | |---|---|---|---|---|---| @@ -1875,7 +1875,7 @@ calls, and the executor CLI accepts them without `--experimental`. For example, ### 13.3 Versioning Each backend's graduation event (ephemeral, state-aware, or both at once) triggers a -schema version bump in `docs/versioning.md`, following the existing MXC convention for +schema version bump in `docs/development/architecture/versioning.md`, following the existing MXC convention for graduating features. The version bump and the associated SDK type changes (such as dropping `experimental: true` requirements for graduated containment values) ship as a single release. diff --git a/docs/architecture.md b/docs/development/architecture/repository-architecture.md similarity index 95% rename from docs/architecture.md rename to docs/development/architecture/repository-architecture.md index 25cd27bec..b76f47b5c 100644 --- a/docs/architecture.md +++ b/docs/development/architecture/repository-architecture.md @@ -81,11 +81,11 @@ Production parsing selects an exact registered contract. Version-specific adapters produce the private `CommonRequestIR` normalization input, and shared normalization constructs the runtime `ExecutionRequest`. No rolling whole-request parser or model remains. See -[Versioning](versioning.md) and [Schema code generation](schema-codegen.md). +[Versioning](versioning.md) and [Schema code generation](../build-and-test/schema-codegen.md). State-aware requests follow the same parsing path and produce a typed lifecycle operation. See the -[State-aware sandbox API](state-aware-lifecycle/mxc-state-aware-sandbox-api.md). +[Container lifecycle architecture](container-lifecycle.md). ## Execution surfaces @@ -138,5 +138,5 @@ schema tooling. |-----------|----------| | Rust unit and contract tests | Under `src/mxc-sdk/src/` and `src/mxc-sdk/tests/` | | Executor E2E tests | `src/mxc-sdk/tests/wxc_e2e_tests_*` | -| Host-dependent backend suites | [`tests/scripts/`](../tests/scripts/README.md) | -| Scheduled backend validation | [CI validation infrastructure](ci-validation-infrastructure.md) | +| Host-dependent backend suites | [`tests/scripts/`](../../../tests/scripts/README.md) | +| Scheduled backend validation | [CI validation infrastructure](../build-and-test/ci-validation-infrastructure.md) | diff --git a/docs/telemetry/telemetry-consent-design.md b/docs/development/architecture/telemetry-consent-design.md similarity index 100% rename from docs/telemetry/telemetry-consent-design.md rename to docs/development/architecture/telemetry-consent-design.md diff --git a/docs/telemetry/telemetry.md b/docs/development/architecture/telemetry.md similarity index 100% rename from docs/telemetry/telemetry.md rename to docs/development/architecture/telemetry.md diff --git a/docs/versioning.md b/docs/development/architecture/versioning.md similarity index 98% rename from docs/versioning.md rename to docs/development/architecture/versioning.md index dd4e461d7..c81bb8f86 100644 --- a/docs/versioning.md +++ b/docs/development/architecture/versioning.md @@ -51,8 +51,8 @@ The sections below distinguish the [three version axes](#the-three-version-axes) [contract shipping and parsing](#schema-shipping-model), [SDK major targets](#high-level-sdk-major-targets), and [backend authorization](#experimental-flag). Artifact regeneration belongs in -[Schema Code Generation](schema-codegen.md); backend execution flow is covered -by [Architecture](architecture.md). +[Schema Code Generation](../build-and-test/schema-codegen.md); backend execution flow is covered +by [Architecture](repository-architecture.md). ## Core Concepts @@ -187,7 +187,7 @@ Only the v1.1 prerelease file under `schemas/dev/` is a generated development artifact. Published v0.9 and v1.0 are represented by exact Rust contracts and immutable stable schemas. Exact fixtures and adapter/runtime tests remain ordinary mutable tests so they can gain regression coverage as implementations -evolve. See [Schema Code Generation](schema-codegen.md) for the regeneration +evolve. See [Schema Code Generation](../build-and-test/schema-codegen.md) for the regeneration commands and independent drift/history gates. ### Typed state-aware dispatch @@ -362,7 +362,7 @@ the state-aware JSON exports. Typed binding writers select the SDK-owned contract; raw APIs preserve the caller's exact document. These exports use the registered contract parser and take non-configuration controls, including experimental authorization, as typed FFI arguments rather than JSON fields. -The [SDK conformance fixtures](../tests/policy/README.md#sdk-v1-conformance-fixtures) +The [SDK conformance fixtures](../../../tests/policy/README.md#sdk-v1-conformance-fixtures) pair high-level invocations with independently hand-authored expected exact documents to check mapping intent across Rust, Node, and .NET. @@ -419,7 +419,7 @@ The SDK passes `--experimental` to the underlying binary when this option is set ### Forking Code for Experimental Features Developers adding experimental features follow this pattern. For a detailed -step-by-step guide, see [Authoring a New Feature](authoring-a-new-feature.md). +step-by-step guide, see [Authoring a New Feature](../guides/authoring-a-new-feature.md). **In the exact development contract (the production parse + schema source of truth):** diff --git a/docs/ci-validation-infrastructure.md b/docs/development/build-and-test/ci-validation-infrastructure.md similarity index 99% rename from docs/ci-validation-infrastructure.md rename to docs/development/build-and-test/ci-validation-infrastructure.md index d4d86f6c8..ff98b4937 100644 --- a/docs/ci-validation-infrastructure.md +++ b/docs/development/build-and-test/ci-validation-infrastructure.md @@ -9,7 +9,7 @@ retire something. This document describes the GitHub Actions validation matrix only. PR-time build/lint/SDK validation is covered by [`pull-requests.md`](pull-requests.md); the individual local test scripts are documented in -[`tests/scripts/README.md`](../tests/scripts/README.md). +[`tests/scripts/README.md`](../../../tests/scripts/README.md). ## At a glance diff --git a/docs/fuzzing.md b/docs/development/build-and-test/fuzzing.md similarity index 100% rename from docs/fuzzing.md rename to docs/development/build-and-test/fuzzing.md diff --git a/docs/pull-requests.md b/docs/development/build-and-test/pull-requests.md similarity index 100% rename from docs/pull-requests.md rename to docs/development/build-and-test/pull-requests.md diff --git a/docs/schema-codegen.md b/docs/development/build-and-test/schema-codegen.md similarity index 100% rename from docs/schema-codegen.md rename to docs/development/build-and-test/schema-codegen.md diff --git a/docs/wsl/wslc-sdk-bindings.md b/docs/development/build-and-test/wslc-sdk-bindings.md similarity index 100% rename from docs/wsl/wslc-sdk-bindings.md rename to docs/development/build-and-test/wslc-sdk-bindings.md diff --git a/docs/authoring-a-new-feature.md b/docs/development/guides/authoring-a-new-feature.md similarity index 97% rename from docs/authoring-a-new-feature.md rename to docs/development/guides/authoring-a-new-feature.md index 1e82d65a6..7767c0271 100644 --- a/docs/authoring-a-new-feature.md +++ b/docs/development/guides/authoring-a-new-feature.md @@ -18,9 +18,9 @@ Read these in order: -1. [Sandbox Policy spec](sandbox-policy/0.7.0/policy.md): what +1. [Containment configuration spec](../../containment-configuration/0.7.0/policy.md): what Policy and ContainerConfig are, design principles. -2. [Versioning Design](versioning.md): how policy/schema/SDK +2. [Versioning Design](../architecture/versioning.md): how policy/schema/SDK versions relate and when to bump. ## Step 0: Where does my feature go? @@ -87,7 +87,7 @@ the OS engineer. > flows through all layers. For detailed OS contribution steps (FlatBuffer schema, processmodel, -BaseContainerRunner), see [process-container/guide.md](process-container/guide.md). +BaseContainerRunner), see [process-container/guide.md](process-container-adding-os-features.md). ## Step 3+: Implementation @@ -101,7 +101,7 @@ If your feature touches SandboxPolicy, update If your feature adds policy or config fields, you will need to plumb them through `createConfigFromPolicy()` in `sdk/node/src/sandbox.ts`. See the -[worked example in the Sandbox Policy spec](sandbox-policy/0.7.0/policy.md#10-worked-example-ui-policy) +[worked example in the containment configuration spec](../../containment-configuration/0.7.0/policy.md#10-worked-example-ui-policy) for a walkthrough. --- diff --git a/docs/diagnostics.md b/docs/development/guides/diagnostics.md similarity index 97% rename from docs/diagnostics.md rename to docs/development/guides/diagnostics.md index 98b66ef14..3994f26ba 100644 --- a/docs/diagnostics.md +++ b/docs/development/guides/diagnostics.md @@ -1,6 +1,6 @@ # MXC Diagnostics -> **Audience:** MXC consumers and developers +> **Audience:** MXC developers A unified diagnostic view across every layer of the MXC stack: @@ -146,9 +146,9 @@ internal trace. Retained ETL can contain sensitive paths and identifiers; the caller is responsible for deleting it when it is no longer needed. The checked-in -[`tests/examples/29_capture_denials.json`](../tests/examples/29_capture_denials.json) +[`tests/examples/29_capture_denials.json`](../../../tests/examples/29_capture_denials.json) is a minimal block-mode example. See -[Learning-mode capabilities](learning-mode/capabilities.md#relationship-to-denial-capture) +[Logging access denied](../../logging-access-denied.md#relationship-to-denial-capture) for the output schemas, bounds, host-selection behavior, and SDK metadata surfaces. @@ -267,12 +267,12 @@ the `MXC_DIAG_CONSOLE` pipe β€” never to stdout, so they cannot pollute an SDK caller's captured output. With neither sink configured, these JSON records are not emitted and no record is built. When Windows ETW telemetry is explicitly enabled, the separate `Microsoft.MXC` TraceLogging provider may still receive the bounded M-ETW -events described in [`docs/telemetry/telemetry.md`](telemetry/telemetry.md); +events described in [telemetry architecture](../architecture/telemetry.md); those events are local ETW only and are not uploaded by MXC. These are **local diagnostics, not ETW telemetry**: no provider, no consent gate, nothing uploaded. See -[`docs/telemetry/telemetry.md` Β§ Local audit log records](telemetry/telemetry.md#local-audit-log-records) +[Telemetry architecture: Local audit log records](../architecture/telemetry.md#local-audit-log-records) for the JSON-lines format, the full record inventory with fields, the content rules (bounded vocabularies, config field *paths* but never values, no raw user identifiers), diff --git a/docs/process-container/guide.md b/docs/development/guides/process-container-adding-os-features.md similarity index 92% rename from docs/process-container/guide.md rename to docs/development/guides/process-container-adding-os-features.md index f5a4a6b1e..c391d2a6a 100644 --- a/docs/process-container/guide.md +++ b/docs/development/guides/process-container-adding-os-features.md @@ -11,13 +11,13 @@ networking fields remain available under their published contracts. Backend selection depends on host capability and requested policy, not schema version. For which policy aspects this backend can enforce on each Windows 11 release, -see [Windows OS-version policy support](./os-version-support.md). +see [Windows OS-version policy support](../../backends/process-container/os-version-support.md). ## Prerequisites -1. Read the [Sandbox Policy spec](../sandbox-policy/0.7.0/policy.md) to +1. Read the [containment configuration spec](../../containment-configuration/0.7.0/policy.md) to understand how `SandboxPolicy` maps to `ContainerConfig`. -2. Read [authoring-a-new-feature.md](../authoring-a-new-feature.md), especially +2. Read [authoring-a-new-feature.md](authoring-a-new-feature.md), especially Step 1 (feature spec) and Step 2 (OS changes). 3. Submit a feature spec so reviewers understand the end-to-end flow. @@ -65,7 +65,7 @@ src/mxc-sdk/src/core/process_security_environment_spec/ Update the exact development config contract, normalized wire model, runtime model, and parser mapping. Follow -[authoring-a-new-feature.md](../authoring-a-new-feature.md) and regenerate the +[authoring-a-new-feature.md](authoring-a-new-feature.md) and regenerate the development schemas and generated SDK wire types rather than editing generated artifacts by hand. diff --git a/docs/backend-support-probe-api-plan.md b/docs/development/plans/backend-support-probe-api.md similarity index 99% rename from docs/backend-support-probe-api-plan.md rename to docs/development/plans/backend-support-probe-api.md index 5c959fc3b..d0f3250f2 100644 --- a/docs/backend-support-probe-api-plan.md +++ b/docs/development/plans/backend-support-probe-api.md @@ -67,7 +67,7 @@ Example results: > **"Stock Windows"** here means a clean Windows install with only the default > optional features enabled (no BaseContainer, Windows Sandbox, etc.), so the > process-container backend falls to its `appcontainer-dacl` floor. See -> [`docs/process-container/os-version-support.md`](process-container/os-version-support.md) +> [`docs/backends/process-container/os-version-support.md`](../../backends/process-container/os-version-support.md) > for the per-release policy-support matrix that determines the reachable tier. | Host | Result | diff --git a/docs/bwrap-support/bubblewrap-backend-plan.md b/docs/development/plans/bubblewrap-backend.md similarity index 98% rename from docs/bwrap-support/bubblewrap-backend-plan.md rename to docs/development/plans/bubblewrap-backend.md index 09da94e9b..04566b209 100644 --- a/docs/bwrap-support/bubblewrap-backend-plan.md +++ b/docs/development/plans/bubblewrap-backend.md @@ -303,10 +303,10 @@ the LXC runner: apply rules before execution, remove rules after. ### 10. Documentation -- `docs/bwrap-support/bubblewrap-backend.md` β€” user guide +- `docs/backends/bwrap/bubblewrap-backend.md` β€” user guide - Update `docs/schema.md` β€” new containment value and config block - Update `.github/copilot-instructions.md` β€” add to backend table -- Update `docs/authoring-a-new-feature.md` if the experimental feature checklist changes +- Update `docs/development/guides/authoring-a-new-feature.md` if the experimental feature checklist changes ## Effort Estimate (Complexity) @@ -363,7 +363,7 @@ policy gap is a design decision, not an implementation challenge. - `sdk/node/src/helper.ts` β€” no changes needed (lxc-exec handles both backends) ### Documentation (new/modify) -- `docs/bwrap-support/bubblewrap-backend.md` (new) +- `docs/backends/bwrap/bubblewrap-backend.md` (new) - `docs/schema.md` (modify) - `.github/copilot-instructions.md` (modify β€” add to backend table) diff --git a/docs/linux-wsl-roadmap-june-2026.md b/docs/development/plans/linux-wsl-roadmap-june-2026.md similarity index 99% rename from docs/linux-wsl-roadmap-june-2026.md rename to docs/development/plans/linux-wsl-roadmap-june-2026.md index 3d9055bdf..cec96adce 100644 --- a/docs/linux-wsl-roadmap-june-2026.md +++ b/docs/development/plans/linux-wsl-roadmap-june-2026.md @@ -103,7 +103,7 @@ File:line citations reference paths under `src/backends//...` and `src/ | # | Item | Status | Description | Effort | |---|---|---|---|---| -| 16 | **(N4) Deny-wins precedence** | βœ… Addressed | `egress.deny[]` rules are emitted ahead of `egress.allow[]` rules, matching the ordering already used for the legacy host lists. The legacy DNS exemption is not carried into a directional posture β€” port 53 is governed by the same rules as every other forwarded destination, per GA decision D3. Two paths still sit outside the generated rules: the base chain's `ESTABLISHED,RELATED` accept, and the bridge resolver, which the container reaches through the host's `INPUT` path rather than this chain. Both are stated in `docs/lxc-support/lxc-backend.md`. | S | +| 16 | **(N4) Deny-wins precedence** | βœ… Addressed | `egress.deny[]` rules are emitted ahead of `egress.allow[]` rules, matching the ordering already used for the legacy host lists. The legacy DNS exemption is not carried into a directional posture β€” port 53 is governed by the same rules as every other forwarded destination, per GA decision D3. Two paths still sit outside the generated rules: the base chain's `ESTABLISHED,RELATED` accept, and the bridge resolver, which the container reaches through the host's `INPUT` path rather than this chain. Both are stated in `docs/backends/lxc/lxc-backend.md`. | S | | 17 | **(N5) Proxy β€” env vars + enforcement** | 🟑 Actionable | Schema field exists, backend ignores it. Fix: inject `HTTP_PROXY`/`HTTPS_PROXY`, clear all inherited proxy vars, and restrict egress to proxy port only via iptables. | M | > **Example (N5).** Consumer starts proxy on `127.0.0.1:8080`. MXC sets `HTTP_PROXY=127.0.0.1:8080` inside the container and applies `iptables -A OUTPUT -d 127.0.0.1 --dport 8080 -j ACCEPT` + default DROP. An app ignoring the env var tries `connect(140.82.112.4:443)` β†’ dropped. @@ -135,7 +135,7 @@ File:line citations reference paths under `src/backends//...` and `src/ | # | Item | Description | Effort | |---|---|---|---| | 29 | **Structured denied-resource diagnostics** | Process Container surfaces structured denial reasons; LXC returns opaque "execution failed" strings β€” wire equivalent telemetry. | M | -| 30 | **Doc drift cleanup** | `docs/lxc-support/lxc-backend.md:38-49,102-103` references `containerName` and `removeRulesOnExit` fields that don't exist in code. | S | +| 30 | **Doc drift cleanup** | `docs/backends/lxc/lxc-backend.md:38-49,102-103` references `containerName` and `removeRulesOnExit` fields that don't exist in code. | S | | 31 | **Un-gate LXC network tests in CI** | Done for GHA (PR `user/sodas/lxc-ci-enablement`). `MXC_SKIP_LXC_NETWORK_TESTS=1` kept on both GHA and ADO. ADO egress blocks `lxcbr0` NAT'd traffic. *(see [Ext-Dep E1](#external-dependencies))* | M | --- @@ -219,7 +219,7 @@ File:line citations reference paths under `src/backends//...` and `src/ | 28 | **Resource limits (cgroups v2)** | No CPU / memory / PID / IO governance. Same gap as LXC. *(see [Ext-Dep E7](#external-dependencies))* | L | | 29 | **Stable backend surface** | Addressed β€” Bubblewrap is published in v0.8. | β€” | | 30 | **State-aware lifecycle** | Implement `StatefulSandboxBackend` for bwrap. | L | -| 31 | **Update plan doc** | `docs/bwrap-support/bubblewrap-backend-plan.md:42-60,295-324` still describes core implementation as "planned" even though it's shipped. | M | +| 31 | **Update plan doc** | `docs/development/plans/bubblewrap-backend.md:42-60,295-324` still describes core implementation as "planned" even though it's shipped. | M | | 32 | **Structured per-host network decision trace** | Surface why each connection attempt was allowed/denied. | M | | 33 | **Structured denied-resource diagnostics** | Parity with Process Container's structured denial reporting. | M | | 34 | **CI job for `tests/scripts/run_bwrap_all_tests.sh`** | Bwrap E2E suite is manual-only today. *(see [Ext-Dep E3](#external-dependencies))* | M | @@ -486,7 +486,7 @@ File:line citations reference paths under `src/backends//...` and `src/ | # | Item | Status | Description | Effort | |---|---|---|---|---| | 28 | **Port-mapping support** | βœ… Addressed | TCP hostβ†’container port forwarding shipped in [PR #530](https://github.com/microsoft/mxc/pull/530) (merged 2026-06-23). Provides explicit per-port inbound exposure (the `hostLoopback: "allow"` primitive for mapped ports); policy-driven `ingress.hostLoopback` default posture still needs the VM-level API (see Network #16 / SDK dep #1). | β€” | -| 29 | **State-aware lifecycle** | βœ… Addressed | Daemon-backed warm session/container reuse across separate phase processes (`wxc-wslc-daemon.exe`) implements `StatefulSandboxBackend` for WSLC β€” the highest-value WSLC win (slowest cold start). See `docs/wsl/wslc-state-aware.md`. | β€” | +| 29 | **State-aware lifecycle** | βœ… Addressed | Daemon-backed warm session/container reuse across separate phase processes (`wxc-wslc-daemon.exe`) implements `StatefulSandboxBackend` for WSLC β€” the highest-value WSLC win (slowest cold start). See `docs/backends/wslc/wslc-state-aware.md`. | β€” | | 30 | **Structured denied-resource diagnostics** | 🟑 Actionable | Parity with Process Container's structured denial reporting. | M | | 31 | **Un-gate WSLC tests in CI** | β›” Blocked | Needs `wslcsdk.dll` public NuGet (see SDK dep #2 above). | M | diff --git a/docs/nanvix-microvm/nanvix-integration-plan.md b/docs/development/plans/nanvix-integration.md similarity index 99% rename from docs/nanvix-microvm/nanvix-integration-plan.md rename to docs/development/plans/nanvix-integration.md index e5b5cdbd7..ea17d2741 100644 --- a/docs/nanvix-microvm/nanvix-integration-plan.md +++ b/docs/development/plans/nanvix-integration.md @@ -129,8 +129,8 @@ mxc/src/ β”œβ”€β”€ mxc-sdk/src/bin/windows_sandbox_guest/ # UNCHANGED └── mxc-sdk/src/bin/windows_sandbox_daemon/ # UNCHANGED -mxc/docs/nanvix-microvm/ -└── nanvix-integration-plan.md # NEW β€” this document +mxc/docs/development/plans/ +└── nanvix-integration.md # NEW β€” this document mxc/tests/configs/ └── microvm_hello.json # NEW β€” example microvm config diff --git a/docs/examples.md b/docs/examples.md index 55fd6b562..00c1aee31 100644 --- a/docs/examples.md +++ b/docs/examples.md @@ -65,7 +65,7 @@ writable directory. The destination is numeric because directional rules accept IP/CIDR, not hostnames. It must be reachable from the host to demonstrate the allow rule; -see the [ProcessContainer networking guide](process-container/networking.md) +see the [ProcessContainer networking guide](backends/process-container/networking.md) for host requirements and enforcement limits. ### Directional Network Policy (schema 0.9+) @@ -101,7 +101,7 @@ separate ingress defaults: See [`tests/examples/30_network_0_8_directional.json`](../tests/examples/30_network_0_8_directional.json) for the complete config and -[`sandbox-policy/0.8.0/networking/networking.md`](sandbox-policy/0.8.0/networking/networking.md) +[`containment-configuration/0.8.0/networking/networking.md`](containment-configuration/0.8.0/networking/networking.md) for the historical GA design; use the [supported schema guide](schema.md) for current backend authoring. @@ -138,7 +138,7 @@ configured proxy address and port, but does not verify which process owns that endpoint. It requires native PSEC 1.1 ingress/host-loopback support; unsupported hosts reject the request. For production ProcessContainer deployments, identify a packaged proxy through `processContainer.network.allowedProxyPeer` instead; see -[proxy deployment choices](process-container/networking.md#proxy-deployment-choices). +[proxy deployment choices](backends/process-container/networking.md#proxy-deployment-choices). Bubblewrap and Seatbelt also support a caller-managed loopback proxy, but their supported ingress policies differ. See their backend guides. @@ -147,7 +147,7 @@ their supported ingress policies differ. See their backend guides. Every supported contract (`0.9.0-alpha` or later) accepts the directional shape and rejects the retired `defaultPolicy`, host-list, and `network.proxy` fields. This is the cross-backend schema (see -[`docs/sandbox-policy/0.8.0/networking/networking.md`](sandbox-policy/0.8.0/networking/networking.md) +[`docs/containment-configuration/0.8.0/networking/networking.md`](containment-configuration/0.8.0/networking/networking.md) for the full design and per-backend enforcement matrix), not a backend-specific format: it's parsed the same way regardless of `containment`. Each backend independently declares which parts of it β€” if @@ -158,7 +158,7 @@ Note that `EGRESS_RULES` is what carries per-CIDR/port rules; a backend without it accepts only `egress.default`. On Seatbelt, `runtimeConfig.networkProxy` covers only loopback endpoints; there is no supported equivalent for a remote proxy URL or `builtinTestServer`. See -[`docs/sandbox-policy/0.8.0/networking/schema-updates.md`](sandbox-policy/0.8.0/networking/schema-updates.md) +[`docs/containment-configuration/0.8.0/networking/schema-updates.md`](containment-configuration/0.8.0/networking/schema-updates.md) for the full field mapping and [`tests/examples/31_mac_network_0_8.json`](../tests/examples/31_mac_network_0_8.json) for a complete example: diff --git a/docs/learning-mode/capabilities.md b/docs/logging-access-denied.md similarity index 99% rename from docs/learning-mode/capabilities.md rename to docs/logging-access-denied.md index e5c5dbb69..3c6e1e55e 100644 --- a/docs/learning-mode/capabilities.md +++ b/docs/logging-access-denied.md @@ -340,7 +340,7 @@ event contains a valid JSON array of complete signatures and document reconstruction metadata. Before emission, MXC derives provider GUIDs from the closed provider enum and drops every verbose property name and value. MXC does not send the actionable denials file, workload-derived properties, or raw ETL -through telemetry. See [MXC telemetry](../telemetry/telemetry.md). +through telemetry. See [MXC telemetry](development/architecture/telemetry.md). **Locating the file.** Set `captureDenials.outputPath` to name the file explicitly (its parent directory must already exist). MXC inserts a unique diff --git a/docs/schema.md b/docs/schema.md index cca93d31d..eee4fd404 100644 --- a/docs/schema.md +++ b/docs/schema.md @@ -266,8 +266,8 @@ that can be executed independently. > is rejected with a parse error. Callers cannot supply `correlationVector`; > it is rejected as an unknown field because lifecycle correlation is internal > to MXC and is not part of the request or response contract. See -> [`docs/state-aware-lifecycle/mxc-state-aware-sandbox-api.md`](state-aware-lifecycle/mxc-state-aware-sandbox-api.md) -> and [`docs/telemetry/telemetry.md`](telemetry/telemetry.md). +> [Container lifecycle architecture](development/architecture/container-lifecycle.md) +> and [telemetry architecture](development/architecture/telemetry.md). ### Working Directory @@ -284,8 +284,8 @@ use: |---------|----------------------------------------| | Windows ProcessContainer (AppContainer / BaseContainer) | First `readwritePaths` entry that is an existing directory, else the first such `readonlyPaths` entry, else the system drive root (`%SystemDrive%\`). Never `NULL`. | | Seatbelt (macOS) | Same precedence, with `~` expanded as the profile expands it; falls back to `/`. | -| Bubblewrap (Linux) | No substitution β€” a policy grant is never adopted. `--chdir` is emitted only for an explicit `process.cwd`, which from 0.9 is also normalized against the sandbox root and used as `HOME`. With no explicit `cwd` there is no `--chdir` and `HOME` is unset β€” see [`docs/bwrap-support/bubblewrap-backend.md`](bwrap-support/bubblewrap-backend.md). | -| LXC / WSL Container | The container root β€” see [`docs/lxc-support/lxc-backend.md`](lxc-support/lxc-backend.md). | +| Bubblewrap (Linux) | No substitution β€” a policy grant is never adopted. `--chdir` is emitted only for an explicit `process.cwd`, which from 0.9 is also normalized against the sandbox root and used as `HOME`. With no explicit `cwd` there is no `--chdir` and `HOME` is unset β€” see [`docs/backends/bwrap/bubblewrap-backend.md`](backends/bwrap/bubblewrap-backend.md). | +| LXC / WSL Container | The container root β€” see [`docs/backends/lxc/lxc-backend.md`](backends/lxc/lxc-backend.md). | | MicroVM (NanVix) / Hyperlight | Not applicable β€” these backends reject a working directory outright. | Policy entries that are blank, name a file, or do not exist yet are skipped: @@ -296,7 +296,7 @@ Windows drive path, which is mapped under `/mnt/` (for example `C:\work` becomes `/mnt/c/work`); any other value is rejected before the container is created. WSL Container state-aware `exec` takes an absolute in-container path instead. See -[`docs/wsl/wsl-container-getting-started.md`](wsl/wsl-container-getting-started.md). +[`docs/backends/wslc/wsl-container-getting-started.md`](backends/wslc/wsl-container-getting-started.md). ### Environment @@ -326,7 +326,7 @@ launch. What the default block contains is backend-specific; see the backend's guide. On the WSL Container backend it is the container image's own `ENV`, which MXC neither authors nor enumerates β€” see -[`docs/wsl/wsl-container-getting-started.md`](wsl/wsl-container-getting-started.md#environment). +[`docs/backends/wslc/wsl-container-getting-started.md`](backends/wslc/wsl-container-getting-started.md#environment). ### Filesystem Policy @@ -390,7 +390,7 @@ documentation before relying on the default. **Per-backend support.** `ui` is enforced by the Windows ProcessContainer backend (via job-object UI restrictions plus the Win32k mitigation β€” see -[`process-container/UIPolicy_Schema.md`](process-container/UIPolicy_Schema.md)) +[`backends/process-container/UIPolicy_Schema.md`](backends/process-container/UIPolicy_Schema.md)) and by the macOS Seatbelt backend (via the generated sandbox profile). Other backends do not implement UI restrictions; each backend's documentation states whether it applies, rejects, or ignores the section. **IsolationSession and WSLc @@ -398,9 +398,9 @@ refuse any supplied `ui` at every phase on both surfaces**, and each accepts an omitted one without applying any UI restriction β€” so the section's default-deny reading does not hold on either. The reasons differ: no `ui` posture is truthful for a session-isolated sandbox (see -[`isolation-session/state-aware-rust.md`](isolation-session/state-aware-rust.md)), +[IsolationSession state-aware Rust architecture](development/architecture/backends/isolation-session/state-aware-rust.md)), while WSLc has no mechanism to enforce UI restrictions on a container (see -[`wsl/wslc-state-aware.md`](wsl/wslc-state-aware.md)). +[`backends/wslc/wslc-state-aware.md`](backends/wslc/wslc-state-aware.md)). The Windows `processContainer.ui` sub-block carries the ProcessContainer-only fields `isolation`, `desktopSystemControl`, `systemSettings`, and `ime`. `processContainer.filesystem` carries `enumeratePaths`. Both sub-blocks are @@ -440,8 +440,8 @@ force a particular backend. | `"microvm"` | MicroVM isolation via Windows HyperV Platform (NanVix microkernel) | | `"hyperlight"` | MicroVM isolation via Hyperlight + Unikraft with an embedded CPython snapshot (experimental) | | `"isolation_session"` | Windows isolation session β€” runs the workload as a freshly-provisioned, per-execution isolated user account in its own OS-managed session. Dual-mode: one-shot and state-aware. | -| `"seatbelt"` | macOS sandbox isolation (Seatbelt). Requires macOS 15 or later β€” see [`docs/seatbelt/seatbelt-backend.md`](seatbelt/seatbelt-backend.md). | -| `"bubblewrap"` | Unprivileged Linux sandboxing via Bubblewrap/user namespaces. The Linux default β€” see [`docs/bwrap-support/bubblewrap-backend.md`](bwrap-support/bubblewrap-backend.md). | +| `"seatbelt"` | macOS sandbox isolation (Seatbelt). Requires macOS 15 or later β€” see [`docs/backends/seatbelt/seatbelt-backend.md`](backends/seatbelt/seatbelt-backend.md). | +| `"bubblewrap"` | Unprivileged Linux sandboxing via Bubblewrap/user namespaces. The Linux default β€” see [`docs/backends/bwrap/bubblewrap-backend.md`](backends/bwrap/bubblewrap-backend.md). | Only the backend section matching the selected `containment` value is accepted; a config that also carries an unrelated backend's section is **rejected** with a @@ -499,7 +499,7 @@ State-aware-capable backends today are `isolation_session`, `windows_sandbox`, and `wslc` (all Windows-only). IsolationSession does not require runtime experimental authorization; Windows Sandbox does. -Full lifecycle API: [`docs/state-aware-lifecycle/mxc-state-aware-sandbox-api.md`](state-aware-lifecycle/mxc-state-aware-sandbox-api.md). +Full lifecycle API: [container lifecycle](container-lifecycle.md). ### Schema Versioning diff --git a/docs/telemetry/telemetry-administrative-policy.md b/docs/telemetry.md similarity index 97% rename from docs/telemetry/telemetry-administrative-policy.md rename to docs/telemetry.md index 3fa1e4100..438528de1 100644 --- a/docs/telemetry/telemetry-administrative-policy.md +++ b/docs/telemetry.md @@ -165,5 +165,5 @@ application-specific policy under `SOFTWARE\Policies\Microsoft\`. ## See also -- [Telemetry overview](telemetry.md) -- [Telemetry consent design](telemetry-consent-design.md) +- [Telemetry architecture](development/architecture/telemetry.md) +- [Telemetry consent design](development/architecture/telemetry-consent-design.md) diff --git a/sdk/dotnet/Microsoft.Mxc.Sdk/V1/MxcTelemetry.cs b/sdk/dotnet/Microsoft.Mxc.Sdk/V1/MxcTelemetry.cs index 87af72ea0..39be2b0a5 100644 --- a/sdk/dotnet/Microsoft.Mxc.Sdk/V1/MxcTelemetry.cs +++ b/sdk/dotnet/Microsoft.Mxc.Sdk/V1/MxcTelemetry.cs @@ -11,7 +11,7 @@ namespace Microsoft.Mxc.Sdk.V1; /// /// Administers MXC telemetry consent. See -/// docs/telemetry/telemetry-consent-design.md for the contract. +/// docs/development/architecture/telemetry-consent-design.md for the contract. /// public static class MxcTelemetry { diff --git a/sdk/dotnet/Microsoft.Mxc.Sdk/V1/TelemetryPolicyState.cs b/sdk/dotnet/Microsoft.Mxc.Sdk/V1/TelemetryPolicyState.cs index 14522c454..c69bc0d96 100644 --- a/sdk/dotnet/Microsoft.Mxc.Sdk/V1/TelemetryPolicyState.cs +++ b/sdk/dotnet/Microsoft.Mxc.Sdk/V1/TelemetryPolicyState.cs @@ -5,7 +5,7 @@ namespace Microsoft.Mxc.Sdk.V1; /// /// The administrative (MDM / Group Policy) telemetry decision for this machine. -/// See docs/telemetry/telemetry-administrative-policy.md for the admin-facing reference. +/// See docs/telemetry.md for the admin-facing reference. /// /// An administrator can disable MXC telemetry machine-wide via Intune, another /// MDM, or Group Policy. The policy is a ceiling, never a grant: an diff --git a/sdk/dotnet/README.md b/sdk/dotnet/README.md index ac44389a0..bdedb26e7 100644 --- a/sdk/dotnet/README.md +++ b/sdk/dotnet/README.md @@ -158,8 +158,8 @@ Use `SpawnInContainer` or `SpawnInContainerAsync` for live piped execution. The asynchronous methods are convenience wrappers over native operations and support cancellation. Backend and phase-specific policy requirements are described in the -[IsolationSession](https://github.com/microsoft/mxc/blob/main/docs/isolation-session/state-aware-rust.md) and -[WSLC](https://github.com/microsoft/mxc/blob/main/docs/wsl/wslc-state-aware.md) guides. +[IsolationSession](https://github.com/microsoft/mxc/blob/main/docs/development/architecture/backends/isolation-session/state-aware-rust.md) and +[WSLC](https://github.com/microsoft/mxc/blob/main/docs/backends/wslc/wslc-state-aware.md) guides. `MxcLifecycle.SpawnInContainerWithPty(id, request, options?)` starts an IsolationSession exec with a caller-controlled terminal and returns an `MxcPtyProcess`. Set `SpawnInContainerWithPtyOptions.Size` to choose initial @@ -216,9 +216,9 @@ Backend/platform discovery, errors, telemetry, and helpers are also in | Terminal process outcome | `WaitResult` | All types above are in `Microsoft.Mxc.Sdk.V1`. See the -[networking guide](https://github.com/microsoft/mxc/blob/main/docs/sandbox-policy/0.8.0/networking/networking.md) +[networking guide](https://github.com/microsoft/mxc/blob/main/docs/containment-configuration/0.8.0/networking/networking.md) for policy behavior and the -[SDK API reference](https://github.com/microsoft/mxc/blob/main/docs/reference/README.md) +[SDK API reference](https://github.com/microsoft/mxc/blob/main/docs/api-reference/README.md) for complete signatures and types. ## Errors, warnings, and discovery @@ -260,6 +260,6 @@ pipeline produces the publishable NuGet package; `build.bat` creates local architecture-specific packages under `output\packages`. For API details, see the -[SDK API reference](https://github.com/microsoft/mxc/blob/main/docs/reference/README.md). +[SDK API reference](https://github.com/microsoft/mxc/blob/main/docs/api-reference/README.md). Build and validation commands are in the -[pull request guide](https://github.com/microsoft/mxc/blob/main/docs/pull-requests.md). +[pull request guide](https://github.com/microsoft/mxc/blob/main/docs/development/build-and-test/pull-requests.md). diff --git a/sdk/node/CHANGELOG.md b/sdk/node/CHANGELOG.md index 366e7fab7..bd5bcb569 100644 --- a/sdk/node/CHANGELOG.md +++ b/sdk/node/CHANGELOG.md @@ -85,7 +85,7 @@ Entries below describe historical release APIs, not the current V1 surface. policy (`readwritePaths` / `readonlyPaths` / `deniedPaths`) is honored at provision and is immutable thereafter; `network` / `ui` / Entra `user` bundles are not honored on this backend. See - [`docs/windows-sandbox/windows-sandbox.md`](../../docs/windows-sandbox/windows-sandbox.md) + [`docs/backends/windows-sandbox/windows-sandbox.md`](../../docs/backends/windows-sandbox/windows-sandbox.md) for the full per-phase config matrix. ### Changed diff --git a/sdk/node/README.md b/sdk/node/README.md index 677c20c7e..9f0f120cc 100644 --- a/sdk/node/README.md +++ b/sdk/node/README.md @@ -157,8 +157,8 @@ IsolationSession exec with a caller-driven terminal and returns a to 24 rows by 80 columns. IsolationSession provision requires an explicit unrestricted directional network posture; WSLC network posture is fixed at provision. See the -[IsolationSession](https://github.com/microsoft/mxc/blob/main/docs/isolation-session/state-aware-typescript.md) and -[WSLC](https://github.com/microsoft/mxc/blob/main/docs/wsl/wslc-state-aware.md) guides for backend and phase +[IsolationSession](https://github.com/microsoft/mxc/blob/main/docs/development/architecture/backends/isolation-session/state-aware-typescript.md) and +[WSLC](https://github.com/microsoft/mxc/blob/main/docs/backends/wslc/wslc-state-aware.md) guides for backend and phase requirements. Provisioning takes a discriminated `ProvisionRequest` and optional @@ -214,10 +214,10 @@ remain on the selected containment configuration. | Host consent presenter | `TelemetryConsentPresenter` | Network policy details are in the -[networking guide](https://github.com/microsoft/mxc/blob/main/docs/sandbox-policy/0.8.0/networking/networking.md); +[networking guide](https://github.com/microsoft/mxc/blob/main/docs/containment-configuration/0.8.0/networking/networking.md); host-specific behavior and supported capabilities are documented in the backend guides under [`docs/`](https://github.com/microsoft/mxc/tree/main/docs). -See the [SDK API reference](https://github.com/microsoft/mxc/blob/main/docs/reference/README.md) +See the [SDK API reference](https://github.com/microsoft/mxc/blob/main/docs/api-reference/README.md) for complete signatures and types. ## Errors, warnings, and telemetry diff --git a/sdk/node/src/v1/types.ts b/sdk/node/src/v1/types.ts index 03ca908c0..53e137c21 100644 --- a/sdk/node/src/v1/types.ts +++ b/sdk/node/src/v1/types.ts @@ -798,7 +798,7 @@ export interface ProbeFacts { * namespace and default-drop everything except the proxy endpoint. That * requires host tooling (slirp4netns, util-linux unshare, nsenter, the * iptables family) plus unprivileged user and network namespaces the kernel - * will actually grant; see `docs/bwrap-support/bubblewrap-backend.md` for the + * will actually grant; see `docs/backends/bwrap/bubblewrap-backend.md` for the * full list. There is deliberately no fallback to the weaker shared-host-network * model, so a request that cannot configure private networking fails rather * than silently degrading. This reports, before launching, whether the host diff --git a/src/ffi/mxc_ffi/tests/ffi.rs b/src/ffi/mxc_ffi/tests/ffi.rs index a85886aa3..7a96aa1c7 100644 --- a/src/ffi/mxc_ffi/tests/ffi.rs +++ b/src/ffi/mxc_ffi/tests/ffi.rs @@ -373,10 +373,10 @@ fn extern_spawn_json_failure_returns_no_handle_and_an_owned_error() { } /// A real run requires a host backend; on Windows that means an elevated, -/// host-prepped host (see docs/host-prep.md), so this is `#[ignore]`d. +/// host-prepped host (see docs/backends/process-container/host-prep.md), so this is `#[ignore]`d. #[cfg(target_os = "windows")] #[test] -#[ignore = "requires an elevated, host-prepped Windows host (see docs/host-prep.md)"] +#[ignore = "requires an elevated, host-prepped Windows host (see docs/backends/process-container/host-prep.md)"] fn extern_run_executes_command() { let container_id = format!( "ffi-json-{}-{}", diff --git a/src/host/plm/readme.md b/src/host/plm/readme.md index 303fe6f09..674168db2 100644 --- a/src/host/plm/readme.md +++ b/src/host/plm/readme.md @@ -337,5 +337,5 @@ recorded race) still fails closed and terminates the job. ## See also -- [`docs/process-container/guide.md`](../../../docs/process-container/guide.md) β€” process-container backend overview +- [Adding ProcessContainer OS features](../../../docs/development/guides/process-container-adding-os-features.md) β€” process-container backend overview - [README β†’ Debugging β†’ Audit Mode](../../../README.md#audit-mode-permissive-learning-mode) β€” `wxc-exec --audit` integration diff --git a/src/mxc-sdk/README.md b/src/mxc-sdk/README.md index d61c5c40f..a8caa50a4 100644 --- a/src/mxc-sdk/README.md +++ b/src/mxc-sdk/README.md @@ -46,7 +46,7 @@ to 24 rows by 80 columns. Set the request's typed `Containment` when a specific backend is required. Shared restrictions remain on `ContainerRequest`; backend-specific settings are carried by the selected containment variant. These types are documented in -the [SDK API reference](https://github.com/microsoft/mxc/blob/main/docs/reference/README.md). +the [SDK API reference](https://github.com/microsoft/mxc/blob/main/docs/api-reference/README.md). `UiPolicy.disable` defaults to `true`; clipboard and input-injection permissions are authored separately. @@ -105,8 +105,8 @@ Use `v1::container::spawn_in_container` for live piped execution. terminal; PTY support is currently available for IsolationSession. Attached execution is not exposed by the Rust SDK. Lifecycle operations and existing-container execution are synchronous in Rust. Backend support and phase-specific requirements are described in the -[IsolationSession](https://github.com/microsoft/mxc/blob/main/docs/isolation-session/state-aware-rust.md) and -[WSLC](https://github.com/microsoft/mxc/blob/main/docs/wsl/wslc-state-aware.md) guides. +[IsolationSession](https://github.com/microsoft/mxc/blob/main/docs/development/architecture/backends/isolation-session/state-aware-rust.md) and +[WSLC](https://github.com/microsoft/mxc/blob/main/docs/backends/wslc/wslc-state-aware.md) guides. Lifecycle calls use distinct `ProvisionOptions`, `StartOptions`, `StopOptions`, and `DeprovisionOptions`. Existing-container execution uses @@ -144,7 +144,7 @@ For host discovery, use `mxc_sdk::v1::platform_support` and `mxc_sdk::v1::available_backends`. Errors are returned as `mxc_sdk::v1::Error` with an `ErrorCode`. Telemetry and policy helpers are also under `v1`. The -[launch-choice table](../../../docs/reference/rust/v1/api.md#choosing-a-launch-operation) +[launch-choice table](../../docs/api-reference/rust/v1/api.md#choosing-a-launch-operation) compares captured, piped, and terminal execution. ## Build features and backend support diff --git a/src/mxc-sdk/build/wslc_common/README.md b/src/mxc-sdk/build/wslc_common/README.md index 256839795..f8cf6b29b 100644 --- a/src/mxc-sdk/build/wslc_common/README.md +++ b/src/mxc-sdk/build/wslc_common/README.md @@ -58,4 +58,4 @@ environment variable. `include/wslcsdk.h` (struct sizes, exported symbol names, signatures) β€” the SDK is in preview and its ABI can change between releases. 5. Update the required WSL runtime floor in - `docs/wsl/wsl-container-getting-started.md` if it changed. + `docs/backends/wslc/wsl-container-getting-started.md` if it changed. diff --git a/src/mxc-sdk/src/backends/bubblewrap/common/bwrap_command.rs b/src/mxc-sdk/src/backends/bubblewrap/common/bwrap_command.rs index 89e661e0e..5e6420e79 100644 --- a/src/mxc-sdk/src/backends/bubblewrap/common/bwrap_command.rs +++ b/src/mxc-sdk/src/backends/bubblewrap/common/bwrap_command.rs @@ -600,7 +600,7 @@ fn resolved_env(request: &ExecutionRequest) -> Vec { /// I/O and so stays unit-testable on every host. Unit tests and any caller that /// has not stat'd the denied paths use it. The Bubblewrap runner uses /// [`build_args_classified`] instead. See -/// docs/bwrap-support/bubblewrap-backend.md for how denied paths are masked. +/// docs/backends/bwrap/bubblewrap-backend.md for how denied paths are masked. pub fn build_args(request: &ExecutionRequest, proxy_address: Option<&ProxyAddress>) -> Vec { build_args_classified(request, proxy_address, &HashSet::new()) } @@ -623,7 +623,7 @@ pub fn build_args(request: &ExecutionRequest, proxy_address: Option<&ProxyAddres /// `denied_files` is the set of `deniedPaths` entries the runner classified as /// files (built by `symlink_metadata`-probing each denied path, so this function /// performs no filesystem I/O and stays unit-testable on every host). See -/// docs/bwrap-support/bubblewrap-backend.md for how denied paths are masked. +/// docs/backends/bwrap/bubblewrap-backend.md for how denied paths are masked. pub fn build_args_classified( request: &ExecutionRequest, proxy_address: Option<&ProxyAddress>, @@ -649,7 +649,7 @@ pub(crate) fn build_args_classified_with_mode( // unsharing, leaving that descriptor open in the workload. It is inert only // because bwrap empties the capability sets before exec β€” asserted by // run_bwrap_network_proxy_test.sh, explained in - // docs/bwrap-support/bubblewrap-backend.md. + // docs/backends/bwrap/bubblewrap-backend.md. args.extend( ["--unshare-pid", "--unshare-ipc", "--unshare-uts"] .into_iter() diff --git a/src/mxc-sdk/src/backends/bubblewrap/common/bwrap_runner.rs b/src/mxc-sdk/src/backends/bubblewrap/common/bwrap_runner.rs index 0bd358c32..788a117bc 100644 --- a/src/mxc-sdk/src/backends/bubblewrap/common/bwrap_runner.rs +++ b/src/mxc-sdk/src/backends/bubblewrap/common/bwrap_runner.rs @@ -140,7 +140,7 @@ impl SandboxBackend for BubblewrapScriptRunner { // Resolve denied paths that traverse a symlink to their real host path // and classify each as a file/dir mask (see [`resolve_denied_paths`]). // Only clones the request when a path needs rewriting (common case: - // none). See docs/bwrap-support/bubblewrap-backend.md. + // none). See docs/backends/bwrap/bubblewrap-backend.md. let plan = match resolve_denied_paths(&request.policy, logger) { Ok(plan) => plan, Err(msg) => return Err(ScriptResponse::error(&msg)), diff --git a/src/mxc-sdk/src/backends/bubblewrap/common/network_rules.rs b/src/mxc-sdk/src/backends/bubblewrap/common/network_rules.rs index d87a736fa..49d71202e 100644 --- a/src/mxc-sdk/src/backends/bubblewrap/common/network_rules.rs +++ b/src/mxc-sdk/src/backends/bubblewrap/common/network_rules.rs @@ -13,7 +13,7 @@ //! //! # Addresses are IP literals and CIDRs, never names //! -//! The 0.8 networking contract (`docs/sandbox-policy/0.8.0/networking`, D3) +//! The 0.8 networking contract (`docs/containment-configuration/0.8.0/networking`, D3) //! makes rule addresses IPv4/IPv6 literals or CIDRs and rejects DNS names at //! validation time: a name is bypassable and non-deterministic, since the //! sandbox can resolve it itself and the answer varies by resolver, TTL and diff --git a/src/mxc-sdk/src/backends/wslc/common/image.rs b/src/mxc-sdk/src/backends/wslc/common/image.rs index 688a20a73..653bb4880 100644 --- a/src/mxc-sdk/src/backends/wslc/common/image.rs +++ b/src/mxc-sdk/src/backends/wslc/common/image.rs @@ -398,7 +398,7 @@ fn pull_failure( retry once it is available. Otherwise set wslc.imageTarPath to a local tar, \ or warm this cache from a machine that can reach the registry with: \ wxc-exec.exe --setup-wslc --image {}{}. \ - See docs/wsl/wsl-container-getting-started.md.", + See docs/backends/wslc/wsl-container-getting-started.md.", image, detail, image, @@ -719,7 +719,7 @@ pub unsafe fn begin_resolve( container exists and outside the policy the request declares. Warm the \ cache first with wxc-exec.exe --setup-wslc --image {}{}, set \ wslc.imageTarPath to a local tar, or allow egress. \ - See docs/wsl/wsl-container-getting-started.md.", + See docs/backends/wslc/wsl-container-getting-started.md.", image, image, storage_arg(storage_path), diff --git a/src/mxc-sdk/src/backends/wslc/common/registry_policy.rs b/src/mxc-sdk/src/backends/wslc/common/registry_policy.rs index 379c4a2ad..fd16855bc 100644 --- a/src/mxc-sdk/src/backends/wslc/common/registry_policy.rs +++ b/src/mxc-sdk/src/backends/wslc/common/registry_policy.rs @@ -247,7 +247,7 @@ mod platform { assert!( !upper.starts_with(blocked), "{POLICY_SUBKEY} is under {blocked}, which no MDM can deploy; see \ - docs/wsl/wslc-registry-allowlist-policy.md" + docs/backends/wslc/wslc-registry-allowlist-policy.md" ); } } diff --git a/src/mxc-sdk/src/core/mxc_common/network_parser_ingress_default_tests.rs b/src/mxc-sdk/src/core/mxc_common/network_parser_ingress_default_tests.rs index 574c7676a..12bf6dcf4 100644 --- a/src/mxc-sdk/src/core/mxc_common/network_parser_ingress_default_tests.rs +++ b/src/mxc-sdk/src/core/mxc_common/network_parser_ingress_default_tests.rs @@ -3,8 +3,8 @@ //! Tests the resolved value of an omitted `network.ingress.hostLoopback`. //! -//! Contract source: `docs/sandbox-policy/0.8.0/networking/networking.md` -//! ("Host Loopback and Inbound Policy") and `docs/sandbox-policy/0.8.0/policy.md`: +//! Contract source: `docs/containment-configuration/0.8.0/networking/networking.md` +//! ("Host Loopback and Inbound Policy") and `docs/containment-configuration/0.8.0/policy.md`: //! both ingress controls default to `deny`, and `hostLoopback` resolves //! independently of `ingress.default` rather than inheriting it. //! diff --git a/src/mxc-sdk/src/core/mxc_common/telemetry/consent.rs b/src/mxc-sdk/src/core/mxc_common/telemetry/consent.rs index a5c7b6f88..6833e83e8 100644 --- a/src/mxc-sdk/src/core/mxc_common/telemetry/consent.rs +++ b/src/mxc-sdk/src/core/mxc_common/telemetry/consent.rs @@ -3,7 +3,7 @@ //! Persisted, per-user telemetry consent. //! -//! See `docs/telemetry/telemetry-consent-design.md` for the full design and +//! See `docs/development/architecture/telemetry-consent-design.md` for the full design and //! privacy rationale. In short: //! //! - MXC does not and must not collect telemetry on any platform other than @@ -803,7 +803,7 @@ mod platform { /// Per-user (not `%ProgramData%`) because consent is a personal choice β€” /// multiple people sharing one machine each control their own, with no /// elevation required to change it (mirrors `wxc-exec.exe` never - /// self-elevating; see `docs/host-prep.md`). + /// self-elevating; see `docs/backends/process-container/host-prep.md`). fn consent_file_path() -> Option { local_app_data_dir().map(|dir| dir.join("mxc").join("telemetry-consent.json")) } diff --git a/src/mxc-sdk/src/core/mxc_common/telemetry/policy.rs b/src/mxc-sdk/src/core/mxc_common/telemetry/policy.rs index e6ebe32bc..60f061e8f 100644 --- a/src/mxc-sdk/src/core/mxc_common/telemetry/policy.rs +++ b/src/mxc-sdk/src/core/mxc_common/telemetry/policy.rs @@ -3,8 +3,8 @@ //! Administrative (MDM / Group Policy) telemetry policy. //! -//! See `docs/telemetry/telemetry-administrative-policy.md` for the admin-facing reference and -//! `docs/telemetry/telemetry-consent-design.md` for how this composes with +//! See `docs/telemetry.md` for the admin-facing reference and +//! `docs/development/architecture/telemetry-consent-design.md` for how this composes with //! user consent. In short: //! //! - An administrator (via Intune, another MDM, or Group Policy) may **deny** @@ -144,7 +144,7 @@ mod platform { /// Microsoft's own ADMX-ingestion documentation uses for third-party apps. /// /// This is the administrator-facing contract documented in - /// `docs/telemetry/telemetry-administrative-policy.md`; changing it breaks deployed + /// `docs/telemetry.md`; changing it breaks deployed /// policy. const POLICY_SUBKEY: &str = r"SOFTWARE\Policies\Mxc"; const POLICY_VALUE_NAME: &str = "AllowTelemetry"; @@ -384,7 +384,7 @@ mod platform { !upper.starts_with(blocked), "policy key {POLICY_SUBKEY:?} sits under {blocked:?}, which Windows \ forbids ADMX-ingested policies from writing; see \ - docs/telemetry/telemetry-administrative-policy.md" + docs/telemetry.md" ); } } diff --git a/src/mxc-sdk/src/core/plm/elevated.rs b/src/mxc-sdk/src/core/plm/elevated.rs index e617fd976..d1c0ef10e 100644 --- a/src/mxc-sdk/src/core/plm/elevated.rs +++ b/src/mxc-sdk/src/core/plm/elevated.rs @@ -1941,7 +1941,7 @@ fn recovery_required_error( "{reason}; recovery marker: {}; refusing to stop or cancel unverified host-wide WPR \ state. From an elevated terminal, inspect the recording, preserve or discard it, \ confirm WPR is inactive, and only then delete the marker. See \"Recovering guarded-WPR \ - state\" in docs/diagnostics.md", + state\" in docs/development/guides/diagnostics.md", marker_path.display() )) } @@ -2846,7 +2846,7 @@ mod tests { assert!(message.contains("inspect the recording")); assert!(message.contains("confirm WPR is inactive")); assert!(message.contains("only then delete the marker")); - assert!(message.contains("docs/diagnostics.md")); + assert!(message.contains("docs/development/guides/diagnostics.md")); assert!(message.contains("wpr start diagnostic")); } diff --git a/src/mxc-sdk/src/policy.rs b/src/mxc-sdk/src/policy.rs index b10f81382..a9655edc3 100644 --- a/src/mxc-sdk/src/policy.rs +++ b/src/mxc-sdk/src/policy.rs @@ -1648,7 +1648,7 @@ mod tests { // The shared parser owns the wire contract and its `captureDenials` branch // is not Windows-gated, so drive it directly to pin the combination on // every platform. The only documented mutual exclusion is with the - // `--audit` CLI flag (docs/learning-mode/capabilities.md), which + // `--audit` CLI flag (docs/logging-access-denied.md), which // `wxc-exec` enforces in `validate_audit_request`. #[test] fn wire_contract_accepts_capture_denials_together_with_a_network_proxy() { diff --git a/src/mxc-sdk/src/telemetry.rs b/src/mxc-sdk/src/telemetry.rs index 821618ea3..df900d7dc 100644 --- a/src/mxc-sdk/src/telemetry.rs +++ b/src/mxc-sdk/src/telemetry.rs @@ -5,7 +5,7 @@ //! //! A host supplies presentation for the canonical consent resource; the SDK //! persists the typed decision. See -//! `docs/telemetry/telemetry-consent-design.md`. +//! `docs/development/architecture/telemetry-consent-design.md`. //! //! ```no_run //! use std::error::Error; diff --git a/src/mxc-sdk/tests/sandbox.rs b/src/mxc-sdk/tests/sandbox.rs index 74ea51cc7..f69720766 100644 --- a/src/mxc-sdk/tests/sandbox.rs +++ b/src/mxc-sdk/tests/sandbox.rs @@ -216,13 +216,13 @@ fn seatbelt_defaults_cwd_to_allowed_path_without_getcwd_leak() { // AppContainer by host capability; these guards hold for whichever backend the // host selects. // They run a real sandbox, so they require an elevated, host-prepped Windows -// host (see docs/host-prep.md) and are therefore `#[ignore]`d β€” run them with +// host (see docs/backends/process-container/host-prep.md) and are therefore `#[ignore]`d β€” run them with // `cargo test -p mxc-sdk -- --ignored` on such a host. // --------------------------------------------------------------------------- #[cfg(target_os = "windows")] #[test] -#[ignore = "requires an elevated, host-prepped Windows host (see docs/host-prep.md)"] +#[ignore = "requires an elevated, host-prepped Windows host (see docs/backends/process-container/host-prep.md)"] fn process_container_captures_stdout() { // Regression guard: a valid exit code and captured stdout prove the // process handle was not closed out from under the wait. @@ -241,7 +241,7 @@ fn process_container_captures_stdout() { #[cfg(target_os = "windows")] #[test] -#[ignore = "requires an elevated, host-prepped Windows host (see docs/host-prep.md)"] +#[ignore = "requires an elevated, host-prepped Windows host (see docs/backends/process-container/host-prep.md)"] fn process_container_finite_timeout_fires() { // Regression guard: a finite timeout must fire even when the command // spawns a descendant that keeps the inherited stdout write-end open. If @@ -290,7 +290,7 @@ fn run_reports_timeout_seatbelt() { #[cfg(target_os = "windows")] #[test] -#[ignore = "requires an elevated, host-prepped Windows host (see docs/host-prep.md)"] +#[ignore = "requires an elevated, host-prepped Windows host (see docs/backends/process-container/host-prep.md)"] fn run_captures_stdout_process_container() { // `run` spawns, waits, and returns captured stdout/stderr in one call. let output = mxc_sdk::v1::run( diff --git a/src/mxc-sdk/tests/streaming_processcontainer.rs b/src/mxc-sdk/tests/streaming_processcontainer.rs index 8a2ecbe2b..0928aafff 100644 --- a/src/mxc-sdk/tests/streaming_processcontainer.rs +++ b/src/mxc-sdk/tests/streaming_processcontainer.rs @@ -4,7 +4,7 @@ //! Windows ProcessContainer streaming integration test, in its own //! Windows-gated file. The sibling `streaming.rs` is `#![cfg(macos)]`, which //! would otherwise make a `#[cfg(windows)]` test there impossible to compile. -//! Requires an elevated, host-prepped Windows host (see docs/host-prep.md), so +//! Requires an elevated, host-prepped Windows host (see docs/backends/process-container/host-prep.md), so //! it is `#[ignore]`d. #![cfg(target_os = "windows")] @@ -14,7 +14,7 @@ use mxc_sdk::v1::WaitResult; use mxc_sdk::v1::{spawn, ContainerRequest, Containment, FilesystemPolicy}; #[test] -#[ignore = "requires an elevated, host-prepped Windows host (see docs/host-prep.md)"] +#[ignore = "requires an elevated, host-prepped Windows host (see docs/backends/process-container/host-prep.md)"] fn streaming_processcontainer_bidirectional_stdio() { use std::io::{Read, Write}; diff --git a/src/mxc-sdk/tests/support/wxc_e2e_tests.rs b/src/mxc-sdk/tests/support/wxc_e2e_tests.rs index 2d5824097..7f81f3aab 100644 --- a/src/mxc-sdk/tests/support/wxc_e2e_tests.rs +++ b/src/mxc-sdk/tests/support/wxc_e2e_tests.rs @@ -702,7 +702,7 @@ pub fn has_bwrap() -> bool { /// Opt-in switch for the Windows ProcessContainer characterization tests. /// /// AppContainer/BaseContainer execution requires an elevated, host-prepped -/// Windows host (see `docs/host-prep.md`). Standard CI runners are NOT capable, +/// Windows host (see `docs/backends/process-container/host-prep.md`). Standard CI runners are NOT capable, /// so these tests are skipped unless a host-prepped lane explicitly sets /// `MXC_E2E_HOST_PREPPED=1`. This keeps them from ever red-failing on incapable /// CI while still being runnable on a prepared box. diff --git a/src/mxc-sdk/tests/wxc_e2e_tests_e2e_processcontainer_characterization.rs b/src/mxc-sdk/tests/wxc_e2e_tests_e2e_processcontainer_characterization.rs index a2da25eea..e9678182f 100644 --- a/src/mxc-sdk/tests/wxc_e2e_tests_e2e_processcontainer_characterization.rs +++ b/src/mxc-sdk/tests/wxc_e2e_tests_e2e_processcontainer_characterization.rs @@ -9,7 +9,7 @@ //! lands. They assert what the code does **today**. //! //! ProcessContainer execution requires an elevated, host-prepped Windows host -//! (see `docs/host-prep.md`). Standard CI runners are **not** capable, so these +//! (see `docs/backends/process-container/host-prep.md`). Standard CI runners are **not** capable, so these //! tests skip unless a prepared lane sets `MXC_E2E_HOST_PREPPED=1` //! (`host_prepped_optin()`), and additionally skip if `wxc-exec.exe` has not //! been built or the host is missing process prerequisites. They therefore diff --git a/src/testing/fuzz/README.md b/src/testing/fuzz/README.md index ce03f7748..8bb5d3d38 100644 --- a/src/testing/fuzz/README.md +++ b/src/testing/fuzz/README.md @@ -4,7 +4,7 @@ cargo-fuzz harnesses for the MXC config-parsing surface. Continuous fuzzing runs daily under [OneFuzz](https://aka.ms/onefuzz) on Windows x64 with -AddressSanitizer. See [`docs/fuzzing.md`](../../docs/fuzzing.md) for the +AddressSanitizer. See [fuzzing](../../../docs/development/build-and-test/fuzzing.md) for the full reference. ## Targets diff --git a/tests/examples/33_mac_local_dev_server.json b/tests/examples/33_mac_local_dev_server.json index ea7e9329c..0daf95704 100644 --- a/tests/examples/33_mac_local_dev_server.json +++ b/tests/examples/33_mac_local_dev_server.json @@ -4,7 +4,7 @@ "version": "1.0.0", "containment": "seatbelt", "process": { - "commandLine": "echo 'Local dev server access over loopback'; echo '============================================================'; echo ''; echo 'hostLoopback defaults to deny. Without the explicit ingress block below,'; echo 'this sandbox would reach the internet but NOT its own localhost.'; echo ''; rc=0; PORT=8931; python3 -m http.server $PORT --bind 127.0.0.1 > /dev/null 2>&1 & SRV=$!; sleep 2; echo \"Test 1: Serving on 127.0.0.1:$PORT and fetching it back...\"; if curl -s --max-time 5 --noproxy '*' http://127.0.0.1:$PORT/ > /dev/null 2>&1; then echo ' SUCCESS: loopback reachable'; else echo ' ERROR: loopback unreachable (this is what hostLoopback=deny looks like)'; rc=1; fi; kill $SRV 2>/dev/null; wait $SRV 2>/dev/null; echo ''; echo 'Test 2: Reaching the public internet (denied -- egress.default is deny)...'; if curl -s --max-time 5 --noproxy '*' https://example.com > /dev/null 2>&1; then echo ' ERROR: Should not have connected!'; rc=1; else echo ' SUCCESS: outbound blocked'; fi; echo ''; echo 'Note: allowing loopback also allows unscoped inbound -- Seatbelt cannot'; echo 'accept loopback while refusing LAN. See docs/seatbelt/seatbelt-backend.md.'; echo ''; echo '============================================================'; if [ $rc -eq 0 ]; then echo 'Local dev server test complete!'; else echo 'Local dev server test FAILED'; fi; exit $rc", + "commandLine": "echo 'Local dev server access over loopback'; echo '============================================================'; echo ''; echo 'hostLoopback defaults to deny. Without the explicit ingress block below,'; echo 'this sandbox would reach the internet but NOT its own localhost.'; echo ''; rc=0; PORT=8931; python3 -m http.server $PORT --bind 127.0.0.1 > /dev/null 2>&1 & SRV=$!; sleep 2; echo \"Test 1: Serving on 127.0.0.1:$PORT and fetching it back...\"; if curl -s --max-time 5 --noproxy '*' http://127.0.0.1:$PORT/ > /dev/null 2>&1; then echo ' SUCCESS: loopback reachable'; else echo ' ERROR: loopback unreachable (this is what hostLoopback=deny looks like)'; rc=1; fi; kill $SRV 2>/dev/null; wait $SRV 2>/dev/null; echo ''; echo 'Test 2: Reaching the public internet (denied -- egress.default is deny)...'; if curl -s --max-time 5 --noproxy '*' https://example.com > /dev/null 2>&1; then echo ' ERROR: Should not have connected!'; rc=1; else echo ' SUCCESS: outbound blocked'; fi; echo ''; echo 'Note: allowing loopback also allows unscoped inbound -- Seatbelt cannot'; echo 'accept loopback while refusing LAN. See docs/backends/seatbelt/seatbelt-backend.md.'; echo ''; echo '============================================================'; if [ $rc -eq 0 ]; then echo 'Local dev server test complete!'; else echo 'Local dev server test FAILED'; fi; exit $rc", "cwd": "/tmp", "timeout": 30000 }, diff --git a/docs/playground-limitations.md b/tests/playground/playground-limitations.md similarity index 98% rename from docs/playground-limitations.md rename to tests/playground/playground-limitations.md index 975ca3ef7..2a5e5a728 100644 --- a/docs/playground-limitations.md +++ b/tests/playground/playground-limitations.md @@ -4,7 +4,7 @@ > For a per-release policy-support matrix (filesystem, network, and UI > restrictions across Windows 11 23H2 / 24H2 / 25H2 / 25H2+), see -> [Windows OS-version policy support](./process-container/os-version-support.md). +> [Windows OS-version policy support](../../docs/backends/process-container/os-version-support.md). ## Platform Support diff --git a/tests/scripts/lib/WinProcessContainer.Common.ps1 b/tests/scripts/lib/WinProcessContainer.Common.ps1 index 497eacca2..151a426b7 100644 --- a/tests/scripts/lib/WinProcessContainer.Common.ps1 +++ b/tests/scripts/lib/WinProcessContainer.Common.ps1 @@ -801,7 +801,7 @@ function Assert-RequiredTier { # Network test infrastructure -# Documented in docs/process-container/networking.md Β§2: PSEC is the only +# Documented in docs/backends/process-container/networking.md Β§2: PSEC is the only # ProcessContainer path that receives directional egress filters, proxy peer # identity, or host-loopback configuration. The probe does not name the # process-creation contract, so the tier stands in for it β€” `base-container` @@ -1068,8 +1068,8 @@ function Get-LoopbackFetchCommand { # Phase 8 β€” directional network policy. # -# Asserts the documented contract (docs/process-container/networking.md and -# docs/sandbox-policy/0.8.0/networking/networking.md), not the current code, so +# Asserts the documented contract (docs/backends/process-container/networking.md and +# docs/containment-configuration/0.8.0/networking/networking.md), not the current code, so # an assertion that outruns the backend fails by design. Every positive is # paired with a negative control on an otherwise identical config: from one run # on a host with no connectivity, "reached it" and "blocked by policy" look the diff --git a/tests/scripts/run_lxc_network_no_network_test.sh b/tests/scripts/run_lxc_network_no_network_test.sh index 05f92fd0b..1a1dd6f09 100644 --- a/tests/scripts/run_lxc_network_no_network_test.sh +++ b/tests/scripts/run_lxc_network_no_network_test.sh @@ -3,7 +3,7 @@ # # Proves that a request with the `network` section omitted entirely receives # the directional deny defaults stated in the contract: the workload cannot reach -# the network. The contract is docs/sandbox-policy/0.8.0/policy.md: "A schema +# the network. The contract is docs/containment-configuration/0.8.0/policy.md: "A schema # 0.8 policy with no network fields selects directional deny defaults." # # The first run is the positive control. It sends the same workload and probe @@ -112,7 +112,7 @@ run_config "positive control: request with explicit egress allow to $PROBE_ADDRE assert_allowed "an explicitly allowed destination was unreachable on the positive control. The second run's blocked result would prove nothing, so this test fails rather than proceeding." run_config "case under test: request with network section omitted entirely" "$OMIT_CONFIG" -assert_blocked "the workload reached $PROBE_ADDRESS under a request with no network section. The contract (docs/sandbox-policy/0.8.0/policy.md) states that omitted permissions remain denied and a 0.8 policy with no network fields selects directional deny defaults." +assert_blocked "the workload reached $PROBE_ADDRESS under a request with no network section. The contract (docs/containment-configuration/0.8.0/policy.md) states that omitted permissions remain denied and a 0.8 policy with no network fields selects directional deny defaults." echo "PASS: a request with the network section omitted cannot reach the network." echo "LXC omitted-network-section test complete." diff --git a/tests/scripts/run_processcontainer_all_tests.ps1 b/tests/scripts/run_processcontainer_all_tests.ps1 index 148555583..846c81943 100644 --- a/tests/scripts/run_processcontainer_all_tests.ps1 +++ b/tests/scripts/run_processcontainer_all_tests.ps1 @@ -13,7 +13,7 @@ # # Generated positive configs target published stable 1.0.0. Raw rejection # cases select their exact version. Network areas assert the supported -# directional contract (docs/process-container/networking.md); unsupported +# directional contract (docs/backends/process-container/networking.md); unsupported # policy fails. # # Prerequisites fail, they do not skip: a -RequireTier mismatch, an unreachable diff --git a/tests/scripts/run_processcontainer_network_capability_test.ps1 b/tests/scripts/run_processcontainer_network_capability_test.ps1 index 71675f591..f71126a22 100644 --- a/tests/scripts/run_processcontainer_network_capability_test.ps1 +++ b/tests/scripts/run_processcontainer_network_capability_test.ps1 @@ -24,7 +24,7 @@ Initialize-WpcContext @PSBoundParameters # Phase 8a β€” the documented egress x ingress capability matrix. -# docs/process-container/networking.md Β§1 gives the mapping. The deny/allow +# docs/backends/process-container/networking.md Β§1 gives the mapping. The deny/allow # row is the one combination the doc says a non-PSEC tier must REFUSE rather # than approximate: privateNetworkClientServer is bidirectional, so accepting # it there would grant inbound access the caller never asked for. diff --git a/tests/scripts/run_processcontainer_network_egress_test.ps1 b/tests/scripts/run_processcontainer_network_egress_test.ps1 index cab235f79..f878ede6e 100644 --- a/tests/scripts/run_processcontainer_network_egress_test.ps1 +++ b/tests/scripts/run_processcontainer_network_egress_test.ps1 @@ -25,7 +25,7 @@ Initialize-WpcContext @PSBoundParameters # Phase 8c β€” explicit WFP egress rules (PSEC only). # -# From docs/process-container/networking.md Β§3 and the shared spec's D4: a +# From docs/backends/process-container/networking.md Β§3 and the shared spec's D4: a # CIDR/port allow permits that destination and still blocks everything else, # and an explicit deny beats an overlapping allow. Off PSEC the documented # behavior is a typed rejection β€” a silently dropped rule set would leave the @@ -149,4 +149,3 @@ function Phase-NetworkEgressRules { Invoke-WpcPhase -Key 'NetworkEgressRules' -Body { Phase-NetworkEgressRules } Complete-WpcChild - diff --git a/tests/scripts/run_processcontainer_network_model3_test.ps1 b/tests/scripts/run_processcontainer_network_model3_test.ps1 index 9358c0c33..9c60e8b2e 100644 --- a/tests/scripts/run_processcontainer_network_model3_test.ps1 +++ b/tests/scripts/run_processcontainer_network_model3_test.ps1 @@ -25,7 +25,7 @@ Initialize-WpcContext @PSBoundParameters # Phase 8b β€” model 3 has three spellings and they must be identical. # -# docs/process-container/networking.md Β§Model 3 states that an explicit +# docs/backends/process-container/networking.md Β§Model 3 states that an explicit # deny-everything block, an omitted `network` key, and `"network": {}` are # equivalent. This is exactly the kind of property that rots silently: a # parser change that makes an absent section mean "inherit" rather than @@ -68,4 +68,3 @@ function Phase-NetworkModel3Equivalence { Invoke-WpcPhase -Key 'NetworkModel3Equivalence' -Body { Phase-NetworkModel3Equivalence } Complete-WpcChild - diff --git a/tests/scripts/run_processcontainer_network_proxy_test.ps1 b/tests/scripts/run_processcontainer_network_proxy_test.ps1 index 74fa0c9cf..2ea433c52 100644 --- a/tests/scripts/run_processcontainer_network_proxy_test.ps1 +++ b/tests/scripts/run_processcontainer_network_proxy_test.ps1 @@ -25,7 +25,7 @@ Initialize-WpcContext @PSBoundParameters # Phase 8e β€” runtime proxy (model 2). # -# Per docs/process-container/networking.md: HTTP(S)_PROXY (both cases) point +# Per docs/backends/process-container/networking.md: HTTP(S)_PROXY (both cases) point # at the loopback endpoint, NO_PROXY must not carry it, direct egress is # blocked, egress rules do not apply, identity-less proxy requires # hostLoopback allow, and no fallback to an AppContainer tier. @@ -219,4 +219,3 @@ function Invoke-NetworkProxyAssertions { Invoke-WpcPhase -Key 'NetworkProxy' -Body { Phase-NetworkProxy } Complete-WpcChild - diff --git a/tests/scripts/run_processcontainer_ui_mitigations_test.ps1 b/tests/scripts/run_processcontainer_ui_mitigations_test.ps1 index 0d0323eb6..cd075d655 100644 --- a/tests/scripts/run_processcontainer_ui_mitigations_test.ps1 +++ b/tests/scripts/run_processcontainer_ui_mitigations_test.ps1 @@ -1,7 +1,7 @@ # Copyright (c) Microsoft Corporation. # Licensed under the MIT License. # -# JOB_OBJECT_UILIMIT_* mitigation matrix (docs/process-container/UIPolicy_Schema.md). +# JOB_OBJECT_UILIMIT_* mitigation matrix (docs/backends/process-container/UIPolicy_Schema.md). # # Runs standalone, or under run_processcontainer_all_tests.ps1. diff --git a/tests/scripts/run_processcontainer_ui_policy_matrix_test.ps1 b/tests/scripts/run_processcontainer_ui_policy_matrix_test.ps1 index f475ff509..59ba3fdac 100644 --- a/tests/scripts/run_processcontainer_ui_policy_matrix_test.ps1 +++ b/tests/scripts/run_processcontainer_ui_policy_matrix_test.ps1 @@ -16,7 +16,7 @@ # only decidable where the host can actually perform the operation: a permissive # knob omits the matching UILIMIT bit, it does not grant the capability, and the # rest of the process-container security environment may still deny it -# (docs/process-container/UIPolicy_Schema.md). Measure-UiGrantable establishes +# (docs/backends/process-container/UIPolicy_Schema.md). Measure-UiGrantable establishes # which capabilities are reachable at all, and the cases below skip the allow # direction for the rest. # diff --git a/tests/scripts/run_seatbelt_rejections_test.sh b/tests/scripts/run_seatbelt_rejections_test.sh index 110d24210..c22951b7d 100755 --- a/tests/scripts/run_seatbelt_rejections_test.sh +++ b/tests/scripts/run_seatbelt_rejections_test.sh @@ -2,7 +2,7 @@ # Seatbelt policy rejections. # # Every case here is a config MXC must refuse rather than approximate, per the -# "What gets rejected" table in docs/seatbelt/seatbelt-backend.md. Each asserts +# "What gets rejected" table in docs/backends/seatbelt/seatbelt-backend.md. Each asserts # both that the run failed and that the workload never started: a policy that # is "enforced" by the command failing afterwards is not enforcement. #