# Add OpenSSF Scorecard to a Python Project

Yes. An agent adds the OpenSSF Scorecard workflow to your Python project, publishes results to code scanning, adds the badge, lints it with zizmor and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-openssf-scorecard/python/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent clones the repository into its own cloud sandbox and reads the security posture the project already has before it adds a workflow that measures it. In a project like psf/requests, `.github/workflows/` holds `run-tests.yml` with a matrix of Python 3.10 through 3.15-dev plus PyPy across three operating systems, `lint.yml` running `pre-commit` pinned at a version, `typecheck.yml`, `codeql-analysis.yml` on a weekly cron, `zizmor.yml` scanning the workflows themselves, and `publish.yml` on `v*` tags. Every action is pinned to a full commit SHA with the version in a trailing comment, every `checkout` sets `persist-credentials: false`, and each workflow starts with `permissions: contents: read`. `.github/dependabot.yml` updates actions and pre-commit hooks weekly with a seven day cooldown, and the repository carries `SECURITY.md`, `CODEOWNERS` and an `AI_POLICY.md`. `README.md` has badges for the PyPI version, supported versions, downloads, contributors and docs, and nothing from Scorecard.

It writes `.github/workflows/scorecard.yml` in the house style: on `push` to `main`, on a weekly `schedule`, and on `branch_protection_rule` so a change to protection re-scores the repository; `permissions: read-all` at the top and, on the one job, `security-events: write` to upload results and `id-token: write` because `publish_results: true` signs the upload. The steps are `actions/checkout` with `persist-credentials: false`, `ossf/scorecard-action` with `results_file: results.sarif`, `results_format: sarif` and `publish_results: true`, `actions/upload-artifact` with a five day retention, and `github/codeql-action/upload-sarif` so each check lands in the code scanning tab beside the CodeQL alerts. Each action is pinned to its full commit SHA with the tag in a comment, which is also what the Scorecard's own pinned-dependencies check looks for.

It adds the Scorecard badge to `README.md` after the documentation badge, pointing at `api.scorecard.dev` for the image and the public viewer for the link, both keyed on the repository path. Dependabot's existing `github-actions` entry covers the three new pinned actions without a change, and because the new workflow is itself a workflow, `zizmor.yml` scans it on the pull request.

In the sandbox the agent installs `zizmor` and runs it on the new file to catch what the repository's own scanner would flag, runs `actionlint`, and checks the YAML against the conventions of the sibling workflows. It cannot run Scorecard itself, which reads the repository through GitHub's API from the workflow, so the pull request says the first results arrive on the first `main` run after merge, and lists the checks the repository is likely already prepared for, pinned actions, token permissions, a dependency update tool, SAST through CodeQL and a security policy, along with the one it may flag: the unhashed `pip install -r requirements-dev.txt` behind `make init`.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add the OpenSSF Scorecard workflow to this Python project. Read every file under .github/workflows, .github/dependabot.yml and README.md first and match their conventions. Write .github/workflows/scorecard.yml that runs on push to main, a weekly schedule and branch_protection_rule, with read-all permissions and only security-events and id-token write on the job, runs ossf/scorecard-action with SARIF output and publish_results enabled, uploads the SARIF as an artifact and to code scanning, and pins every action to a full commit SHA with the version in a comment. Add the Scorecard badge to the README next to the existing badges. Run zizmor and actionlint on the new workflow in your sandbox and open a pull request that says which Scorecard checks the repository already satisfies and which it may fail.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request on its own branch that adds `.github/workflows/scorecard.yml` and changes `README.md`. The description explains each trigger and permission, lists the pinned SHAs with their tags, pastes the `zizmor` and `actionlint` output from the sandbox, and gives a short table of Scorecard checks with what in the repository answers each one and where it expects a lower mark.

The run's record keeps the sandbox commands with their output beside the diff, and the repository's own `zizmor.yml` and lint workflows run on the pull request, so a reviewer sees the new file pass the same scanners as every other workflow before merge.

Before merging, a reviewer confirms code scanning is enabled on the repository so the SARIF upload has somewhere to go, decides whether the badge belongs in the README of a project this visible, and after the first `main` run reads the score in the viewer and files the follow-ups the agent predicted.

## Run it on every new repository in your organization

GitHub signs its webhooks and cannot add the `Authorization` header a Rush `webhook` trigger requires, so a handler on your server receives the organization's `repository` event, checks the signature and sends this body to `POST /o/{org}/sessions` with the new repository in `resources`. It sends a `request_id` that is a UUID v5 of the delivery id, so a redelivery returns the run already started.

With a `webhook_url` on the key, Rush posts `run.completed` with the `session_url` when the turn ends, and the handler reads the pull request from the session and posts it where the repository's owners will see it. Each Python project in the organization then gets Scorecard, pinned to the same SHAs, in its first week.

## Why run it on Rush?

The Scorecard workflow is short, but the places it goes wrong are exactly what it measures: an action pinned to a tag instead of a SHA, write permissions at the workflow level, a missing `id-token` scope that makes publishing fail silently, or a style that the repository's own workflow scanner rejects. The agent reads the sibling workflows, writes the new one to match, and runs the same scanners on it in its own sandbox before the pull request exists.

Every command and its output stays in the run's record, so the reviewer reads the real `zizmor` result rather than a promise. Several projects can get the workflow at once in separate sandboxes, each ending in its own pull request pinned to the same commits.

## Frequently asked questions

### Does the workflow need a token or secret?

No. The default `GITHUB_TOKEN` is enough for a public repository; `publish_results` uses the job's `id-token: write` scope to sign the upload. A personal token is only needed if you want classic branch protection settings reflected in the score, and the pull request leaves that out.

### Why can the agent not run Scorecard in the sandbox?

The action reads the repository, its workflows and its protection rules through GitHub's API from inside a workflow run on the default branch. The sandbox can lint and scan the new file, which it does, and the first real score appears on the first `main` run after merge.

### Will this show up in the code scanning tab?

Yes. The SARIF upload step files one entry per Scorecard check next to the CodeQL alerts the repository already has, so the same tab shows both. Code scanning has to be enabled on the repository for the upload to be accepted.

### What is the repository likely to be marked down for?

The pull request names what it found: the `make init` target installs from `requirements-dev.txt` without hashes, which the pinned-dependencies check counts, and anything the agent could not see from the clone, such as branch protection, is left for the first run to answer.

## More Python jobs

- [Add pip-audit to a Python Project's CI](https://getrush.ai/run/add-pip-audit-to-ci/python/)
- [Add Pre-commit Hooks to a Python Project](https://getrush.ai/run/add-pre-commit-hooks/python/)
- [Add towncrier Changelog Fragments to a Python Package](https://getrush.ai/run/add-towncrier-changelog/python/)

## The same job on other stacks

- [Add OpenSSF Scorecard to a TypeScript Library](https://getrush.ai/run/add-openssf-scorecard/typescript-library/)
- [Add OpenSSF Scorecard to a Repository with GitHub Actions](https://getrush.ai/run/add-openssf-scorecard/github-actions/)

## More jobs like this: Hand off a long task

- [Add OpenTelemetry Tracing to an Actix Web App](https://getrush.ai/run/add-opentelemetry/actix/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
