## Summary Explore extending the `license_finding` rule in **Merge Request Approval Policies** to support license override mappings for dependencies detected as `unknown`. This would allow organizations to centrally specify the correct SPDX identifier for packages where automated detection fails, unblocking license compliance enforcement at scale. ## Problem GitLab's license scanner reports `unknown` for packages in several structurally unavoidable scenarios: - **Proprietary/internal components** with no open-source license that will never appear in any SPDX registry - **Dual-licensed modules** (e.g., `GPL-2.0 OR commercial`) where the applicable license depends on the consuming organization's usage context and cannot be inferred automatically - **SPDX license expressions** not yet supported (https://gitlab.com/gitlab-org/gitlab/-/issues/336878) - **Packages missing from the Package Metadata DB** or with incomplete upstream metadata There is currently **no mechanism** to override or patch these license classifications at scale. License Approval Policies that block non-whitelisted licenses will therefore always require manual approval for these packages, even when the actual license is known to the organization. Under the **EU Cyber Resilience Act (CRA)**, organizations are required to present SBOMs with complete and accurate license obligations. SBOMs with `unknown` license fields are non-compliant regardless of the reason. ## Proposed Approach Since GitLab 17.11, the `license_finding` rule supports a [`licenses` field](https://gitlab.com/groups/gitlab-org/-/epics/10203) with package-level exclusions using [purl](https://github.com/package-url/purl-spec). This spike proposes extending this existing mechanism with a `license_overrides` array that maps specific packages (identified by purl) to known SPDX identifiers. ### Proposed schema extension ```yaml approval_policy: - name: "License compliance with overrides" rules: - type: license_finding branch_type: protected license_states: - newly_detected - detected licenses: allowed: - name: "MIT License" - name: "Apache License 2.0" license_overrides: - purl: "pkg:pypi/urllib3" license: "MIT License" mode: "patch" # apply only when detected license is "unknown" - purl: "pkg:maven/com.acme/internal-sdk" license: "LicenseRef-Acme-Innersource" mode: "overwrite" # always use this, regardless of detected license actions: - type: require_approval approvals_required: 1 user_approvers: - security-team ``` ### Mode definitions - **`patch`**: The override is applied **only** when the scanner reports the license as `unknown`. If the scanner detects a known license (even an incorrect one), the override is not applied. This is the safe default for correcting detection gaps. - **`overwrite`**: The override is **always** applied, regardless of what the scanner detects. This is needed for dual-licensed packages where the organization has chosen a specific license, or for proprietary components where the scanner may detect an incorrect license from bundled dependencies. ### Key design questions 1. **Schema placement**: Should `license_overrides` live inside the `license_finding` rule (as shown above), or as a sibling to `rules` at the policy level? Rule-level keeps overrides scoped to specific rule configurations; policy-level avoids duplication across rules. 2. **Interaction with `licenses` allowlist/denylist**: After an override is applied, the overridden license should be evaluated against the `allowed`/`denied` lists as if the scanner had detected it. Is this the correct behavior, or should overrides implicitly allow the package? 3. **Custom `LicenseRef-*` identifiers**: SPDX allows custom identifiers via `LicenseRef-` prefix. How should these interact with the `allowed`/`denied` license lists? They won't appear in the standard SPDX list, so users would need to add them to their allowlist explicitly. 4. **Scope of effect**: This proposal affects **policy evaluation only** (whether the MR is blocked). It does **not** change the underlying license data in the Dependency List or SBOM export. Is this sufficient, or should the spike also consider propagation to those surfaces? (See Alternative C below.) 5. **Scalability**: For organizations with hundreds of overrides, is inline YAML practical? Should we consider a maximum count or recommend the external file approach from https://gitlab.com/gitlab-org/gitlab/-/issues/503390 for large override sets? 6. **Version handling**: The existing `purl` exclusion mechanism supports optional version pinning (`pkg:pypi/urllib3@2.0.0`). Should overrides follow the same convention, where omitting the version applies to all versions? ## Alternatives to Explore ### Alternative A: Vulnerability Management Policy with auto-dismiss for unknown licenses Extend the [Vulnerability Management Policy](https://docs.gitlab.com/user/application_security/policies/vulnerability_management_policy_schema/) with a new rule/action type that auto-resolves or auto-dismisses license findings when the license is `unknown` and a known mapping exists. This leverages existing policy infrastructure but is a conceptual mismatch: license overrides are metadata corrections, not vulnerability triage decisions. The VMP schema would need new rule types (`license_unknown`) and actions (`auto_assign_license`) that don't fit its current design. ### Alternative B: Group-level license mapping DB table Create a standalone feature (not a policy) with a new database table (`group_id | purl | license_spdx_id`) where group owners define package-to-license mappings. The DS Analyzer checks this table when a package has an `unknown` license and fills in the mapping. This is the cleanest separation of concerns and was [proposed by the Composition Analysis team](https://gitlab.com/gitlab-org/gitlab/-/issues/503390), but requires cross-team work (Composition Analysis, Security Policies, Security Insights) and a new DB table, estimated at roughly one quarter for CA alone. ### Alternative C: SBOM enrichment pipeline with custom licenses Allow users to download the GitLab-generated SBOM, enrich it with correct license data for `unknown` packages, and re-upload it. The enriched SBOM would then be used by the License Approval Policy for evaluation. This solves both the policy evaluation and CRA/SBOM compliance problems but introduces a complex workflow (download, modify, upload) and requires GitLab to accept non-SPDX license identifiers in CycloneDX ingestion, which currently fails validation. ## References - https://gitlab.com/gitlab-org/gitlab/-/issues/503390 - Add option to reference file with licenses in MR Approval Policy - https://gitlab.com/groups/gitlab-org/-/epics/10861 - User provided license information for components - https://gitlab.com/gitlab-org/gitlab/-/issues/336878 - SPDX license expression support - https://gitlab.com/groups/gitlab-org/-/epics/10203 - Exclude packages from MR Approval Policies for License Approval Rules (parent of `licenses` field) ## Expected Outcome A written assessment covering: - Technical feasibility of extending the `license_finding` rule with `license_overrides` - Recommended schema design with purl-based package identification - How overrides interact with existing `licenses` allowed/denied evaluation - Whether the proposed approach, or one of the alternatives, best addresses the problem - Effort estimate and cross-team dependencies (Composition Analysis, Security Insights, Security Policies) - Identified risks and open questions