README
ΒΆ
ossf-scout
Discover GitHub repositories where security practices are weakest β and where a well-crafted PR can make the biggest impact.
Searches GitHub for popular repositories, queries the OpenSSF Scorecard API for each, and surfaces projects missing key security practices β no CI tests, no SAST, no branch protection, etc.
Available as a CLI tool or a web server with a browser UI, scan history, scheduled audits, remediation tracking, and portfolio views.
π Generate a full DevSecOps audit
Point ossf-scout at any public repo and it clones it, runs 30+ security tools, and produces a formal Markdown report β findings with CVSS scores and OWASP/STRIDE mapping, fix commands, and ready-to-paste CI guardrails. Free as a static snapshot, or AI-synthesised via Anthropic, OpenAI, Gemini, or Ollama.
π See real samples β AI-synthesised report β
examples/directus-audit-report-ai.mdΒ Β·Β static snapshot βexamples/directus-audit-report.mdΒ Β·Β raw evidence context βexamples/directus-audit-context.md
How it compares
Most OpenSSF Scorecard tooling answers "how secure is this repo?" or "how is my org trending?". ossf-scout asks the inverse question: which popular repositories are weakest right now, so I know where a contribution lands hardest?
| Tool | Focus | Where ossf-scout differs |
|---|---|---|
ossf/scorecard |
The scoring engine + API | ossf-scout consumes the API and adds a discovery/search layer on top |
scorecard-visualizer |
Pretty view of one repo's score | ossf-scout ranks many repos by weakness, not one at a time |
scorecard-monitor |
Tracking score changes for your own orgs | ossf-scout finds other people's popular-but-weak repos to contribute to |
| deps.dev / Socket | Package/dependency (SCA) security | ossf-scout looks at repo-level security posture, not packages |
The niche: GitHub Search + Scorecard filters to surface popular-but-weak repos, plus an AI-powered DevSecOps audit/remediation workspace β all in one self-contained binary.
Features
Discovery & Scorecard scanning
- GitHub Search + OpenSSF Scorecard discovery β ranks popular repositories whose Scorecard results fall below your threshold
- Scorecard API + CLI fallback β queries
api.securityscorecards.dev; optionally falls back to the localscorecardbinary for repos not yet indexed - Single-repo mode β score any public repo directly by
owner/repowithout running a GitHub Search query - GitHub Trending scanner β scrapes trending repositories by language/time window and scores them against OpenSSF data
- Organization scan queue β lists public repos for a GitHub org, filters forks/archived repos/min stars, and queues selected repos for audit
- Open issues count β enriches scan rows through GitHub Search API without requiring extra token scopes
- Flexible filters β language, topic, keyword, pushed-after date, min stars, max Scorecard score, min Maintained score, and highlighted checks
- Quick presets β DevSecOps opportunities, AI/LLM, MCP/Agents, Cloud Native, and Security tooling
Web workspace
- Browser UI β scan form, scan history, result details, sortable/filterable results, resizable columns, sticky headers, and Scorecard check docs links
- Persistent SQLite history β scans, results, audits, audit contexts, schedules, issue/PR summaries, remediation items, and trend data survive restarts
- Portfolio dashboard β aggregates watched repos with latest score, stars, weak checks, audit counts, provider, language, and score sparklines
- Score trend API/UI β tracks Scorecard score and star history per repo across repeated scans
- Remediation board β extracts findings from audit reports, creates remediation cards, and tracks status, severity, notes, due dates, and resolution
- Schedules β run recurring audits at configurable intervals, enable/disable jobs, trigger now, and constrain runs to UTC time windows
- Auto-detected audit schedules β suggests schedules for repos that repeatedly appear weak or are already being audited
- Issues/PR intelligence β caches security-relevant open/closed issues and PR summaries for a repo;
?refresh=trueforces a live re-fetch - Notifications β in-app toast and browser Notification API on scan completion; optional outbound webhook after audit completion (
NOTIFY_WEBHOOK_URL) - Authentik-compatible access control β optional forward-auth mode with read/write/admin group checks
DevSecOps audits
- Static snapshot mode β runs for free without an AI key and returns the collected evidence as a structured Markdown report
- AI report generation β supports Anthropic, OpenAI, Gemini, and local/remote Ollama models
- Split generation β lets a cheaper/fast model summarise evidence sections before a stronger final model writes the report
- Saved evidence context β stores the compact Markdown/JSON context so reports can be regenerated later with another provider or model
- Context caching β reuses a recent audit context when the repo HEAD SHA has not changed
- Automatic context compaction β if a provider rejects the prompt as too large (token-per-minute limit or context window exceeded), automatically retries with a compacted context; applies to all providers (Anthropic, OpenAI, Gemini, Ollama)
- Skip-secrets option β skips the slower
gitleaks/trufflehogpasses when speed matters - Audit compare β generates two reports from the same saved context and compares providers/models side-by-side
- Supply-chain graph β visualizes GitHub Actions pinning suggestions and unresolved action references from saved audit context
- Export formats β download Markdown reports, AI context Markdown, full JSON exports, or SARIF suitable for GitHub Code Scanning
- Reasoning-model output cleaning β strips
<think>β¦</think>blocks emitted by reasoning models (DeepSeek-R1, QwQ, etc.) before saving the report - Ground-truth claim verification β after generation, every concrete claim (commit/pin SHA,
file:line,#PR, CVE,pkg@version, workflow file, CVSS band/vector) is checked against the collected evidence and the CVSS base score recomputed; unverifiable claims are listed in an appendix and the report is marked DRAFT - Cost tracking and guardrails β records input/output tokens, estimates per-model cost, aggregates 30-day spend, and can reject audits above
MAX_AUDIT_COST_USD - GitHub webhook audits β signed GitHub
pull_request/pushwebhooks can automatically run a free static audit when security-sensitive files change
Packaging
- Self-contained binary β React frontend embedded via
//go:embed, SQLite via pure-Go driver - Docker image with bundled tools β ships
scorecard,gitleaks,actionlint,osv-scanner,trivy,helm,zizmor,kube-linter,trufflehog,semgrep, Node/npm, andpnpm - Offline-friendly Ollama profile β Docker Compose can run an Ollama sidecar for local AI generation
Screenshots
Scan configuration and history

Scan results β repos with weak Scorecard scores

GitHub Trending scored against Scorecard API

Quick Start
CLI
export GITHUB_TOKEN=ghp_...
go run . -lang go -min-stars 1000 -max-score 5 -limit 50
Web Server
go run . -serve
# Open http://localhost:7878
Docker
GITHUB_TOKEN=ghp_... docker compose up --build
# Open http://localhost:7878
The scan history is stored in ./data/ossf-scout.db and persists across restarts.
Audit Tab
π Sample output for
directus/directus:
- AI-synthesised report β
examples/directus-audit-report-ai.mdβ a derived security-posture score, calibrated findings (Evidence + Observation/Risk/Recommendation, CVSS), severity/exploitability/effort triage, a "not assessed" scope boundary, a phased remediation roadmap, CI-automated verification, and a STRIDE threat model (the full audit format)- Static snapshot β
examples/directus-audit-report.mdβ free, no-AI raw data dump- AI input context β
examples/directus-audit-context.mdβ the evidence fed to the model
Open the Audit tab in the web UI:
go run . -serve
# Navigate to http://localhost:7878 β Audit tab
Enter owner/repo (e.g. directus/directus), choose a provider, and click Run Audit:
| Provider | Cost | Setup |
|---|---|---|
| Static snapshot | Free | No key needed β returns structured raw data |
| Anthropic | Paid | API key via UI or ANTHROPIC_API_KEY; models: Opus 4.8, Sonnet 4.6, Haiku 4.5, Opus 4.7, Opus 4.6, Sonnet 4.5, Opus 4.5 |
| OpenAI | Paid | API key via UI or OPENAI_API_KEY; models: GPT-5.5, GPT-5.4, GPT-5.4 mini, GPT-4.1 family, GPT-4o family, o-series (o1/o3/o4-mini) |
| Gemini | Paid | API key via UI or GEMINI_API_KEY; models: Gemini 3.5 Flash, 3.1 Flash Lite, 2.5 Pro/Flash/Flash-Lite, 2.0 Flash, 1.5 Pro/Flash |
| Ollama | Free/local | OLLAMA_BASE_URL on the server; model name selected in the UI |
Approximate per-run costs are shown in the UI after each audit based on recorded input/output tokens and the configured model price table. Static snapshots and Ollama runs are treated as free.
The tool sends Markdown context to the AI instead of raw JSON β the Zizmor SARIF output (which can be 40 000+ lines) is replaced with a compact findings table, reducing input tokens by ~90% compared to the JSON approach. AI paths use this format for single-stage generation, split section analysis, split synthesis, and later re-generation from a saved context.
Enable Split generation in the UI to have an analysis model summarise each evidence section first; the selected final model then synthesises the report. Recommended for large monorepos where per-section analysis improves finding quality. Split mode is currently implemented for Anthropic and Ollama.
Ollama setup:
ollama serve
ollama pull llama3.2 # or qwen2.5, deepseek-r1:8b, etc.
For Ollama, set OLLAMA_BASE_URL on the server. When running via Docker, the default (http://host.docker.internal:11434) is pre-configured in docker-compose.yml; for native use set it to http://localhost:11434. If the model's context window is too small, the tool automatically retries with a compacted context (verbose tool outputs truncated).
For an offline/local profile:
OLLAMA_BASE_URL=http://ollama:11434 docker compose --profile offline up --build
The Markdown report appears in the browser when complete (~1β3 min for AI, ~30s for snapshot) and can be downloaded as a .md file. If AI generation fails, the static snapshot is saved as a fallback β a Run with AI button on the detail page lets you re-run the same saved context with a different provider.
A Download AI context button is available for every audit (including static snapshots) once the repo has been cloned and analysed. It downloads the compact Markdown that would be sent to the AI β useful for pasting into any LLM manually or for inspecting exactly what evidence was collected.
Audit detail pages also expose a supply-chain graph for GitHub Actions pinning, JSON export, SARIF export, and a remediation extraction action that turns report findings into trackable remediation items.
What it collects
| Category | Checks |
|---|---|
| CI/CD | Unpinned GitHub Actions, zizmor workflow analysis, actionlint workflow linting, workflow file list |
| Code | eval(), Math.random(), raw SQL, X-Powered-By, hardcoded secrets, weak crypto, process.exit/os.Exit, SQL injection (knex.raw/whereRaw), SSRF (fetch/axios/got), path traversal, XXE, deserialization, rate limiting, CORS config, Semgrep auto findings |
| Key files | Entry point (first 150 lines), auth middleware, permission system, security config (helmet/cors/session), startup validation checks, CODEOWNERS file |
| Infrastructure | helm lint, Helm secret templates + values, Dockerfile |
| Dependencies | pnpm audit / npm audit / yarn audit JSON, workspace overrides |
| Git history | Last 30 commits, files changed in the last 10 commits |
| GitHub API | Open issues (up to 50), open PRs (up to 20), secret-scanning alerts, branch protection rules, Dependabot alerts (requires security_events scope), release history |
| Secrets | gitleaks, trufflehog, private key headers, .env file contents, AWS/JWT/GH token regex patterns |
| IaC | Terraform file list, trivy config, osv-scanner, Kubernetes manifest list, kube-linter |
| Policy as Code | OPA .rego files, Kyverno ClusterPolicy/Policy YAMLs, Falco rule detection |
| SLSA / Supply Chain | Provenance / SBOM files, cosign keys, SLSA GitHub Generator workflow usage, signed commit check |
All tools are bundled in the Docker image (amd64 + arm64) β no separate installation needed.
Report structure
The generated Markdown document follows a fixed structure:
- Metadata table β date, repo, commit, auditor, status
- Scope & Methodology
- Findings Summary β table with ID, Priority (P0βP2), CVSS Severity, OWASP 2021 category
- Per-finding sections β Root Cause Β· Impact Chain Β· Fix Β· Verification shell commands
- Open GitHub Issues & PRs β security-relevant items with risk assessment
- Remediation Status table & Verification Checklist
- P2 Recommendations β table with Effort (hours/days) and Risk Reduction estimates
- Shift-left guardrails β maps each finding to an automated CI gate with a runnable GitHub Actions YAML snippet
- Threat Model (STRIDE) β table covering Spoofing, Tampering, Repudiation, Information Disclosure, DoS, Elevation of Privilege across auth flows, CI/CD, supply chain, secrets, and API inputs
- Appendix β full assessment across SQL Injection, Auth, Authorisation, SSRF, XXE, Path Traversal, Cryptography, Rate Limiting, Dependencies, HTTP Headers, Container, Kubernetes/Helm
Cost: Free without an API key (static snapshot). With a paid provider, token counts and estimated cost are shown in the audit history table and the cost dashboard. Set MAX_AUDIT_COST_USD to reject runs whose pre-flight estimate is above your budget.
CLI Flags
| Flag | Default | Description |
|---|---|---|
-lang |
(any) | Filter by language (go, python, java, β¦) |
-topic |
(any) | Filter by GitHub topic (llm, kubernetes, β¦) |
-keyword |
(any) | Filter by keyword in repo name or description |
-repo |
(none) | Scan a single specific repo (owner/repo), skips GitHub search |
-pushed-after |
(none) | Only include repos pushed after this date (YYYY-MM-DD) |
-min-stars |
500 |
Minimum GitHub star count |
-max-score |
5.0 |
Maximum OpenSSF score to include (0β10) |
-min-maintained |
0 |
Minimum Maintained check score (0 = disabled) |
-limit |
100 |
Max repos to fetch from GitHub search |
-workers |
5 |
Concurrent Scorecard API queries |
-checks |
(security set) | Comma-separated check names to highlight |
-json |
false |
Output as JSON instead of a table |
-token |
$GITHUB_TOKEN |
GitHub personal access token |
-cli-fallback |
false |
Use local scorecard CLI for repos not in the Scorecard database |
-serve |
false |
Start web server mode |
-port |
7878 |
Port for web server mode |
-db |
ossf-scout.db |
SQLite database path (server mode) |
Environment Variables
| Variable | Description |
|---|---|
GITHUB_TOKEN |
GitHub PAT. Without it, GitHub limits unauthenticated requests to 60/hour. |
ANTHROPIC_API_KEY |
Anthropic API key for the Audit tab. Can also be provided per-audit in the web UI (overrides the server-level key). |
OPENAI_API_KEY |
OpenAI API key for the Audit tab. Can also be provided per-audit in the web UI. |
GEMINI_API_KEY |
Google Gemini API key for the Audit tab. Can also be provided per-audit in the web UI. |
OLLAMA_BASE_URL |
Base URL for a local/remote Ollama instance (e.g. http://localhost:11434). Defaults to http://host.docker.internal:11434 in Docker. |
MAX_AUDIT_COST_USD |
Optional budget cap. Audits whose pre-flight cost estimate exceeds this value are rejected before any tokens are sent. |
GITHUB_WEBHOOK_SECRET |
Optional. If set, incoming GitHub webhook payloads are validated against the X-Hub-Signature-256 header β unsigned requests are rejected. |
NOTIFY_WEBHOOK_URL |
Optional. A URL to POST a JSON notification to after each audit completes (repo, status, audit ID). |
AUTH_REQUIRED |
Set to true to enable Authentik forward-auth mode. Requests missing X-Authentik-Username return 401; write/admin endpoints additionally check ossf-write/ossf-admin groups. |
The GitHub token and AI API keys can also be provided per-scan/per-audit in the web UI (override the server-level values).
Token scopes
| Mode | Required scopes |
|---|---|
Default (REST API via api.securityscorecards.dev) |
None β any valid token is enough to raise the rate limit |
-cli-fallback (scorecard CLI) |
Classic PAT with public_repo scope β needed for the Branch-Protection check (GraphQL query) |
| Dependabot alerts collection (audit) | security_events scope β needed to read Dependabot vulnerability alerts via the GitHub API |
To create a classic PAT: GitHub β Settings β Developer settings β Personal access tokens β Tokens (classic) β tick public_repo under repo.
Building from Source
Prerequisites: Go 1.25+, Node 22+
make build
# Produces ./ossf-scout β a single self-contained binary
Architecture
Single Go binary. The web server embeds the React frontend via //go:embed β no separate static file serving needed. Scan history is stored in SQLite using modernc.org/sqlite (pure Go, no CGo required).
The OpenSSF checks evaluated by default:
CI-Tests Β· SAST Β· Dependency-Update-Tool Β· Vulnerabilities Β· Pinned-Dependencies Β· Branch-Protection Β· Code-Review Β· Maintained
Contributing
PRs welcome. Run make dev to build locally. The web server embeds the frontend at build time β edit frontend/src/ and rebuild with make dev.
Eating Our Own Dog Food
ossf-scout exists to surface open-source projects with weak security postures so contributors can improve them β so we ran it against this repo too. Applying its own findings took the Scorecard score from 5.2 β 7.7 / 10 through 11 documented fixes (broken Scorecard CI, branch protection, license, security policy, Dockerfile digest pinning, fuzz tests, CodeQL, and more).
π Full running log: docs/SCORECARD-JOURNEY.md
License
The Unlicense β public domain
Documentation
ΒΆ
There is no documentation for this package.
Source Files
ΒΆ
- audit_claude.go
- audit_context.go
- audit_gemini.go
- audit_github.go
- audit_ollama.go
- audit_openai.go
- audit_prompt.go
- audit_runner.go
- config.go
- constants.go
- db.go
- github.go
- main.go
- middleware.go
- output.go
- scheduler.go
- scorecard.go
- server.go
- server_audits.go
- server_remediation.go
- server_scans.go
- server_schedules.go
- server_webhooks.go
- trending.go
- validate.go
- verify.go
- workers.go