A comprehensive Claude Code / GitHub Copilot skill that helps developers build secure applications following OpenSSF (Open Source Security Foundation) best practices — and evaluate open source projects as an ensemble.
Supports both GitHub Copilot and Claude Code.
Two modes, one skill:
- Advisor — help me build or fix a specific control. Threat models, SECURITY.md, SBOM setup, Sigstore signing, Dockerfile hardening, secrets pre-commit hooks, Scorecard workflows. Assess → recommend → implement.
- Audit — tell me how safe this is. Run the OpenSSF tools together and fuse the signals into one decision-ready verdict:
- Consume: Is this dependency safe to adopt? → Adopt / Adopt-with-mitigations / Avoid
- Produce: Is the project we build trustworthy and hardened? → A–F posture grade + roadmap
Sometimes you know exactly what you need — "generate a SECURITY.md," "set up SBOM generation," "harden this Dockerfile." That's advisor mode: it assesses your project, recommends prioritized next steps, and walks you through building the artifact using the bundled references, templates, and workflows.
Other times you just want a verdict. Most security tooling makes you run Scorecard, then OSV-Scanner, then a secrets scan, then check signing… and then you decide what it all means. Audit mode does the fusing for you:
Scorecard ─┐
OSV / audits ───┤
SBOM ─────┤ normalize → weight by mode → escalate ┌─ Adopt / Avoid (consume)
signing/SLSA ───┼──► (live secrets & critical CVEs cap it) ──► │
secrets ────┤ ensemble/risk-model.md └─ A–F grade (produce)
maintenance ────┤
OSPS Baseline ───┘
The same tools run in both audit sub-modes — the mode only changes the weights.
Copy the Copilot instructions file to your repository:
# Create .github directory if it doesn't exist
mkdir -p .github
# Download the instructions file
curl -o .github/copilot-instructions.md \
https://raw.githubusercontent.com/ryanwaite/openssf-skill/main/.github/copilot-instructions.mdThen enable custom instructions in VS Code:
- Open Settings (
Cmd+,orCtrl+,) - Search for "Copilot instruction"
- Enable
github.copilot.chat.codeGeneration.useInstructionFiles
Copilot will now apply OpenSSF security best practices to all code suggestions in that repository.
# Clone directly to your global skills directory
git clone https://github.com/ryanwaite/openssf-skill.git ~/.claude/skills/openssf# Clone into your project's .claude/skills directory
mkdir -p .claude/skills
git clone https://github.com/ryanwaite/openssf-skill.git .claude/skills/openssfThen invoke the skill in any project with /openssf.
The simplest way to get started:
- Start GitHub Copilot or Claude Code
cdto the root of an open source project- Run
/openssf what can you do for me?
The router sends your request to the right mode.
/openssf help me create a threat model for my authentication system
/openssf generate a SECURITY.md for this project
/openssf what OpenSSF Scorecard checks am I failing?
/openssf set up SBOM generation for my releases
/openssf review this code for security issues
The skill will:
- Assess your project's current security posture
- Detect languages and existing security artifacts
- Recommend prioritized security improvements
- Guide you through creating security artifacts
/openssf evaluate this repo
/openssf is [email protected] safe for us to adopt?
/openssf grade our security posture before release
The agent establishes the mode (consume vs produce), runs the ensemble, and returns a verdict with evidence, ranked risks, and concrete next actions.
# Evaluate a dependency you might adopt
python3 scripts/ensemble-eval.py --target [email protected] --mode consume
# Grade a repo you own
python3 scripts/ensemble-eval.py --target . --mode produce --format mdAny tool that isn't installed is reported as unknown (and lowers confidence) —
never silently skipped.
This walkthrough demonstrates using the OpenSSF skill with GitHub Copilot to assess and improve the security posture of an open source repository.
Start by invoking the OpenSSF skill in your project:
The skill looks at the project and provides an assessment of the overall project:
The skill provides a comprehensive list of security features it can help with:
The skill provides a prioritized list of what to do next along with the approximate time to complete each activity:
In this walkthrough we go with the recommendation to start with running Scorecard:
The skill spins up a container, runs the Scorecard analysis, and provides the results:
From here, you can use the skill to keep implementing changes.
| Layer | File(s) | Role |
|---|---|---|
| Router | SKILL.md, .github/copilot-instructions.md |
Sends the request to advisor or audit |
| Advisor | skills/advisor/ |
Assess → recommend → implement a specific control |
| Audit orchestrator | skills/audit/ |
Establishes consume/produce mode, runs the battery, produces the report |
| Audit modes | skills/audit/consume/, skills/audit/produce/ |
Mode-specific batteries and outputs |
| Fusion engine | ensemble/risk-model.md |
Normalization, mode weights, escalation rules, outcome mapping |
| Output spec | ensemble/report-template.md |
The decision-ready report format |
| Runner | scripts/ensemble-eval.py |
Executes the audit ensemble, emits fused JSON/Markdown (degrades gracefully) |
| Detector | scripts/assess-project.py |
Local language/artifact detection |
| Grounding | references/ |
Deep per-tool guidance both modes draw on |
- Mode sets the weights. Consume leans on known CVEs + maintenance; produce leans on secrets + provenance + code review.
- Escalations override the average. A live secret or an unpatched CRITICAL with a fix available caps the verdict no matter how good everything else looks.
- Unknown ≠ fine. Missing data lowers confidence; it never inflates the score.
- Every claim cites a tool. Every verdict shows its math. Two evaluators running the same tools on the same target reach the same verdict.
openssf-skill/
├── .github/
│ └── copilot-instructions.md # GitHub Copilot instructions (router + secure-coding)
├── SKILL.md # Claude Code skill file — router: advisor | audit
├── skills/
│ ├── advisor/SKILL.md # Build/fix a specific control (v1 guidance behavior)
│ └── audit/
│ ├── SKILL.md # Ensemble orchestrator (establishes consume/produce)
│ ├── consume/SKILL.md # Third-party OSS → Adopt / Adopt-with-mitigations / Avoid
│ └── produce/SKILL.md # Projects you ship → A–F grade + roadmap
├── ensemble/
│ ├── risk-model.md # Normalization, weights, escalation, outcome mapping
│ └── report-template.md # Decision-ready report format
├── scripts/
│ ├── assess-project.py # Project language/artifact detection
│ └── ensemble-eval.py # Runs the audit ensemble, emits fused verdict
├── tests/
│ ├── test_assess_project.py # Unit tests
│ └── test_ensemble_eval.py # Fusion / risk-model tests
├── templates/
│ ├── SECURITY.md.template
│ ├── threat-model.md.template
│ └── vulnerability-disclosure-policy.md.template
├── workflows/
│ ├── scorecard.yml.template
│ ├── slsa-provenance.yml.template
│ ├── sbom-generation.yml.template
│ ├── dependency-review.yml.template
│ └── gitlab-ci-security.yml.template # GitLab CI/CD
└── references/
├── threat-modeling/ # STRIDE methodology
├── scorecard/ # All 19 checks + remediation
├── osps-baseline/ # Compliance checklists
├── sbom/ # Language-specific tools
├── slsa/ # Supply chain security
├── dependency-security/ # Vulnerability scanning
├── security-policies/ # Policy creation guides
├── security-requirements/ # Requirements checklist
├── code-review/ # Security review guide
├── secrets-scanning/ # Secret leak prevention
├── signing/ # Sigstore/Cosign guide
├── container-security/ # Docker hardening
└── best-practices-badge/ # OpenSSF Badge guide
| Topic | Description |
|---|---|
| Threat Modeling | STRIDE methodology, DFD creation, risk assessment |
| Security Policies | SECURITY.md, vulnerability disclosure, response timelines |
| OpenSSF Scorecard | 19 automated security checks with remediation |
| OSPS Baseline | Level 1 compliance checklist |
| SBOM | SPDX generation (default) for all major languages |
| SLSA | Supply chain security levels 0-3 |
| Dependencies | Vulnerability scanning, update strategies |
| Code Review | OWASP Top 10, language-specific patterns |
| Secrets Scanning | Gitleaks, TruffleHog, detect-secrets, pre-commit hooks |
| Artifact Signing | Sigstore ecosystem: Cosign, Fulcio, Rekor, Gitsign |
| Container Security | Dockerfile hardening, image scanning, distroless bases |
| Best Practices Badge | OpenSSF Badge self-certification (Passing/Silver/Gold) |
| Tool | Required For |
|---|---|
| GitHub Copilot | Copilot instructions |
| Claude Code | Claude Code skill |
| Git | Cloning the repository |
| Python 3 | Running scripts/ and the ensemble runner |
Contributions are welcome! See CONTRIBUTING.md for detailed guidelines, content standards, and testing instructions.
Quick start:
- Fork the repository
- Create a feature branch
- Make your changes (run
python3 -m unittest discover tests/ -vto validate) - Submit a pull request
MIT License - see LICENSE for details.
- OpenSSF Best Practices
- OpenSSF Scorecard
- SLSA Framework
- OSPS Baseline
- OWASP Top 10
- GitHub Copilot Custom Instructions
Built following OpenSSF guidelines and recommendations for secure software development.