# Security Policy

Thank you for helping keep this project and its users safe. We take security seriously. This document covers how to report vulnerabilities, what is in scope, and how the project's supply chain integrity works.

## Scope

This policy applies to repositories under this organization.

- Public repositories: client, protocol, and conformance assets
- Private repositories: backend, infrastructure, and internal operations

Do not disclose sensitive details publicly until we complete coordinated remediation.

## Out of Scope

The following are normally out of scope:

- Cosmetic/content issues without security impact
- Vulnerabilities in upstream repositories that we do not distribute yet (report these to the upstream project directly)
- DoS volume testing without prior approval
- Reports based only on missing best-practice headers without exploitability

## Reporting a Vulnerability

Please report vulnerabilities privately:

- Preferred: GitHub Security Advisories — Use the `Security > Advisories` tab to submit a private report.
- Alternate: Send a report to [oss-security@windlasstech.com](mailto:oss-security@windlasstech.com).

### What to Include

1. Affected repository and commit/tag/version
2. Description of the vulnerability and its potential impact
3. Reproduction steps or proof of concept
4. Suggested mitigation (if available)

### Response Timeline

| Step                              | Timeline                                      |
| --------------------------------- | --------------------------------------------- |
| Acknowledgment of report          | 3 business days                               |
| Triage and severity assessment    | 7 business days                               |
| Fix for critical or high severity | 14 days                                       |
| Fix for medium or low severity    | 30 days                                       |
| Public disclosure                 | After fix is released, or 90 days from report |

These timelines are best-effort commitments and are not guaranteed SLAs. Complex issues may take longer, but we will keep you informed of progress — at least every 7 business days until closure.

## Disclosure Policy

We follow coordinated disclosure:

1. The reporter submits a private vulnerability report.
2. We acknowledge, triage, and work on a fix privately.
3. Once a fix is released, we publish a GitHub Security Advisory with full details.
4. The reporter is credited in the advisory unless they request anonymity.
5. If no fix is released within 90 days, the reporter may disclose publicly.

We will not take legal action against researchers who report vulnerabilities in good faith and follow this policy.

## Safe Harbor

We support good-faith security research.

Please do not:

- Access non-public data beyond what is required to prove impact
- Degrade service availability
- Social engineer, spam, or perform destructive testing

## Security Monitoring

### Audit Logging

- All workflow runs are logged via GitHub's audit log
- Access to secrets is logged
- Deployment activity is tracked

### Vulnerability Scanning

- Dependabot alerts are enabled on all repositories
- Code scanning with CodeQL runs on all PRs
- OSV Scanner runs on PRs and scheduled full scans
- Secret scanning prevents credential leakage

### OpenSSF Scorecard

This organization uses [OpenSSF Scorecard](https://securityscorecards.dev/) to continuously monitor security posture:

- Binary artifacts
- Branch protection
- Code review
- Dependency update tool
- Fuzzing
- License
- Maintained
- Pinned dependencies
- SAST
- Security policy
- Signed releases
- Token permissions
- Vulnerabilities

## Supply Chain Integrity

This organization follows the [SLSA (Supply-chain Levels for Software Artifacts)](https://slsa.dev/) framework to ensure software supply chain security. Detailed implementation guidance is available in the companion documents linked below.

### At a Glance

- Build L1/L2 required; Build L3+ target wherever feasible
- Source L1/L2 required; Source L3 controls followed wherever feasible
- Source L4 not achievable in a 1-person organization
- SHA-pinned workflows, hardened runners, least-privilege permissions
- Lockfiles committed, dependency review, OSV scanning
- Signed commits, protected branches, OIDC, release integrity
- Build provenance and SBOM attestations for released artifacts
- Linked artifacts metadata for registry-published release artifacts

### Detailed Requirements

| Topic                     | Companion document                                                                         |
| :------------------------ | :----------------------------------------------------------------------------------------- |
| SLSA compliance framework | [docs/security/slsa-compliance-framework.md](./docs/security/slsa-compliance-framework.md) |
| Workflow hardening        | [docs/security/workflow-hardening.md](./docs/security/workflow-hardening.md)               |
| Artifact attestations     | [docs/security/artifact-attestations.md](./docs/security/artifact-attestations.md)         |
| Dependency security       | [docs/security/dependency-security.md](./docs/security/dependency-security.md)             |

### Source and Workflow Integrity

Source and workflow controls are implemented through signed commits, protected branches, SHA-pinned actions, hardened runners, least-privilege workflow permissions, and OIDC-based cloud authentication.

- Source track requirements, branch protection controls, and commit signing expectations are documented in [SLSA Compliance Framework: SLSA Source Track Requirements](./docs/security/slsa-compliance-framework.md#slsa-source-track-requirements).
- GitHub Actions hardening, permission patterns, and OIDC provider examples are documented in [Workflow Hardening](./docs/security/workflow-hardening.md).

### Release Integrity

- **GPG-signed tags** — All release tags are GPG-signed annotated tags
- **GPG-signed commits** — All commits on `main` must be GPG-signed (enforced by repository rulesets)
- **Linear history** — Squash-merge-only policy prevents history rewriting; force-push to `main` is blocked
- **CI gate** — All required status checks must pass before any merge to `main`
- **SLSA Build L3+ provenance** — Released artifacts should use SLSA GitHub Generator builders or reusable workflow based attestation to produce hardened Build L3+ provenance wherever feasible
- **Baseline build provenance attestations** — If an L3+ path is not available for a repository yet, released artifacts that consumers run, install, deploy, or download must still include signed provenance attestations
- **SBOM attestations and release assets** — Released binaries and container images must include signed SPDX and CycloneDX SBOM attestations when the build can generate them, and public releases should publish the same SBOM files as release assets
- **Linked artifacts metadata** — Registry-published release artifacts should upload storage metadata to GitHub's linked artifacts page through `actions/attest` or the artifact metadata API

Implementation requirements for provenance, SBOM attestations, linked artifacts uploads, and release verification are documented in [Artifact Attestations](./docs/security/artifact-attestations.md).

## Verifying Artifacts

Consumers can verify the authenticity, integrity, and provenance of artifacts from this organization using GitHub artifact attestations and SLSA provenance verification tools.

Verification confirms:

1. **Authenticity** — The artifact was built by the claimed repository
2. **Integrity** — The artifact has not been tampered with since build
3. **Provenance** — The artifact's build process is documented
4. **Source** — The exact source code revision used to build the artifact is known
5. **Build environment** — The workflow that produced the artifact is identified

Detailed verification commands for binaries, container images, SBOM attestations, and SLSA provenance are documented in [Artifact Attestations: Verification Expectations](./docs/security/artifact-attestations.md#verification-expectations).

## References

Detailed reference lists for each topic are available in the companion documents:

- [SLSA Framework references](./docs/security/slsa-compliance-framework.md#references)
- [GitHub Actions and Step Security references](./docs/security/workflow-hardening.md#references)
- [Artifact attestation references](./docs/security/artifact-attestations.md#references)
- [OSV Scanner and Additional Resources](./docs/security/dependency-security.md#references)