GitLab Application Security Inventory

The AppSec Inventory is a private GitLab project to identify and track all projects, components, and dependencies that matter for AppSec

GitLab Application Security Inventory

Securing GitLab means building a security program at scale. The number of changes in the codebase is constantly increasing, along with the number of side projects. Keeping track of all these moving parts can not rely only upon our current understanding and vision of the GitLab software architecture. Automation is a key aspect of our work, and GitLab is no exception.

The AppSec Inventory is a private GitLab project to identify and track all projects, components, and dependencies important to us. The project is available at https://gitlab.com/gitlab-com/gl-security/product-security/inventory to GitLab team members. The Inventory is built using this CLI tool.

Not all projects are important, and we certainly don’t want to monitor projects that are POCs, demos, or tests. That’s why we need to categorize the projects created by GitLab team members, understand their nature, and make decisions at scale.

Categories

To quickly identify the purpose and characteristics of a project, a strict categorization is necessary. The following categories can be used to decorate the projects we want to monitor.

Categories Description
product Part of GitLab’s software supply chain (i.e. used to build, package, release, deploy GitLab, or used as part of the product)
library A library, package source, component (not necessarily a product one)
deploy Used to deploy GitLab.com
website Deployed to a website (URL will be required)
api/service
green/yellow/orange/red_data Data classification standard
3rdparty Interaction with 3rd parties
demo/test/poc
temporary Temporary projects (should be removed at some point)
internal Available for GitLab team members only
external User facing
use_pat Personal Access Token being used
marked_for_deletion Project should be removed
keep_private Should remain private indefinitely
docs Used to generate documentation
tooling Engineering tooling
container A Docker image is built
fork Fork of another project (on gitlab.com or somewhere else)

Rules

Rules define actions to take, based on the project categories. These actions are performed by the GitLab Inventory Builder and are currently hard coded. We plan to make them dynamic in the future.

Categories Actions
All (even if no category is defined) Download [Dependencies], Protected Branches, Approvals, Approval Rules
product, library, red_data Download CI/CD configuration
product, secrets_monitoring Download [Vulnerabilities]

Policies

Categories Policies
red_data, product, library SAST, Dependency Scanning, and Secret Detection must be enabled
red_data, product, library Default branch must be protected (Allowed to merge: Maintainers, Allowed to push: No one)
use_pat, website+external Dependency Scanning and Secret Detection must be enabled
website+external + yellow/orange/red_data DAST must be enabled. Overall SSL grade must be ‘A’ or ‘A+’
product + container Container Scanning must be enabled
keep_private Project visibility must be private
docs Secret Detection must be enabled
marked_for_deletion Project will be deleted
deprecated Project will be archived
all Projects can’t have internal visibility
all Default branch must be protected
all SECRET_DETECTION_HISTORIC_SCAN must not be set in the CI/CD configuration

These policies are aligned with our GitLab Projects Baseline Requirements.

How to categorize projects

The inventory relies on a folder tree structure, used as a database, in a data/ folder. Leaves are folders and can be groups or projects, and they’re identified by specific files (project.json for projects, group.json for groups). These files are created automatically when syncing the Inventory.

The tree structure reflects the organization of groups and projects in a GitLab instance, in our case: https://gitlab.com. For example, the GitLab project will be located under data/gitlab-org/gitlab/ in the Inventory.

Projects can be categorized by creating a properties.yml file in their folder. This file can contain a categories array, with the categories of the project.

For example, to add the product and library categories:

categories:
  - product
  - library

Subgroups can be ignored (skipped during synchronization) by adding an ignore file into their folder.

Learn more with the GitLab Inventory Builder Documentation, and this example inventory.

How to add or update your GitLab Project

  1. Note the namespace of your project.
  2. Visit https://gitlab.com/gitlab-com/gl-security/product-security/inventory/-/tree/main/data/
  3. Navigate the folder structure to find your project’s existing properties.yml file.
    1. If your project does not exist, create a file at data/your-namespace/your-project/properties.yml.
    2. Projects created in GitLab’s namespaces are added automatically on a weekly basis.
  4. Open a Merge Request that adds or updates the categories. Remember to “say why, not just what”.

Websites

Along with the categorization of the projects, the Inventory is also used to link websites we deploy with their projects. The properties.yml file can contain a urls array to list all the URLs (starting with https://) of a project. These URLs are used to validate the SSL configuration of the servers, and insecure findings are reported.

For example, to add the GitLab website URL:

urls:
  - https://gitlab.com

Weekly triage process

A synchronization pipeline runs every week, on Monday mornings. If successful, it will generate a Merge Request to review the changes.

The review aims to:

  1. Categorize newly created projects: Add a properties.yml file in the project folder to specify its categories. Ask the project owner in doubt.
  2. Ignore newly created groups we don’t want to track: Add an ignore file if the group should be ignored. Delete its subgroups and projects in the review Merge Request.
  3. Review projects and groups updates: Review project.json and group.json for changes, especially the visibility (public/private).

The Merge Request will report a test coverage, corresponding to the ratio of projects categorized. Ideally, these review Merge Requests keep the same coverage, which means the new projects are categorized before getting merged.

Last modified October 29, 2024: Fix broken links (455376ee)
View page source - Edit this page - please contribute. Creative Commons License