OpenSSF Scorecard (ossf/scorecard)

OpenSSF Scorecard

https://github.com/ossf/scorecard
Admin
OpenSSF Scorecard is an automated tool that assesses open source project security practices through...

Tokens:43,090
Snippets:377
Trust Score:8.1
Update:2 months ago
Show doc for...
Context Summary (auto-generated)
Raw
# OpenSSF Scorecard

OpenSSF Scorecard is an automated security assessment tool that evaluates open source projects against a set of security best practices. Developed by the Open Source Security Foundation (OpenSSF), it analyzes repositories to help maintainers improve their security posture and helps consumers assess the risks of their dependencies. The tool runs security checks (heuristics) against GitHub, GitLab, and Azure DevOps repositories, assigning scores from 0-10 for each check and producing an aggregate weighted score based on risk levels (Critical, High, Medium, Low).

Scorecard can be used as a command-line interface, a Go library for programmatic integration, a GitHub Action for automated scanning on repository changes, or via a REST API for querying pre-calculated scores. It supports running individual probes for fine-grained analysis, configuring maintainer annotations to provide context for security findings, and outputting results in multiple formats including JSON, SARIF, and in-toto statements for integration with CI/CD pipelines and security tooling.

## Command Line Interface

The CLI provides the primary interface for running Scorecard checks against repositories. It supports GitHub, GitLab, Azure DevOps repositories, local directories, and package manager lookups.

```bash
# Basic usage - scan a GitHub repository
export GITHUB_AUTH_TOKEN=ghp_xxxx
scorecard --repo=github.com/ossf/scorecard

# Scan a GitLab repository
export GITLAB_AUTH_TOKEN=glpat-xxxx
scorecard --repo=gitlab.com/fdroid/fdroidclient

# Scan a local directory
scorecard --local=/path/to/local/repo

# Run specific checks only
scorecard --repo=github.com/ossf/scorecard --checks=Branch-Protection,Code-Review,Vulnerabilities

# Output in JSON format with details
scorecard --repo=github.com/ossf/scorecard --format=json --show-details

# Show maintainer annotations
scorecard --repo=github.com/ossf/scorecard --show-annotations

# Scan via package manager (npm, pypi, rubygems, nuget)
scorecard --npm=angular
scorecard --pypi=requests

# Scan a specific commit
scorecard --repo=github.com/ossf/scorecard --commit=abc123def456

# Use with GitHub Enterprise Server
export GH_HOST=github.corp.com
export GITHUB_AUTH_TOKEN=token
scorecard --repo=github.corp.com/org/repo

# Docker usage
docker run -e GITHUB_AUTH_TOKEN=token ghcr.io/ossf/scorecard:latest \
  --repo=github.com/ossf/scorecard --show-details
```

## Go Library - Run Function

The `scorecard.Run` function is the main entry point for programmatic usage, analyzing a repository and returning detailed results including check scores, raw data, and findings.

```go
package main

import (
    "context"
    "encoding/json"
    "fmt"
    "log"

    "github.com/ossf/scorecard/v5/clients/githubrepo"
    "github.com/ossf/scorecard/v5/pkg/scorecard"
    sclog "github.com/ossf/scorecard/v5/log"
)

func main() {
    ctx := context.Background()

    // Create a repository reference
    repo, err := githubrepo.MakeGithubRepo("ossf/scorecard")
    if err != nil {
        log.Fatalf("Failed to create repo: %v", err)
    }

    // Run scorecard with options
    result, err := scorecard.Run(ctx, repo,
        scorecard.WithCommitSHA("HEAD"),
        scorecard.WithCommitDepth(30),
        scorecard.WithLogLevel(sclog.InfoLevel),
        scorecard.WithChecks([]string{"Branch-Protection", "Code-Review", "Vulnerabilities"}),
    )
    if err != nil {
        log.Fatalf("Scorecard run failed: %v", err)
    }

    // Print results
    fmt.Printf("Repository: %s\n", result.Repo.Name)
    fmt.Printf("Commit: %s\n", result.Repo.CommitSHA)
    fmt.Printf("Scorecard Version: %s\n", result.Scorecard.Version)

    for _, check := range result.Checks {
        fmt.Printf("Check: %s, Score: %d/10, Reason: %s\n",
            check.Name, check.Score, check.Reason)
    }

    // Output JSON
    jsonBytes, _ := json.MarshalIndent(result, "", "  ")
    fmt.Println(string(jsonBytes))
}
```

## Creating Repository References

Scorecard supports multiple repository types through the `clients.Repo` interface. Each forge (GitHub, GitLab, Azure DevOps) and local directories have specific constructors.

```go
package main

import (
    "context"
    "fmt"
    "log"

    "github.com/ossf/scorecard/v5/clients/githubrepo"
    "github.com/ossf/scorecard/v5/clients/gitlabrepo"
    "github.com/ossf/scorecard/v5/clients/localdir"
    "github.com/ossf/scorecard/v5/pkg/scorecard"
)

func main() {
    ctx := context.Background()

    // GitHub repository - accepts "owner/repo" or full URL
    githubRepo, err := githubrepo.MakeGithubRepo("ossf/scorecard")
    if err != nil {
        log.Fatalf("GitHub repo error: %v", err)
    }
    fmt.Printf("GitHub URI: %s\n", githubRepo.URI())

    // GitLab repository - requires full host path
    gitlabRepo, err := gitlabrepo.MakeGitlabRepo("gitlab.com/fdroid/fdroidclient")
    if err != nil {
        log.Fatalf("GitLab repo error: %v", err)
    }
    fmt.Printf("GitLab URI: %s\n", gitlabRepo.URI())

    // Local directory
    localRepo, err := localdir.MakeLocalDirRepo("/path/to/local/repo")
    if err != nil {
        log.Fatalf("Local repo error: %v", err)
    }
    fmt.Printf("Local path: %s\n", localRepo.URI())

    // Run scorecard on any repo type
    result, err := scorecard.Run(ctx, githubRepo)
    if err != nil {
        log.Fatalf("Scorecard failed: %v", err)
    }

    fmt.Printf("Aggregate checks run: %d\n", len(result.Checks))
}
```

## Run Options Configuration

The `scorecard.Run` function accepts various options to customize the analysis, including commit selection, check filtering, probe execution, and custom clients.

```go
package main

import (
    "context"
    "log"

    "github.com/ossf/scorecard/v5/clients"
    "github.com/ossf/scorecard/v5/clients/githubrepo"
    "github.com/ossf/scorecard/v5/pkg/scorecard"
    sclog "github.com/ossf/scorecard/v5/log"
)

func main() {
    ctx := context.Background()

    repo, _ := githubrepo.MakeGithubRepo("ossf/scorecard")

    // Full options example
    result, err := scorecard.Run(ctx, repo,
        // Analyze specific commit (default: HEAD)
        scorecard.WithCommitSHA("abc123def456789"),

        // Number of commits to analyze (default: 30)
        scorecard.WithCommitDepth(50),

        // Set log level (default: InfoLevel)
        scorecard.WithLogLevel(sclog.DebugLevel),

        // Run only specific checks (default: all checks)
        scorecard.WithChecks([]string{
            "Binary-Artifacts",
            "Branch-Protection",
            "CI-Tests",
            "Code-Review",
            "Dangerous-Workflow",
            "Dependency-Update-Tool",
            "Fuzzing",
            "License",
            "Maintained",
            "Pinned-Dependencies",
            "SAST",
            "Security-Policy",
            "Signed-Releases",
            "Token-Permissions",
            "Vulnerabilities",
        }),

        // Run specific probes instead of checks
        scorecard.WithProbes([]string{
            "archived",
            "hasRecentCommits",
            "hasBinaryArtifacts",
        }),

        // Use git mode for file fetching (slower but handles .gitattributes)
        scorecard.WithFileModeGit(),

        // Custom vulnerability client
        scorecard.WithVulnerabilitiesClient(clients.DefaultVulnerabilitiesClient()),

        // Custom OpenSSF Best Practices client
        scorecard.WithOpenSSFBestPraticesClient(clients.DefaultCIIBestPracticesClient()),
    )
    if err != nil {
        log.Fatalf("Scorecard run failed: %v", err)
    }

    log.Printf("Analyzed %s at commit %s", result.Repo.Name, result.Repo.CommitSHA)
}
```

## Result Processing and Formatting

Scorecard results can be output in multiple formats: default text, JSON, SARIF, in-toto statements, and probe format. The library provides formatting functions for each.

```go
package main

import (
    "context"
    "os"

    "github.com/ossf/scorecard/v5/clients/githubrepo"
    docChecks "github.com/ossf/scorecard/v5/docs/checks"
    "github.com/ossf/scorecard/v5/options"
    "github.com/ossf/scorecard/v5/pkg/scorecard"
    sclog "github.com/ossf/scorecard/v5/log"
)

func main() {
    ctx := context.Background()
    repo, _ := githubrepo.MakeGithubRepo("ossf/scorecard")
    result, _ := scorecard.Run(ctx, repo)

    // Load check documentation
    checkDocs, _ := docChecks.Read()

    // Output as formatted text to stdout
    textOpts := &scorecard.AsStringResultOption{
        LogLevel:    sclog.InfoLevel,
        Details:     true,   // Show detailed findings
        Annotations: true,   // Show maintainer annotations
    }
    result.AsString(os.Stdout, checkDocs, textOpts)

    // Output as JSON
    jsonOpts := &scorecard.AsJSON2ResultOption{
        Details:     true,
        Annotations: true,
        LogLevel:    sclog.InfoLevel,
    }
    result.AsJSON2(os.Stdout, checkDocs, jsonOpts)

    // Output as SARIF for code scanning integration
    opts := &options.Options{
        ShowDetails: true,
        LogLevel:    "info",
    }
    result.AsSARIF(true, sclog.InfoLevel, os.Stdout, checkDocs, nil, opts)

    // Output as in-toto statement for supply chain security
    inTotoOpts := &scorecard.AsInTotoResultOption{
        AsJSON2ResultOption: scorecard.AsJSON2ResultOption{
            Details:  true,
            LogLevel: sclog.InfoLevel,
        },
    }
    result.AsInToto(os.Stdout, checkDocs, inTotoOpts)

    // Calculate aggregate score
    aggregateScore, _ := result.GetAggregateScore(checkDocs)
    // Score is weighted: Critical=10, High=7.5, Medium=5, Low=2.5
}
```

## RepoClient Interface

The `RepoClient` interface provides methods to query repository data. Custom implementations can be created for different forges or data sources.

```go
package main

import (
    "context"
    "fmt"
    "io"
    "log"

    "github.com/ossf/scorecard/v5/clients"
    "github.com/ossf/scorecard/v5/clients/githubrepo"
    sclog "github.com/ossf/scorecard/v5/log"
)

func main() {
    ctx := context.Background()

    // Create repo and client
    repo, _ := githubrepo.MakeGithubRepo("ossf/scorecard")
    client, _ := githubrepo.NewRepoClient(ctx,
        githubrepo.WithFileModeGit(), // Use git for file operations
    )

    // Initialize client with repo
    err := client.InitRepo(repo, clients.HeadSHA, 30)
    if err != nil {
        log.Fatalf("InitRepo failed: %v", err)
    }
    defer client.Close()

    // Query repository information
    uri := client.URI()
    fmt.Printf("Repository: %s\n", uri)

    archived, _ := client.IsArchived()
    fmt.Printf("Archived: %v\n", archived)

    defaultBranch, _ := client.GetDefaultBranchName()
    fmt.Printf("Default branch: %s\n", defaultBranch)

    createdAt, _ := client.GetCreatedAt()
    fmt.Printf("Created: %s\n", createdAt)

    // List files matching a predicate
    files, _ := client.ListFiles(func(path string) (bool, error) {
        return len(path) > 0, nil // Match all files
    })
    fmt.Printf("Total files: %d\n", len(files))

    // Read file content
    reader, err := client.GetFileReader("README.md")
    if err == nil {
        defer reader.Close()
        content, _ := io.ReadAll(reader)
        fmt.Printf("README length: %d bytes\n", len(content))
    }

    // List commits
    commits, _ := client.ListCommits()
    fmt.Printf("Recent commits: %d\n", len(commits))

    // List releases
    releases, _ := client.ListReleases()
    fmt.Printf("Releases: %d\n", len(releases))

    // List contributors
    contributors, _ := client.ListContributors()
    fmt.Printf("Contributors: %d\n", len(contributors))

    // Search for code patterns
    searchResult, _ := client.Search(clients.SearchRequest{
        Query: "func main",
    })
    fmt.Printf("Search hits: %d\n", searchResult.Hits)
}
```

## Policy File Configuration

Policy files allow defining required checks and minimum scores for SARIF output, enabling enforcement of security requirements in CI/CD pipelines.

```yaml
# policy.yml - Define required checks and minimum scores
version: 1
policies:
  Binary-Artifacts:
    score: 8
    mode: enforced
  Branch-Protection:
    score: 7
    mode: enforced
  Code-Review:
    score: 7
    mode: enforced
  Dangerous-Workflow:
    score: 9
    mode: enforced
  Dependency-Update-Tool:
    score: 5
    mode: enforced
  Fuzzing:
    score: 0
    mode: disabled  # Optional check
  License:
    score: 9
    mode: enforced
  Maintained:
    score: 5
    mode: enforced
  Pinned-Dependencies:
    score: 7
    mode: enforced
  SAST:
    score: 5
    mode: enforced
  Security-Policy:
    score: 8
    mode: enforced
  Signed-Releases:
    score: 5
    mode: enforced
  Token-Permissions:
    score: 8
    mode: enforced
  Vulnerabilities:
    score: 9
    mode: enforced
```

```bash
# Run with policy file (requires ENABLE_SARIF=1)
export ENABLE_SARIF=1
scorecard --repo=github.com/ossf/scorecard --policy=policy.yml --format=sarif
```

## Maintainer Annotations Configuration

Maintainers can add context to Scorecard results using annotation files, explaining security decisions or marking false positives.

```yaml
# scorecard.yml - Place in repo root, .scorecard.yml, or .github/scorecard.yml
annotations:
  # Annotate binary files used only for testing
  - checks:
      - binary-artifacts
    reasons:
      - reason: test-data  # Files are only used for testing

  # Annotate a dangerous workflow that requires approval
  - checks:
      - dangerous-workflow
    reasons:
      - reason: remediated  # Workflow runs only under maintainer approval

  # Annotate unpinned dependencies in library context
  - checks:
      - pinned-dependencies
    reasons:
      - reason: not-applicable  # Library should not pin dependencies

  # Annotate when using unsupported SAST tool
  - checks:
      - sast
    reasons:
      - reason: not-supported  # Using Clang-Tidy (not detected by Scorecard)

  # Multiple annotations for one check
  - checks:
      - binary-artifacts
    reasons:
      - reason: test-data       # test.exe for testing
      - reason: remediated      # vendor.exe has verified signature

  # Multiple checks with same annotation
  - checks:
      - binary-artifacts
      - pinned-dependencies
    reasons:
      - reason: test-data  # Both issues are in test directories
```

```bash
# View annotations in results
scorecard --repo=github.com/ossf/scorecard --show-annotations
```

## GitHub Action Integration

The Scorecard GitHub Action runs automatically on repository changes and uploads results to the Security tab.

```yaml
# .github/workflows/scorecard.yml
name: Scorecard Analysis

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  schedule:
    - cron: '0 0 * * 0'  # Weekly on Sunday
  workflow_dispatch:

permissions: read-all

jobs:
  analysis:
    name: Scorecard analysis
    runs-on: ubuntu-latest
    permissions:
      security-events: write  # Upload SARIF results
      id-token: write         # Publish results
      contents: read
      actions: read

    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          persist-credentials: false

      - name: Run Scorecard
        uses: ossf/scorecard-action@v2
        with:
          results_file: results.sarif
          results_format: sarif
          publish_results: true  # Enable badge and REST API

      - name: Upload SARIF results
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif
```

```markdown
<!-- Add badge to README.md -->
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/{owner}/{repo}/badge)](https://scorecard.dev/viewer/?uri=github.com/{owner}/{repo})
```

## REST API Usage

Query pre-calculated scores for projects via the Scorecard REST API at `api.scorecard.dev`.

```bash
# Get scorecard results for a repository
curl -s "https://api.scorecard.dev/projects/github.com/ossf/scorecard" | jq .

# Example response structure
{
  "date": "2024-01-15",
  "repo": {
    "name": "github.com/ossf/scorecard",
    "commit": "abc123"
  },
  "scorecard": {
    "version": "v5.0.0",
    "commit": "def456"
  },
  "score": 8.5,
  "checks": [
    {
      "name": "Binary-Artifacts",
      "score": 10,
      "reason": "no binaries found in the repo",
      "details": null
    },
    {
      "name": "Branch-Protection",
      "score": 9,
      "reason": "branch protection is not maximal on development and all release branches",
      "details": ["Info: 'force pushes' disabled on branch 'main'"]
    }
  ]
}

# Query via BigQuery for historical data
bq query --nouse_legacy_sql '
SELECT date, score, repo.name
FROM `openssf.scorecardcron.scorecard-v2_latest`
WHERE repo.name = "github.com/ossf/scorecard"
ORDER BY date DESC
LIMIT 10'
```

## Probes - Fine-Grained Analysis

Probes provide individual heuristics for fine-grained security assessment, returning true/false findings with optional locations.

```go
package main

import (
    "context"
    "fmt"
    "log"

    "github.com/ossf/scorecard/v5/clients/githubrepo"
    "github.com/ossf/scorecard/v5/pkg/scorecard"
)

func main() {
    ctx := context.Background()
    repo, _ := githubrepo.MakeGithubRepo("ossf/scorecard")

    // Run specific probes instead of full checks
    result, err := scorecard.Run(ctx, repo,
        scorecard.WithProbes([]string{
            "archived",                           // Is the repo archived?
            "hasRecentCommits",                   // Recent commit activity?
            "hasBinaryArtifacts",                 // Binary files present?
            "hasDangerousWorkflowScriptInjection", // Script injection risk?
            "hasLicenseFile",                     // License file exists?
            "hasOpenSSFBadge",                    // OpenSSF badge level?
            "branchesAreProtected",               // Branch protection enabled?
            "codeApproved",                       // Code review practices?
            "fuzzed",                             // Fuzzing integration?
            "pinsDependencies",                   // Dependencies pinned?
            "sastToolConfigured",                 // SAST tools configured?
            "securityPolicyPresent",              // SECURITY.md present?
            "releasesAreSigned",                  // Signed releases?
            "hasOSVVulnerabilities",              // Known vulnerabilities?
        }),
    )
    if err != nil {
        log.Fatalf("Probe run failed: %v", err)
    }

    // Process probe findings
    for _, finding := range result.Findings {
        fmt.Printf("Probe: %s\n", finding.Probe)
        fmt.Printf("  Outcome: %s\n", finding.Outcome)
        fmt.Printf("  Message: %s\n", finding.Message)
        if finding.Location != nil {
            fmt.Printf("  Location: %s", finding.Location.Path)
            if finding.Location.LineStart != nil {
                fmt.Printf(":%d", *finding.Location.LineStart)
            }
            fmt.Println()
        }
    }
}
```

```bash
# Run probes via CLI with probe output format
scorecard --repo=github.com/ossf/scorecard \
  --probes=archived,hasRecentCommits,hasBinaryArtifacts \
  --format=probe
```

OpenSSF Scorecard serves as a critical tool for evaluating and improving open source software security. Its primary use cases include automated security posture assessment for maintainers, dependency risk evaluation for consumers, compliance verification through policy files, and integration into CI/CD pipelines for continuous security monitoring. Organizations commonly use it to establish security baselines for accepted dependencies, while open source projects use it to demonstrate their security practices through badges and public scores.

Integration patterns typically involve running Scorecard as a GitHub Action on every push or pull request, querying the REST API for dependency evaluation in software composition analysis, using the Go library for custom tooling and dashboards, and leveraging BigQuery for large-scale ecosystem analysis. The probe-based architecture allows for flexible security requirements, enabling teams to focus on specific security behaviors relevant to their threat model while ignoring checks that don't apply to their context.