@sebastienrousseau/dotfiles 0.2.519 → 0.2.521

package/docs/security/ENCRYPTION.md

@@ -1,57 +0,0 @@
----
-render_with_liquid: false
----
-
-# Secrets Encryption with SOPS and age
-
-## Quick Start
-
-```bash
-# 1. Generate an age key (one-time)
-mkdir -p ~/.config/sops/age
-age-keygen -o ~/.config/sops/age/keys.txt
-
-# 2. Get your public key
-age-keygen -y ~/.config/sops/age/keys.txt
-# Output: age1abc123...
-
-# 3. Update .sops.yaml with your public key
-# Replace the placeholder key in .sops.yaml with your actual public key
-
-# 4. Encrypt a file
-sops --encrypt --age $(age-keygen -y ~/.config/sops/age/keys.txt) secrets.yaml > secrets.sops.yaml
-
-# 5. Edit encrypted files
-sops secrets.sops.yaml
-```
-
-## Key Management
-
-- **Private key**: `~/.config/sops/age/keys.txt` — never commit this file.
-- **Public key**: Safe to share. It lives in `.sops.yaml`.
-- **Backup**: Keep your private key in a password manager or a hardware security module.
-
-## 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.
-
-## Integration with Chezmoi
-
-Chezmoi has built-in support for age encryption.
-
-```bash
-chezmoi add --encrypt ~/.ssh/config
-```
-
-This encrypts the file in the source state. It uses the age key set in `~/.config/chezmoi/chezmoi.toml`:
-
-```toml
-encryption = "age"
-[age]
-identity = "~/.config/sops/age/keys.txt"
-recipient = "age1abc123..."
-```

package/docs/security/FMEA.md

@@ -1,159 +0,0 @@
----
-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.
-
-## Purpose
-
-This document applies Failure Mode and Effects Analysis (FMEA) to a chezmoi-managed dotfiles repository. Each failure mode is evaluated by Severity, Occurrence, and Detection ratings to produce a Risk Priority Number (RPN). The RPN drives mitigation priority and review cadence.
-
-Methodology: IEC 60812:2018 — Analysis techniques for system reliability.
-
-## Scope
-
-| Domain | Coverage |
-|--------|----------|
-| Shell configuration | Zsh, Fish, Nushell startup, aliases, functions, `rc.d` modules |
-| Tool management | mise, Homebrew, Nix flakes, Zinit plugins, Neovim plugins |
-| Secrets management | Age encryption, gitleaks, 1Password integration, Atuin history |
-| CI/CD pipeline | GitHub Actions workflows, pre-commit hooks, compliance guards |
-| Cross-platform deployment | macOS (BSD), Linux (GNU), WSL, chezmoi templating |
-| Git integrity | Signed commits, branch protection, CODEOWNERS |
-
----
-
-## Rating Scales
-
-### Severity (S)
-
-| Rating | Level | Definition |
-|--------|-------|------------|
-| 1 | None | No effect on system operation |
-| 2 | Very Minor | Cosmetic defect noticed only by maintainer |
-| 3 | Minor | Minor degradation, workaround available |
-| 4 | Very Low | Subsystem partially impaired, user notices |
-| 5 | Low | Subsystem degraded, reduced functionality |
-| 6 | Moderate | System operates with degraded performance |
-| 7 | High | System operates but critical function impaired |
-| 8 | Very High | System inoperable, data at risk |
-| 9 | Hazardous with Warning | Potential security breach, credentials exposed |
-| 10 | Hazardous without Warning | Secret exfiltration, supply chain compromise, silent data loss |
-
-### Occurrence (O)
-
-| Rating | Level | Definition |
-|--------|-------|------------|
-| 1 | Nearly Impossible | < 1 in 1,000,000 operations |
-| 2 | Remote | 1 in 100,000 operations |
-| 3 | Very Low | 1 in 10,000 operations |
-| 4 | Low | 1 in 1,000 operations |
-| 5 | Moderate | 1 in 200 operations |
-| 6 | Moderately High | 1 in 50 operations |
-| 7 | High | 1 in 20 operations |
-| 8 | Very High | 1 in 10 operations |
-| 9 | Extremely High | 1 in 3 operations |
-| 10 | Certain | Every operation |
-
-### Detection (D)
-
-| Rating | Level | Definition |
-|--------|-------|------------|
-| 1 | Almost Certain | Automated control detects failure every time |
-| 2 | Very High | Automated control with >99% detection rate |
-| 3 | High | Automated test catches most occurrences |
-| 4 | Moderately High | CI pipeline detects on PR merge |
-| 5 | Moderate | Detected during routine manual review |
-| 6 | Low | Detected only by targeted audit |
-| 7 | Very Low | Requires manual inspection to discover |
-| 8 | Remote | Detected only after user reports failure |
-| 9 | Very Remote | Detected only after external incident |
-| 10 | Undetectable | No mechanism exists to detect the failure |
-
----
-
-## FMEA Table
-
-| ID | Component | Failure Mode | Effect | S | O | D | RPN | Mitigation | Status |
-|----|-----------|-------------|--------|---|---|---|-----|------------|--------|
-| FM-01 | Secrets Management | Secrets committed to git (gitleaks bypass) | API keys, tokens, or passwords exposed in public git history | 10 | 3 | 2 | 60 | Gitleaks pre-commit hook, TruffleHog CI scan, detect-secrets baseline, `.gitignore` excludes `key.txt`/`.env` | Mitigated |
-| FM-02 | Shell Configuration | `chezmoi apply` corrupts shell config | Login shell fails to start, user locked out of interactive session | 9 | 3 | 3 | 81 | `chezmoi apply --dry-run` in CI, `chezmoi diff` pre-check, version-controlled rollback via `git checkout` | Mitigated |
-| FM-03 | Git Integrity | Unsigned commit pushed (GPG/SSH bypass) | Commit attribution unverifiable, compliance violation (SOC 2 CC6.8) | 7 | 4 | 2 | 56 | Pre-push hook verifies signatures, `compliance-guard.yml` CI check, `commit.gpgsign = true` default | Mitigated |
-| FM-04 | Tool Management | mise tool update introduces vulnerability | Compromised binary executes with user privileges on every shell start | 10 | 2 | 6 | 120 | Pinned tool versions in `.tool-versions`, Nix flake lock reproducibility, manual version audit | Monitoring |
-| FM-05 | Shell Performance | Shell startup exceeds 500ms | Degraded developer experience, productivity loss, user disables safety features | 5 | 5 | 3 | 75 | `_cached_eval` mtime-based caching, `DOTFILES_ULTRA_FAST=1` bypass, `dot health` startup benchmark | Mitigated |
-| FM-06 | Cross-Platform | BSD vs GNU incompatibility | Script fails silently or produces incorrect output on macOS or Linux | 6 | 5 | 3 | 90 | `cross-platform-test.yml` CI on macOS + Linux, `$OSTYPE` guards, portable alternatives documented in COMPLIANCE.md | Mitigated |
-| FM-07 | CI/CD Pipeline | CI workflow tampered (Actions injection) | Attacker executes arbitrary code in CI, exfiltrates secrets, modifies artifacts | 10 | 2 | 4 | 80 | Actions pinned to SHA, `permissions: contents: read` default, concurrency control, explicit job timeouts | Mitigated |
-| FM-08 | Secrets Management | Age encryption key lost | Encrypted dotfiles unrecoverable, secrets permanently inaccessible | 9 | 2 | 8 | 144 | Key backup in 1Password vault, documented recovery procedure in KEYS.md, periodic backup verification | Monitoring |
-| FM-09 | Shell Configuration | Alias conflict breaks existing command | User command produces unexpected behavior, data loss in destructive operations | 7 | 4 | 5 | 140 | Alias naming conventions (`chezmoi_` prefix for internal), unit tests for all 99 alias files, `type` command verification | Monitoring |
-| FM-10 | Tool Management | Nix flake lock stale (>30 days) | Outdated dependencies with known vulnerabilities, reproducibility drift | 6 | 6 | 4 | 144 | `nightly.yml` dependency version checks, `nix flake update` in maintenance schedule, `dot health` staleness check | Monitoring |
-| FM-11 | Git Integrity | Pre-commit hook bypassed (`--no-verify`) | Secrets, lint failures, and insecure patterns reach the repository | 8 | 4 | 7 | 224 | CI re-runs all pre-commit checks (`compliance-guard.yml`), branch protection requires CI pass, audit log review | Mitigated |
-| FM-12 | Cross-Platform | Config drift between machines | Inconsistent behavior across workstations, unreproducible environments | 5 | 5 | 6 | 150 | Chezmoi state management, `chezmoi status` diff check, feature flags in `.chezmoidata.toml`, CI dry-run on both platforms | Monitoring |
-| FM-13 | Network Security | TLS certificate validation disabled | Man-in-the-middle interception of downloads, credential theft | 10 | 2 | 2 | 40 | `curl -k` and `wget --no-check-certificate` blocked by pre-commit and CI, pattern scanning in `compliance-guard.yml` | Mitigated |
-| FM-14 | File Permissions | World-writable file permissions (chmod 777) | Any local user or process can modify configs, privilege escalation vector | 9 | 2 | 2 | 36 | `chmod 777/666` blocked by pre-commit and CI, chezmoi `private_` prefix enforces 0600, `umask 022` default | Mitigated |
-| FM-15 | Template Engine | Template rendering failure (`.tmpl` syntax error) | Chezmoi apply fails, partial deployment leaves inconsistent state | 7 | 4 | 2 | 56 | `chezmoi apply --dry-run` in CI on Linux + macOS, template syntax validated before merge, `chezmoi execute-template` for local testing | Mitigated |
-
----
-
-## Risk Priority Summary
-
-### Critical (RPN > 200)
-
-| ID | Component | Failure Mode | RPN | Action Required |
-|----|-----------|-------------|-----|-----------------|
-| FM-11 | Git Integrity | Pre-commit hook bypassed (`--no-verify`) | 224 | CI enforcement layer catches all bypassed checks; add GitHub branch protection rule requiring status checks to pass |
-
-### High (RPN 100-200)
-
-| ID | Component | Failure Mode | RPN | Action Required |
-|----|-----------|-------------|-----|-----------------|
-| FM-12 | Cross-Platform | Config drift between machines | 150 | Implement `chezmoi status` in `dot health` dashboard; alert on drift >24 hours |
-| FM-10 | Tool Management | Nix flake lock stale (>30 days) | 144 | Enforce flake freshness check in nightly CI; auto-create PR on staleness |
-| FM-08 | Secrets Management | Age encryption key lost | 144 | Quarterly key backup verification; document recovery runbook |
-| FM-09 | Shell Configuration | Alias conflict breaks existing command | 140 | Expand alias unit tests with conflict detection; `type` validation in CI |
-| FM-04 | Tool Management | mise tool update introduces vulnerability | 120 | Pin versions, audit changelogs before updates, monitor CVE databases |
-
-### Medium (RPN 50-100)
-
-| ID | Component | Failure Mode | RPN | Action Required |
-|----|-----------|-------------|-----|-----------------|
-| FM-06 | Cross-Platform | BSD vs GNU incompatibility | 90 | Maintain cross-platform CI matrix; document portable alternatives |
-| FM-02 | Shell Configuration | `chezmoi apply` corrupts shell config | 81 | CI dry-run enforcement; rollback documentation |
-| FM-07 | CI/CD Pipeline | CI workflow tampered (Actions injection) | 80 | SHA-pinned actions; minimal permissions; periodic audit |
-| FM-05 | Shell Performance | Shell startup exceeds 500ms | 75 | Performance regression tests in CI; cache warming |
-| FM-01 | Secrets Management | Secrets committed to git (gitleaks bypass) | 60 | Multi-layered scanning (pre-commit + CI + detect-secrets) |
-| FM-03 | Git Integrity | Unsigned commit pushed (GPG/SSH bypass) | 56 | Pre-push hook + CI verification |
-| FM-15 | Template Engine | Template rendering failure (`.tmpl` syntax error) | 56 | CI dry-run on both platforms |
-
-### Low (RPN < 50)
-
-| ID | Component | Failure Mode | RPN | Action Required |
-|----|-----------|-------------|-----|-----------------|
-| FM-13 | Network Security | TLS certificate validation disabled | 40 | Automated pattern blocking; no further action |
-| FM-14 | File Permissions | World-writable file permissions (chmod 777) | 36 | Automated pattern blocking; no further action |
-
----
-
-## Review Schedule
-
-| Activity | Cadence | Owner | Deliverable |
-|----------|---------|-------|-------------|
-| FMEA full review | Quarterly | Repository maintainer | Updated FMEA table, revised RPNs |
-| RPN recalculation | After each mitigation change | Repository maintainer | Updated RPN values, status changes |
-| Critical item review | Monthly | Repository maintainer | Action items for RPN > 200 |
-| New failure mode triage | Per incident | Repository maintainer | New FMEA row, initial RPN assignment |
-| Detection control audit | Quarterly | Repository maintainer | Verify automated controls function correctly |
-| Mitigation effectiveness | Semi-annually | Repository maintainer | Compare actual vs predicted occurrence rates |
-
-**Next scheduled review:** 2026-06-20
-
----
-
-## References
-
-- [IEC 60812:2018](https://www.iso.org/standard/64076.html) — Analysis techniques for system reliability
-- [AIAG FMEA Handbook](https://www.aiag.org/quality/automotive-core-tools/fmea) — Automotive Industry Action Group FMEA methodology
-- [COMPLIANCE.md](COMPLIANCE.md) — Regulatory mapping and security controls
-- [THREAT_MODEL.md](THREAT_MODEL.md) — Trust boundaries and attack surface analysis
-- [SECURITY.md](SECURITY.md) — Vulnerability reporting and response SLAs

package/docs/security/FUZZING.md

@@ -1,114 +0,0 @@
----
-title: "Fuzzing"
-date: 2026-05-17
----
-
-# Fuzzing
-
-The project ships native-Go fuzz harnesses for every user-input
-parsing surface in the framework. The harnesses run locally via
-`go test -fuzz`, in CI on every PR via `.github/workflows/fuzz.yml`,
-and (pending upstream submission) continuously on Google's OSS-Fuzz
-infrastructure.
-
-## Why Go fuzzing
-
-The framework is bash. Bash has no first-class fuzzing framework
-that OpenSSF Scorecard recognises (Scorecard scores `Fuzzing` 0
-unless the project ships an integration with one of: OSS-Fuzz,
-ClusterFuzzLite, native Go fuzz, libFuzzer, Atheris). The
-pragmatic path is to **port each user-input parsing surface
-into a small Go function**, run the fuzzer against the Go port,
-and keep the Go port in lockstep with the shell original via
-identical regex / control-flow.
-
-Drift between the shell and Go port IS the bug class the
-fuzzer is designed to surface — if the Go port accepts a string
-the shell rejects (or vice-versa), one of them has a hole.
-
-## Harnesses today
-
-| Harness | Mirrors | What it proves |
-|---------|---------|----------------|
-| `FuzzValidateName` | `scripts/dot/lib/utils.sh:101` (`validate_name`) | Every accepted name contains only `[a-zA-Z0-9._-]`; no shell metacharacter slips through; empty input refused. |
-| `FuzzInitURLResolver` | `scripts/dot/commands/init.sh` (URL construction in `dot init <user\|owner/repo\|url>`) | Accepted URLs use `https://` / `git@` / `ssh://` only; plain HTTP refused; no shell metacharacters in constructed URLs; one input shape per acceptable form. |
-
-Add a harness when:
-
-- a new `dot <subcommand>` accepts user input via `$1` / `--flag`,
-- a new regex appears in `scripts/dot/lib/utils.sh`,
-- a new "construct a URL / path / shell-eval string" code path lands.
-
-## Running locally
-
-```sh
-cd oss-fuzz-integration/fuzz
-
-# 30-second smoke (find regressions quickly)
-go test -run TestNothing -fuzz=FuzzValidateName    -fuzztime=30s ./...
-go test -run TestNothing -fuzz=FuzzInitURLResolver -fuzztime=30s ./...
-
-# Longer run when investigating a flake
-go test -run TestNothing -fuzz=FuzzValidateName    -fuzztime=10m ./...
-```
-
-Failures land in `testdata/fuzz/Fuzz<Name>/` as auto-saved
-reproducers. Commit them — they become permanent regression
-guards via `go test ./...`.
-
-## OSS-Fuzz integration (pending)
-
-The `oss-fuzz-integration/` directory contains everything OSS-Fuzz
-needs to onboard this project:
-
-```
-oss-fuzz-integration/
-├── project.yaml      # OSS-Fuzz project metadata
-├── Dockerfile        # build environment
-├── build.sh          # compiles every harness in fuzz/
-└── fuzz/             # the harnesses themselves
-    ├── go.mod
-    ├── validate_name_test.go
-    └── init_url_resolver_test.go
-```
-
-To onboard:
-
-1. Fork `github.com/google/oss-fuzz`.
-2. Copy `oss-fuzz-integration/` contents to `projects/dotfiles/` in the fork.
-3. Verify locally per <https://google.github.io/oss-fuzz/getting-started/new-project-guide/#testing-locally>:
-
-   ```sh
-   python infra/helper.py build_image dotfiles
-   python infra/helper.py build_fuzzers --sanitizer address dotfiles
-   python infra/helper.py check_build dotfiles
-   python infra/helper.py run_fuzzer dotfiles fuzz_validate_name
-   ```
-
-4. Open a PR to `google/oss-fuzz` per <https://google.github.io/oss-fuzz/getting-started/accepting-new-projects/>.
-5. Once merged, OSS-Fuzz schedules continuous runs on GCP; findings land as private issues in the OSS-Fuzz tracker and are mirrored to the maintainer email in `project.yaml`.
-6. Update `docs/security/SCORECARD.md` — Scorecard's `Fuzzing` check recognises OSS-Fuzz projects automatically (0 → 10).
-
-The upstream PR opens the door to the **CIFuzz** GitHub Action,
-which runs OSS-Fuzz-style fuzzing on every PR in this repo
-(separate from the local-go-fuzz CI job).
-
-## CI workflow
-
-`.github/workflows/fuzz.yml` (planned) runs each harness for
-60 seconds on every PR touching:
-
-- `scripts/dot/lib/utils.sh`
-- `scripts/dot/commands/init.sh`
-- `oss-fuzz-integration/**`
-
-This is the local equivalent of CIFuzz and catches the
-"shell-regex-change without Go-port update" drift class before
-PR merge.
-
-## See also
-
-- `docs/security/SCORECARD.md` — `Fuzzing` check tracking.
-- [Go native fuzzing tutorial](https://go.dev/doc/tutorial/fuzz).
-- [OSS-Fuzz new project guide](https://google.github.io/oss-fuzz/getting-started/new-project-guide/).
-- [CIFuzz GitHub Action](https://google.github.io/oss-fuzz/getting-started/continuous-integration/).

package/docs/security/HISTORY_FILTERING.md

@@ -1,132 +0,0 @@
----
-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