Security notes#
This page lists how Rollcall keeps itself and the fleet safe, and exactly what its GitLab token needs. Next: run the checks.
- Read-only toward GitLab and everything else: one gate in the GitLab adapter allows only
GETandHEAD, and a test fails if a write verb appears insrc/. - The GitLab token is a group or project access token (a GitLab bot), or a service account's personal access token,
with the
read_apiscope only, the Reporter role and an expiry. The stack's own is the group access tokenrollcall-scanner(see the scanner token and how to rotate it). It goes in the environment asROLLCALL_GITLAB_TOKEN, never in git, is sent only to the configuredhttpshost, and is hidden from debug output and error messages. When the source is GitLab,scanreads the token's own record (GET /api/v4/personal_access_tokens/self) and prints a note 14 days before it expires, or when it has already expired. The note names the date; the stack maintainer rotates the token before its expiry, never Rollcall. The check is advisory: a refused, unreachable or unparseable answer prints nothing and never fails the scan, and the token value never appears in output. - Composer files are parsed as data. No
composer install, script or plugin from a scanned repository ever runs. - PROCTOR reports, image tags and app ids are outside input: shapes are validated, text is bounded, and terminal output strips control characters.
The GitLab token, exactly#
Rollcall needs one scope, read_api, and one role, Reporter, on each project it scans. Nothing else. GitLab
describes read_api as read access to the API for the token's scope, and every call Rollcall makes is a read
through the REST API.
Every call Rollcall makes#
| Call | When | Why | Covered by |
|---|---|---|---|
GET /api/v4/groups/:id/projects?include_subgroups=true&simple=true&archived=false&per_page=100 |
ROLLCALL_GITLAB_GROUPS is set and ROLLCALL_GITLAB_PROJECTS is not |
Lists the projects to scan, following Link pagination to the same host |
read_api |
GET /api/v4/projects/:id?simple=true |
ROLLCALL_GITLAB_PROJECTS is set (no group is listed) |
Reads each named project's id and default branch | read_api |
HEAD /api/v4/projects/:id/repository/files/:file_path?ref= |
Every scan, for composer.json, composer.lock and booster-hop.json |
Reads the blob id, so an unchanged Composer file is not fetched again (a 404 means the app has no such file) | read_api |
GET /api/v4/projects/:id/repository/files/:file_path/raw?ref= |
When a file is new or changed | Reads the file's bytes, without cloning | read_api |
GET /api/v4/projects/:id/pipelines?ref=&scope=finished&order_by=id&sort=desc&per_page=5 |
ROLLCALL_PROCTOR_SOURCE=gitlab, once per project per scan |
Finds the newest finished pipelines on the default branch, passed or failed | read_api (Reporter reads pipelines) |
GET /api/v4/projects/:id/pipelines/:pipeline_id/jobs?per_page=100 |
ROLLCALL_PROCTOR_SOURCE=gitlab, newest pipeline first until one ran the proctor job |
Finds that pipeline's proctor job id, following Link pagination to the same host |
read_api |
GET /api/v4/projects/:id/jobs/:job_id/artifacts/:artifact_path |
ROLLCALL_PROCTOR_SOURCE=gitlab, when a proctor job was found |
Reads the one report file (proctor.json) from that job's artifact; 404 means no report |
read_api (Reporter reads job artifacts) |
GET /api/v4/personal_access_tokens/self |
Every scan | Reads the token's own expiry date for the 14-day note (advisory) | any valid token |
tests/TokenScopeDocsTest.php fails if the GitLab adapter calls an API path this table does not list.
Scopes it must not have#
| Scope | Why not |
|---|---|
api |
Read and write access to the whole API. Rollcall never writes, so a leaked api token would hand out powers Rollcall never uses |
write_repository |
Push access. Rollcall never pushes |
read_repository |
Git-over-HTTP pull. Rollcall never clones; it reads single files through the API, which read_api covers |
read_user |
The /user profile. Rollcall never reads a profile; the expiry note uses personal_access_tokens/self |
read_registry, read_virtual_registry |
Container and package registries. Rollcall reads no images; the image tag comes from an export |
self_rotate |
Lets the token rotate itself. The stack maintainer rotates the token, never Rollcall |
create_runner, manage_runner, k8s_proxy, ai_features and any admin scope |
Nothing Rollcall does |
Role, membership and expiry#
- Reporter, on each project to scan, and nothing more. Reporter is the lowest role that can read a private project's files; Guest cannot. Developer and above add powers Rollcall never uses.
- Membership is the real fence.
ROLLCALL_GITLAB_PROJECTSlimits what Rollcall asks for, not what the token can read. A group token reads every project in its group. For the tightest fence, the token's user is a member of just the projects to scan: a service account, or a bot on a small group made for the purpose. The stack's own token takes the wider road on purpose (below), and the scan job's project list keeps the asking narrow. - An expiry, always. GitLab caps a token at 365 days by default.
scanprints a note 14 days before the expiry and again once it has passed, naming the date. - Where it lives. In the environment of the job that scans, as
ROLLCALL_GITLAB_TOKEN: on GitLab CI a masked, hidden and protected CI/CD variable on the Rollcall project, not a file variable. Never in git,.env.example, an image or a log. - Who rotates it. A role, not a person: the stack maintainer creates the replacement, updates the variable and revokes the old token before the expiry date. Rollcall only reminds.
- A refused token stops the scan. A
401or403ends the scan loudly with exit2, so a dead token never produces a flattering partial roll. One403is not the token: withROLLCALL_PROCTOR_SOURCE=gitlab, a403on a project's pipeline list means CI/CD is off for that project (the same token has just read its files), so that app has no PROCTOR report and the scan carries on.
The scanner token and how to rotate it#
The stack's weekly scan on git.wayne.edu reads with one token. Everything about it except its value is here.
| What | The stack's answer |
|---|---|
| Token | The group access token rollcall-scanner on the enterprise-apps group: Reporter, read_api only. The project owner chose group reach (2026-11-06), so it can read the group's projects; the job asks only for the 13 it lists |
| Where it lives | Its value lives only in the CI/CD variable ROLLCALL_GITLAB_TOKEN on enterprise-apps/rollcall: masked, hidden, protected, not a file. The token itself is listed under the group's Settings > Access tokens |
| Expires | 2027-11-06. scan starts its note on 2027-10-23 |
| Who rotates it | The stack maintainer, a role, not a named person. Creating a group access token needs the Owner role on the group; a stack maintainer without it asks a group Owner for step 1 and does the rest |
| What uses it | The rollcall-scan job, on the Monday schedule with ROLLCALL_JOB=scan, or started by hand |
Rotate it in one sitting, well before the expiry and not just before the Monday schedule runs:
- Make the replacement. In the group's Settings > Access tokens, add a new token: name
rollcall-scanner, role Reporter, scoperead_apionly, an expiry at most a year out. Copy the value once; GitLab never shows it again. (The token list's Rotate button is the shortcut, but it revokes the old token at once and you must check the new expiry it gives: GitLab's API defaults a rotated token to one week.) - Update the variable. In
enterprise-apps/rollcall, Settings > CI/CD > Variables, editROLLCALL_GITLAB_TOKENand paste the new value. Keep it masked, hidden and protected, not a file. Paste it nowhere else: not a chat, a ticket, a file or a commit. - Prove it. Run a pipeline on
mainwith the variableROLLCALL_JOBset toscan. In the job log, look forPresent: 13 apps.and nonot set; skipping, noGitLab refused the tokenand noNote: the GitLab tokenline (the new token is a year from expiry, so it gets no note). - Revoke the old one. Back in the group's access tokens, revoke the old
rollcall-scanner(the one with the earlier expiry). - Write down the new date. Change the expiry in the table above, and note the rotation in
CHANGELOG.md, in the same merge request.
A token that leaked is rotated the same way, at once, without waiting for its date. Revoking it first is fine: the scan stops loudly until step 2 is done.