@sebastienrousseau/dotfiles 0.2.500 → 0.2.501

package/docs/security/CI_EGRESS_ALLOWLIST.md

@@ -0,0 +1,127 @@
+---
+render_with_liquid: false
+---
+
+# CI Egress Allowlist
+
+This page documents the network endpoints CI jobs are allowed to
+reach when `step-security/harden-runner` is operating in `block`
+mode. Managed under
+[#878](https://github.com/sebastienrousseau/dotfiles/issues/878).
+
+## Status
+
+All 76 jobs across the 28 workflow files in `.github/workflows/` are
+currently in **`audit` mode** — harden-runner is the first step in
+every job and records outbound network calls to the
+[step-security telemetry dashboard](https://app.stepsecurity.io) but
+does not block them.
+
+The next iteration (tracked as a follow-up under #878) flips each
+group to `block` once the audit-mode runs confirm the allowlist is
+complete. Switching one job at a time keeps blast radius small:
+a missing endpoint on a `block`-mode job fails the run loud and the
+list below gets updated.
+
+## Allowlist (by domain)
+
+This is the union of endpoints the entire workflow surface needs.
+When flipping a specific job to `block` mode, narrow this list to
+the endpoints that particular job actually touches.
+
+### GitHub itself (universally required)
+
+| Endpoint | Used by | Why |
+|---|---|---|
+| `github.com:443` | every job | git clone, gh CLI |
+| `api.github.com:443` | every job | gh CLI, issue/PR API |
+| `objects.githubusercontent.com:443` | every job | release-asset downloads, LFS objects |
+| `*.actions.githubusercontent.com:443` | every job | runner ↔ orchestrator |
+| `pkg.actions.githubusercontent.com:443` | every job | action-cache CDN |
+| `results-receiver.actions.githubusercontent.com:443` | every job | workflow telemetry |
+| `codeload.github.com:443` | jobs that `git clone` tagged refs | tarball downloads for some actions |
+| `uploads.github.com:443` | jobs that upload artifacts | `actions/upload-artifact` |
+| `raw.githubusercontent.com:443` | the install-script jobs | curl-pull of unversioned content |
+
+### Package managers (apt, brew, cargo, npm, luarocks)
+
+| Endpoint | Used by | Why |
+|---|---|---|
+| `azure.archive.ubuntu.com:443` | ubuntu jobs running `apt-get` | apt mirror |
+| `archive.ubuntu.com:80` | ubuntu jobs running `apt-get` | apt mirror |
+| `security.ubuntu.com:80` | ubuntu jobs running `apt-get` | security updates |
+| `keyserver.ubuntu.com:443` | jobs that add repo signing keys | GPG keyserver |
+| `formulae.brew.sh:443` | macOS jobs running `brew` | Homebrew formula index |
+| `ghcr.io:443` + `*.docker.io:443` | docker / container jobs | image pulls |
+| `registry.npmjs.org:443` | npm-publish.yml + the pre-commit npm hook | npm metadata + publish |
+| `registry-1.docker.io:443` | docker jobs | image manifests |
+| `crates.io:443` + `static.crates.io:443` | cargo-install jobs | crate downloads |
+| `index.crates.io:443` | cargo-install jobs | crate index |
+| `luarocks.org:443` + `*.luarocks.org:443` | reusable-lua-lint.yml | luacheck install |
+
+### Project-specific installers (chezmoi / mise / starship / stylua / typos / etc.)
+
+| Endpoint | Used by | Why |
+|---|---|---|
+| `get.chezmoi.io:443` | `setup-chezmoi` composite (fallback path) | chezmoi installer |
+| `mise.run:443` | `setup-mise` composite | mise installer |
+| `releases.starship.rs:443` | mise-managed install of starship | starship binary |
+
+### Security / SBOM / scanning
+
+| Endpoint | Used by | Why |
+|---|---|---|
+| `api.osv.dev:443` | grype / scorecard | OSV vuln database |
+| `vulners.com:443` | grype | vulnerability metadata |
+| `toolbox-data.anchore.io:443` | anchore/sbom-action | SBOM tooling |
+| `api.deps.dev:443` | future deps.dev integration (#877) | package metadata |
+| `api.securityscorecards.dev:443` | scorecard.yml | publish_results upload |
+| `*.codeql.github.com:443` | codeql.yml | CodeQL bundle download |
+
+## Job-level egress notes (legitimate broad-egress jobs)
+
+A few jobs need wider network access than the standard allowlist
+covers. Each carries an inline comment near the harden-runner step
+explaining the deviation so reviewers can audit at a glance.
+
+### `update-deps.yml` — broad GitHub API egress
+
+Polls multiple `github.com/<repo>/releases/latest` endpoints to find
+new tool versions. Allowlist needs to include `api.github.com:443`
+and the raw-content domain for sed-replacing version strings.
+
+### `devcontainer-prebuild.yml` — registry push
+
+Pushes to `ghcr.io:443` with the `packages: write` token. The egress
+allowlist for that job is the standard set plus `ghcr.io` writes.
+
+### `nightly.yml` — `Beta/Nightly Tools Test` job
+
+This job deliberately runs `curl ... | tar -xJf -` against the
+shellcheck release. Justified because the job is `continue-on-error: true`
+and is opt-in (manual or scheduled). Future hardening: download the
+release asset, verify a known hash, then exec — same shape as
+`scripts/ci/install-chezmoi-verified.sh`.
+
+## Updating this page
+
+Whenever a job is flipped to `block` mode:
+
+1. Run the audit-mode workflow at least once after every recent
+   workflow change to make sure the harden-runner telemetry reflects
+   reality.
+2. Visit the [step-security dashboard](https://app.stepsecurity.io/)
+   filtered to the repo + job + last 7 days.
+3. Add any endpoints the dashboard reports that aren't already in
+   this page's tables.
+4. Edit the job to set `egress-policy: block` and add the per-job
+   `allowed-endpoints:` block listing only what that specific job
+   needs (not the whole union).
+5. Land the change, watch the first run; if anything fails the run
+   loud, add the missing endpoint and retry.
+
+## References
+
+- `step-security/harden-runner` — [https://github.com/step-security/harden-runner](https://github.com/step-security/harden-runner)
+- `docs/security/SCORECARD.md` — Token-Permissions check ties to harden-runner adoption.
+- Issue [#878](https://github.com/sebastienrousseau/dotfiles/issues/878).

package/docs/security/COMPLIANCE.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Compliance Architecture
 
 This document describes the compliance, security, and cross-platform compatibility controls implemented in this repository, mapped to standard regulatory frameworks (SOC 2, ISO 27001, GDPR).
@@ -77,6 +81,7 @@ All network operations require valid TLS certificates:
 | Plaintext HTTP | `http://` URLs | CI warning |
 
 **Files:**
+
 - Pre-commit: `config/pre-commit-config.yaml`
 - CI: `.github/workflows/compliance-guard.yml`
 

package/docs/security/DEPS_DEV_EXCEPTIONS.md

@@ -0,0 +1,86 @@
+---
+render_with_liquid: false
+---
+
+# deps.dev Advisory Exceptions
+
+The CI workflow `.github/workflows/deps-dev-validation.yml` scans
+direct dependencies (npm + PyPI + GitHub Actions) against the
+[deps.dev Insights API](https://docs.deps.dev/) on every PR, every
+push to `master`, and every Tuesday at 04:00 UTC. When an advisory
+is reported at or above the threshold (default `HIGH`), the workflow
+fails.
+
+This page is where time-bound exceptions live. An entry here suppresses
+the check for one specific `(ecosystem, package)` pair, with an expiry
+date so the exception cannot accumulate quietly.
+
+Managed under [#877](https://github.com/sebastienrousseau/dotfiles/issues/877).
+
+## Active exceptions
+
+_(none currently)_
+
+## Adding an exception
+
+Add an entry below in this exact format — the scanner greps for
+`` `<ecosystem>:<package>` `` at the start of a line (case-sensitive,
+backtick-delimited):
+
+```
+`NPM:lodash` (expires 2026-12-31): Maintained fork; advisory affects
+only the unused stream-API code path. Confirmed via static analysis.
+Tracked under #NNNN.
+```
+
+`<ecosystem>` is one of:
+
+| Ecosystem | Source |
+|---|---|
+| `NPM` | `package.json` direct deps |
+| `PYPI` | `pyproject.toml` direct deps |
+| `GITHUB_ACTIONS` | `uses:` references in `.github/workflows/*.yml` |
+
+`(expires YYYY-MM-DD)` is required. Use a 90-day window for routine
+work; longer windows need a sentence explaining why and a follow-up
+issue link.
+
+## When to add vs not add
+
+**Legitimate exception**:
+
+- The advisory is in a code path your usage doesn't reach (e.g.
+  vulnerable function isn't called by anything in this repo).
+- The upstream fix is in flight and you've already opened a PR or
+  bumped to a beta.
+- The package is end-of-life and you're tracking the migration to a
+  successor under a dedicated issue.
+
+**Not an exception** — fix the dep instead:
+
+- "Bumping the version is annoying" — that's the whole point of the
+  gate.
+- "The advisory might be a false positive" — verify via deps.dev's
+  underlying source; if confirmed FP, file with deps.dev rather than
+  exception here.
+- "We don't have time this sprint" — that's a deferral, not an
+  exception. Bump the issue to next sprint, don't suppress.
+
+## Expiry policy
+
+The scanner does not currently parse expiry dates (deferred — needs
+a date-comparison helper). A monthly maintainer review of this page
+is the human gate. Any entry past its expiry should either be
+resolved (dep bumped, exception removed) or re-justified with a new
+expiry.
+
+When the date-parsing automation lands, expired exceptions will
+auto-fail the gate even when they're still listed here.
+
+## References
+
+- [`scripts/ci/check-deps-dev.sh`](../../scripts/ci/check-deps-dev.sh) — the scanner.
+- [`.github/workflows/deps-dev-validation.yml`](../../.github/workflows/deps-dev-validation.yml) — CI wiring.
+- [`tests/unit/security/test_check_deps_dev.sh`](../../tests/unit/security/test_check_deps_dev.sh) — contract test against canned fixtures.
+- [deps.dev API reference](https://docs.deps.dev/api/v3/).
+- Issue [#877](https://github.com/sebastienrousseau/dotfiles/issues/877).

package/docs/security/ENCRYPTION.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Secrets Encryption with SOPS and age
 
 ## Quick Start
@@ -30,6 +34,7 @@ sops secrets.sops.yaml
 ## Recovery
 
 If you lose your age private key, follow these steps:
+
 1. Create a new key: `age-keygen -o ~/.config/sops/age/keys.txt`
 2. Re-encrypt all secrets with the new public key.
 3. Update `.sops.yaml` with the new public key.

package/docs/security/FMEA.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Failure Mode and Effects Analysis (FMEA)
 
 Systematic risk assessment of the chezmoi-managed dotfiles repository per IEC 60812 methodology. Identifies failure modes, quantifies risk priority, and documents mitigations across all configuration management subsystems.

package/docs/security/HISTORY_FILTERING.md

@@ -0,0 +1,132 @@
+---
+render_with_liquid: false
+---
+
+# Atuin History Filtering
+
+This page documents how high-risk command patterns are excluded from
+Atuin shell history, how to extend the list for your machine, and the
+trade-offs of filter design.
+
+## Why
+
+Atuin syncs shell history across machines and exposes a fuzzy-search UI
+(`Ctrl-R`). Without a filter, every command — including ones that
+contain secrets passed inline (`AWS_SECRET_ACCESS_KEY=...`, `op run`,
+`vault read`, `curl -H 'Authorization: Bearer ...'`) — is captured,
+synced to a remote service, and made grep-able.
+
+The `history_filter` array in `~/.config/atuin/config.toml` lists
+regular expressions that, if matched, prevent Atuin from recording the
+command at all (it never enters the local DB, and therefore never
+syncs).
+
+## How it ships
+
+Patterns are sourced from `.chezmoidata/secrets-patterns.toml` and
+materialised into `~/.config/atuin/config.toml` by the chezmoi template
+at `dot_config/atuin/config.toml.tmpl`.
+
+```
+.chezmoidata/secrets-patterns.toml
+  └── [atuin.history_filter]
+        defaults  = [...]      # audited baseline (this repo)
+        extra     = [...]      # empty by default; populated per machine
+
+dot_config/atuin/config.toml.tmpl
+  └── chezmoi apply  ─────►  ~/.config/atuin/config.toml
+```
+
+Run `chezmoi apply ~/.config/atuin/config.toml` after editing the
+defaults; `dot doctor` reports the count of deployed patterns and
+fails loud if the block is missing.
+
+## What's filtered by default
+
+The audited baseline covers:
+
+- Generic env-var exports: `^export (SECRET|TOKEN|PASSWORD|API_KEY|AWS_)`,
+  `^PASSWORD=`, `^[A-Z_]+_TOKEN=`, `^[A-Z_]+_KEY=`.
+- Cloud provider auth: `aws ... configure|auth|login`, `gcloud auth ...`,
+  `az login`, `kubectl ... --kubeconfig`.
+- AI provider keys: Anthropic, OpenAI, Gemini, Mistral.
+- SaaS secrets: Stripe, GitHub PAT (`GH_TOKEN`, `GITHUB_TOKEN`), `NPM_TOKEN`,
+  `CARGO_REGISTRY_TOKEN`.
+- Authorization headers (`curl -H 'Authorization: ...'`).
+- Embedded creds in git URLs (`git clone https://user:pass@...`).
+- Secret managers: `vault`, `op` (1Password), `chamber`.
+- Key material: `ssh-keygen`, `ssh-add`, `gpg --import|--export-secret`,
+  `age -d|-e --passphrase`.
+- DB connection strings with inline creds
+  (`postgres|mysql|mongodb|redis://user:pass@host`).
+
+See `.chezmoidata/secrets-patterns.toml` for the canonical list.
+
+## Adding per-host patterns
+
+Each contributor or machine can extend the list without editing the
+shared template. In `~/.config/chezmoi/chezmoi.toml`:
+
+```toml
+[data.atuin.history_filter]
+extra = [
+  "^my-private-tool ",
+  "^OUR_CORP_API_KEY=",
+  "tailscale up --auth-key=",
+]
+```
+
+Then re-apply:
+
+```bash
+chezmoi apply ~/.config/atuin/config.toml
+```
+
+The `extra` patterns are appended to the defaults in the deployed
+config.
+
+## Adding a pattern to the project defaults
+
+Edit `.chezmoidata/secrets-patterns.toml` and add a regex to
+`[atuin.history_filter].defaults`. Then:
+
+1. Add a fixture command to `tests/unit/secrets/test_atuin_history_filter.sh`
+   under `LEAKED_FIXTURES` — your new pattern must catch at least one
+   real-shape command.
+2. Run the test: `bash tests/unit/secrets/test_atuin_history_filter.sh`.
+3. Add a benign-fixture if your regex is broad enough to risk false
+   positives.
+4. Open a PR; CI runs the same test.
+
+## Trade-offs
+
+`history_filter` is a deny-list. Two classes of failure to design
+around:
+
+- **False positives**: an overly broad regex hides commands the user
+  needs to recall. Mitigation: every new pattern must include a
+  fixture under `BENIGN_FIXTURES` that the regex correctly does *not*
+  match.
+- **False negatives**: a new secret format ships, no pattern matches,
+  the secret lands in history. Mitigation: the OpenSSF Scorecard
+  workflow (issue #869) and the nightly drift detector (#875) will
+  surface new exposure surfaces; review them quarterly.
+
+`history_filter` does not replace:
+
+- A real secret manager (`age`/`sops`, 1Password, Vault) — see
+  `docs/security/ENCRYPTION.md`.
+- Pre-commit `gitleaks` / `detect-secrets` scans — see
+  `config/pre-commit-config.yaml`.
+- Server-side audit logging — see `docs/security/COMPLIANCE.md`.
+
+It's the last line of defence against accidental command-line capture,
+not the first.
+
+## References
+
+- Atuin config schema: <https://atuin.sh/docs/config>
+- Chezmoi template data: <https://www.chezmoi.io/reference/templates/>
+- Issue #872 (this hardening)
+- `tests/unit/secrets/test_atuin_history_filter.sh` (pattern-coverage test)
+- `scripts/diagnostics/doctor.sh` — "Atuin History Filter" section

package/docs/security/INCIDENT_RESPONSE.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Incident Response Plan
 
 Incident response procedures for the dotfiles repository. Covers supply chain compromise, secrets exposure, configuration drift, tool tampering, and CI pipeline attacks. Based on NIST SP 800-61 Rev. 2 (Computer Security Incident Handling Guide).

package/docs/security/INSTALL_VERIFICATION.md

@@ -0,0 +1,122 @@
+---
+render_with_liquid: false
+---
+
+# Install Verification
+
+This page documents what gets verified during `install.sh` execution,
+why those checks matter, and how to obtain the per-release expected
+hashes used by the verified-install path in the README.
+
+Managed under
+[#858](https://github.com/sebastienrousseau/dotfiles/issues/858).
+
+## What is verified
+
+`install.sh` performs three classes of verification before doing
+anything destructive:
+
+### 1. The installer itself (verified path)
+
+The README's **Verified install** snippet pins to a release tag
+(e.g. `v0.2.501`), downloads the installer, and asks `shasum -a 256
+-c` (or `sha256sum -c`) to check the contents against an expected
+hash. If the hash doesn't match, the verify step exits non-zero and
+the install never starts.
+
+### 2. The `chezmoi` binary (always verified when possible)
+
+`install.sh` prefers the bundled checksum-verified installer at
+`scripts/ci/install-chezmoi-verified.sh`, which:
+
+- Resolves the platform (`uname -s` + `uname -m`).
+- Downloads `chezmoi_<version>_<os>_<arch>.tar.gz` AND the matching
+  `chezmoi_<version>_checksums.txt` from the official
+  `twpayne/chezmoi` GitHub release.
+- Greps the checksum file for the asset's expected SHA256.
+- Verifies the downloaded tarball against that SHA256 using
+  `shasum -a 256 -c` / `sha256sum -c`.
+- Aborts with a clear error if the asset isn't in the checksum file
+  or the verification fails.
+
+When the verified installer isn't available (e.g. the curl one-liner
+mode where `install.sh` is fetched in isolation), the code falls back
+to `get.chezmoi.io` with two defense-in-depth checks:
+
+- The downloaded installer must be smaller than 100 KiB (sanity
+  guard against a CDN serving an arbitrary binary).
+- The first line must start with `#!/` (must look like a shell
+  script).
+
+These are weaker than a SHA256 check, but they catch the obvious
+"installer got replaced with a 50 MB malicious binary" failure mode.
+
+### 3. The chezmoi source tree
+
+After chezmoi is installed, `install.sh` clones the dotfiles repo
+itself. This isn't currently cryptographically verified beyond Git's
+own object integrity, but commits in the repo are SSH-signed and
+branch protection on `master` requires signed commits (see #853).
+
+## How to obtain per-release hashes
+
+The verified-install snippet uses the SHA256 of the `install.sh`
+file *as it exists at the release tag*. To regenerate after a release:
+
+```bash
+git switch master
+git pull
+NEW_TAG="v0.2.502"   # adjust
+git tag -s "$NEW_TAG" -m "..."
+git push origin "$NEW_TAG"
+
+# Compute the hash:
+shasum -a 256 install.sh
+
+# Update README.md's verified-install snippet with the new hash + tag.
+```
+
+A follow-up automation (tracked at the bottom of this page) will
+publish a `.sha256` sibling next to the install.sh asset in GitHub
+Releases so the README snippet can reference a stable URL instead
+of a hardcoded value.
+
+## What to do if the hash doesn't match
+
+If you run the verified install and `shasum -a 256 -c` reports
+`FAILED`:
+
+1. **Don't run the installer.** The hash mismatch means either the
+   release was retagged (rare) or someone is MITM-ing your download.
+2. Check the [Releases page](https://github.com/sebastienrousseau/dotfiles/releases)
+   for the matching tag. The per-release `install.sh` SHA is
+   embedded in the README at the time of that release; you can also
+   recover it from the git history of `README.md`.
+3. If the README hash is stale (release was retagged for legitimate
+   reasons), `git log` on `install.sh` will show the change. Inspect
+   the diff before trusting a new hash.
+
+## What is NOT verified (yet)
+
+- **Cosign keyless signature** on `install.sh` — tracked separately
+  under #876.
+- **deps.dev attestation lookup** for npm/Python deps used during
+  install — tracked under #877.
+- **Reproducible-build guarantee** for the chezmoi binary itself —
+  out of scope; rely on the upstream project's release engineering.
+
+## Negative-test coverage
+
+`tests/unit/install/test_install_chezmoi_verified.sh` exercises the
+verification path with a deliberately tampered checksum to confirm
+the installer aborts. The test ships with the repo and runs on every
+PR.
+
+## References
+
+- `install.sh` — the entry point.
+- `scripts/ci/install-chezmoi-verified.sh` — the SHA256-pinned
+  chezmoi installer.
+- `tests/unit/install/test_install_chezmoi_verified.sh` — the
+  negative test.
+- Issue [#858](https://github.com/sebastienrousseau/dotfiles/issues/858).

package/docs/security/KEYS.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Keybindings
 
 This is the single source of truth for navigation and muscle-memory shortcuts

package/docs/security/KEY_ROTATION.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Key Rotation Guide
 
 This guide covers rotating encryption keys for secrets managed by Age and SOPS.

package/docs/security/MCP_POLICY.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # MCP Policy
 
 MCP is treated as a controlled execution boundary.
@@ -7,6 +11,7 @@ MCP is treated as a controlled execution boundary.
 The tracked default is `strict-local`.
 
 Properties:
+
 - local-first
 - least privilege
 - no broad filesystem roots
@@ -21,6 +26,7 @@ Approved package pins live in [mcp-lock.json](/home/seb/.dotfiles/dot_config/dot
 Tracked server registry entries live in [mcp-registry.json](/home/seb/.dotfiles/dot_config/dotfiles/mcp-registry.json).
 
 Current defaults:
+
 - Allowed launchers: `npx`, `node`, `uvx`
 - Trusted transports: `stdio`, `http`
 - Blocked filesystem roots: `/`, `/home`, `/Users`
@@ -45,6 +51,7 @@ The JSON form is the audit artifact for CI, release validation, and workstation
 ## Change control
 
 Any change to MCP policy requires:
+
 1. A signed commit
 2. A matching test update
 3. A release note if the effective trust boundary changes
@@ -55,11 +62,13 @@ Any change to MCP policy requires:
 Phase 2 adds explicit package locking for default MCP servers.
 
 Current approved refs:
+
 - `mcp-server-git@2025.1.14`
 - `@modelcontextprotocol/server-memory@2025.8.4`
 - `mcp-server-sqlite@2025.1.14`
 
 `dot mcp --strict` and `dot mcp -s` now verify that:
+
 - package refs are version-pinned
 - the pinned refs match the tracked lock manifest
 - non-approved package refs are rejected in strict mode

package/docs/security/POLICY_RELEASES.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Policy Bundle Releases
 
 Policy bundles are released as tracked governance artifacts.

package/docs/security/README.md

@@ -1,3 +1,7 @@
+---
+render_with_liquid: false
+---
+
 # Security Documentation
 
 This directory contains security documentation for the dotfiles project.

package/docs/security/SCORECARD.md

@@ -0,0 +1,80 @@
+---
+render_with_liquid: false
+---
+
+# OpenSSF Scorecard
+
+This page records the current OpenSSF Scorecard posture for this
+repository, the known gaps, and the remediation roadmap. The badge in
+the README links to the live result; this page is the maintained
+narrative behind it.
+
+## Live score
+
+[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/sebastienrousseau/dotfiles/badge)](https://scorecard.dev/viewer/?uri=github.com/sebastienrousseau/dotfiles)
+
+The badge above is regenerated every Monday at 06:00 UTC and on every
+push to `master` by `.github/workflows/scorecard.yml`. The SARIF
+result is uploaded to GitHub Code Scanning (Security tab) and
+retained as a 30-day workflow artifact.
+
+## Threshold policy
+
+| Score | Action |
+|---|---|
+| ≥ 8.0 | Healthy. Keep doing what we're doing. |
+| 7.0 – 7.9 | Acceptable. Tracked. |
+| < 7.0 | Regression — the workflow auto-opens a tracking issue labelled `type:security + priority:high`. |
+
+Regressions are triaged within one Monday cycle: identify the check
+that dropped, either remediate or file an exception entry below with
+a rationale and an expiry date.
+
+## Per-check posture (snapshot)
+
+The checks below come from OpenSSF Scorecard's published rubric. Tick
+marks reflect this repo's posture at the time of writing — the
+*live* badge is authoritative if these diverge.
+
+| Check | Status | Notes |
+|---|---|---|
+| Branch-Protection | ✓ | `master` requires signed commits, linear history, required checks. Codified at `.github/rulesets/master.json` and `.github/branch-protection-config.json`. |
+| Code-Review | ✓ | Every PR requires at least one approval; CODEOWNERS in place. |
+| Signed-Commits | ✓ | Enforced by pre-push hook (`scripts/git-hooks/pre-push`) and at-push by branch protection (#853 + #857). |
+| Dependency-Update-Tool | ✓ | Dependabot configured for github-actions / npm / docker / devcontainers / uv. |
+| Fuzzing | ⚠ | `install.sh` fuzz harness lives under `tests/fuzz/` (closes #881). Coverage is the script's CLI surface plus chaos input fixtures — not full corpus fuzzing yet. |
+| License | ✓ | Apache-2.0 at repo root. |
+| Maintained | ✓ | Active commit cadence; the [README](../../README.md) lists the current `dotfiles_version` (v0.2.501). |
+| Pinned-Dependencies | ✓ | Every workflow action is pinned to a 40-char commit SHA; the lint rule under `actionlint` enforces this on PR. |
+| SAST | ✓ | CodeQL (`.github/workflows/codeql.yml`) + Checkov + Grype. |
+| SBOM | ✓ | Generated per PR by `sbom-diff.yml` and per release by `security-release.yml`. |
+| Security-Policy | ✓ | `.github/SECURITY.md` + this page + `docs/security/THREAT_MODEL.md`. |
+| Token-Permissions | ✓ | Workflows use least-privilege `permissions:` blocks. `harden-runner` adoption (#878) tightens this further. |
+| Vulnerabilities | ✓ | Grype gate hard-fails on `high` / `critical` on `master` (#852). |
+| Webhooks | n/a | No external webhooks configured. |
+| CI-Tests | ✓ | Comprehensive CI matrix (Linux + macOS Intel + Apple Silicon, optional Windows). |
+| CII-Best-Practices | ☐ | Not applied yet — see "Open work" below. |
+| Dangerous-Workflow | ✓ | No `pull_request_target` with checkout-PR-code anti-pattern. |
+| Packaging | ✓ | `npm publish --provenance` via OIDC (`.github/workflows/npm-publish.yml`); `policy-bundle-release.yml` for the policy artifact. |
+
+## Open work
+
+- Apply for the [OpenSSF Best Practices badge (CII)](https://www.bestpractices.dev/) and embed it next to the Scorecard badge. (Maintainer action — needs the project to register with the BestPractices.dev site.)
+- Once `harden-runner` is in `block` mode across all jobs (#878), the **Token-Permissions** check should hit its maximum.
+- Once Cosign keyless signing is wired into the release pipeline (#876), the **Signed-Releases** check should hit its maximum.
+
+## Exceptions
+
+| Check | Expiry | Rationale |
+|---|---|---|
+| *(none currently)* | *—* | *—* |
+
+If you add an exception, include the check name, an expiry date
+(don't allow indefinite), and the rationale. Re-evaluate every quarter.
+
+## References
+
+- `.github/workflows/scorecard.yml` — the scanner.
+- [Scorecard project](https://github.com/ossf/scorecard).
+- [Scorecard checks reference](https://github.com/ossf/scorecard/blob/main/docs/checks.md).
+- Issue [#869](https://github.com/sebastienrousseau/dotfiles/issues/869).