Skip to content
ROLLCALL

Register 1.2.0 part of the Wayne State app stack

Menu

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 GET and HEAD, and a test fails if a write verb appears in src/.
  • The GitLab token is a group or project access token (a GitLab bot), or a service account's personal access token, with the read_api scope only, the Reporter role and an expiry. The stack's own is the group access token rollcall-scanner (see the scanner token and how to rotate it). It goes in the environment as ROLLCALL_GITLAB_TOKEN, never in git, is sent only to the configured https host, and is hidden from debug output and error messages. When the source is GitLab, scan reads 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_PROJECTS limits 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. scan prints 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 401 or 403 ends the scan loudly with exit 2, so a dead token never produces a flattering partial roll. One 403 is not the token: with ROLLCALL_PROCTOR_SOURCE=gitlab, a 403 on 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:

  1. Make the replacement. In the group's Settings > Access tokens, add a new token: name rollcall-scanner, role Reporter, scope read_api only, 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.)
  2. Update the variable. In enterprise-apps/rollcall, Settings > CI/CD > Variables, edit ROLLCALL_GITLAB_TOKEN and 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.
  3. Prove it. Run a pipeline on main with the variable ROLLCALL_JOB set to scan. In the job log, look for Present: 13 apps. and no not set; skipping, no GitLab refused the token and no Note: the GitLab token line (the new token is a year from expiry, so it gets no note).
  4. Revoke the old one. Back in the group's access tokens, revoke the old rollcall-scanner (the one with the earlier expiry).
  5. 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.