Skip to content

Security Advisories and Vulnerability Management

Repository Security Advisories

Repository security advisories provide a private workspace for maintainers to discuss, fix, and publish vulnerability information.

About Repository Security Advisories - Overview

Why Use Them

  • Coordinated disclosure without leaking details
  • Private fork for developing and testing the fix
  • Formal advisory publication with CVE assignment
  • Propagates to the Global Advisory Database, powering Dependabot alerts for downstream users

Lifecycle

  1. Draft - Maintainers create a draft advisory, describe the vulnerability, and set severity
  2. Private fork - Create an automatic private fork to develop the fix
  3. Collaborate - Invite specific collaborators to the advisory
  4. Request CVE - Ask GitHub (a CNA) to assign a CVE if appropriate
  5. Release fix - Merge the fix into the main repo
  6. Publish advisory - Make the advisory public with affected versions and references

Advisory Fields

  • Title
  • Description
  • Severity (Low, Moderate, High, Critical) and CVSS v3.x score
  • Affected products (ecosystem, package name, affected version range, patched versions)
  • CWE identifiers
  • Credits to reporters
  • References (links, patches)

CVE Requests

  • GitHub is a CVE Numbering Authority (CNA)
  • Maintainers can request a CVE as part of the advisory
  • Requests are reviewed before issuance
  • The advisory includes the CVE ID once assigned

Private Vulnerability Reporting

A repo (or organization) can enable private vulnerability reporting so external researchers can report issues through GitHub UI privately.

Enablement

  • Repo Settings > Security > Private vulnerability reporting
  • Or at org level for all repos

Reporter Flow

  1. Researcher opens the Security tab, clicks "Report a vulnerability"
  2. Fills a form with description, severity, reproduction steps
  3. GitHub creates a draft advisory visible only to maintainers

Maintainer Flow

  1. Review the draft advisory
  2. Engage the reporter in the advisory thread (private)
  3. Develop fix in a private fork
  4. Publish once patched

Private Vulnerability Reporting - Reporting guide

Global Advisory Database

  • Public, searchable database at https://github.com/advisories
  • Every entry has a GHSA ID (GHSA-xxxx-xxxx-xxxx) and may have a CVE ID
  • Sources:
  • Published repository advisories
  • GitHub Security Lab research
  • National Vulnerability Database (NVD) feed
  • Community contributions

How It Powers Dependabot

Dependabot matches your dependency graph against the Advisory Database. Each affected package/version pair generates an alert.

Security Policy (SECURITY.md)

A repository-level file describing how to report vulnerabilities. Typical contents:

  • Supported versions
  • Preferred reporting channel (private vulnerability reporting, email, etc.)
  • Response time expectations
  • Scope (what is in-scope and out-of-scope)

Place at repo root, .github/, or docs/ directory.

Adding SECURITY.md - Security policy guide

Severity Scoring

CVSS v3.x

  • Base metrics: Attack Vector, Attack Complexity, Privileges Required, User Interaction, Scope, Confidentiality, Integrity, Availability
  • Produces a numeric score (0.0 - 10.0)
  • GitHub maps to severity buckets

Severity Buckets

Bucket CVSS Range
Critical 9.0-10.0
High 7.0-8.9
Moderate 4.0-6.9
Low 0.1-3.9

CWE Mapping

CWE (Common Weakness Enumeration) classifies the type of weakness. Example: CWE-89: SQL Injection. Advisories can include one or more CWEs.

Dependabot and Your Own Advisories

When you publish an advisory for your own package, downstream users consuming your package via Dependabot will receive alerts. This is the primary reason to use advisories rather than just a blog post.

End-to-End Coordinated Disclosure Example

  1. Researcher reports via private vulnerability reporting
  2. Maintainer creates a draft advisory from the report
  3. Maintainer spins up a private fork, develops and tests a fix
  4. Maintainer requests a CVE from GitHub
  5. Fix is merged to main; a patched version is released
  6. Advisory is published with CVE, affected versions, and patched versions
  7. Downstream consumers receive Dependabot alerts

Common Pitfalls

  • Publishing advisory details before a fix is available (coordinated disclosure violation)
  • Skipping the advisory and publishing only a changelog note (no Dependabot alerts for users)
  • Not setting affected version ranges correctly (false negatives or positives)
  • Forgetting SECURITY.md so reporters don't know where to start

Enterprise Considerations

  • Org admins can enable private vulnerability reporting across all repos
  • Security managers have read access to advisories across the org
  • Advisory events appear in the audit log

Organization-Level Advisory Management

  • View draft and published advisories across the org under Security > Advisories (org level)
  • Coordinate response across multiple repos if a vulnerability affects them

Key Exam Facts

  • Repository security advisories are the canonical way to coordinate, fix, and disclose vulnerabilities
  • GitHub is a CNA and can assign CVEs for repository advisories
  • Private vulnerability reporting can be enabled at repo or org level
  • Advisory entries in the Global Advisory Database drive Dependabot alerts
  • CVSS severity buckets: Low (<4), Moderate (<7), High (<9), Critical (>=9)
  • SECURITY.md documents how to report; it does not itself create advisories

Study Checklist

  • I can walk through the full coordinated disclosure lifecycle
  • I know the difference between SECURITY.md and a security advisory
  • I can describe the reporter flow for private vulnerability reporting
  • I know how advisories drive Dependabot alerts downstream
  • I can state the CVSS severity buckets