[rfc] Publishing OpenTitan Security Advisories on GitHub Infrastructure

### Description

## Summary

OpenTitan adopts GitHub repository security advisories for coordinating, embargoing, and publishing security vulnerability information.

Encrypted-email intake (`security@opentitan.org` \+ PGP) remains the primary contact point. All coordination, review, and publication move to GitHub infrastructure to provide:

- A first-class, auditable embargo workflow (private drafts, private collaboration forks).
- Built-in access controls and reviews tied to existing repo/org roles.
- A public advisory dashboard maintained automatically by GitHub, with the option of a lightweight statically generated aggregation site layered on top if a cross-repo or OpenTitan specific view is desired.
- A clean path to CVE assignment and inclusion in the global GitHub Advisory Database.

The model is deliberately close to the one already in production for [Caliptra](https://github.com/chipsalliance/Caliptra/security/policy), so OpenTitan benefits from a proven pattern used by a peer hardware root-of-trust project.

## Motivation

### Current process

OpenTitan's [Coordinated Vulnerability Disclosure (CVD) policy](https://opentitan.org/cvd-policy/index.html) defines a certifiable intake path: researchers email `security@opentitan.org`, receive a PGP key, and submit an encrypted report. The team acknowledges within three working days, investigates, keeps the reporter updated, and commits to public disclosure once a fix or mitigation is in place. Reporters are explicitly asked not to use public GitHub issues.

The *post-intake* lifecycle is largely undefined in tooling terms. In particular, the current policy does not describe:

- **Structured embargo mechanism.** The current policy lacks documented embargo durations, notification lists, and state tracking for access control.
- **Coordination surface.** Current tooling lacks a private environment for maintainers, reporters, and code owners to collaborate on fixes using standard review workflows.
- **CVE lifecycle management.** The project requires a defined path for CVE identification and Numbering Authority (CNA) interaction.
- **Machine-readable advisory records.** Integrators and automated scanners require a canonical, discoverable record of past advisories.

Integrators need predictable embargo windows to prepare and ship fixes, and they need a durable, citable advisory record for their own compliance and customer communications.

## GitHub Security Advisories

GitHub native security features manage the vulnerability lifecycle through three mechanisms:

### Embargo management (private by default)

Security advisories remain in **draft** status and are not available in public until publication. Fix development occurs in **temporary private forks** to ensure technical enforcement of the embargo boundary.

### Reviews and access controls

Advisory management is gated by existing GitHub organization roles. Maintainers add **collaborators** (reporters, code owners) to specific advisories. This reuses the established OpenTitan access model for auditable, need-to-know collaboration.

## Proposed OpenTitan workflow

This section defines the post-validation lifecycle for the OpenTitan TC and security team:

```mermaid
flowchart TB
Intake["Intake
(email+PGP or GitHub private report)"] --> Triage
Triage -->|valid| Draft["Draft advisory created
(private)"]
Triage -->|invalid / not security| Rejected["Closed / converted to issue"]
Draft --> Assigned["Assigned
CVE requested, severity (CVSS),
collaborators + private fork"]
Assigned --> Review["Fix under review
(private fork PR)"]
Review --> Merged["Fix merged to affected branches
(disclosure-safe PR text)"]
Merged -->|embargo elapses| Published["Advisory published
CVE finalized, dashboard updated"]
Review --> Rejected
```

### Dual intake, unchanged for researchers

- `security@opentitan.org` \+ PGP remains the documented first contact.
- Optionally, **enable GitHub Private Vulnerability Reporting** on the relevant repos so researchers who prefer GitHub can file directly. Either path lands in the same advisory workflow.

### Embargo policy

OpenTitan will implement a **bounded, written embargo policy**. The window includes an internal fix period followed by an integrator preparation period. The TC and security team will define specific durations.

### Integrator notification

Silicon integrators and downstream maintainers with a demonstrated need-to-know will join a vetted **vulnerability-alerts list**. Membership and access mirror the discipline used for the private advisory collaborator list.

### CVE / CNA

Project implementation follows this phased approach:

1. **Use GitHub's CVE request flow** per advisory (lowest overhead; GitHub acts as the CNA).
2. **Pursue OpenTitan CNA status** so CVEs are assigned within the project.

This RFC recommends starting with option 1 and treating CNA registration as a follow up.

### Disclosure-safe fixes

Pull requests merged during embargo must describe changes functionally. Descriptions must not reveal the vulnerability nature, exploitability, or CVE ID. The contributor guide will be updated with these requirements.

## Dashboard and publication

| Document | Required Update |
| :---- | :---- |
| `SECURITY.md` | Link to advisories; define the embargo and notification list. |
| CVD Policy | Specify bounded embargo windows and dashboard links. |
| Contributor Guide | Instructions for disclosure-safe functional descriptions in PRs. |

## References

- OpenTitan CVD policy — [https://opentitan.org/cvd-policy/index.html](https://opentitan.org/cvd-policy/index.html)
- OpenTitan RFC process — [https://opentitan.org/book/doc/project\_governance/rfc\_process.html](https://opentitan.org/book/doc/project_governance/rfc_process.html)
- Caliptra security policy — [https://github.com/chipsalliance/Caliptra/security/policy](https://github.com/chipsalliance/Caliptra/security/policy)
- Creating a repository security advisory (GitHub Docs) — [https://docs.github.com/en/code-security/how-tos/report-and-fix-vulnerabilities/fix-reported-vulnerabilities/creating-a-repository-security-advisory](https://docs.github.com/en/code-security/how-tos/report-and-fix-vulnerabilities/fix-reported-vulnerabilities/creating-a-repository-security-advisory)
- REST API for repository advisories — [https://docs.github.com/en/rest/security-advisories/repository-advisories](https://docs.github.com/en/rest/security-advisories/repository-advisories)