GitHub Action for OSPS Baseline

This repo provides a GitHub Action for running OSPS (Open Source Project Security) Baseline assessments on your GitHub repository. This action evaluates your repository against security controls defined in the Open Source Project Security Baseline and can optionally upload results to GitHub's Security tab as SARIF files.

Features

• Automated security assessments against OSPS Baseline controls
• Multiple output formats: YAML, JSON, or SARIF
• Direct integration with GitHub Security tab via SARIF upload

Results

Usage

Basic Example

name: OSPS Security Assessment

on:
  schedule:
    - cron: "0 9 * * 1"  # Weekly on Mondays at 9 AM UTC
  workflow_dispatch:  # Allow manual triggering

jobs:
  osps-assessment:
    runs-on: ubuntu-latest
    
    permissions:
      contents: read
      security-events: write  # Required for SARIF upload
    
    steps:
      - name: Checkout repository
        uses: actions/checkout@v6
      
      - name: Open Source Project Security Baseline Scanner
        uses: revanite-io/osps-baseline-action@v1.3.2
        with:
            owner: ${{ github.repository_owner }}
            repo: ${{ github.event.repository.name }}
            token: ${{ secrets.PVTR_GITHUB_TOKEN }}
            catalog: "osps-baseline-2026-02"
            upload-sarif: "true"
      
      - name: Upload Assessment Results
        if: always()
        uses: actions/upload-artifact@v7
        with:
          name: osps-assessment-results-${{ github.run_number }}
          path: evaluation_results/
          retention-days: 30

Inputs

Input	Description	Required	Default
owner	Repository owner (organization or user)	Yes	-
repo	Repository name	Yes	-
token	GitHub Personal Access Token with repo read permissions	Yes	-
catalog	Catalog ID to assess against (OSPS Baseline release bundled in the scanner; e.g. osps-baseline-2026-02)	No	osps-baseline-2026-02
output-format	Output format (yaml, json, or sarif)	No	yaml
upload-sarif	Upload results as SARIF to GitHub Security tab. When true, output-format is automatically set to sarif	No	false
sarif-only-failures	Upload only failed controls (error-level results) to GitHub Code Scanning. Needs-review and passed controls stay in the workflow summary and results files. Set to false to upload all results	No	true
fail-on-error	Fail the workflow if any controls have errors. When false, results are reported but the step always passes	No	false

Catalog Input (catalog)

The catalog input identifies which OSPS Baseline catalog version to run. Catalogs are versioned in the scanner and map to specific baseline releases.

Examples:

• osps-baseline-2026-02 (current default in this action)
• osps-baseline-2025-10 (older baseline release)

How to choose a compatible value:

1. Pin your scanner image/source version.
2. Use a catalog ID that exists in that scanner version.
3. Prefer newer catalog IDs unless you need compatibility with older reporting.

NOTE: If the catalog does not exist in the scanner version you run, the scan may produce empty results or no parsed control findings.

Examples in this README use the latest tagged action release (v1.3.2). For production workflows, pin to a commit SHA for deterministic behavior.

Requirements

Your GitHub Personal Access Token needs repository read permissions. For public repositories, you can use the repo scope, or public_repo for public repos only. An additional check for multi-factor authentication will run if your token includes admin:org permissions.

Creating a PAT

1. Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
2. Generate a new token with repo scope (or public_repo for public repositories)
3. Add the token as a secret in your repository (Settings → Secrets and variables → Actions)
4. Reference it by name in your workflow, such as ${{ secrets.PVTR_GITHUB_TOKEN }}

Output Formats

• YAML (Default): Human-readable format, suitable for local review and CI/CD pipelines
• JSON: Machine-readable format, useful for programmatic processing and integration with other tools
• SARIF: Static Analysis Results Interchange Format, connects results to GitHub's Security tab

Security Tab Alerts and "Needs Review" Controls

The scanner marks controls it cannot fully verify as "Needs Review" and re-emits them on every scan by design (per Gemara, final interpretation belongs to the audit phase). GitHub Code Scanning opens an alert for every uploaded SARIF result and only closes an alert when a later upload no longer contains it, so uploading "Needs Review" results creates alerts that never close.

For that reason, by default (sarif-only-failures: true) only failed controls are uploaded to the Security tab. Failed-control alerts open when a control fails and auto-close once a later scan no longer reports the failure. "Needs Review" and passed controls remain in the workflow step summary and in the evaluation_results output files.

If no controls failed, nothing is uploaded (GitHub rejects SARIF uploads with zero results) and the workflow summary is the place to review the assessment.

Avoid dismissing "Needs Review" alerts from older uploads: the results carry no fingerprints, so a dismissed alert can mask a later genuine failure of the same control. Set sarif-only-failures: false to restore the old upload-everything behavior.

FAQ

Q: Can I use GITHUB_TOKEN instead of a Personal Access Token?

A: Unfortunately, no. For running the OSPS plugin against public repositories, the builtin CI token does not have access to make API calls.

Q: Why isn't my SARIF file uploading to the Security tab?

A: There are several common reasons:

1. Missing permissions: Ensure your workflow includes security-events: write permission. Organization-level settings may also restrict security event uploads.
2. Invalid SARIF format: The action validates the SARIF file before upload. Check the workflow logs for any errors produced by the plugin
3. Plugin crash: Because of the reliance on API calls to collect data, the plugin occasionally encounters an error and needs to be re-run
4. User Permissions: If you are not authorized to view the security tab, it may have uploaded without your knowledge.

Q: What if I get permission errors when accessing files?

A: The action automatically fixes file permissions after the Docker container runs. If you still encounter permission issues:

• Ensure the workflow has write access to the workspace
• Check that the evaluation_results directory is created and writable
• Review the workflow logs for specific permission error messages

Q: Can I customize the maturity level being assessed?

A: Currently, the action assesses against "Maturity Level 1" by default. This is hardcoded in the action because higher maturity levels do not currently produce high-confidence results from the pvtr-github-repo plugin. You can use the plugin directly to access any assessments that are available.

Q: How do I troubleshoot a failed assessment?

A: Follow these steps:

1. Check workflow logs: Review the full workflow output for error messages
2. Verify token permissions: Ensure your token has the required repository read access
3. Check repository accessibility: Confirm the repository exists and is accessible with the provided token
4. Review artifact uploads: Download and inspect the evaluation_results artifact for detailed logs
5. Validate configuration: Ensure all required inputs are provided correctly

Contributing

Contributions are welcome! Please see our contributing guidelines for more information.

License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.

Related Projects

• Privateer - The core assessment engine
• Gemara - OSPS Baseline control definitions
• OSPS Baseline - Open Source Project Security Baseline specification