Skip to content

Home

CI CD ProjectTester SecurityPracticesChecker Best Practices Baseline

ByteOrderMarkerFormatter CICDLinter CICDSecurityChecker CaseConflictChecker CodeAnalyzer DeadCodeChecker DependencyChecker EndOfFileFormatter EndOfLineFormatter FuzzTester JSONFormatter JSONLinter LargeFileChecker MarkdownLinter MergeConflictChecker ModuleTestNamingChecker PythonLinter PythonOrderLinter SecretsChecker SecurityChecker ShellFormatter ShellLinter SpellChecker TOMLLinter TrailingWhitespaceFormatter TypeChecker XMLLinter YAMLLinter

PackageManager Pyrigger RemoteVersionController VersionControlHookManager VersionController

DocsBuilder PackageIndex ProgrammingLanguage License


A pyrig plugin that integrates OpenSSF functionality.


Overview

pyrig-openssf is a pyrig plugin that extends pyrig's generated GitHub Actions health-check workflow with OpenSSF Scorecard analysis. It also generates Best Practices assessment proposals and Security Insights metadata, and adds OpenSSF badges.

Install it as a development dependency, then run pyrig sync; plugin discovery applies the overrides automatically.

Installation

uv add pyrig-openssf --dev
uv run pyrig sync

The plugin requires Python 3.12 or newer.

Setup

Commit and push to your public GitHub repository's default branch. The Scorecard workflow publishes its results publicly.

The Best Practices and Baseline badges require a project entry on bestpractices.dev:

  1. Sign in with GitHub at bestpractices.dev.
  2. Create or open your project's entry.
  3. Review the generated assessment proposals and fill in any missing information.
  4. Submit the assessment once all required information is provided.

After completion, the badges should reflect the submitted assessment.

Reusable Security Practices workflow

The plugin adds a reusable .github/workflows/security-practices.yml workflow and calls it from the generated health-check workflow as the security-practices job.

The analyze job checks out the repository, runs the pinned OpenSSF Scorecard action, and uploads scorecard.sarif to GitHub code scanning. Scorecard result publication is enabled. The job has repository and Actions read permissions, code-scanning write permission, and OIDC permission for publication.

A separate check-alerts job runs after the upload and fails if the analyzed ref has any open Scorecard alerts, whether new or pre-existing. Fixed and dismissed alerts are excluded. API errors also fail the check; this is an alert gate, not a minimum overall Scorecard score.

The plugin extends pyrig's jobs_health_check() hook; pyrig automatically adds the reusable job to the aggregate health-check job's needs list. The aggregate health check therefore waits for Scorecard and the normal project checks, remaining the workflow's release gate.

Best Practices proposals

The plugin generates .bestpractices.json in the repository root. It contains status and justification fields for the OpenSSF Best Practices and Baseline assessments. Justifications link to the project's repository, policies, configuration, and workflows.

Answers reflect pyrig conventions and opinionated defaults. They can be Met, Unmet, or N/A; criteria without a proposed answer are omitted. These are proposals, not the results of a comprehensive compliance audit. Review their applicability and evidence for your project before accepting them.

To customize an answer, subclass BestPracticesConfigFile in your project's pyrig configuration package and override the corresponding justification_<criterion> method. Each method returns a (status, justification) tuple. Override justifications() to change which criteria are generated, then run pyrig sync again.

Customize the generator rather than editing its generated answers directly: synchronization reapplies the configured defaults.

Security Insights metadata

The plugin generates security-insights.yml in the repository root using the Security Insights schema. It describes:

  • Project identity, contacts, documentation, and vulnerability reporting.
  • Repository status, license, contribution policies, and release channels.
  • A security-controls self-assessment and security champion contact.
  • Security tools, their configuration links, and declared integrations.

The defaults describe a typical pyrig-managed project. Review contacts, repository assumptions, and tool integrations for your project. Tool results objects are empty by default; the plugin does not invent signed result attestations or artifact URLs.

Override the section builders on SecurityInsightsConfigFile to customize the metadata, then run pyrig sync. Existing review and update dates are preserved; missing dates default to the current UTC date. Keep those dates accurate when reviewing or changing the metadata.

This file is machine-readable security metadata, not a separate badge application, and does not automatically complete a Best Practices assessment.

How it works

The plugin adds its own configuration and tool classes:

  • BestPracticesConfigFile to generate assessment answers and evidence links.
  • SecurityInsightsConfigFile to generate security metadata.
  • SecurityPracticesWorkflowConfigFile to generate Scorecard analysis and the alert gate.
  • SecurityPracticesChecker to represent Scorecard and add the three OpenSSF badges.

It also subclasses pyrig's HealthCheckWorkflowConfigFile to include the security-practices job, and SecretsChecker to exclude only the generated .bestpractices.json file from detect-secrets scanning. Other files remain subject to the normal scanner configuration.

API Reference

For class- and method-level details, see the API Reference, generated automatically from the source.