Skip to content
Tutorials Center
My learning

Topics

Lesson 25 of 36 ยท Security Features

Security Policy, Advisories and Supply-Chain Safety

Publish a SECURITY.md, handle private vulnerability reports and advisories, and harden your supply chain: pinned actions, minimal token permissions, SBOMs and attestations.

Finding problems is only part of security. You also need a way for other people to tell you about a problem privately, a way to publish a fix and warn users, and a build pipeline that attackers cannot easily hijack. This lesson covers the human side (policies and advisories) and the technical side (supply-chain hardening for your workflows).

SECURITY.md: tell people how to report

A file named SECURITY.md in the repository root, in .github/, or in docs/ is your security policy. GitHub links it from the Security tab and from the "new issue" screen, so a researcher who finds a flaw sees the right instructions instead of posting it publicly.

MARKDOWN
# Security Policy

## Supported versions

| Version | Supported |
| ------- | --------- |
| 2.x     | yes       |
| 1.x     | security fixes only until 2027-01-01 |
| < 1.0   | no        |

## Reporting a vulnerability

Please do not open a public issue. Use the "Report a vulnerability"
button on the Security tab, or email [email protected].
We acknowledge reports within 3 working days and aim to release
a fix within 30 days.

Good policies state supported versions, the private channel, expected response times, and whether you accept coordinated disclosure (you fix first, then announce together).

Private vulnerability reporting

Turn on Settings -> Advanced Security -> Private vulnerability reporting. A visitor then sees a Report a vulnerability button and fills a private form. Only maintainers see the report, and a conversation can happen there without leaking details. If the report is valid you can convert it into a draft security advisory in one click.

Repository security advisories

A security advisory is a published notice about a vulnerability in your project. The workflow:

  1. Draft the advisory under Security -> Advisories -> New draft: affected package and versions, patched version, severity (CVSS), a description and credits.
  2. Collaborate in private. A draft can create a temporary private fork where you and the reporter write and test the fix out of public view.
  3. Request a CVE identifier. GitHub is a CVE Numbering Authority, so you can request one directly from the advisory, or provide your own.
  4. Publish when the fixed version is released. The advisory becomes public, reaches the GitHub Advisory Database, and triggers Dependabot alerts for everyone who depends on you.

Publishing the fix and the advisory at the same time gives users the shortest window of exposure.

Supply-chain risks in a build pipeline

Your workflows run code from other repositories (uses:), install packages, and hold tokens. An attacker who compromises any of these can steal secrets or ship a malicious build. Four rules cut most of the risk.

1. Pin actions to a commit SHA

A tag such as @v4 can be moved by whoever controls that repository. A full 40-character commit SHA cannot. For third-party actions, pin the SHA and keep a comment with the human-readable version, and let Dependabot's github-actions ecosystem raise the pin when a new release appears:

YAML
- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2

Actions published by GitHub itself are lower risk, but pinning everything is the strict, consistent rule. Organizations can enforce it with an allowed-actions policy under Settings -> Actions -> General.

2. Give the token the least privilege

Set permissions: contents: read at the top of every workflow and raise it only in the job that needs more. A default read-only token limits damage if a step is compromised. See secrets and the GITHUB_TOKEN.

3. Never feed untrusted input to a shell

Issue titles, branch names and pull request bodies are controlled by outsiders. Pass them through env variables, not directly inside run: text. Also be careful with pull_request_target and workflow_run: these run with access to secrets in the context of the base repository, so they must never check out and execute code from a fork's pull request.

4. Protect your release path

Require reviews on workflow files (use CODEOWNERS for .github/), restrict who can push tags, use environments with required reviewers for production deploys, and prefer OIDC over stored cloud keys.

The stand-in below is a tiny linter for these rules. It reads a simplified workflow object (not real YAML parsing) and reports problems. It is a teaching tool written for this lesson; real projects should use maintained tools such as zizmor or actionlint, plus CodeQL's workflow queries.

JS Stand-in: workflow security linter (simplified)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

SBOMs and attestations

A software bill of materials (SBOM) is a machine-readable list of every component in a build. From the dependency graph you can Export SBOM in SPDX format (the repository's Insights -> Dependency graph page, or the API), which customers and compliance teams increasingly request.

An artifact attestation is a signed statement saying "this file was built from this commit by this workflow". The actions/attest-build-provenance action creates one using Sigstore, and users verify it with gh attestation verify. With provenance, a downloaded binary can be traced back to the exact source and pipeline that produced it, which defeats many tampering attacks. It needs the permissions id-token: write and attestations: write.

Four habits for a safe pipeline

Pin Actions by commit SHA
Least privilege Read-only token by default
Untrusted input Pass through env, not run
Provenance SBOM and attestations

Small defaults prevent big incidents.

1 / 2

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where does GitHub look for a security policy file?

    A SECURITY.md in one of those folders is shown on the Security tab.
  2. 2. Why pin a third-party action to a full commit SHA?

    An immutable reference prevents a maintainer, or an attacker who controls the repo, from swapping the code.
  3. 3. What happens when you publish a repository security advisory?

    Published advisories enter the GitHub Advisory Database and notify users of affected versions.
  4. 4. Which is the safest way to use a pull request title in a shell step?

    An env variable keeps the title as data, so it cannot add commands to the script.

Summary

  • Add a SECURITY.md, turn on private vulnerability reporting, and handle problems with draft advisories.
  • Publish the advisory together with the fixed release so dependents get alerts quickly.
  • Pin actions to SHAs, minimize GITHUB_TOKEN permissions, treat event text as untrusted, and protect release paths.
  • SBOMs and artifact attestations let consumers verify what is in a build and where it came from.

Next: GitHub Pages: Hosting a Website