GitLab Application Security Inventory

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. xtThe 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.

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.

Policies

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:

1
2
3

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:

1
2

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.

View page source - Edit this page - please contribute.