Meet the OpenSSF OSPS Baseline as a maintainer: the levels, every Level 1 control on GitHub, and the evidence

The Open Source Project Security Baseline (OSPS Baseline) is a list of MUST statements for open-source projects, maintained by the OpenSSF. Versions are dated: v2025.02.25, v2025.10.10, v2026.02.19 and the current v2026.08.28, released on 28 August 2026. The project says previous versions are for historical reference and only the current one should be used for new compliance efforts, so pin the version in every claim. The v2026.08.28 release added no controls; it let OSPS-LE-03.01 accept a LICENSES/ directory and moved the mappings to other frameworks into machine-readable Gemara documents. The previous release retired OSPS-BR-01.02 and added OSPS-BR-01.03, OSPS-DO-07.01 and OSPS-BR-01.04.

Each requirement belongs to a control and a family: OSPS-AC-03.01 is the first requirement of control 03, Protect the Primary Branch from Accidental Modification, in the Access Control family. Each requirement lists the maturity levels it applies to. Level 1 is for any code or non-code project with any number of maintainers or users; Level 2 is for a code project with at least two maintainers and a small number of consistent users; Level 3 is for a code project with a large number of consistent users. The published checklist files each requirement under the first level it applies to: 24 at Level 1, 19 at Level 2 and 21 at Level 3.

The Baseline is not a score and not a comparison between projects; its FAQ says so directly. Nothing requires you to meet it unless a sponsoring organization such as a foundation does, but every project is encouraged to meet Level 1. Compliance is self-attested and point in time, so write the claim the way the FAQ suggests: as of 11 October 2026, this project complies with OSPS Baseline version 2026.08.28, Level 1. Some controls depend on admin-only settings that a consumer can't see, which is why the evidence you keep matters more than a badge.

The table counts the active requirements in each family by the level at which they first apply. Most Level 1 requirements also list Levels 2 and 3; if you script against the catalog YAML, note that in v2026.08.28 OSPS-BR-07.01 and OSPS-VM-02.01 list only Level 1, although the published checklist and the requirements' purpose apply them at every level.

Level 1 is the floor the Baseline asks every project to reach. On GitHub most of it is a setting or a file. The evidence column says what to keep: an API export, a file at a path, or a scan result, dated. /domains/supply-chain/ci-cd/source-repository-protection/ has the ruleset JSON and the commands to apply it, and /domains/supply-chain/ci-cd/github-actions-hardening/ covers the workflow patterns behind OSPS-BR-01.01 and OSPS-BR-01.03.

Several requirements depend on things an API can't infer: which channels are official, which repositories belong to the project, where the support policy and the self-assessment are. The Baseline's maintainer guidance points to the OpenSSF Security Insights specification for this, and the Privateer scanner reads the file for many controls. Put security-insights.yml at the repository root or in .github/. The example below uses schema 2.2.0 (January 2026) and records the evidence for OSPS-BR-03.02, OSPS-QA-04.01, OSPS-VM-02.01, OSPS-DO-05.01 and the self-assessment behind OSPS-SA-03.01.

Validate it before you publish it. With CUE 0.17.1 and the specification's schema.cue from the v2.2.0 tag, cue vet -c -d '#SecurityInsights' schema.cue security-insights.yml exits 0 for this file and fails with the field name when a required value such as reports-accepted is missing or status is not one of the allowed values. Update last-reviewed whenever you review it, because a stale file is evidence of nothing.

header:
  schema-version: 2.2.0
  last-updated: '2026-10-11'
  last-reviewed: '2026-10-11'
  url: https://github.com/example-org/tidepool/raw/main/security-insights.yml
project:
  name: tidepool
  administrators:
    - name: Ana Ruiz
      affiliation: Example Org
      email: ana@example.org
      primary: true
  repositories:
    - name: tidepool
      url: https://github.com/example-org/tidepool
      comment: The library and its command-line tool; the only codebase in this project.
  vulnerability-reporting:
    reports-accepted: true
    bug-bounty-available: false
    policy: https://github.com/example-org/tidepool/blob/main/SECURITY.md
    contact:
      name: tidepool security team
      email: security@example.org
      primary: true
  documentation:
    quickstart-guide: https://github.com/example-org/tidepool/blob/main/README.md
    support-policy: https://github.com/example-org/tidepool/blob/main/SUPPORT.md
    signature-verification: https://github.com/example-org/tidepool/blob/main/docs/verify.md
repository:
  url: https://github.com/example-org/tidepool
  status: active
  accepts-change-request: true
  accepts-automated-change-request: true
  core-team:
    - name: Ana Ruiz
      primary: true
    - name: Ben Okafor
      primary: false
  license:
    url: https://github.com/example-org/tidepool/blob/main/LICENSE
    expression: Apache-2.0
  documentation:
    contributing-guide: https://github.com/example-org/tidepool/blob/main/CONTRIBUTING.md
    dependency-management-policy: https://github.com/example-org/tidepool/blob/main/docs/dependencies.md
    governance: https://github.com/example-org/tidepool/blob/main/GOVERNANCE.md
    security-policy: https://github.com/example-org/tidepool/blob/main/SECURITY.md
  release:
    automated-pipeline: true
    distribution-points:
      - uri: https://github.com/example-org/tidepool/releases
        comment: Signed release archives with SLSA provenance and an SBOM.
    changelog: https://github.com/example-org/tidepool/releases/tag/v{version}
  security:
    assessments:
      self:
        comment: Threat model and security self-assessment, reviewed at each minor release.
        evidence: https://github.com/example-org/tidepool/blob/main/docs/security-assessment.md
        date: '2026-09-30'
    tools:
      - name: osv-scanner
        type: SCA
        rulesets: [default]
        integration: {adhoc: false, ci: true, release: true}
        results: {}

Level 2 assumes at least two maintainers and regular users, so it adds the controls that keep a release trustworthy when more than one person can ship. The table covers the ones that change settings or pipelines. The rest are documents: OSPS-DO-06.01 (how you select, obtain and track dependencies), OSPS-DO-07.01 (build instructions), OSPS-GV-01.01 and OSPS-GV-01.02 (members with access to sensitive resources, and roles), OSPS-GV-03.02 (requirements for acceptable contributions), OSPS-SA-01.01 and OSPS-SA-02.01 (design documentation of actors and actions, and external interfaces), OSPS-BR-02.01 (a unique version for each release) and OSPS-BR-05.01 (standard dependency tooling).

These workflows meet OSPS-AC-04.02 (every job asks for only the permissions it needs, under an empty top-level default), OSPS-QA-06.01, OSPS-BR-06.01 and OSPS-QA-02.02. The pull-request workflow runs the tests and the dependency review action, which fails on a newly added dependency with a high or critical advisory or a license outside the allowlist; it runs on public repositories, and on private ones with GitHub Code Security. The release workflow attests the archives twice with actions/attest: once for SLSA build provenance and once for the CycloneDX SBOM. Actions are pinned to full commit SHAs with the version in a comment. Both files pass actionlint 1.7.12.

Require the test and dependency-review checks in the default-branch ruleset, and add the ruleset rule Require code scanning results with CodeQL so a new high-severity finding blocks the merge. That pair is the automated enforcement OSPS-VM-05.03 and OSPS-VM-06.02 ask for at Level 3, alongside the written thresholds in OSPS-VM-05.01, OSPS-VM-05.02 and OSPS-VM-06.01.

name: pull-request
on:
  pull_request:
    branches: [main]
permissions: {}
jobs:
  test:
    runs-on: ubuntu-24.04
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
      - run: make test
  dependency-review:
    runs-on: ubuntu-24.04
    permissions:
      contents: read
    steps:
      - uses: actions/dependency-review-action@a1d282b36b6f3519aa1f3fc636f609c47dddb294 # v5.0.0
        with:
          fail-on-severity: high
          allow-licenses: Apache-2.0, BSD-2-Clause, BSD-3-Clause, ISC, MIT
---
name: release
on:
  push:
    tags: ['v*']
permissions: {}
jobs:
  release:
    runs-on: ubuntu-24.04
    permissions:
      contents: write
      id-token: write
      attestations: write
      artifact-metadata: write
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
      - run: make dist
      - uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2
        with:
          subject-path: dist/*.tar.gz
      - uses: actions/attest@1e69f48acb82d1966a394da916b4c1698aa569d6 # v4.2.2
        with:
          subject-path: dist/*.tar.gz
          sbom-path: dist/sbom.cdx.json
      - run: gh release create "$GITHUB_REF_NAME" dist/* --verify-tag --notes-file dist/release-notes.md
        env:
          GH_TOKEN: ${{ github.token }}

Level 3 is for projects with a large number of consistent users, where a compromise reaches many people. Its requirements mostly turn Level 2 practices into enforced rules and published commitments.

• OSPS-QA-07.01: at least one non-author human approval before merging to the primary branch. Require one approval in the ruleset, with Require approval of the most recent reviewable push, so the approved revision is the merged one; a single-maintainer project can't meet this.
• OSPS-VM-05.03 and OSPS-VM-06.02: every change is evaluated against a documented policy for vulnerable and malicious dependencies and for code weaknesses, and blocked on violation unless declared non-exploitable. The required checks above do this; the policy documents are OSPS-VM-05.01, OSPS-VM-05.02 and OSPS-VM-06.01.
• OSPS-QA-02.02: every compiled release asset ships with an SBOM. /domains/supply-chain/sbom/generate-release-inventory/ covers generating one per release.
• OSPS-DO-03.01 and OSPS-DO-03.02: documentation explains how to verify release integrity and authenticity, and the expected identity of the signer. Name the repository and the signing workflow, not only the tool, and keep the instructions outside the release pipeline so one breach can't change both.
• OSPS-VM-04.02: vulnerabilities in components that don't affect the project are recorded in a VEX document. /domains/supply-chain/vex/producer-and-consumer-decisions/ covers writing the statements.
• OSPS-DO-04.01 and OSPS-DO-05.01: a statement of the scope and duration of support for each release, and when releases stop getting security updates, in SUPPORT.md or SECURITY.md.
• OSPS-SA-03.02: threat modeling and attack surface analysis of critical code paths, updated for new features.
• OSPS-GV-04.01, OSPS-BR-07.02 and OSPS-BR-01.04: a policy to review collaborators before granting escalated permissions, a policy for storing, accessing and rotating secrets, and sanitizing even trusted collaborators' manual workflow inputs such as workflow_dispatch values.
• OSPS-AC-04.02, OSPS-BR-02.02, OSPS-QA-04.02, OSPS-QA-06.02 and OSPS-QA-06.03: job-level least privilege, every release asset tied to the release identifier, subprojects held to the same rules, and documented testing practice and policy.

For OSPS-DO-03.02, the instructions must tell users who is expected to have produced the release. With GitHub artifact attestations that identity is the repository and the workflow file that signed the provenance. The commands below are the shape to publish; the same commands verify the GitHub CLI's own release: with gh 2.94.0, gh attestation verify gh_2.94.0_linux_arm64.tar.gz --repo cli/cli --signer-workflow cli/cli/.github/workflows/deployment.yml exits 0, and naming any other workflow file makes it fail. Add --source-ref when you know which branch or tag the release workflow runs from.

# Verify a tidepool release (example-org/tidepool) before you use it.
# 1. The archive is the one the release workflow built and attested:
gh attestation verify tidepool-1.4.0.tar.gz \
  --repo example-org/tidepool \
  --signer-workflow example-org/tidepool/.github/workflows/release.yml \
  --deny-self-hosted-runners
# 2. The SBOM attestation for the same archive:
gh attestation verify tidepool-1.4.0.tar.gz \
  --repo example-org/tidepool \
  --predicate-type https://cyclonedx.org/bom

Keep one dated record per requirement: its ID, its status, the evidence, and the date. The script below collects what GitHub's API shows for the Level 1 and Level 2 settings it can read, as JSON lines, and marks admin-only settings needs-admin instead of guessing. Run it with an authenticated gh and jq. On 11 October 2026 it reported pass for all ten readable rows on ossf/scorecard, whose default branch has an active ruleset with pull_request, deletion, non_fast_forward and required_status_checks rules, and needs-admin for its workflow permissions and push protection. On ossf/security-baseline, whose branch uses classic protection, the three branch rows were needs-admin; on octocat/Hello-World they failed, as did the license, CONTRIBUTING and SECURITY.md rows.

Keep the rest by hand: the organization MFA and base-permission exports, the workflow review behind OSPS-BR-01.01, links to documentation at the release tag, and the scanner output. Store the records with each release, and repeat the collection on a schedule so a quietly weakened setting shows up.

#!/usr/bin/env bash
# Record the OSPS Baseline v2026.08.28 evidence GitHub's API shows for one repository.
# Usage: ./osps-evidence.sh owner/repo > evidence.jsonl   (needs an authenticated gh and jq)
# "needs-admin" means the setting is only visible to a repository or organization admin.
set -euo pipefail
repo="$1"
emit() { jq -cn --arg id "$1" --arg status "$2" --arg evidence "$3" \
  '{baseline: "v2026.08.28", id: $id, status: $status, evidence: $evidence, checked: (now | todate)}'; }

meta=$(gh api "repos/$repo")
branch=$(jq -r .default_branch <<<"$meta")
rules=$(gh api "repos/$repo/rules/branches/$branch" --jq '[.[].type] | unique')
has_rule() { jq -e --arg t "$1" 'index($t) != null' <<<"$rules" >/dev/null && echo pass || echo fail; }
if [ "$rules" = "[]" ] && [ "$(gh api "repos/$repo/branches/$branch" --jq .protected)" = "true" ]; then
  # Classic branch protection is only readable with admin rights; rulesets are public.
  for id in OSPS-AC-03.01 OSPS-AC-03.02 OSPS-QA-03.01; do
    emit "$id" needs-admin "$branch is protected by a classic rule; export it with an admin token"
  done
else
  emit OSPS-AC-03.01 "$(has_rule pull_request)" "rules on $branch: $rules"
  emit OSPS-AC-03.02 "$(has_rule deletion)" "rules on $branch: $rules"
  emit OSPS-QA-03.01 "$(has_rule required_status_checks)" "rules on $branch: $rules"
fi

visibility=$(jq -r .visibility <<<"$meta")
emit OSPS-QA-01.01 "$([ "$visibility" = public ] && echo pass || echo fail)" "visibility: $visibility"
emit OSPS-GV-02.01 "$(jq -r 'if .has_issues or .has_discussions then "pass" else "fail" end' <<<"$meta")" \
  "issues: $(jq .has_issues <<<"$meta"), discussions: $(jq .has_discussions <<<"$meta")"

if license=$(gh api "repos/$repo/license" 2>/dev/null); then
  spdx=$(jq -r '.license.spdx_id // "NOASSERTION"' <<<"$license")
  emit OSPS-LE-03.01 pass "license file: $(jq -r .path <<<"$license")"
  free=$(curl -fsS https://spdx.org/licenses/licenses.json | jq -r --arg id "$spdx" \
    '[.licenses[] | select(.licenseId == $id and (.isOsiApproved or .isFsfLibre))] | length')
  emit OSPS-LE-02.01 "$([ "$free" = 1 ] && echo pass || echo manual)" "SPDX ID $spdx; OSI or FSF approved: $free"
else
  emit OSPS-LE-03.01 fail "no license file GitHub can find"
  emit OSPS-LE-02.01 fail "no license file GitHub can find"
fi

contributing=$(gh api "repos/$repo/community/profile" --jq '.files.contributing.html_url // empty')
emit OSPS-GV-03.01 "$([ -n "$contributing" ] && echo pass || echo fail)" "contributing guide: ${contributing:-none}"

policy=none
for path in SECURITY.md .github/SECURITY.md docs/SECURITY.md; do
  if gh api "repos/$repo/contents/$path" --silent 2>/dev/null; then policy=$path; break; fi
done
emit OSPS-VM-02.01 "$([ "$policy" != none ] && echo pass || echo fail)" "security policy: $policy"

pvr=$(gh api "repos/$repo/private-vulnerability-reporting" --jq .enabled)
emit OSPS-VM-03.01 "$([ "$pvr" = true ] && echo pass || echo manual)" \
  "private vulnerability reporting: $pvr (another private channel in SECURITY.md also counts)"

perm=$(gh api "repos/$repo/actions/permissions/workflow" --jq .default_workflow_permissions 2>/dev/null) || perm=unknown
case "$perm" in
  read) emit OSPS-AC-04.01 pass "default GITHUB_TOKEN permissions: read" ;;
  write) emit OSPS-AC-04.01 fail "default GITHUB_TOKEN permissions: write" ;;
  *) emit OSPS-AC-04.01 needs-admin "workflow permissions are not readable with this token" ;;
esac

push=$(jq -r '.security_and_analysis.secret_scanning_push_protection.status // "unknown"' <<<"$meta")
case "$push" in
  enabled) emit OSPS-BR-07.01 pass "secret scanning push protection: enabled" ;;
  disabled) emit OSPS-BR-07.01 fail "secret scanning push protection: disabled" ;;
  *) emit OSPS-BR-07.01 needs-admin "security_and_analysis is only returned to admins" ;;
esac

Automated tools help, but none of them can see every requirement, and the Baseline FAQ warns against treating tool output as the true security posture. Know what each one reads before you cite it as evidence.

The Baseline is written for the people who run a project, but its readers include the companies that depend on it. Its FAQ says a consumer can accept the project's self-attestation or make another arrangement, because some controls depend on settings only maintainers see. Make that easy: publish the claim with its version, level and date in the README or SECURITY.md, link the Security Insights file and the scanner output, and keep the per-requirement records available on request.

On the consumer side, the OpenSSF's Secure Supply Chain Consumption Framework describes how organizations take in open source, and /domains/supply-chain/dependencies/s2c2f-adoption/ walks through it. /domains/supply-chain/dependencies/project-health-and-intake/ shows how a consumer weighs signals such as Scorecard results when deciding to adopt a package.

Sources & further reading

The standards, specifications and documentation behind the guidance above. Each is the evidence for a claim on this page; consult it for detail beyond the defaults and versions listed here.

1. OpenSSF OSPS Baseline v2026.08.28 (controls, levels and recommendations). v2026.08.28 (28 August 2026).
2. OSPS Baseline v2026.08.28 checklist by level. v2026.08.28.
3. OSPS Baseline: versions and guiding principles
4. OSPS Baseline release notes. 2026-08-28 and 2026-02-19 entries.
5. OSPS Baseline FAQ (self-attestation, point-in-time claims, consumers)
6. OSPS Baseline: implementation guidance for maintainers
7. ossf/security-baseline: control catalog YAML at tag v2026.08.28. v2026.08.28.
8. OpenSSF Security Insights specification: schema.cue. v2.2.0 (31 January 2026).
9. Privateer plugin for GitHub repositories (OSPS Baseline scanner). v0.32.0 (9 October 2026).
10. OSPS Baseline Scanner GitHub Action. v1.5.2 (1 October 2026).
11. Minder rules and profiles: OpenSSF Security Baseline
12. OpenSSF Scorecard: OSPS Baseline coverage analysis. Written against Baseline v2026.02.19.
13. OpenSSF Scorecard v6 proposal: OSPS Baseline conformance
14. GitHub Docs: Available rules for rulesets
15. GitHub Docs: Managing GitHub Actions settings for a repository (workflow permissions)
16. GitHub Docs: Configuring private vulnerability reporting for a repository
17. GitHub blog: Push protection is generally available, and free for all public repositories. May 2023.
18. GitHub Docs: Managing the commit signoff policy for your organization
19. actions/attest: generate signed attestations (provenance and SBOM). v4.2.2.
20. GitHub Docs: About dependency review
21. SPDX License List (isOsiApproved and isFsfLibre). 3.29.0 (16 September 2026).

Reference information

Tags

Dependency managementSupply chain attacksCI/CD securitySecure development lifecycleSupplier and open source risk

SDLC phase

DevelopmentReleaseSecurity program

Role

Developers

Download this guide as Markdown

Continue exploring