Skip to content

Proposal: standardized GitLab security audit workflow

This issue proposes a standardized GitLab workflow for handling security audits across projects. The goal is to ensure audits are managed consistently, with traceable ownership and funder accountability, while using GitLab features for visibility and reporting.

Why Standardize?

  • Provides consistent audit structure across teams
  • Makes security work visible, trackable, and reportable
  • Ensures issues are correctly assigned, not lost, and milestones dates are met
  • Supports funder deliverables and public disclosure expectations
  • Uses GitLab features like boards, scoped labels, and burndown charts to get a better handle of where things are at

Proposed Workflow

This workflow would produce the following (with linked examples):

  • Milestone to track the time-boxed activity
  • A convenient Parent Issue that has all the relevant issues linked and viewable in one place
  • Issue relationships (showing what is blocked by what, so we know ordering)
  • Filterable and customizable issue boards, or saved searches
  • A clear, trackable paths from private audit findings to public reporting

Useful views into different states

Triage View: A board showing all issues labeled Needs Review by severity. This helps see what is still pending validation

If we had team-based scoped labels (eg. team::UX, team::NH, etc.) and project-based scoped lables we could make cross-team status board views that let us filter audit issues grouped by team, we could also use this to see all Security issues per-team.

We can make project-based views into ongoing security audits, for example (this board is just an example, it doesn't have every project).

High-level Roadmap view

High-level Milestone view

Workflow

1. Create a Milestone (Top-Level Group)

Where:
Create the milestone in the top-level tpo group

Name Format:
[P###] <Brief Project Name> Security Audit, example: [P101] VPN Security Audit

Justification:

  • Group milestones created in tpo are visible to all subgroups (e.g., Applications/VPN, Core/onionmasq, etc.)
  • This allows audit tasks across multiple dev projects to be unified under one milestone
  • Supports milestone-level reporting and burn down charts
  • Ensures deadline visibility across all teams involved
  • Prefixing the milestone name with [P###] ensures it's immediately clear which project the milestone belongs to—without needing to dig into metadata. It also makes it so when viewing a list of milestones (e.g., in the group-level milestones page), including the project number allows for fast visual scanning and sorting by project, especially when multiple projects have similarly named milestones like "Security Audit", "Beta Release", etc.

Action:

  • Create a milestone in tpo with a clear due date (e.g. the funder deadline)
  • Optionally, link it to the related project epic

2. Create a Parent Issue

Where:
Create the parent/master issue in the tpo/Organization group

Justification:

  • Centralizes high-level coordination of audit process steps at the org level
  • Keeps top-level tracking separate from implementation details
  • This issue should be owned by PMs, as they are tracking it, and because of that it fits in this group.

Action:

  • Title: [P###] VPN Security Audit – Parent Issue
  • Add it to the audit milestone
  • Assign it to the PM who is tracking it
  • Use auto-updating checklists to track audit tasks and issue completion
  • Use labels SecurityAudit Alliances - Cure53 (for example), Security and Project labels

3. Create Process-Level Issues (in tpo/Organization)

Each of the following issues should:

  • Be created in tpo/Organization
  • Be linked to the parent issue
  • Be assigned to the milestone
  • Be labeled with: SecurityAudit, Security, and relevant project labels
Issue Title Dependencies Justification
Create Mitigation Plan Blocked by findings Required deliverable to funders. Tracks cross-cutting risk response efforts.
Share with Funder Blocked by plan Ensures clear tracking of when and how deliverables were submitted.
Evaluate Confidentiality Flags Blocks publication Tracks decisions about public disclosure. Required before posting audit.
Publish Report Blocked by evaluation Final step in external accountability. Links to blog and website publication.

4. Create Confidential Issues for Each Audit Finding

Where:
Create one confidential issue for each audit finding in the appropriate dev group (e.g., Applications/VPN, core/onionmasq, etc.) depending on what the audit findings are about.

Justification:

  • Allows findings to be triaged and discussed confidentially
  • Supports per-team ownership
  • Tracks work by relevant development teams while maintaining central coordination
  • Enables team-level dashboards

Action:

  • Create one confidential issue per finding
  • Include full finding text from the audit report
  • Include audit evaluation checklist (see below)
  • Link to the parent issue
  • Assign to the milestone
  • Set the issue to block the mitigation plan issue
  • Assign to the appropriate developer
  • Apply labels: SecurityAudit Security Needs Review priorityhigh, severity::<audit severity> and any relevant project labels

Audit evaluation checklist:

### Next Steps

Please review and respond to the following:

- [ ] Validation: Does the finding make sense and accurately reflect the code? Provide your comments in the issue and then remove ~"Needs Review" when done.
- [ ] Exploitability: Do you agree with the severity? Adjust `severity::*` labels if needed.
- [ ] Mitigation Plan: Propose how to mitigate or defer.
- [ ] Estimated Time: Rough time estimate to address, please update the issue metadata with your estimate.
- [ ] Issue Weight: Using the [estimation guidelines](operations/-/issues/?sort=created_date&state=opened&first_page_size=100) determine relative complixity+uncertainty weight. Please add that as a weight in the metadata for this issue (round up or down to the nearest whole number, as floating points are not allowed).
- [ ] Release Sensitivity: Should this be fixed before a release? If so label appropriately.

🔒 **Reminder**: This issue is confidential. Any information provided in this issue, that is not added as an "Internal Note" will be made public once we have evaluated the issue, and developed a mitigation plan. If you reference it in other issues or merge requests, use confidential contexts only.

5. Go back to the parent issue you created, and add to the body of the issue, auto-updating checklists for each issue, for example:

### Audit Process Tracking

- [ ] #1234 Create Mitigation Plan
- [ ] #1235 Share with Funder
- [ ] #1236 Evaluate Confidentiality Flags
- [ ] #1237 Publish Final Report

### Audit Findings

- [ ] #1240 Buffer validation missing in vpn_core.rs
- [x] #1241 Timing leak in handshake
- [ ] #1242 Log sanitization issue

GitLab Features and Why

Feature Purpose
Confidential Issues Secure handling of undisclosed findings
Group Milestones Unified deadline tracking across subprojects
Blocking Relationships Tracks dependencies between process steps
Scoped Labels Enables planning board consistencyon
Issue Weights Supports planning based on complexity
Auto-updating Checklists Inline status overview; complements milestone and linked issue tracking

Feedback Requested

@bella and @gaba Please review and provide feedback, what do you think about this process? are there steps you would change, remove, or clarify?

Edited by micah
To upload designs, you'll need to enable LFS and have an admin enable hashed storage. More information