feat(policy): authorize workspace hosts in sandbox policy (#80)

* feat(policy): authorize workspace hosts in sandbox policy

Reads network.hosts from workspace.json and emits a single
'workspace' NetworkPolicyRule in the baked policy.yaml. Each
host becomes an endpoint; all four PATH glob paths
(/bin/**, /usr/bin/**, /usr/local/bin/**, /sandbox/.local/bin/**)
plus the agent binary (when present) are authorized as binaries.

Closes #75

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Signed-off-by: Philippe Martin <phmartin@redhat.com>

* fix(policy): fail fast on malformed workspace host entries

parse_workspace_host and workspace_hosts_policy now return
Result and propagate URL parse errors instead of silently
falling back to (original_input, 443), which would emit
invalid endpoint hosts into the sandbox policy.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Signed-off-by: Philippe Martin <phmartin@redhat.com>

* chore(docs): document workspace network rules feature

Adds 'workspace network rules' to the intro feature list and
the sandbox policy layer breakdown, and adds a new dedicated
section explaining network.hosts in workspace.json, the
authorised binary globs, error behaviour, and a worked example
for Rust/crates.io access.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Signed-off-by: Philippe Martin <phmartin@redhat.com>

* chore(docs): update sandbox-policy skill for workspace network layer

Reflects the fourth policy merge layer: description, merge code
snippet, merge order note, rules table, and build_policy() test
example all updated to include the workspace hosts fragment.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Signed-off-by: Philippe Martin <phmartin@redhat.com>

---------

Signed-off-by: Philippe Martin <phmartin@redhat.com>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: feloy

.agents/skills/sandbox-policy/SKILL.md

@@ -11,11 +11,12 @@ How the sandbox policy is assembled, what each section means, and how to add or
 
 Every built image contains `/etc/openshell/policy.yaml`. The openshell runtime reads it at startup to configure filesystem access, the user the agent runs as, and which network endpoints each binary is allowed to reach.
 
-The final policy is assembled by `build_policy()` in `src/main.rs` by merging three sources:
+The final policy is assembled by `build_policy()` in `src/main.rs` by merging four sources:
 
 1. **Base policy** — `assets/policy.yaml`, committed to the repo. Contains filesystem and process config, plus baseline network rules shared by all images (git, gh CLI).
 2. **Inference fragment** — returned by `Inference::policy_yaml(agent_binary, base_url)`. Adds network rules for the LLM backend. Only included when both `--agent` and `--inference` are given (the method needs the agent binary path to scope the rule).
 3. **Agent fragment** — returned by `Agent::policy_yaml()`. Adds agent-specific network rules (e.g., Claude needs `platform.claude.com` for telemetry). Only included if the string is non-empty.
+4. **Workspace fragment** — constructed from `workspace.network.hosts` in `.kaiden/workspace.json`. Adds a single `workspace` rule whose endpoints are the user-declared hosts and whose binaries are the four PATH globs (`/bin/**`, `/usr/bin/**`, `/usr/local/bin/**`, `/sandbox/.local/bin/**`) plus the agent binary when present. Only included when `network.hosts` is non-empty. An invalid host entry causes the build to fail immediately.
 
 ## YAML schema
 
@@ -97,11 +98,23 @@ if let Some(agent) = agent {
         sandbox_policy.network_policies.extend(fragment.network_policies);
     }
 }
+
+if let Some(hosts) = workspace
+    .and_then(|ws| ws.network.as_ref())
+    .map(|net| net.hosts.as_slice())
+    .filter(|h| !h.is_empty())
+{
+    let agent_binary = agent.map(|a| a.binary_path());
+    sandbox_policy.network_policies.insert(
+        "workspace".to_string(),
+        workspace_hosts_policy(hosts, agent_binary)?,
+    );
+}
 ```
 
 `network_policies` is a `BTreeMap<String, NetworkPolicyRule>`. The BTreeMap key is the merge slug (e.g. `"anthropic"`, `"claude_code"`). `extend()` means: if a fragment uses a slug that already exists in the base, the base entry is silently replaced. The `name` field inside the rule is separate — it is what the runtime displays, and should match the slug by convention.
 
-**Merge order**: base → inference → agent. An agent rule can therefore override a base or inference rule with the same slug.
+**Merge order**: base → inference → agent → workspace. A workspace rule uses `insert()`, so it can override any earlier rule with the slug `"workspace"` (none exists in base or the other fragments).
 
 ## Existing network rules
 
@@ -113,6 +126,7 @@ if let Some(agent) = agent {
 | `vertexai` | VertexAiInference | `oauth2.googleapis.com:443`, `aiplatform.googleapis.com:443`, `*-aiplatform.googleapis.com:443` | agent binary |
 | `ollama` | OllamaInference | `host.openshell.internal:11434` (or custom host:port) | agent binary |
 | `claude_code` | ClaudeAgent | `raw.githubusercontent.com:443`, `platform.claude.com:443`, `api.github.com:443` (read-only) | `/sandbox/.local/bin/claude` |
+| `workspace` | `workspace.network.hosts` | all user-declared hosts (port defaults to 443) | `/bin/**`, `/usr/bin/**`, `/usr/local/bin/**`, `/sandbox/.local/bin/**`, agent binary |
 
 ## Where to make changes
 
@@ -206,6 +220,7 @@ fn build_policy_with_myprovider_inference_includes_expected_host() {
         Some(&agent::ClaudeAgent),
         Some(&inference::MyProviderInference),
         None,
+        None,
     ).unwrap();
     assert!(yaml.contains("api.myprovider.com"));
 }

.kaiden/workspace.json

@@ -2,5 +2,12 @@
   "features": {
     "ghcr.io/devcontainers/features/rust:1": {},
     "./features/cargo-llvm-cov": {}
+  },
+  "network": {
+    "hosts": [
+      "index.crates.io",
+      "static.crates.io",
+      "static.rust-lang.org"
+    ]
   }
 }

README.md

@@ -19,8 +19,25 @@ The tool assembles the image in layers — base image, agent installation, agent
    - **Base policy** — Git operations over HTTPS and the GitHub REST API.
    - **Agent network rules** — agent-specific endpoints are added by `--agent`.
    - **Inference network rules** — LLM backend endpoints are added by `--inference`.
+   - **Workspace network rules** — user-defined hosts declared in `.kaiden/workspace.json` are added to the policy.
 5. **Installation of project-specific toolchains** — toolchains and utilities declared as Dev Container Features in `.kaiden/workspace.json` are installed in the image.
 
+### workspace.json fields
+
+`.kaiden/workspace.json` is the per-workspace configuration file. The following fields are supported:
+
+| Field | Description | Details |
+| ----- | ----------- | ------- |
+| `features` | Dev Container Features to install in the image | [Dev Container Features](#dev-container-features) |
+| `skills` | Skill directories to copy into the agent's skills directory | [Skills](#skills) |
+| `network.hosts` | Hostnames (and optional ports) to allow through the sandbox network policy | [Workspace network rules](#workspace-network-rules) |
+| ~~`network.mode`~~ | ~~`allow` or `deny` — OpenShell always enforces deny mode; allow-all is not supported~~ | ~~not used by the image builder~~ |
+| ~~`environment`~~ | ~~Environment variables to inject into the workspace~~ | ~~not used by the image builder~~ |
+| ~~`mcp`~~ | ~~MCP server configuration (command-based and URL-based servers)~~ | ~~not used by the image builder~~ |
+| ~~`mounts`~~ | ~~Host directories to mount in the workspace~~ | ~~not used by the image builder~~ |
+| ~~`ports`~~ | ~~TCP ports to expose from the workspace~~ | ~~not used by the image builder~~ |
+| ~~`secrets`~~ | ~~Secret names to inject into the workspace~~ | ~~not used by the image builder~~ |
+
 ### Agent Supported Features
 
 | Agent      | User settings | Auto-onboarding | Skills |
@@ -320,11 +337,12 @@ Every image built by this tool includes `/etc/openshell/policy.yaml`. This file
 - **Filesystem policy** — which paths are read-only, read-write, or inaccessible to the `sandbox` user.
 - **Network policies** — which binaries are allowed to connect to which hosts and ports.
 
-The policy is built in three layers, merged in order:
+The policy is built in four layers, merged in order:
 
 1. **Base** ([`assets/policy.yaml`](assets/policy.yaml)) — general-purpose tooling: Git operations over HTTPS and the GitHub REST API via `gh`.
 2. **Inference** (added by `--inference`) — LLM backend endpoints scoped to the agent binary. For example, `--inference anthropic` adds `api.anthropic.com` and `statsig.anthropic.com`; `--inference vertexai` adds `oauth2.googleapis.com` and `aiplatform.googleapis.com` (including the `*-aiplatform.googleapis.com` wildcard); `--inference ollama` adds `host.openshell.internal:11434` for local model access; `--inference openai` adds `api.openai.com` (or the custom endpoint host when `--endpoint` is used).
 3. **Agent** (added by `--agent`) — agent-specific endpoints. For example, `--agent claude` adds `platform.claude.com`, `raw.githubusercontent.com`, and the GitHub REST API for Claude's coding tools; `--agent opencode` adds `opencode.ai`, `registry.npmjs.org`, and `models.dev`.
+4. **Workspace** (added from `network.hosts` in `.kaiden/workspace.json`) — user-defined hosts that any binary in standard PATH directories (`/bin`, `/usr/bin`, `/usr/local/bin`, `/sandbox/.local/bin`) and the agent binary (when present) may reach. See [Workspace network rules](#workspace-network-rules).
 
 ## Dev Container Features
 
@@ -417,6 +435,57 @@ When `.kaiden/workspace.json` is present, the tool:
 
 Features run as root so install scripts can write to system paths.
 
+## Workspace network rules
+
+The OpenShell sandbox enforces a **deny-by-default** network policy: all outbound connections are blocked unless explicitly listed in the policy. There is no supported way to allow all hosts — the sandbox does not implement an allow-all mode. The `network.mode` field in `workspace.json` (which some orchestrators read to switch between `deny` and `allow`) is ignored by the image builder; the policy is always assembled in deny mode with explicit allow-rules.
+
+Use the `network.hosts` field in `.kaiden/workspace.json` to allow additional hosts — for example, package registries or internal APIs that your project's toolchain needs to reach.
+
+```json
+{
+  "network": {
+    "hosts": [
+      "index.crates.io",
+      "static.crates.io",
+      "static.rust-lang.org"
+    ]
+  }
+}
+```
+
+Each entry is a hostname, optionally followed by a port (`host:port`). When no port is given, port 443 is used.
+
+The builder merges a single `workspace` network policy rule into `policy.yaml` that covers all listed hosts. The rule authorises the following binaries to connect to those hosts:
+
+| Binary glob | Covers |
+|---|---|
+| `/bin/**` | Core system utilities |
+| `/usr/bin/**` | Standard system binaries (e.g. `curl`) |
+| `/usr/local/bin/**` | Locally installed tools |
+| `/sandbox/.local/bin/**` | User-local binaries |
+| agent binary | The agent binary (e.g. `/sandbox/.local/bin/claude`) when `--agent` is used |
+
+An invalid or unparseable host entry (e.g. a bare space or malformed URL) causes the build to fail immediately with a descriptive error message.
+
+### Example — Rust project with crates.io access
+
+```json
+{
+  "features": {
+    "ghcr.io/devcontainers/features/rust:1": {}
+  },
+  "network": {
+    "hosts": [
+      "index.crates.io",
+      "static.crates.io",
+      "static.rust-lang.org"
+    ]
+  }
+}
+```
+
+With this configuration, `cargo build` and `cargo fetch` inside the sandbox can download crate metadata and source tarballs.
+
 ## Full option reference
 
 ```