Add opt-in fail-closed default for background tool governance

What does this MR do and why?

On the background surface, an un-ruled write or execute tool resolves to Allow. A group that wants Duo Developer locked down has to write a Background rule for every tool.

This adds duo_workflow_background_fail_closed, a default-off beta flag checked on the root group. With the flag on, those un-ruled tools resolve to Deny instead.

  • Reads and notify_me_when stay Allow.
  • Un-ruled tools are put in denied_tools by name, not only dropped with their privilege. There are two reasons:
    • A partly ruled group (for example only edit_file allowed) keeps its privilege. Without the names, the other tools in that group would be in no list, and the flow would halt on its first call to one of them.
    • The GitLab MCP spelling of a denied catalog tool, such as gitlab_create_issue, is only reached through denied_tools.
  • run_mcp_tools keeps its group default. It has no catalog tools, so denying it would drop the privilege that pre-approves read-only MCP tools. MCP-only tools fail closed one by one instead.
  • A project rule can't loosen the default. A project Background Allow on a tool the default denies is rejected, and an older one is ignored, the same as under a group Deny rule.
  • The settings page shows Deny in the Background column for those tools, through the same background_effective call that enforcement uses.
  • The helper also requires duo_workflow_background_tool_governance, so the page never shows Deny where background rules aren't enforced.

With duo_workflow_block_start_on_denied_group on and no Background rules, Duo Developer is refused at start with the existing message. Behaviour with the flag off is unchanged.

The flag only changes the default on the background surface, so it has no effect unless duo_workflow_background_tool_governance is on. With that flag off, Developer reads Web rules, as on master.

No docs or changelog in this MR. The flag is default-off and will only be enabled for a test group. The docs and release note land before the first customer group, tracked in https://gitlab.com/gitlab-org/gitlab/-/work_items/636652.

Out of scope:

  • Third-party and client-injected MCP tools. Governance covers the tools served by GitLab's own MCP server.
  • Clamping the workflow row's declared agent_privileges on the background surface. This is unchanged from master. Every tool Duo Developer uses is in the Rails tool map, so the denied ones are stripped through denied_tools. Flows that use tools missing from the map need this before they come under governance (https://gitlab.com/gitlab-org/gitlab/-/work_items/607357).
  • The shell route. Allowing run_command lets the flow write files, commit and open MRs through the shell, even with those tools denied. This is the shell split in https://gitlab.com/gitlab-org/gitlab/-/work_items/633005.

References

Screenshots or screen recordings

No UI code changes. The Background column shows Deny for un-ruled write and execute tools when the flag is on. The GDK results are below.

The group gitlab-duo already had three rules:

  • create_merge_request denied on every surface
  • create_commit denied on Web only
  • MCP search denied on Web only

duo_workflow_background_tool_governance and duo_workflow_block_start_on_denied_group were on for the group in every run. "Flag off" and "Flag on" below refer to duo_workflow_background_fail_closed only.

Assigning Duo Developer on an issue

Flag off (same as master) Flag on, no Background rules
✅ Duo Developer has started. ❌ Could not start processing due to this error: An administrator denied the tools this flow needs to run: create_file_with_contents, edit_file, mkdir, and run_tests and run_command.

Policy sent to DWS / settings page Background column, with no Background rules

Tool master Flag off Flag on
read_file, list_issues, notify_me_when allow / Allow allow / Allow allow / Allow
create_file_with_contents, edit_file, mkdir, run_tests, run_command allow / Allow allow / Allow deny / Deny
run_git_command, create_issue, create_commit (Web-only deny) allow / Allow allow / Allow deny / Deny
create_merge_request (explicit deny) deny / Deny deny / Deny deny / Deny
GitLab MCP tools denied 1 1 16 (the write ones)
Pre-approved privileges all 7 all 7 read_only_gitlab, read_only_files, run_mcp_tools

Partial opt-in, flag on

Background Allow rules Start Policy
edit_file, run_command starts The other three file tools are denied by name
All four file tools and run_command starts Those five are allowed. run_git_command, create_issue and create_commit stay denied. Developer doesn't use them.

How to set up and validate locally

  1. Pick a top-level group with Duo Developer enabled, for example gitlab-duo. In the Rails console:
    group = Group.find_by_full_path('gitlab-duo')
    Feature.enable(:duo_workflow_background_tool_governance, group)
    Feature.enable(:duo_workflow_block_start_on_denied_group, group)
    Feature.enable(:duo_workflow_background_fail_closed, group)
  2. Open the group's AI tool rules settings page. The Background column shows Deny for write and execute tools you haven't set, and Allow for read tools.
  3. Assign the Duo Developer service account to an issue in a project of that group. The account replies that an administrator denied the tools the flow needs.
  4. On the settings page, set run_command and the four file tools (create_file_with_contents, edit_file, mkdir, run_tests) to Allow under Background. Assign Developer again. It starts.
  5. Disable duo_workflow_background_fail_closed for the group. Assigning Developer starts it with no Background rules, as on master.

MR acceptance checklist

Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.

Edited by Rahul Barnwal

Merge request reports

Loading
Loading