GitLab Orbit security

A query returns only the data that your role lets you see in GitLab, even when an agent sends it.

Roles

A role for a top-level group applies to each subgroup and project in it. When you turn on GitLab Orbit, existing access does not change.

Security data is vulnerabilities, security findings, security scans, scanners, and Common Vulnerabilities and Exposures (CVE) and Common Weakness Enumeration (CWE) identifiers. Because GitLab cannot filter aggregate results after a query runs, the response for a user with the Reporter role leaves out security entities, even from aggregate counts.

Queries from administrators and auditors return data from each group where GitLab Orbit is on. If Admin Mode is on for the instance, the administrator must be in Admin Mode, and a personal access token needs the admin_mode scope.

If Admin Mode is on for the instance, queries through the GitLab Duo Agent Platform never use it, so they return data only from groups where the administrator has the required role. Auditors keep access to each group, except in flows that use a composite identity.

How GitLab Orbit enforces access

GitLab authorizes every query. GitLab Orbit adds no permissions of its own, and stores no permission data.

GitLab Orbit enforces access in two layers:

• Namespace scope. Results include only the groups where you have the required role, directly or through a shared group, and their subgroups and projects. A role for a project alone does not give access to that project. A group next to yours in the same parent group stays out of scope unless you have a role for it.
• A check on each result. Before GitLab returns the results, it checks your permission on each item again, and removes each item that you cannot access. This check covers confidential items, SAML group links, and group IP address restrictions. A request from outside the allowed IP address ranges of a group returns no results from that group.

The graph is read-only. It reads changes from GitLab and never writes back.

Access through shared groups

Only direct members of an invited group get access to the shared group, in GitLab and in GitLab Orbit. For more information, see sharing groups.

Programmatic access

Results include only what the token owner can see in GitLab.

Fine-grained personal access tokens

When you create a fine-grained personal access token, add the Read permission of the Orbit resource.

To use the GET /orbit/grep REST API endpoint, also add the Use permission of the Global Search resource.

GitLab Orbit does not support group and project resources. A token with only group and project resources gets 403 Forbidden.

SAML SSO enforcement does not apply. The token keeps working after the SAML session of its owner expires.

Service accounts

Use a service account for automation that runs without a personal account, such as a script, a scheduled report, or an agent. To see data from a group, the service account must be a direct member of the group, or a direct member of a group that is shared with the group. Project membership, and membership of groups where GitLab Orbit is off, do not give access.

Set up a service account

Prerequisites:

• The Owner role for the group.
• GitLab Orbit is turned on for the group.

To set up a service account for GitLab Orbit:

1. Create a service account.
2. Create a personal access token for the service account with the read_api scope. Service accounts cannot use fine-grained personal access tokens.
3. Add the service account with the Reporter role to the lowest subgroup that has the data. To read security data, use the Security Manager role. Repeat this step for each group that the service account must query.

Verify the scope of a service account

Verify the scope after you set up the account, and each time you change its memberships:

1. Save this request in a file named request.json. The query value is a GQL query.

   json

   {
     "query": "MATCH (g:Group) WHERE g.visibility_level IN ['private', 'internal', 'public'] RETURN g.name, g.full_path LIMIT 50",
     "response_format": "raw"
   }

2. Send the query with the service account token.

   shell

   curl --request POST \
     --header "Authorization: Bearer <your_access_token>" \
     --header "Content-Type: application/json" \
     --data @request.json \
     --url "https://gitlab.example.com/api/v4/orbit/query"

   Replace <your_access_token> with the token of the service account, and gitlab.example.com with your instance, or gitlab.com on GitLab.com.

3. Make sure that the full_path values include only the groups where you added the account, and their subgroups. If you see other groups, check the memberships of the account, including groups that its groups are shared with.

Related topics

• GitLab Orbit architecture
• Troubleshooting