<!--IssueSummary start--> <details> <summary> Everyone can contribute. [Help move this issue forward](https://handbook.gitlab.com/handbook/marketing/developer-relations/contributor-success/community-contributors-workflows/#contributor-links) while earning points, leveling up and collecting rewards. </summary> - [Close this issue](https://contributors.gitlab.com/manage-issue?action=close&projectId=278964&issueIid=593631) </details> <!--IssueSummary end--> ## 1. Executive Summary Extend the GitLab Duo Security Analyst Agent to understand, recommend, create, and manage security policies (scan execution, pipeline execution, merge request approval) through natural language interaction in Agentic Chat. Today, configuring security policies requires navigating the UI or hand-writing YAML — both time-consuming and error-prone. This enhancement enables security teams, platform owners, and compliance teams to go from a plain-language requirement (e.g., "enforce SAST on all merge requests targeting production branches") to a validated, deployed policy in minutes rather than hours. --- ## 2. Background & Context ### Current state of the Security Analyst Agent (GA, 18.8) - Reviews vulnerabilities, explains risk in plain language, recommends remediation order - Operates within Agentic Chat across the Web UI and IDEs - Has access to project data: issues, MRs, pipelines, security findings - Cannot create, modify, or recommend security policies ### Current state of Security Policies - Three policy types: Scan Execution Policies, Pipeline Execution Policies, Merge Request Approval Policies - Configuration via UI (point-and-click, no OOTB templates yet) or YAML in a Security Policy Project (SPP) - Enforcement at project, group, or instance level via linked SPPs - Centralized enforcement via Compliance and Security Policy (CSP) groups (GA 18.5) for self-managed instances with multiple top-level groups - Schema validation required for YAML — errors are common and hard to debug - Max 5 scan execution policies per SPP; other limits apply ### Why now - The Duo Agent Platform is GA and the Security Analyst Agent already has deep context on security findings — policy management is the natural next step - No OOTB policy templates exist yet — the agent can serve as an intelligent template engine - Customers on self-managed instances struggle with CSP group setup, SPP linking, and cross-group enforcement — the agent can guide them through this complexity - Policy adoption remains lower than desired because the configuration barrier is too high --- ## 3. Objectives & Success Metrics ### Goals 1. Enable security teams to create and manage security policies using natural language via the Security Analyst Agent 1. Reduce time-to-first-policy for new GitLab Ultimate customers 1. Increase overall policy adoption across projects and groups 1. Smooth out known rough edges in policy configuration (SPP setup, CSP designation, schema validation, cross-group enforcement) ### Non-Goals 1. Building a separate "Security Policy Agent" — this extends the existing Security Analyst Agent 1. Replacing the existing UI or YAML-based policy management — the agent is a complementary path 1. Auto-enforcing policies without human review — the agent proposes, the human approves 1. Supporting non-security CI/CD configuration (general pipeline authoring) ### Success Metrics | Metric | Current | Target | Measurement | |--------|---------|--------|-------------| | Security Analyst Agent monthly active users | Baseline TBD | +30% within 6 months of Phase 1 launch | Duo usage analytics | | Median time-to-first-policy (new Ultimate customers) | TBD (estimate: days/weeks) | < 30 minutes | Telemetry: time from first agent interaction to first policy commit | | % of Ultimate groups with ≥1 active security policy | TBD | +15% within 6 months | Instance/group-level policy adoption metrics | | Policy YAML validation errors on first commit (agent-assisted) | N/A | < 5% | CI pipeline failure rate on SPP MRs created by agent | | User satisfaction (CSAT) for policy-related agent interactions | N/A | ≥ 4.0/5.0 | In-chat feedback prompt | --- ## 4. Target Users & Segments | Segment | Role | Pain Level | Current Workaround | Priority | |---------|------|-----------|-------------------|----------| | **Security / AppSec engineers** | Create and manage policies centrally, enforce scanning and approval requirements | High | Manual YAML authoring, reviewing docs for schema, trial-and-error | Primary | | **Platform / DevOps owners** | Ensure consistent security enforcement across groups/projects, manage SPPs and CSP groups | High | Ruby scripts for CSP migration, manual SPP linking across groups | Primary | | **Compliance teams** | Enforce regulatory requirements (SOC2, PCI-DSS, HIPAA) through policies + compliance frameworks | Medium-High | Manual mapping of compliance requirements to policy configurations | Primary | | **Developers** | Understand why a policy blocks their MR, request adjustments for edge cases | Medium | Ask security team via Slack/issues, read policy YAML directly | Secondary | ### Explicitly not serving (Phase 1) - Users on Free/Premium tiers (security policies require Ultimate) - Custom agent builders who want to fork/extend this capability (future consideration) --- ## 5. User Stories & Requirements ### P0 — Must Have (Phase 1: Policy Advisory & Generation) | # | User Story | Acceptance Criteria | |---|-----------|-------------------| | 1 | As a security engineer, I want to describe my security requirements in plain language so the agent recommends the right policy type(s) and configuration | Agent correctly identifies which policy type(s) to use (SEP, PEP, MRAP), explains why, and generates valid YAML | | 2 | As a security engineer, I want the agent to generate valid policy YAML that passes schema validation so I don't have to debug syntax errors | Generated YAML validates against the current policy schema; agent flags any known constraints (e.g., max 5 SEPs per SPP) | | 3 | As a security engineer, I want the agent to understand my instance/group context (existing policies, projects, compliance frameworks) so recommendations are relevant | Agent reads existing policies from linked SPPs, lists active compliance frameworks, and avoids duplicate/conflicting policies | | 4 | As a platform owner, I want the agent to guide me through setting up a Security Policy Project and linking it to my group/project so I can start enforcing policies | Agent provides step-by-step guidance including SPP creation, branch protection, linking, and verification | | 5 | As any user, the agent must verify I have the required permissions (Owner role or `manage_security_policy_link` custom role) and Ultimate license before attempting policy actions | Agent checks permissions and license; provides clear messaging if insufficient; suggests alternative actions (e.g., "suggest a policy change" for developers) | | 6 | As a security engineer, I want the agent to explain the trade-offs between policy types (SEP vs PEP) so I can make informed decisions | Agent explains when to use each type, their limitations, and how they interact (e.g., PEP + SEP merge behavior) | ### P1 — Should Have (Phase 2: Policy Creation & Management) | # | User Story | Acceptance Criteria | |---|-----------|-------------------| | 7 | As a security engineer, I want the agent to create an MR in my SPP with the generated policy YAML so I can review and merge it | Agent creates a branch in the SPP, commits valid `policy.yml` changes, opens an MR with a clear description of what the policy does | | 8 | As a platform owner on self-managed, I want the agent to help me set up centralized policies via a CSP group so I can enforce policies across multiple top-level groups | Agent guides CSP group designation, helps scope policies (all projects, specific groups, compliance frameworks), warns about double-enforcement | | 9 | As a compliance team member, I want to tell the agent our compliance requirements (e.g., "SOC2 requires dependency scanning on all production code") and get a policy configuration | Agent maps common compliance frameworks to recommended policy configurations | | 10 | As a security engineer, I want to modify existing policies through the agent so I can adjust rules, scopes, and actions without editing YAML directly | Agent reads existing policy, accepts change requests in natural language, generates updated YAML, creates MR | | 11 | As a developer without policy permissions, I want to suggest policy changes to my security team through the agent so edge cases get addressed | Agent creates a GitLab issue in the SPP (or designated project) with the suggested change, tags relevant owners | ### P2 — Nice to Have / Future (Phase 3: Intelligence & Automation) | # | User Story | Acceptance Criteria | |---|-----------|-------------------| | 12 | As a security engineer, I want the agent to analyze my current security posture and proactively recommend policies I'm missing | Agent audits projects for scan coverage gaps, missing approval policies, and suggests specific policies to close gaps | | 13 | As a security engineer, I want the agent to detect policy conflicts or redundancies across my SPPs | Agent identifies overlapping policies, conflicting scopes, and duplicate scan enforcement | | 14 | As a security engineer, I want the agent to help me troubleshoot why a policy isn't working as expected | Agent checks SPP linking, policy scope, branch targeting, bot user status, and pipeline execution to diagnose issues | | 15 | As a platform owner, I want the agent to help me migrate from compliance pipelines to pipeline execution policies | Agent analyzes existing compliance pipeline config and generates equivalent PEP configuration | | 16 | As any user, if my requirement cannot be satisfied by existing policy capabilities, I want the agent to help me submit feedback to GitLab | Agent identifies the gap, drafts a feature request or links to existing issues on gitlab.com, and helps the user submit it | --- ## 6. Solution Overview ### High-level approach The Security Analyst Agent gains new "policy management" capabilities layered onto its existing vulnerability triage functionality. The agent operates within Agentic Chat and uses multi-step reasoning to: 1. **Understand intent** — Parse natural language requirements into structured policy needs (policy type, scan types, scoping, scheduling, approval rules) 1. **Gather context** — Query the GitLab API for existing policies, SPP configuration, project/group structure, compliance frameworks, and user permissions 1. **Recommend** — Suggest the optimal policy type(s) and configuration, explaining trade-offs 1. **Generate** — Produce valid YAML matching the current policy schema 1. **Act** — Create MRs in the SPP (Phase 2), create issues for suggestions (Phase 2), or provide copy-pasteable YAML (Phase 1) ### Key design decisions - **Human-in-the-loop**: The agent never directly merges policy changes. It creates MRs or provides YAML for review. This preserves the separation-of-duties model that security policies are built on. - **Permission-aware**: The agent checks user roles before attempting write actions. Users without `Owner` or `manage_security_policy_link` roles get read-only guidance and the option to suggest changes via issues. - **License-aware**: Policy features require Ultimate. The agent gracefully degrades for non-Ultimate users, explaining what's needed. - **Schema-validated**: All generated YAML is validated against the current policy schema before presenting to the user. The agent is aware of constraints like the 5-SEP limit, valid scan types, branch type options, and policy scope syntax. - **Context-rich**: The agent leverages GitLab's Knowledge Graph and project context to understand the user's environment — existing policies, projects, compliance frameworks, group hierarchy. ### Architecture considerations - **Agent tools/actions needed**: Read policies API, Read SPP configuration, Read group/project structure, Create branch, Create/update file, Create MR, Create issue, Validate YAML schema - **Policy knowledge base**: The agent needs access to current policy documentation, schema definitions, and known issues/limitations as part of its context - **CSP group awareness**: For self-managed instances, the agent must understand CSP group designation and cross-group enforcement patterns --- ## 7. Open Questions | Question | Owner | Deadline | |----------|-------|----------| | What API endpoints does the agent need that don't exist today? (e.g., policy schema validation endpoint) | Engineering | Phase 1 scoping | | How do we keep the agent's policy knowledge current as new features/options are added each release? | PM + Engineering | Phase 1 design | | Should the agent be able to preview the effect of a policy before it's created (e.g., "this policy would affect 47 projects")? | PM | Phase 1 design | | What is the interaction model for CSP group setup — can the agent run the `csp_designation.rb` script or equivalent via API? | Engineering | Phase 2 scoping | | How do we handle the agent recommending policies that reference projects/groups the user can't see (permissions boundary)? | Engineering | Phase 1 design | | Should the agent integrate with the upcoming OOTB policy templates when they ship? | PM | Phase 2 scoping | | What telemetry/instrumentation is needed to measure agent-assisted policy creation vs. manual? | Data/Analytics | Phase 1 design | --- ## 8. Timeline & Phasing ### Phase 1: Policy Advisory & Generation (~2-3 milestones) - Agent understands all three policy types, their schemas, and trade-offs - Agent reads existing policies, SPPs, and group/project context - Agent generates valid, schema-compliant policy YAML from natural language - Agent guides SPP setup and linking - Permission and license checks enforced - Output: Copy-pasteable YAML + step-by-step instructions ### Phase 2: Policy Creation & Management (~2-3 milestones after Phase 1) - Agent creates MRs directly in SPPs with generated policy YAML - Agent modifies existing policies via natural language - Agent supports CSP group setup and centralized policy management (self-managed) - Compliance requirement to policy mapping (SOC2, PCI-DSS, etc.) - Developers can suggest policy changes via agent-created issues - Agent assists with compliance pipeline to PEP migration ### Phase 3: Intelligence & Automation (~2 milestones after Phase 2) - Proactive policy gap analysis and recommendations - Policy conflict/redundancy detection - Policy troubleshooting and diagnostics - Feedback loop to GitLab for unsupported use cases (link to existing issues or draft new ones) - Integration with OOTB policy templates (when available) ### Dependencies - Duo Agent Platform API capabilities for file creation and MR creation in SPPs - Policy schema validation endpoint or client-side validation library - Knowledge Graph integration for policy documentation and known issues - CSP group API (for Phase 2 self-managed support)