@sebastienrousseau/dotfiles 0.2.499 → 0.2.501

package/docs/security/FMEA.md

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