search

ossf / scorecard-monitor

Simplify OpenSSF Scorecard tracking in your organization with automated markdown and JSON reports, plus optional GitHub issue alerts
https://github.com/marketplace/actions/openssf-scorecard-monitor
Apache License 2.0
31 stars 6 forks source link
github-actions open-source-management openssf-scorecard security security-audit security-tools

readme

OpenSSF Scorecard Monitor

Simplify OpenSSF Scorecard tracking in your organization with automated markdown and JSON reports, plus optional GitHub issue alerts.

This project is part of OpenSSF Scorecard. Read the announcement for more details.

🔮 About

If you're feeling overwhelmed by an avalanche of scorecards across your organizations, you can breathe easy: automation is here to make your life easier! Scorecard Monitor streamlines the process of keeping track of them all by providing a comprehensive report in Markdown and a local database in JSON with all the scores. To stay on top of any changes in the scores, you can also choose to get notifications through Github Issues.

✅ Requirements

Please ensure that any repository you wish to track with Scorecard Monitor has already been analyzed by OpenSSF Scorecard at least once. This can be accomplished using the official GitHub Action or the Scorecard CLI.

It's also possible that some repositories in your organization are already being automatically tracked by OpenSSF in this CSV file via weekly cronjob. One caveat: Automatically tracked projects do not include certain checks in their analysis (CI-Tests,Contributors,Dependency-Update-Tool,Webhooks).

If you're not sure whether a specific project is already using OpenSSF Scorecard, you can always spot-check with the following URL pattern: https://securityscorecards.dev/viewer/?uri=github.com/<ORG_NAME>/<REPO_NAME> (substitute <ORG_NAME> and <REPO_NAME> as appropriate). The Scorecard API is also able to fetch scores for a given repository.

📺 Tutorial

This section is coming soon. If you would like to contribute to the documentation, please feel free to open a pull request for review.

❤️ Awesome Features

🎉 Demo

Sample Report

sample report

_Sample report_

Sample Issue

sample issue preview

Sample issue

:shipit: Used By

📡 Usage

Standalone with auto-discovery version

With the following workflow, you will get the most out of this action:

name: "OpenSSF Scoring"
on: 
  # Scheduled trigger
  schedule:
    # Run every Sunday at 00:00
    - cron: "0 0 * * 0"
  # Manual trigger
  workflow_dispatch:

permissions:
  # Write access in order to update the local files with the reports
  contents: write
  # Write access only required if creating PRs (see Advanced Tips below)
  pull-requests: none 
  # Write access in order to create issues
  issues: write
  packages: none

jobs:
  security-scoring:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: OpenSSF Scorecard Monitor
        uses: ossf/scorecard-monitor@v2.0.0-beta8
        with:
          scope: reporting/scope.json
          database: reporting/database.json
          report: reporting/openssf-scorecard-report.md
          auto-commit: true
          auto-push: true
          generate-issue: true
          # The token is needed to create issues, discovery mode and pushing changes in files
          github-token: ${{ secrets.GITHUB_TOKEN }}
          discovery-enabled: true
          # As an example nodejs Org and Myself
          discovery-orgs: 'UlisesGascon,nodejs'

Options

Outputs

name: "OpenSSF Scoring"
on: 
  # ...

permissions:
  # ...

jobs:
  security-scoring:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: OpenSSF Scorecard Monitor
        uses: ossf/scorecard-monitor@v2.0.0-beta8
        id: openssf-scorecard-monitor
        with:
          # ....
      - name: Print the scores
        run: |
          echo '${{ steps.openssf-scorecard-monitor.outputs.scores }}'

🚀 Advanced Tips

Avoid committing directly to the branch and instead generate a PR

If you have implemented the recommended branch protection rules from the OpenSSF Scorecard, committing and pushing directly to the main branch will be impossible. An easy alternative is to extend the pipeline to automatically generate a PR for you:

name: "OpenSSF Scoring"
on: 
  # ...

permissions:
  contents: write
  pull-requests: write
  issues: write
  packages: none

jobs:
  security-scoring:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: OpenSSF Scorecard Monitor
        uses: ossf/scorecard-monitor@v2.0.0-beta8
        id: openssf-scorecard-monitor
        with:
          auto-commit: false
          auto-push: false
          generate-issue: true
          # ....
      - name: Print the scores
        run: |
          echo '${{ steps.openssf-scorecard-monitor.outputs.scores }}'
      - name: Create Pull Request
        uses: peter-evans/create-pull-request@38e0b6e68b4c852a5500a94740f0e535e0d7ba54 # v4.2.4
        with:
            token: ${{ secrets.GITHUB_TOKEN }}
            commit-message: OpenSSF Scorecard Report Updated
            title: OpenSSF Scorecard Report Updated
            body: OpenSSF Scorecard Report Updated
            base: main
            assignees: ${{ github.actor }}
            branch: openssf-scorecard-report-updated
            delete-branch: true

Embed Report version

If you want to mix the report in markdown format with other content, then you can use report-tags-enabled=true then report file will use the tags to add/update the report summary without affecting what is before or after the tagged section.

This is very useful for static websites, here is an example using docusaurus.

Custom tags

By default we use <!-- OPENSSF-SCORECARD-MONITOR:START --> and <!-- OPENSSF-SCORECARD-MONITOR:END -->, but this can be customize by adding your custom tags as report-start-tag and report-end-tag

Increase HTTP request in parallel

You can control the amount of parallel requests performed against the OpenSSF Scorecard Api by defining any numerical value in max-request-in-parallel, like max-request-in-parallel=15.

By default the value is 10, higher values might not be a good use of the API and you can hit some limits, please check with OpenSSF if you want to rise the limits safely.

Exclude repos

In some scenarios we want to enable the auto-discovery mode but we want to ignore certain repos, the best way to achieve that is by editing the scope.json file and add any report that you want to ignore in the excluded section for that specific organization.

🍿 Other

Scoping Structure

Just for reference, the scope will be stored this way:

File: reporting/scope.json

{
    "github.com": {
      "included": {
        "UlisesGascon":[
          "tor-detect-middleware", 
          "check-my-headers", 
          "express-simple-pagination"
        ]
      },
      "excluded": {
        "UlisesGascon": [
          "demo-stuff"
        ]
      }
    }

}

Database structure

Just for reference, the database will store the current value and previous values with the date:

{
  "github.com": {
    "UlisesGascon": {
      "check-my-headers": {
        "previous": [ {
          "score": 6.7,
          "date": "2022-08-21"
        }],
        "current": {
          "score": 4.4,
          "date": "2022-11-28"
        }
      }
    }
  }
}

💪 Contributing

Please read CONTRIBUTING.md for details on our code of conduct and the process for submitting pull requests to us. You need to accept DCO 1.1 in order to make contributions.