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/engineering-and-research/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.
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 |
Used as a component of GitLab at some point |
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 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 |
product, library | use_pat | website | api/service | green/yellow/red-data | 3rdparty |
Download Vulnerability Reports, Dependencies, Protected branches, and CI/CD configuration |
fork |
Download Protected branches |
| Categories | Policies |
|---|---|
red-data, product, library |
SAST, Dependency Scanning, and Secret Detection must be enabled |
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 |
library, use_pat, website, api/service, green/yellow/red-data, 3rdparty, fork |
Default branch must be protected (Allowed to merge: Maintainers, Allowed to push: Maintainers) |
docs |
Secret Detection must be enabled |
| all | Projects can't have internal visibility |
| all | SECRET_DETECTION_HISTORIC_SCAN must not be set in the CI/CD configuration |
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.
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
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:
properties.yml file in the project folder to specify its categories. Ask the project owner in doubt.ignore file if the group should be ignored. Delete its subgroups and projects in the review Merge Request.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.