Home¶
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¶
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:
- Sign in with GitHub at bestpractices.dev.
- Create or open your project's entry.
- Review the generated assessment proposals and fill in any missing information.
- 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:
BestPracticesConfigFileto generate assessment answers and evidence links.SecurityInsightsConfigFileto generate security metadata.SecurityPracticesWorkflowConfigFileto generate Scorecard analysis and the alert gate.SecurityPracticesCheckerto 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.