<details> <summary>Table of Contents</summary> [[_TOC_]] </details> # :lock: Interlock details --- ## Executive Summary Secret Push Protection is a critical security feature that prevents secrets from being committed to repositories, but its current enablement experience creates friction for security teams trying to deploy it at scale. Security managers need a streamlined way to enable Secret Push Protection across multiple projects without requiring: - Manual YAML configuration in each project - Deep understanding of CI/CD pipeline configuration - Individual project-by-project enablement This epic delivers the **first implementation** of the basic scan configuration profiles framework, starting with Secret Push Protection as the foundational use case. This will establish the patterns, infrastructure, and user experience that will be replicated for other scan types (SAST, Dependency Scanning, Container Scanning) in subsequent iterations. ## :chart_with_upwards_trend: Target Metrics 1. **Overall Target: 70% of Ultimate tier active projects adopting 2+ security scanners** ([Tableau](https://10az.online.tableau.com/#/site/gitlab/views/High-LevelSecurityMetricCharts/ofGitLab_comUltimateProjectswith2SecurityScannersRunning?:iid=1)) 1. Incremental target: Increase usage (% of active Ultimate projects with SPP enabled to 60% within 3 months following release) ([Tableau](https://10az.online.tableau.com/#/site/gitlab/views/PDSecSecureMetrics/ofProjectswithSPP?:iid=2)) ## Dependencies - Team dependencies: - Security Inventory - Project-level `secret_push_protection_enabled` setting - Security Manager role and permissions - Group-level Security Configuration page - Epic/Issue dependencies - _Link to dependent epics/issues via the linked items widget below for ease of drill down_ - External dependencies: - ~&quot;group::secret detection&quot; - DRI for Q1 supporting in guidance, defining default configurations, planning for custom configurations, aligning on architectural schema ## Engineering Assessment See [Scan Profiles Vision](https://docs.google.com/presentation/d/1dR2z-809QPPx1bkVks5F2MY5gRb-YhOeESKUONW4wVU/edit?slide=id.g2df33939f65_0_1787#slide=id.g2df33939f65_0_1787), which includes full project delivery plan and dependencies. ## DRIs - **PM**: @m-omokoh - **EM**: @or.gal @minac - **UX/PDM**: @mfangman - **Group(s)**: ~&quot;group::security platform management&quot; - **Engineering Owner**: @rvider ## Initiative Driver - Product or Engineering? - [x] **Product-driven initiatives (P1/P2/P3)** - Customer-facing features or improvements driven by Product teams that require engineering resources and commitment - These initiatives require a Product Priority label (P1/P2/P3) - They may also receive GTM tier labels (T1/T2/T3) for external communication - [ ] **Engineering-driven initiatives (E1/E2/E3)** - Internal technical improvements that may not have customer-facing components - These initiatives require an Engineering Priority label (E1/E2/E3) - They have internal visibility only and are not externally communicated - Examples include: technical debt reduction, infrastructure improvements, refactoring, dependency upgrades --- # :package: Product Delivery Plans ## Acceptance Criteria 1. **Enablement at Scale**: Security managers can enable Secret Push Protection for multiple projects simultaneously through the Security Inventory interface 2. **Zero YAML Required**: Projects receive Secret Push Protection without developers needing to modify `.gitlab-ci.yml` files 3. **Project-level Control**: Development teams can disable Secret Push Protection at the project level if they experience negative impacts 4. **Foundation for Future Profiles**: Infrastructure and UX patterns established can be easily extended to other scan types ## Intended users - [Amy, Application Security Engineer](/handbook/product/personas/#amy-application-security-engineer) - Primary: Needs to enable Secret Push Protection across all projects in her organization - [Alex, Security Operations Engineer](/handbook/product/personas/#alex-security-operations-engineer) - Secondary: Monitors security posture and compliance - [Sasha, Software Developer](/handbook/product/personas/#sasha-software-developer) - Affected: May need to disable if experiencing issues ## User experience goal See full design - https://gitlab.com/gitlab-org/gitlab/-/issues/574600+. **For Security Managers:** 1. Navigate to Security Inventory at the group level 2. Filter/select target projects (e.g., all "business critical" projects) 3. Bulk apply "Secret Push Protection - Default" profile 4. View coverage metrics showing which projects have Secret Push Protection enabled **For Developers:** 1. Visit project-level Security Configuration page 2. See "Secret Push Protection - Default" profile applied (read-only view) 3. Option to remove profile if experiencing issues 4. Clear messaging about why the profile was applied and who applied it ## Detailed Proposal ### 1. Profile Structure - **Profile Name**: "Secret Push Protection - Default" - **Configuration**: Read-only default ruleset (no customization in v1) - **Behavior**: Toggles the `secret_push_protection_enabled` project setting - **Versioning**: Tied to `latest` scanner version (no version pinning in v1) - **Scope**: Can be applied at group or project level ### 2. Group-level Management (Security Configuration Page) - Display "Secret Push Protection - Default" profile in read-only mode - Show profile details: - What it does (prevents secrets from being pushed) - Default ruleset information - Projects currently using this profile - **Action**: "Apply to projects" button → redirects to Security Inventory for bulk application - **Metrics**: Show % of projects in group with Secret Push Protection enabled ### 3. Security Inventory Integration - **New Column**: "Secret Push Protection" status (Enabled/Disabled/Not Applicable) - **Bulk Actions**: - Select multiple projects - "Apply Secret Push Protection Profile" action - Confirmation dialog showing impact - **Filtering**: Filter by Secret Push Protection status - **Hover States**: - Aggregated view: "X% of selected projects have Secret Push Protection enabled" - Single project view: "Enabled via profile" or "Enabled via project settings" ### 4. Project-level Management - **Security Configuration Page Updates**: - New section: "Scan Profiles Applied" - Display "Secret Push Protection - Default" if applied - Show who applied it and when - "Remove Profile" button (requires Maintainer+ role) - Clear messaging: "This profile was applied by \[Security Manager Name\] at the group level" - **Additive Behavior**: If Secret Push Protection is already enabled via project settings, profile application is additive (no conflicts) ### 5. Permissions - **Apply Profile (Group-level)**: Security Manager role required - **Apply Profile (Project-level)**: Maintainer or Owner role required - **Remove Profile (Project-level)**: Maintainer or Owner role required - **View Profile**: Guest+ can view applied profiles (read-only) ## Technical Considerations ### Scalability - Batch profile application across projects (max 100 projects per batch) - Asynchronous processing with progress tracking - Graceful handling of failures (partial success scenarios) ### Extensibility - Profile schema designed to accommodate future scan types - Abstraction layer for different enablement mechanisms: - Secret Push Protection: Toggle project setting - Pipeline scans (future): Inject CI configuration via policy engine - Metadata tracking: Applied by, applied at, profile version ### Migration Path - Users who need customization can: 1. Remove the profile 2. Configure Secret Push Protection manually via project settings 3. Use Security Policies for more advanced configuration - Clear documentation on when to use profiles vs. policies vs. manual configuration ## User Flows ### Flow 1: Security Manager Enables Secret Push Protection at Scale 1. Amy navigates to Group \> Security \> Inventory 2. Filters for "business critical" projects without Secret Push Protection 3. Selects 50 projects 4. Clicks "Apply Profile" → Selects "Secret Push Protection - Default" 5. Confirms action 6. Background job processes applications 7. Amy receives notification when complete 8. Inventory updates to show new coverage metrics ### Flow 2: Developer Removes Profile Due to Issues 1. Sasha's team experiences false positives blocking commits 2. Sasha navigates to Project \> Security \> Configuration 3. Sees "Secret Push Protection - Default" profile applied by Amy 4. Clicks "Remove Profile" 5. Confirmation dialog explains impact 6. Profile removed, Secret Push Protection disabled 7. Amy receives notification that profile was removed from project ### Flow 3: Viewing Coverage Metrics 1. Amy navigates to Group \> Security \> Configuration 2. Views "Secret Push Protection - Default" profile 3. Sees metrics: - 150 projects using this profile - 75% coverage across all projects in group 4. Clicks "View Projects" to see detailed list 5. Can navigate to Security Inventory for bulk management ## Feature Usage Metrics 1. `profiles_secret_push_protection_applied_count` - Total profiles applied 2. `profiles_secret_push_protection_removed_count` - Total profiles removed 3. `profiles_bulk_apply_action_count` - Bulk applications via Inventory 4. `profiles_project_level_apply_count` - Individual project applications 5. `profiles_coverage_percentage` - % of projects with profile enabled per group 6. `profiles_page_views_count` - Unique visits to profile pages 7. `profiles_inventory_filter_usage` - Usage of Secret Push Protection filter in Inventory ## Documentation Requirements 1. **Concept Documentation**: What are scan profiles and when to use them 2. **How-to Guides**: - Enable Secret Push Protection at scale using profiles - Remove a profile from a project - View profile coverage metrics 3. **Comparison Guide**: Profiles vs. Security Policies vs. Manual Configuration 4. **Migration Guide**: Moving from manual configuration to profiles 5. **Troubleshooting**: Common issues and solutions ## Availability & Testing - **GA**: 18.9 - **Tier**: Ultimate only - **Testing**: - Unit tests for profile CRUD operations - Integration tests for bulk application - E2E tests for complete user flows - Performance tests for 1000+ project scenarios ## Risks and Mitigations | Risk | Impact | Mitigation | |------|--------|------------| | Performance issues with bulk application | High | Implement batching and async processing | | Conflicts with existing configurations | Medium | Additive approach, clear messaging | | Users expect customization in v1 | Medium | Clear documentation on migration paths | | Removal of profiles disrupts security posture | High | Notifications to Security Managers, audit logs | ## Future Iterations (Out of Scope) 1. Custom profiles with configurable rulesets 2. Profile versioning and rollback 3. Scheduled profile application 4. Profile templates and inheritance 5. Integration with compliance frameworks 6. Profiles for SAST, Dependency Scanning, Container Scanning ## Links / references - Parent Epic: [Basic enablement-only scan profiles](/groups/gitlab-org/-/epics/19572) - Related: [Security Inventory Beta](link) - Design: [Figma mockups](link) - Technical Design: [Architecture doc](https://handbook.gitlab.com/handbook/engineering/architecture/design-documents/security_analyzer_configuration_profiles/) --- > [!important] > > This page may contain information related to upcoming products, features and functionality. It is important to note that the information presented is for informational purposes only, so please do not rely on the information for purchasing or planning purposes. Just like with all projects, the items mentioned on the page are subject to change or delay, and the development, release, and timing of any products, features, or functionality remain at the sole discretion of GitLab Inc.