Document that sandbox network limits need the sandbox to be applied

Andrew Dunnrequested to merge
docs/sandbox-network-limits-need-sandbox into master

What does this MR do?

The sandbox page says a flow runs without the sandbox when the sandbox runtime (SRT) cannot create it, but not that the network policy and the instance and group network access controls then do nothing. It also ties the default domain limit to SRT being installed, and two security pages state the limit with no condition. This MR states that the limits apply only when the sandbox is applied, on each page that makes the claim.

  • environment_sandbox.md:
    • Adds "The job can create the user and mount namespaces that SRT needs" to the conditions for the sandbox.
    • Says the network policy and the instance and group network access controls apply only when the sandbox is applied.
    • Adds to the fallback section that the job then reaches any destination its runner reaches, and what to restrict instead.
  • security-considerations.md: makes "network access to the GitLab instance only" conditional on the sandbox.
  • security_threats.md: makes the sandbox, egress control, risk profile and "full sandbox isolation" statements conditional.

Observed on a self-managed GitLab 19.4.1 test instance. The fallback is unchanged at this commit: with the duo_workflow_nono_sandbox feature flag off, its default, ee/lib/gitlab/duo_workflow/sandbox.rb puts the network settings only in the SRT configuration and runs the command directly when SRT cannot create the sandbox.

  • Rootless runner: the job log warned that SRT could not create the sandbox and ran the command directly. With strict network access controls set, the flow still ran directly, outside the sandbox.
  • Kubernetes runner with no network policy: a job pod reached the cluster API, the kubelet, and outside hosts.
  • Same runner with a default-deny egress policy: those were refused, and the flow still completed.
flowchart TD
  A[Flow job starts on a runner] --> B{Sandbox runtime in the image?}
  B -- No --> F
  B -- Yes --> C{Job can create the sandbox?}
  C -- Yes --> S[Sandbox applied: only allowed domains are reachable]
  C -- No --> F[Fallback: flow runs directly, warning in the job log]
  F --> G[No network setting applies: the job reaches what the runner network reaches]

An AI coding assistant wrote this change. The assistant also checked each claim against the three pages and ee/lib/gitlab/duo_workflow/sandbox.rb at master commit d6e9da8b and against job logs from a self-managed GitLab 19.4.1 test instance, and ran Vale and markdownlint-cli2 with the project's own configuration on the three changed pages on a local machine.

Related issues

  • Related to #607753, which proposes a setting that fails the flow when the sandbox cannot start. This MR does not depend on it.

Author's checklist

If you are a GitLab team member and only adding documentation, do not add any of the following labels:

  • ~"frontend"
  • ~"backend"
  • ~"type::bug"
  • ~"database"

These labels cause the MR to be added to code verification QA issues.

Reviewer's checklist

Documentation-related MRs should be reviewed by a Technical Writer for a non-blocking review, based on Documentation Guidelines and the Style Guide.

If you aren't sure which tech writer to ask, use roulette or ask in the #docs Slack channel.

  • If the content requires it, ensure the information is reviewed by a subject matter expert.
  • Technical writer review items:
    • Ensure docs metadata is present and up-to-date.
    • Ensure the appropriate labels are added to this MR.
    • Ensure a release milestone is set.
    • If relevant to this MR, ensure content topic type principles are in use, including:
      • The headings should be something you'd do a Google search for. Instead of Default behavior, say something like Default behavior when you close an issue.
      • The headings (other than the page title) should be active. Instead of Configuring GDK, say something like Configure GDK.
      • Any task steps should be written as a numbered list.
      • If the content still needs to be edited for topic types, you can create a follow-up issue with the docs-technical-debt label.
  • Review by assigned maintainer, who can always request/require the reviews above. Maintainer's review can occur before or after a technical writer review.

Merge request reports