docs: add RELEASES.md covering release notes + vulnerability-disclosure flow (Best Practices criteria)

.github/workflows/govulncheck.yml

@@ -0,0 +1,76 @@
+name: govulncheck
+
+# Reachability-aware vulnerability scan against every PR + push to main.
+# Fails the build if our code calls into a known-vulnerable function in
+# any direct or transitive Go dep.
+#
+# This is the enforcement half of the documented SCA policy in
+# docs/DEPENDENCIES.md "Pre-release SCA gate". OpenSSF Baseline
+# OSPS-VM-05.03 requires changes to be automatically evaluated against
+# a documented policy and blocked on violation, except when declared
+# non-exploitable (which we do via vex/openvex.json).
+#
+# Why govulncheck instead of osv-scanner / Trivy on Go modules:
+# govulncheck is the reachability-aware scanner maintained by the Go
+# security team. It runs the call-graph against the OSV advisory data
+# and reports only vulnerabilities whose symbols are reachable from
+# OUR code. Module-level scanners (osv-scanner, Trivy) flag any vuln
+# in any transitive dep regardless of whether the vulnerable symbol
+# is called — which produces false positives like GO-2022-0635/0646
+# (aws-sdk-go v1 s3crypto, transitively pulled in by Pulumi but never
+# called). Those false positives are documented in vex/openvex.json
+# but govulncheck filters them at the scan level without needing the
+# VEX consult.
+#
+# CI behaviour:
+#   - PR: fails if govulncheck reports any reachable vulnerability.
+#   - main push: same gate; an unfixable transitive that suddenly
+#     becomes reachable would block the next release.
+#   - Weekly cron: catches newly-published advisories landing against
+#     existing reachable code paths.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: '37 6 * * 1'  # Monday 06:37 UTC — early week, off-peak
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.head.sha || github.sha }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  govulncheck:
+    name: govulncheck (reachability-aware)
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Set up Go
+        uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c  # v6
+        with:
+          go-version-file: go.mod
+          cache: true
+
+      - name: Install govulncheck
+        run: |
+          set -euo pipefail
+          go install golang.org/x/vuln/cmd/govulncheck@latest
+          govulncheck -version
+
+      - name: Run govulncheck on source
+        run: |
+          set -euo pipefail
+          # -mode=source: scan the call graph from this module's main
+          # packages outward (reachability-aware). Exits non-zero if
+          # any reachable vulnerability is found.
+          govulncheck -mode=source ./...

README.md

@@ -1,6 +1,7 @@
 # **Simple Container**
 
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/simple-container-com/api/badge)](https://scorecard.dev/viewer/?uri=github.com/simple-container-com/api)
+[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/12886/badge)](https://www.bestpractices.dev/projects/12886)
 [![OpenSSF Baseline](https://www.bestpractices.dev/projects/12886/baseline)](https://www.bestpractices.dev/projects/12886)
 [![CodeQL](https://github.com/simple-container-com/api/actions/workflows/codeql.yml/badge.svg?branch=main)](https://github.com/simple-container-com/api/actions/workflows/codeql.yml)
 [![Semgrep](https://github.com/simple-container-com/api/actions/workflows/semgrep.yml/badge.svg?branch=main)](https://github.com/simple-container-com/api/actions/workflows/semgrep.yml)
@@ -69,7 +70,13 @@ Check out the [full documentation](https://docs.simple-container.com) for detail
 
 ## **Contributing**
 
-We welcome contributions! Please see our [CONTRIBUTING.md](docs/CONTRIBUTING.md) for guidelines on how to get involved.
+We welcome contributions! Please see our [CONTRIBUTING.md](docs/CONTRIBUTING.md) for guidelines on how to get involved, and our [CODE_OF_CONDUCT.md](docs/CODE_OF_CONDUCT.md) for the community standards every participant is expected to uphold.
+
+---
+
+## **Roadmap**
+
+See [ROADMAP.md](docs/ROADMAP.md) for current themes, release cadence, and where planned work surfaces in the [Issues](https://github.com/simple-container-com/api/issues) tracker.
 
 ---
 

docs/ARCHITECTURE.md

@@ -97,7 +97,8 @@ For deeper component-level designs, see:
 ## Related security documentation
 
 - [SECURITY.md](SECURITY.md) — threat model (STRIDE) + attack vectors V1–V5 + responsible-disclosure channels
-- [`../HARDENING.md`](../HARDENING.md) — phase-by-phase hardening tracker (Phase 1 image hardening → Phase 8 OpenSSF visibility)
-- [`../SECURITY-CONTROLS.md`](../SECURITY-CONTROLS.md) — control matrix mapping STRIDE categories to specific controls
 - [DEPENDENCIES.md](DEPENDENCIES.md) — dependency selection / obtaining / tracking
+- [SECRETS-POLICY.md](SECRETS-POLICY.md) — secret categorisation, storage, rotation cadence
 - [MAINTAINERS.md](MAINTAINERS.md) — project members with access to sensitive resources
+- [RELEASES.md](RELEASES.md) — release pipeline, signing chain, vuln-disclosure flow
+- [ROADMAP.md](ROADMAP.md) — public roadmap state (Issues labels, themes, release cadence)

docs/CODE_OF_CONDUCT.md

@@ -0,0 +1,87 @@
+# Contributor Covenant Code of Conduct
+
+This is the code of conduct for the Simple Container project.
+Violations should be reported to creed@simple-container.com, consistent with docs/SECURITY.md and docs/MAINTAINERS.md.
+The maintainer group is responsible for enforcement according to the standard process below.
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at creed@simple-container.com. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at [https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

docs/CONTRIBUTING.md

@@ -118,9 +118,10 @@ If your change touches:
 - Anything in the SLSA / cosign / sigstore chain
 
 … open the PR with a **threat-model note**: which entry in
-[HARDENING.md](../HARDENING.md) does this change address or affect?
-Maintainers will pull in additional reviewers (codex + gemini round +
-human security review) for changes here.
+[`SECURITY.md`](SECURITY.md)'s STRIDE table + attack vectors V1–V5
+does this change address or affect, and what's the reachability /
+blast-radius story? Maintainers will pull in additional reviewers
+(codex + gemini round + human security review) for changes here.
 
 **Never disable verification** as a fix for a verification bug. If
 sc.sh's cosign-verify path rejects a release, the bug is in the

docs/DEPENDENCIES.md

@@ -27,7 +27,7 @@ selects, obtains, and tracks its dependencies."
 | **Go** | `go.mod` + `go.sum` | `go.sum` hashes every direct + transitive dep | `govulncheck` (reachability-aware), `osv-scanner` (via Scorecard), `trivy fs` |
 | **Python (docs)** | `docs/requirements.in` (sources) + `docs/requirements.txt` (compiled with `--generate-hashes`) | `pip install --require-hashes` in `push.yaml` docs-build step | `pip-audit`, Scorecard pinned-deps check |
 | **npm (docs examples)** | example `package*.json` files | Lockfile-aware install (`npm ci` when lockfile present, falls back to `npm install`) | Scorecard pinned-deps check |
-| **Docker base images** | `Dockerfile`s + `.Dockerfile`s at repo root + example dirs | SHA digest pin: `python@sha256:401f...`, `node:22-alpine@sha256:757e...` | `trivy image` per published image (see HARDENING.md Phase 1) |
+| **Docker base images** | `Dockerfile`s + `.Dockerfile`s at repo root + example dirs | SHA digest pin: `python@sha256:401f...`, `node:22-alpine@sha256:757e...` | `trivy image` per published image |
 | **GitHub Actions** | `.github/workflows/*` + `.github/actions/*` | Commit SHA pin with `# vX.Y.Z` comment for human-readability | Scorecard pinned-deps check; Semgrep custom rules |
 | **End-user installer tools** | `sc.sh` (Pulumi installer) | Tarball + SHA256 checksum verification before extract | n/a (sc.sh is shipped, not built against) |
 
@@ -91,8 +91,10 @@ The PR pipeline runs:
 - Scorecard runs daily; the badge surfaces the current score
 
 A subset of findings is intentionally accepted as documented false
-positives — those live in PR descriptions and in
-[HARDENING.md](../HARDENING.md), never in a suppression file.
+positives — those live in PR descriptions and as OpenVEX
+`not_affected` statements in [`vex/openvex.json`](../vex/openvex.json),
+never in a scanner-suppression file (no `.trivyignore`, no
+`# nosemgrep`, no `// nolint:` for vuln findings).
 
 ## Out-of-tree dependency surface
 
@@ -106,3 +108,81 @@ These are not "deps" in the tree-sense, but the trust chain matters
 the same way: each ships with cosign keyless signature + SLSA L3
 provenance + SHA256. Consumers verify via the patterns documented in
 [SECURITY.md](SECURITY.md).
+
+## Remediation thresholds (SCA policy)
+
+This section satisfies OpenSSF Baseline **OSPS-VM-05.01**
+("the project documentation MUST include a policy that defines a
+threshold for remediation of SCA findings related to vulnerabilities
+and licenses") and is the contract the pre-release gate enforces.
+
+### Vulnerability severity → remediation SLA
+
+| Severity (CVSS or distro rating) | Remediation SLA | Behaviour while open |
+|---|---|---|
+| **CRITICAL** (9.0–10.0) | within **24 hours** of confirmation if there is a known patched version; within **7 days** if upstream fix pending | merge gate blocks all non-emergency PRs |
+| **HIGH** (7.0–8.9) | within **30 days** | merge gate blocks; documented exceptions require VEX (see below) |
+| **MEDIUM** (4.0–6.9) | within **90 days** | best-effort with batch bumps via Dependabot |
+| **LOW** (0.1–3.9) | next scheduled SCA pass (~weekly) | informational |
+
+The SLA clock starts when the advisory is confirmed reachable in our
+codebase by `govulncheck` (reachability-aware). If govulncheck reports
+an advisory as *not* reachable, the finding does NOT block — it is
+declared `not_affected` via `vex/openvex.json` with the govulncheck
+output as evidence (per OSPS-VM-04.02).
+
+### License policy
+
+| License class | Allowed for direct + transitive deps |
+|---|---|
+| MIT / Apache-2.0 / BSD-3-Clause / BSD-2-Clause / ISC / MPL-2.0 | ✅ Allowed |
+| LGPL (any version) | ⚠️ Flagged for maintainer review; case-by-case |
+| GPL / AGPL (any version) | ❌ Rejected for runtime; allowed for build-only tooling iff the tool is not redistributed |
+| Unknown / proprietary | ❌ Rejected |
+
+License compliance is checked at PR review time. License-incompatible
+deps are blocked at merge by maintainer review (no automated license
+scanner yet — tracked internally).
+
+## Pre-release SCA gate
+
+This section satisfies OpenSSF Baseline **OSPS-VM-05.02** ("a policy
+to address SCA violations prior to any release") and **OSPS-VM-05.03**
+("automatically evaluated against a documented policy ... then blocked
+in the event of violations").
+
+Production releases are cut automatically on every merge to `main`
+(`.github/workflows/push.yaml`), so "pre-release" semantically equals
+"pre-merge" — every release IS a merge to main. The SCA gate fires
+on every PR + every push to main:
+
+| Tool | Coverage | Blocks on |
+|---|---|---|
+| **govulncheck** (`.github/workflows/govulncheck.yml`) | Reachable Go vulnerabilities (call-graph aware) | Any reachable advisory finding |
+| **CodeQL** (`.github/workflows/codeql.yml`) | Common-vulnerability patterns (SQL injection, XSS, command injection, taint flow, SSRF) | ERROR-severity findings |
+| **Semgrep** (`.github/workflows/semgrep.yml`) | Custom rules from the SC org (sigstore, gha-extras, pulumi-iac, go-canon) | ERROR-severity findings |
+| **TruffleHog** (`.github/workflows/security-scan.yml`) | Leaked secrets in diff | Any verified secret |
+| **Dependabot** | Daily advisory poll → auto-PR for known vulns | Open security alert (visibility, not blocking, but the auto-PR becomes a blocking item per the SLA above) |
+| **Trivy / Grype** (in shared security-scan workflow) | SBOM-based scan of source-tree deps | Currently reports counts only; planned to graduate to blocking on HIGH/CRITICAL once VEX consumption is wired in |
+
+### Suppressing a finding (non-exploitable / false positive)
+
+The only sanctioned suppression channel is **VEX**: edit
+`vex/openvex.json` and add a `not_affected` statement with:
+
+- `vulnerability.@id` — the OSV / CVE / GHSA ID
+- `justification` — one of the OpenVEX standard values
+  (`vulnerable_code_not_in_execute_path`,
+  `inline_mitigations_already_exist`, etc.)
+- `impact_statement` — free-form explanation citing evidence
+  (e.g., govulncheck output, code-path analysis, mitigation in place)
+
+`.trivyignore`, `# nosemgrep`, `// nolint:`, `# noqa` are NOT
+sanctioned suppression channels. Any of these in a PR must point at
+a documented false positive in the PR description; the project
+prefers the formal VEX statement for tracking.
+
+Per OSPS-VM-05.03, the suppression flow is also "documented policy":
+findings reachable in our code WITHOUT a VEX `not_affected` entry
+block the merge. Findings declared `not_affected` in VEX bypass the
+gate.