## Problem For security conscious customers, the current behavior of our sandbox can be problematic: It fails with a note but in a non-blocking way if it cannot be installed/is not found. This creates a problem if you want to ensure the sandbox always runs. Relevant RFH: https://gitlab.com/groups/gitlab-org/-/work_items/22556 ## Desired Outcome A way to ensure that the flow execution fails if the sandbox is not engaged. ## Decisions so far - The setting lives at the top-level group (GitLab.com) and at the instance level (GitLab Self-Managed and GitLab Dedicated) only. - There is no project-level setting. A project Maintainer could switch it off. - The setting does not cascade to subgroups or projects. We will add that if customers ask for it. - UI: on the GitLab Duo configuration settings page, add a new "Execution environment sandbox" heading above the existing "Network access" section. - Checkbox label: "Don't run flows when the sandbox is unavailable". - Help text: "If the sandbox is unavailable, flows that run on GitLab Runner fail instead of running without network and file system isolation." - The setting is off by default. ### Current behaviour - The default sandbox path (SRT) runs the agent without the sandbox in two cases: - `srt` is not installed. - The `srt` self-test fails. - In both cases it prints a warning and continues. This is the only path that needs to change. - The nono sandbox path (behind the `duo_workflow_nono_sandbox` feature flag) already fails closed. It needs no change. ### Merge requests - [x] **MR 1: Database.** Add a `require_sandbox` boolean column (NOT NULL, default false) to `ai_settings` (instance) and `namespace_ai_settings` (top-level group). - Status: implemented. Branch `607753-add-require-sandbox-setting-columns` is pushed. - [x] **MR 2: Backend and enforcement** * In the SRT wrapper (`ee/lib/gitlab/duo_workflow/sandbox.rb`), when the setting is on, replace the two "run the command directly" branches with an error message and `exit 1`. * When the setting is off, behaviour is unchanged. * Read the setting from the top-level group or instance settings only. Never read it from `agent-config.yml`. * Expose it through the GraphQL settings mutation (instance) and the REST groups API (top-level group). * Update the admin presenter and the group settings helper. * Audit changes to the setting: * Instance: add `require_sandbox` to `AUDIT_EVENT_COLUMNS` in `Ai::DuoSettings::ChangesAuditor` (`ee/lib/ai/duo_settings/changes_auditor.rb`). * Top-level group: add `require_sandbox: 'require_sandbox_updated'` to `EVENT_NAME_PER_COLUMN` in `Namespaces::AiNamespaceSettingChangesAuditor` (`ee/lib/namespaces/ai_namespace_setting_changes_auditor.rb`), and add the event type definition `ee/config/audit_events/types/require_sandbox_updated.yml`. * Auditor specs: a change to the setting creates an audit event with the old and new values, at instance and group level. * Specs cover the setting on and off, for both failure cases. **MR 3: Frontend.** - Add the heading and checkbox on the admin and group settings pages, with the agreed copy. - Needs Technical Writing review for the UI text. - [ ] **MR 4: Docs.** This can ship with MR 2 or MR 3. - Document the setting and what a failed job looks like in `environment_sandbox.md`. - Update the API and GraphQL reference. ### Ordering - MR 2 depends on MR 1 being merged. It does not need MR 1 to be deployed. - Regular migrations run before new code goes live, so MR 2 can follow right after MR 1 merges. --- --- #### What it does in practice When a Duo flow runs on GitLab Runner, it normally runs inside a sandbox (SRT) that isolates the flow's network and file system access. Today, if the sandbox can't start, the flow **warns and runs anyway without isolation**. This happens in two cases: `srt` isn't installed, or the `srt` self-test fails. The job still succeeds, so nobody necessarily notices that isolation was skipped. This issue adds a setting, **off by default**, that changes this to fail closed. When it's on and the sandbox isn't available, the job prints an error and exits with code 1. The flow doesn't run. When it's off, nothing changes. #### How it improves user experience - **Security-conscious admins get a guarantee.** If your policy says flows must always be isolated, you can now enforce it. Before, a runner without `srt`, or with a broken setup, silently ran flows unsandboxed. Any network domain allow or block lists you configured would have had no effect on those runs. - **Failures are visible.** A missing or broken sandbox shows up as a failed job with a clear message, not a warning buried in a successful log. Admins can then fix the runner. - **It's easy to find and use.** It's one checkbox on the GitLab Duo configuration settings page, under a new "Execution environment sandbox" heading above "Network access". The label is "Don't run flows when the sandbox is unavailable". The help text says flows on GitLab Runner fail instead of running without network and file system isolation. - **Project maintainers can't turn it off.** The setting exists only at the top-level group (GitLab.com) or instance level (Self-Managed and Dedicated). It isn't a project setting, and it doesn't cascade to subgroups or projects. - **Changes are audited.** Changes to the setting create audit events at both instance and group level. #### Trade-off Turning it on means flows fail on any runner that lacks a working sandbox. That is the intent, but admins should check their runner fleet first. The nono sandbox path, behind a feature flag, already fails closed, so it didn't need changes. #### Status The issue is closed. The database column, the backend enforcement ([!262117](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/262117)) and the setting ([!263577](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/263577)) are merged. The docs item is still unchecked in the description. A follow-up comment from @bastirehm asks for an internal event to be added for the setting if one doesn't exist yet. Issue: [#607753](https://gitlab.com/gitlab-org/gitlab/-/work_items/607753).