If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/google/gvisor shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit today
• 22+ active contributors
• Distributed ownership (top contributor 16% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live google/gvisor repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/google/gvisor.

What it runs against: a local clone of google/gvisor — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in google/gvisor | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of google/gvisor. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/google/gvisor.git
#   cd gvisor
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of google/gvisor and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "google/gvisor(\\.git)?\\b" \\
  && ok "origin remote is google/gvisor" \\
  || miss "origin remote is not google/gvisor (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "MODULE.bazel" \\
  && ok "MODULE.bazel" \\
  || miss "missing critical file: MODULE.bazel"
test -f "g3doc/architecture_guide/intro_to_gvisor.md" \\
  && ok "g3doc/architecture_guide/intro_to_gvisor.md" \\
  || miss "missing critical file: g3doc/architecture_guide/intro_to_gvisor.md"
test -f ".buildkite/pipeline.yaml" \\
  && ok ".buildkite/pipeline.yaml" \\
  || miss "missing critical file: .buildkite/pipeline.yaml"
test -f "g3doc/user_guide/containerd/quick_start.md" \\
  && ok "g3doc/user_guide/containerd/quick_start.md" \\
  || miss "missing critical file: g3doc/user_guide/containerd/quick_start.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/google/gvisor"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

gVisor is an application kernel written in Go that runs untrusted container workloads in userspace with strong isolation from the host OS. It implements a Linux-compatible syscall interface without relying on the host kernel's syscalls, protecting against container escape vulnerabilities while maintaining the efficiency of containerization. The project includes runsc, an OCI-compliant container runtime that integrates with Docker and Kubernetes. Monorepo organized by subsystem: pkg/ contains core kernel implementation (sentry, memory management, filesystem, networking), runsc/ holds the OCI runtime CLI, cmd/ has utilities, and tools/ provides debugging aids. C++ code in gVisor kernel syscall handlers interfaces with Go via cgo. Bazel BUILD files throughout (not Make-based despite Makefile presence), with Starlark rules for reproducible builds. Test files colocated with source (pkg/**/_test.go, **/_test.cc).

DevOps engineers, Kubernetes operators, and security-conscious organizations running untrusted or potentially malicious container workloads who need sandbox isolation stronger than standard Linux containers but lighter than full VMs. Google engineers and open-source contributors maintaining kernel-level sandboxing technology.

Production-ready and actively developed. The project has 15K+ GitHub stars, extensive CI/CD via Buildkite (.buildkite/pipeline.yaml), comprehensive test coverage, and recent commits. Go 1.25.5 requirement and dependencies like containerd 1.6.36 indicate current maintenance. Multiple CI workflows (build.yml, go.yml, codeql.yml) confirm active quality assurance.

Low risk for a mature Google-backed project, but inherent complexity: 19.7M lines of Go plus 4.7M lines of C++ across syscall implementation requires deep Linux kernel knowledge. Large dependency chain (containerd, kubernetes, protobuf, eBPF libraries) creates supply-chain surface area. Bazel build system (.bazelrc, .bazelversion) has steep learning curve; Bazel version lock is strict. Performance characteristics vary by workload—not a drop-in replacement for all container use cases.

Based on file presence: PGO (Profile-Guided Optimization) integration in .buildkite/scripts/pgo/, GitHub Actions workflows (build.yml, codeql.yml, go.yml) running on every commit, CodeQL security scanning, and DevContainer support (.devcontainer.json). Active labeling system (.github/labeler.yml) and issue templating suggest organized issue triage. Recent Go module update to 1.25.5 indicates ongoing dependency maintenance.

git clone https://github.com/google/gvisor.git
cd gvisor
# Install Bazel (version from .bazelversion)
bazel build //runsc  # Build the OCI runtime
bazel test //pkg/...  # Run test suite

For development setup, see CONTRIBUTING.md. Requires Linux (development on macOS/Windows not supported for full testing).

Daily commands: Build runsc runtime: bazel build //runsc. Then use it with Docker/containerd: docker run --runtime=runsc IMAGE or configure Kubernetes with runtimeClass. Test entire suite: bazel test //... (slow, can take hours). Development iteration: bazel build //cmd/runsc for quick compilation. See g3doc/ and gvisor.dev for detailed setup guides.

• README.md — Entry point explaining gVisor's purpose as a Linux-like application kernel in Go; essential for understanding the project's core mission and architecture.
• MODULE.bazel — Declares all Go module dependencies (containerd, cilium/ebpf, etc.); critical for understanding build system and external integrations.
• g3doc/architecture_guide/intro_to_gvisor.md — Comprehensive architectural overview explaining how gVisor isolates applications; essential reading before diving into kernel code.
• .buildkite/pipeline.yaml — CI/CD pipeline configuration; shows how code is tested, built, and released across multiple platforms.
• g3doc/user_guide/containerd/quick_start.md — Demonstrates runsc OCI runtime integration with containerd; key to understanding how users consume gVisor.
• CONTRIBUTING.md — Documents contribution workflow, coding standards, and development environment setup specific to gVisor.
• Makefile — Primary build entry point using Bazel; defines targets for building, testing, and packaging the kernel and runtime.

Add Support for a New Syscall

1. Read g3doc/architecture_guide/intro_to_gvisor.md to understand how the kernel handles syscalls (g3doc/architecture_guide/intro_to_gvisor.md)
2. Check compatibility matrix in g3doc/user_guide/compatibility.md to see current syscall coverage (g3doc/user_guide/compatibility.md)
3. Implement syscall handler in the kernel (syscall layer, typically in pkg/sentry/syscalls) (Makefile)
4. Add tests for the new syscall coverage (Makefile)
5. Update compatibility.md with new syscall entry and any limitations (g3doc/user_guide/compatibility.md)

Integrate with a New Container Runtime

1. Review g3doc/user_guide/containerd/quick_start.md to understand OCI runtime integration pattern (g3doc/user_guide/containerd/quick_start.md)
2. Implement OCI runtime spec compliance in runsc (cmd/runsc package) (Makefile)
3. Add configuration examples in the documentation (similar to containerd/configuration.md structure) (g3doc/user_guide/containerd/configuration.md)
4. Document integration steps and platform support in user guide (g3doc/user_guide/platforms.md)
5. Add integration tests via CI/CD pipeline (.buildkite/pipeline.yaml)

Add a New Platform (CPU Architecture or OS)

1. Review g3doc/architecture_guide/platforms.md to understand current platform support and constraints (g3doc/architecture_guide/platforms.md)
2. Update .bazelrc with new CPU/OS architecture flags and compiler settings (.bazelrc)
3. Implement platform-specific code in the kernel (pkg/sentry/arch for CPU-specific syscall handling) (Makefile)
4. Add cross-compilation targets in Makefile and .buildkite/pipeline.yaml (Makefile)
5. Document platform support, known issues, and testing approach in g3doc/architecture_guide/platforms.md (g3doc/architecture_guide/platforms.md)

Optimize Network or Filesystem Performance

1. Review g3doc/architecture_guide/performance.md and networking.md to understand current bottlenecks (g3doc/architecture_guide/performance.md)
2. Identify target subsystem (network stack in pkg/tcpip or filesystem in pkg/sentry/fs) (g3doc/architecture_guide/networking.md)
3. Implement optimization and add benchmarks to measure improvement (Makefile)
4. Update performance.md with new metrics and optimization explanation (g3doc/architecture_guide/performance.md)

• Go (Memory-Safe Language) — Eliminates entire classes of memory safety vulnerabilities (buffer overflows, use-after-free) that plague traditional kernels written in C; enables safer isolation layer while maintaining performance.
• Bazel Build System — Provides reproducible, hermetic builds across multiple platforms (Linux x86/ARM, etc.); enables fine-grained dependency management and cross-compilation essential for a portable kernel.
• OCI Runtime Specification — Allows runsc to integrate seamlessly with existing container ecosystems (Docker, Kubernetes, containerd) without requiring toolchain changes; maximizes adoption and compatibility.
• eBPF (cilium/ebpf) — Enables secure, efficient observation and monitoring of kernel behavior without sacrificing isolation; powers observability features like tracing and performance analysis.

• Userspace kernel instead of Linux kernel module

  • Why: Allows complete isolation (no kernel module privilege escalation paths); enables memory-safe implementation; simplifies deployment and updates.
  • Consequence: Higher syscall overhead than native Linux (~2-10x for some operations); requires emulation of Linux behavior rather than direct hardware access; complex TCP/IP stack re-implementation needed.

• Implement custom TCP/IP stack (pkg/tcpip) rather than reusing Linux netstack

  • Why: Provides isolation boundary; reduces attack surface by eliminating kernel network subsystem vulnerabilities.
  • Consequence: High maintenance burden; potential for subtle protocol compliance issues; ongoing effort to match Linux TCP behavior; performance optimization complexity.

• Support Linux-like syscall interface

  • Why: Enables running unmodified applications without recompilation; provides broad compatibility with existing containerized workloads.
  • Consequence: Must maintain extensive syscall compatibility matrix; some syscalls impossible to fully support in isolation (e.g., /proc introspection); ongoing compatibility testing burden.

• Memory isolation through userspace process (not hardware VM)

  • Why: Lower resource overhead than KVM; simpler deployment and integration with container tooling; avoids nested virtualization overhead.
  • Consequence: Weaker isolation than hardware VMs (side-channel attacks possible); dependent on host kernel security; potential for escape if host kernel vulnerable.

• Does not replace the Linux kernel for general-purpose host OS use
• Does not support full hardware virtualization or VMs (it IS the guest kernel, not a hypervisor)
• Does not provide hardware acceleration for all syscalls (some require host OS delegation)
• Does not guarantee protection against privileged host attacks (threat model assumes host kernel is trusted)
• Does not support non-Linux applications or ABIs (Linux-compatible interface only)

1. Bazel version lock: .bazelversion enforces exact Bazel version; installing latest Bazel will fail. 2) Linux-only development: Most tests require Linux kernel features (KVM, ptrace); macOS/Windows require Docker or VM. 3) Long test times: bazel test //... can exceed 1-2 hours; use granular targets like bazel test //pkg/sentry/syscalls/... for iteration. 4) Platform-specific code: Platform implementations in pkg/sentry/platform/{kvm,ptrace,systrap}/—behavior differs per platform. 5) Go/C++ coordination: cgo boundaries in platform code require careful memory management; see pkg/sentry/platform/systrap/stub.c. 6) PGO data: .buildkite/scripts/pgo/ manages profile-guided optimization; CI commits PGO artifacts—do not edit manually. 7) Minimal Docker support: Cannot test runsc-in-runsc nesting without special setup.

• Syscall Interception — The core mechanism gVisor uses to prevent untrusted code from directly calling the host kernel; understanding ptrace, KVM exits, or seccomp BPF tracing is essential to grasping how gVisor isolates containers
• User-Mode Kernel (Userspace OS) — gVisor implements kernel abstractions (process, memory, filesystem, networking) entirely in userspace Go; this is the architectural philosophy that enables memory-safe kernel code but requires reimplementing large swaths of kernel functionality
• OCI Runtime Specification — runsc implements OCI runtime spec; understanding bundle layout, hooks, config.json structure, and lifecycle transitions is required to integrate gVisor with Docker/Kubernetes/containerd
• Goroutine Scheduler as Task Scheduler — gVisor models container processes as goroutines managed by Go's runtime scheduler rather than OS threads; this design choice affects concurrency, debugging, and performance tuning
• Virtual Filesystem (VFS) Abstraction — pkg/sentry/fsimpl/ implements multiple filesystem backends (ext4, tmpfs, gofer for 9P network FS); understanding how gVisor mounts and multiplexes filesystems is critical for storage integration
• Memory Tagging Extension (MTE) / Address Space Layout Randomization (ASLR) — gVisor's memory model must defend against exploits; knowledge of ASLR, stack canaries, and modern exploit mitigation is relevant to hardening the kernel implementation
• Profile-Guided Optimization (PGO) — gVisor uses PGO (managed in .buildkite/scripts/pgo/) to optimize hot paths in the userspace kernel; understanding PGO workflow is necessary for performance tuning and CI integration

• containers/kata-containers — Alternative lightweight VM-based sandbox runtime for containers; similar threat model to gVisor but uses actual QEMU/KVM instead of userspace kernel
• opencontainers/runc — Standard OCI runtime that gVisor/runsc is designed to replace in security-critical scenarios; provides baseline container lifecycle management
• moby/moby — Docker engine; runsc integrates as a Docker runtime plugin—understanding moby's runtime interface is necessary for Docker integration
• kubernetes/kubernetes — Kubernetes scheduler and kubelet; gVisor is deployed via RuntimeClass in k8s, requires understanding of k8s pod lifecycle and CRI interface
• google/gapid — Related Google graphics debugging project; shares Bazel monorepo patterns and Go/C++ interop patterns with gVisor

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for gVisor networking stack (packetflow)

The g3doc/architecture_guide/packetflow.svg and networking.md indicate gVisor has a custom networking implementation, but there's no dedicated test suite visible in the repo structure for networking packet flows. Given the complexity of a custom network stack and the security-critical nature of gVisor, comprehensive integration tests for network packet handling, routing, and edge cases would significantly improve reliability. This aligns with the repo's focus on strong isolation guarantees.

• [ ] Create pkg/tcpip/tests/integration/ or similar directory structure for networking integration tests
• [ ] Add tests covering packet ingress/egress flows referenced in g3doc/architecture_guide/packetflow.svg
• [ ] Add tests for edge cases: malformed packets, MTU boundaries, concurrent packet processing
• [ ] Integrate new tests into .buildkite/pipeline.yaml and .github/workflows/build.yml
• [ ] Document expected test coverage in g3doc/architecture_guide/networking.md

Add GitHub Actions workflow for Go dependency vulnerability scanning

The repo has go.yml and codeql.yml workflows, but no dedicated dependency vulnerability scanner. With 50+ direct Go dependencies in go.mod (including security-critical packages like golang.org/x/sys, containerd, and kubernetes), automated detection of CVEs in dependencies would catch security issues early. This is especially important for a security-focused project like gVisor.

• [ ] Create .github/workflows/govulncheck.yml that runs 'govulncheck ./...' on each commit
• [ ] Configure the workflow to run on: push, pull_request, and schedule (weekly)
• [ ] Add failure conditions for HIGH/CRITICAL vulnerabilities
• [ ] Document findings in SECURITY.md with remediation guidance
• [ ] Reference this workflow in CONTRIBUTING.md for contributor awareness

Add platform-specific Bazel test sharding configuration for multi-platform builds

The g3doc/architecture_guide/platforms.md documents multiple platform support (presumably Linux, potentially others), but .bazelrc appears minimal. The Makefile and BUILD files suggest complex multi-platform testing needs. Adding platform-specific test sharding to .bazelrc (for Linux/x86_64, Linux/ARM64, etc.) would parallelize test execution significantly and catch platform-specific regressions earlier, critical for a kernel-like project.

• [ ] Extend .bazelrc with platform-specific test_arg configurations for each supported platform
• [ ] Add sharding_strategy and shard_count optimizations per platform in .bazelrc
• [ ] Update .buildkite/pipeline.yaml to leverage platform sharding for faster CI feedback
• [ ] Document supported platforms and their test configurations in g3doc/architecture_guide/platforms.md
• [ ] Verify sharding works across existing BUILD files without modification

• Add missing godoc comments to exported functions in pkg/sentry/syscalls/linux/sys_*.go—many syscall handlers lack documentation, making the codebase harder to navigate for newcomers
• Expand integration tests in runsc/test/integration/ for edge cases in filesystem operations (e.g., symlink loops, mutable binaries)—current coverage is minimal for corner cases
• Create example configurations and documentation in examples/ directory for common deployment patterns (e.g., Kubernetes with gVisor RuntimeClass, Docker Compose with runsc)—only one seccheck example exists

gVisor demonstrates a strong security-first design philosophy (memory-safe language, sandboxing focus) and maintains active security reporting processes. However, the codebase has several concerning dependency management issues: notably outdated Go version specification (1.25.5), significantly outdated Kubernetes and containerd dependencies, and use of deprecated protobuf libraries. The most critical issue is the Go version which should be verified immediately. Kubernetes and containerd dependencies need urgent updating to receive security patches. The security posture is

• High · Outdated Go Version — go.mod (go 1.25.5). The go.mod file specifies Go 1.25.5, which appears to be a version far beyond the current stable release timeline (current stable is 1.23.x as of 2024). This could indicate either a typo or use of an unverified/unstable Go version, which may contain unpatched security vulnerabilities or untested code paths. Fix: Verify the intended Go version and update to a stable, well-tested release. Use official Go releases from golang.org. Consider using Go 1.23.x or latest stable LTS version.
• Medium · Outdated Containerd Dependency — go.mod (github.com/containerd/containerd v1.6.36). The codebase uses containerd v1.6.36, which is significantly behind current versions (1.7.x and later are available). This older version may have unpatched security vulnerabilities related to container runtime operations. Fix: Upgrade to the latest stable version of containerd (1.7.x or later) to receive security updates and patches.
• Medium · Deprecated Go Protobuf Version — go.mod (github.com/gogo/protobuf v1.3.2). The codebase uses github.com/gogo/protobuf v1.3.2 which is deprecated. The official recommendation is to migrate to google.golang.org/protobuf, which is already included but gogo/protobuf may introduce compatibility issues and is no longer actively maintained. Fix: Migrate away from gogo/protobuf to google.golang.org/protobuf exclusively. Update all protobuf code generation and imports accordingly.
• Medium · Kubernetes API Version Mismatch — go.mod (k8s.io/api v0.23.16, k8s.io/apimachinery v0.23.16, k8s.io/client-go v0.23.16). The codebase uses Kubernetes client libraries v0.23.16, which is significantly outdated (released in 2022). Current versions are 1.29.x+. This may introduce compatibility issues and security vulnerabilities in Kubernetes-related operations. Fix: Update Kubernetes dependencies to the latest stable version compatible with your deployment targets. Ensure compatibility testing across all Kubernetes API interactions.
• Low · Potential Version Pinning Issue — go.mod (multiple dependencies with +incompatible or custom tags). Several dependencies use '+incompatible' or custom version tags (e.g., github.com/cenkalti/backoff v2.2.1+incompatible), which may indicate module compatibility concerns or non-standard versioning practices. Fix: Review and update dependencies to use stable, officially-released versions. Resolve any module compatibility issues by migrating to compatible versions.
• Low · Missing SBOM and Dependency Audit — .buildkite/pipeline.yaml, .github/workflows/. No evidence of automated dependency scanning, SBOM generation, or regular vulnerability audits in the build pipeline. The .buildkite/pipeline.yaml should include security scanning stages. Fix: Implement automated dependency scanning using 'go list -json -m all | nancy' or similar tools. Add SBOM generation using tools like syft. Include security scanning in CI/CD pipeline.
• Low · No Certificate Pinning for External Dependencies — go.mod, build configuration. No evidence of module verification or checksum validation beyond standard go.sum. For a security-critical project like gVisor, additional supply chain security measures should be considered. Fix: Implement module verification requirements in go.mod. Consider using GitHub's Dependabot with required status checks. Implement signed commits for dependency updates.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.