Package Exports
- @happyhackingspace/scorecard
Readme
@happyhackingspace/scorecard
Reference implementation of OSSF Scorecard in TypeScript.
Computes all 20 OSSF Scorecard checks via the GitHub API directly, without depending on the OSSF public API (which only covers ~1M repos).
Install
bun add @happyhackingspace/scorecard
# or
npm install @happyhackingspace/scorecardUsage
import { computeScorecard } from "@happyhackingspace/scorecard";
const result = await computeScorecard("owner", "repo", {
token: "ghp_...",
});
// → { score: 7.6, date: "2026-03-03", repo: "owner/repo", checks: [...] }Run specific checks
const result = await computeScorecard("owner", "repo", {
token: "ghp_...",
checks: ["Maintained", "License"],
});Custom fetch
const result = await computeScorecard("owner", "repo", {
token: "ghp_...",
fetch: customFetch,
});API
computeScorecard(owner, repo, options)
Returns Promise<ScorecardResult>.
Options
| Option | Type | Required | Description |
|---|---|---|---|
token |
string |
Yes | GitHub personal access token |
checks |
string[] |
No | Run only specific checks |
fetch |
typeof fetch |
No | Custom fetch implementation |
Result
interface ScorecardResult {
date: string;
repo: string;
score: number;
checks: ScorecardCheck[];
}
interface ScorecardCheck {
name: string;
score: number; // 0-10, or -1 (inconclusive)
reason: string;
details?: string[];
}Checks
| Check | Risk | Weight | Description |
|---|---|---|---|
| Maintained | High | 7.5 | Recent commit and issue activity |
| Dependency-Update-Tool | High | 7.5 | Dependabot or Renovate configured |
| Binary-Artifacts | High | 7.5 | No binary files in repository |
| Branch-Protection | High | 7.5 | Branch protection rules enabled |
| CI-Tests | Low | 2.5 | CI checks on recent commits |
| CII-Best-Practices | Low | 2.5 | CII Best Practices badge level |
| Code-Review | High | 7.5 | Changes reviewed before merge |
| Contributors | Low | 2.5 | Multi-org contributor diversity |
| Fuzzing | Medium | 5 | Fuzzing infrastructure detected |
| Packaging | Medium | 5 | Publishing workflows present |
| Pinned-Dependencies | Medium | 5 | Dependencies pinned to SHA |
| SAST | Medium | 5 | Static analysis tools configured |
| SBOM | Medium | 5 | Software bill of materials present |
| Security-Policy | Medium | 5 | SECURITY.md with disclosure info |
| Signed-Releases | High | 7.5 | Release signatures or SLSA provenance |
| Token-Permissions | High | 7.5 | Least-privilege workflow permissions |
| Vulnerabilities | High | 7.5 | Open vulnerability alert count |
| Dangerous-Workflow | Critical | 10 | No script injection or unsafe triggers |
| License | Low | 2.5 | OSI-approved license present |
| Webhooks | Critical | 10 | Webhook secrets configured |
Scoring
Aggregate score uses the exact OSSF formula:
score = Σ(weight × check_score) / Σ(weight)Weights: Critical=10, High=7.5, Medium=5, Low=2.5. Inconclusive checks (score=-1) are excluded.
Development
bun install
bun run test
bun run build
bun run lint
bun run typecheckLicense
MIT