diff --git a/docs/src/content/docs/introduction/architecture.mdx b/docs/src/content/docs/introduction/architecture.mdx index 106b4050f0c..8e745e6a9ce 100644 --- a/docs/src/content/docs/introduction/architecture.mdx +++ b/docs/src/content/docs/introduction/architecture.mdx @@ -1,6 +1,6 @@ --- title: Security Architecture -description: Comprehensive security architecture overview for GitHub Agentic Workflows, including defense-in-depth mechanisms against rogue MCP servers and malicious agents. +description: Security architecture for GitHub Agentic Workflows across hosted runners, ARC with Docker-in-Docker, gVisor, and Docker sbx microVM isolation. sidebar: order: 3 disable-agentic-editing: true @@ -33,7 +33,11 @@ We assume the adversary does not compromise the underlying hardware or cryptogra ### Layer 1: Substrate-Level Trust -AWs run on a GitHub Actions runner virtual machine (VM) and trust Actions' hardware and kernel-level enforcement mechanisms, including the CPU, MMU, kernel, and container runtime. AWs also rely on three privileged containers: (1) a network firewall that is trusted to configure connectivity for other components via `iptables` and launch the agent container, (2) an API proxy that routes model traffic and may hold endpoint-specific credentials or routing configuration for supported engines, and (3) an MCP Gateway that is trusted to configure and spawn isolated MCP-server containers. Collectively, the substrate level ensures memory isolation between components, CPU and resource isolation, mediation of privileged operations and system calls, and explicit, kernel-enforced communication boundaries. These guarantees hold even if an untrusted user-level component is fully compromised and executes arbitrary code. Trust violations at the substrate level require vulnerabilities in the firewall, MCP Gateway, container runtime, kernel, hypervisor, or hardware. If this layer fails, higher-level security guarantees may not hold. +AWs run on GitHub-hosted or Linux self-hosted GitHub Actions runners. Self-hosted deployments can include Actions Runner Controller (ARC) pods that use a privileged Docker-in-Docker (DinD) sidecar. The trusted substrate therefore includes the runner host or Kubernetes cluster, CPU, MMU, kernel, and container runtime. With ARC DinD, the runner container sends Docker API commands to the sidecar daemon, which creates the agent, proxy, and MCP containers and enforces their Docker network boundaries. + +The default agent runtime uses Docker container isolation. Compatible Linux runners can instead use gVisor's `runsc` user-space kernel, or Docker sbx to place the agent in a KVM-isolated microVM. These runtimes add isolation boundaries but do not remove trust in the runner host, firewall, MCP Gateway, container runtime, kernel, hypervisor, or hardware. + +AWs also rely on three trusted infrastructure components: (1) a network firewall that configures connectivity and launches the agent, (2) an API proxy that routes model traffic and may hold endpoint-specific credentials or routing configuration for supported engines, and (3) an MCP Gateway that configures and spawns isolated MCP-server containers. Collectively, the substrate level provides memory and resource isolation, mediation of privileged operations and system calls, and explicit communication boundaries. These guarantees hold even if an untrusted user-level component is fully compromised and executes arbitrary code. If this layer fails, higher-level security guarantees may not hold. --- @@ -79,7 +83,7 @@ flowchart TB end subgraph Isolation["🛡️ Isolation Layer"] - AWF["Agent Workflow Firewall
Network Egress Control"] + AWF["Agent Workflow Firewall
Docker, gVisor, or sbx Isolation"] PROXY["API Proxy
Agent auth-token isolation"] MCP["MCP Server Sandboxing
Container Isolation"] TOOL["Tool Allowlisting
Explicit Permissions"] @@ -175,6 +179,22 @@ Thus, AWF separates two concerns: - **Filesystem**: Controlled access to host binaries and runtimes via chroot - **Network**: All traffic routed through proxy enforcing the domain allowlist +### Runner Topologies and Agent Runtimes + +Runner topology determines where the Docker daemon and workspace live. Agent runtime determines the isolation boundary around the agent process. The supported combinations are: + +| Runner topology | Agent runtime | Security boundary | +| --- | --- | --- | +| GitHub-hosted or Linux self-hosted runner | Docker (default) | AWF launches the agent in a container on an internal Docker network whose only egress path is the Squid proxy. | +| ARC or another split-daemon DinD runner | Docker (default) | `runner.topology: arc-dind` stages the sysroot and workspace for the sidecar daemon. The privileged DinD sidecar creates the isolated network; the runner container remains unprivileged and does not need `NET_ADMIN`. | +| Compatible Linux runner | gVisor (`sandbox.agent.runtime: gvisor`) | The agent container runs under `runsc`, which interposes a user-space kernel between the agent and the host kernel. | +| KVM-capable Linux runner | Docker sbx (`sandbox.agent.runtime: docker-sbx`) | The agent runs inside a hardware-virtualized microVM while the firewall, API proxy, MCP Gateway, and MCP servers remain in host-side containers. | + +> [!IMPORTANT] +> gVisor and Docker sbx are incompatible with `runner.topology: arc-dind`. Installing gVisor invokes `sudo` to register `runsc`, but the agent remains in the default rootless AWF mode with `sandbox.agent.sudo: false`. Docker sbx requires `sandbox.agent.sudo: true`, KVM access, and the `DOCKER_USERNAME` and `DOCKER_PAT` secrets. The compiler rejects incompatible runtime, topology, sudo, and AWF-version combinations; generated Docker sbx workflows fail fast at run time when KVM access or required secrets are unavailable. + +ARC DinD preserves AWF's egress policy through Docker network topology rather than host `iptables`: the DinD daemon creates an internal network with no direct internet route and a dual-homed Squid proxy as the sole egress path. See [Self-Hosted Runners](/gh-aw/reference/self-hosted-runners/) and [How to run GitHub Copilot coding agent on ARC with Docker-in-Docker](/gh-aw/guides/arc-dind-copilot-agent/) for deployment details. + ```mermaid flowchart TB subgraph Agent["AI Agent Process"] @@ -783,9 +803,11 @@ gh aw status | Layer | Mechanism | Protection Against | |-------|-----------|-------------------| -| **Substrate** | GitHub Actions runner (VM, kernel, hypervisor) | Memory corruption, privilege escalation, host escape | -| **Substrate** | Docker container runtime | Process isolation bypass, shared state access | -| **Substrate** | AWF network controls (iptables) | Data exfiltration, unauthorized API calls | +| **Substrate** | GitHub-hosted, self-hosted, or ARC runner substrate | Memory corruption, privilege escalation, host escape | +| **Substrate** | Docker daemon on the runner or in an ARC DinD sidecar | Process isolation bypass, shared state access | +| **Substrate** | gVisor user-space kernel | Exposed host-kernel syscall surface | +| **Substrate** | Docker sbx KVM microVM | Agent-to-host kernel and memory access | +| **Substrate** | AWF Docker network and proxy controls | Data exfiltration, unauthorized API calls | | **Substrate** | MCP sandboxing (container isolation) | Container escape, unauthorized tool access | | **Configuration** | Schema validation, expression allowlist | Invalid configurations, unauthorized expressions | | **Configuration** | Action SHA pinning | Supply chain attacks, tag hijacking | @@ -804,6 +826,9 @@ gh aw status - [Integrity Filtering](/gh-aw/reference/integrity/) - Author-trust and merge-status content filtering - [Threat Detection Guide](/gh-aw/reference/threat-detection/) - Configuring threat analysis - [Network Permissions](/gh-aw/reference/network/) - Network access control +- [Self-Hosted Runners](/gh-aw/reference/self-hosted-runners/) - Runner selection, ARC DinD topology, and split-daemon configuration +- [ARC with Docker-in-Docker](/gh-aw/guides/arc-dind-copilot-agent/) - Kubernetes runner deployment +- [Sandbox Configuration](/gh-aw/reference/sandbox/) - Agent sandbox and runtime configuration - [Safe Outputs Reference](/gh-aw/reference/safe-outputs/) - Output processing configuration - [AI Engines](/gh-aw/reference/engines/) - Engine-specific security features - [Compilation Process](/gh-aw/reference/compilation-process/) - Build-time security validation