@sebastienrousseau/dotfiles 0.2.499 → 0.2.501

package/docs/security/COMPLIANCE.md

@@ -0,0 +1,458 @@
+---
+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).
+
+## Overview
+
+| Framework | Status | Description |
+|-----------|--------|-------------|
+| SOC 2 Type II | Aligned | Security, availability, and confidentiality |
+| ISO 27001 | Aligned | Information security management controls |
+| GDPR/HIPAA | Aligned | Privacy and data protection |
+| ISO 13485 | Aligned | Risk management (FMEA), verification & validation |
+| ALCOA | Implemented | Audit trail integrity |
+| EU AI Act | Exempt | Minimal risk, open-source exemption (Article 2(12)) |
+
+---
+
+## EU AI Act (Regulation (EU) 2024/1689)
+
+| Requirement | Status | Implementation |
+|-------------|--------|----------------|
+| **Risk classification** | Minimal risk | No high-risk use cases (Annex III) |
+| **Open-source exemption** | Applicable | MIT license, no model weights distributed (Article 2(12)) |
+| **Prohibited practices** | Confirmed none | No subliminal, exploitative, or social scoring use (Article 5) |
+| **Transparency** | Voluntary | Agent session logging, model registry, attestation |
+| **GPAI provisions** | Not applicable | Consumer of AI APIs, not a provider |
+
+See [AI_ACT_COMPLIANCE.md](AI_ACT_COMPLIANCE.md) for full assessment.
+
+---
+
+## Regulatory Mapping
+
+### SOC 2 Type II
+
+| Control | Description | Implementation |
+|---------|-------------|----------------|
+| **CC6.1** | Logical Access Security | `zsh` restricted permissions, SSH key management via `1Password`/Agents |
+| **CC6.8** | Unauthorized Code Protection | GPG/SSH signed commits, `slsa-framework` workflow |
+| **CC7.1** | System Operations | `compliance-guard.yml` blocks insecure patterns |
+| **CC7.2** | Change Detection | Pre-commit hooks detect security violations |
+| **CC8.1** | Change Management | Git-based IaC, PR templates, CODEOWNERS |
+| **A1.2** | Audit Logs | `~/.local/share/dotfiles.log` tracks operations |
+
+### ISO 27001
+
+| Control | Description | Implementation |
+|---------|-------------|----------------|
+| **A.9.1.1** | Access Control Policy | Principle of Least Privilege (umask 022/077) |
+| **A.9.4.1** | Information Access Restriction | `chmod 777/666` blocked by CI |
+| **A.12.1.2** | Change Management | Git version control with CI/CD verification |
+| **A.12.6.1** | Technical Vulnerability Management | Gitleaks, TruffleHog secrets scanning |
+| **A.13.1.1** | Network Controls | TLS enforcement (no `curl -k`) |
+| **A.14.2.5** | Secure Engineering | ShellCheck, cross-platform testing |
+| **A.14.2.8** | System Security Testing | Module coverage gate (>=95%, currently 100%), weekly scans |
+
+### GDPR / HIPAA (Privacy)
+
+| Requirement | Description | Implementation |
+|-------------|-------------|----------------|
+| **Data Minimization** | Limit data collection | `privacy-mode` disables CLI telemetry |
+| **Integrity** | Protect against tampering | `lock-configs` prevents modification |
+| **Encryption** | Protect data at rest | Age encryption for sensitive dotfiles |
+
+---
+
+## Security Controls
+
+### TLS Enforcement
+
+All network operations require valid TLS certificates:
+
+| Control | Pattern Blocked | Enforcement |
+|---------|-----------------|-------------|
+| Insecure curl | `curl -k`, `--insecure` | Pre-commit + CI |
+| Certificate bypass | `wget --no-check-certificate` | Pre-commit + CI |
+| Plaintext HTTP | `http://` URLs | CI warning |
+
+**Files:**
+
+- Pre-commit: `config/pre-commit-config.yaml`
+- CI: `.github/workflows/compliance-guard.yml`
+
+### Secrets Management
+
+| Tool | Purpose | Configuration |
+|------|---------|---------------|
+| Gitleaks | Prevent secrets in commits | `config/gitleaks.toml` |
+| TruffleHog | Deep secrets scanning | CI workflow |
+| detect-secrets | Baseline secrets detection | `.secrets.baseline` |
+| Age | Encrypt sensitive dotfiles | Chezmoi integration |
+
+### Permission Controls
+
+| Control | Implementation |
+|---------|----------------|
+| Least privilege CI | `permissions: contents: read` default |
+| No world-writable | `chmod 777/666` blocked by CI |
+| CODEOWNERS | All paths mapped to reviewers |
+| Signed commits | GPG signing enforced |
+
+### Dangerous Pattern Blocking
+
+Patterns automatically blocked by CI and pre-commit hooks:
+
+```bash
+# Blocked - insecure TLS
+curl -k https://...
+wget --no-check-certificate https://...
+
+# Blocked - world-writable permissions
+chmod 777 /path
+chmod -R 666 /files
+
+# Blocked - hardcoded credentials
+password="literal_value"
+```
+
+---
+
+## Cross-Platform Compatibility
+
+### Supported Platforms
+
+| Platform | Tools | Default Shell | Bash Version |
+|----------|-------|---------------|--------------|
+| Linux | GNU | Bash | 5.x |
+| macOS | BSD | Zsh | 3.2 (system) |
+| WSL | GNU | Bash | 5.x |
+
+### Line Ending Normalization
+
+Configured in `.gitattributes`:
+
+| Pattern | Line Ending | Reason |
+|---------|-------------|--------|
+| `*.sh` | LF | Unix scripts |
+| `*.bash` | LF | Unix scripts |
+| `*.zsh` | LF | Unix scripts |
+| `*.bat` | CRLF | Windows batch |
+| `*.ps1` | CRLF | PowerShell |
+
+### BSD vs GNU Compatibility
+
+The `cross-platform-test.yml` workflow validates scripts on both platforms:
+
+| Pattern | Issue | Portable Alternative |
+|---------|-------|---------------------|
+| `sed -i ''` | BSD requires backup ext | Check `$OSTYPE` |
+| `sed -i` | GNU style | Check `$OSTYPE` |
+| `grep -P` | GNU-only PCRE | Use `grep -E` |
+| `date -d` | GNU-only | Use `date +%s` |
+| `readarray` | Bash 4+ only | Use `while read` |
+| `declare -A` | Bash 4+ only | Use indexed arrays |
+
+### Path Handling
+
+| Requirement | Implementation |
+|-------------|----------------|
+| No hardcoded user paths | Use `$HOME` or `~` |
+| Case-insensitive safe | No filename collisions |
+| Cross-platform paths | No platform-specific path literals |
+
+---
+
+## CI/CD Pipeline
+
+### Workflow Matrix
+
+| Workflow | Trigger | Purpose |
+|----------|---------|---------|
+| `ci.yml` | Push/PR | Full CI pipeline, ShellCheck, tests |
+| `compliance-guard.yml` | Push/PR | Security pattern scanning |
+| `cross-platform-test.yml` | Push/PR + weekly | BSD/GNU compatibility |
+| `security-enhanced.yml` | Push/PR | Deep security analysis, SBOM |
+| `codeql.yml` | Push/PR + weekly | Static code analysis |
+| `sbom-diff.yml` | Pull request | SBOM diff and CVE correlation |
+| `nightly.yml` | Daily 2 AM UTC | Dependency version checks |
+
+### Compliance Guard Jobs
+
+```text
+compliance-guard.yml
+├── insecure-patterns     # TLS, credentials, chmod
+├── portability           # ShellCheck, paths, .gitattributes
+├── dockerfile-lint       # Hadolint
+└── compliance-summary    # Report generation
+```
+
+### Cross-Platform Test Jobs
+
+```text
+cross-platform-test.yml
+├── ubuntu-latest (GNU)   # Linux compatibility
+├── macos-latest (BSD)    # macOS compatibility
+└── compatibility-report  # Summary
+```
+
+### GitHub Actions Security
+
+| Control | Implementation |
+|---------|----------------|
+| Pinned versions | All actions pinned to SHA or version |
+| Minimal permissions | `contents: read` by default |
+| Concurrency control | Cancel in-progress duplicates |
+| Timeout limits | All jobs have explicit timeouts |
+
+---
+
+## Pre-Commit Hooks
+
+### Configuration
+
+File: `config/pre-commit-config.yaml`
+
+### Hook Matrix
+
+| Hook | Stage | Purpose |
+|------|-------|---------|
+| `shellcheck` | commit | Shell script linting |
+| `shfmt` | commit | Shell script formatting |
+| `gitleaks` | commit | Secrets detection |
+| `detect-secrets` | commit | Credential scanning |
+| `checkov` | commit | Infrastructure security |
+| `hadolint` | commit | Dockerfile linting |
+| `insecure-tls-check` | commit | Block `curl -k` |
+| `dangerous-chmod-check` | commit | Block `chmod 777/666` |
+| `security-policy-enforcement` | pre-push | Policy validation |
+
+### Installation
+
+```bash
+pip install pre-commit
+pre-commit install
+pre-commit install --hook-type pre-push
+```
+
+---
+
+## Change Management
+
+### Pull Request Requirements
+
+| Requirement | Implementation |
+|-------------|----------------|
+| PR template | `.github/PULL_REQUEST_TEMPLATE.md` |
+| Code owners | `.github/CODEOWNERS` |
+| CI checks | Required to pass |
+| Review required | Auto-assigned via CODEOWNERS |
+
+### PR Template Checklist
+
+```markdown
+- [ ] `chezmoi apply --dry-run` verified
+- [ ] Manual testing on macOS
+- [ ] Manual testing on Linux
+- [ ] CI checks pass
+```
+
+### Commit Requirements
+
+| Requirement | Implementation |
+|-------------|----------------|
+| Signed commits | GPG/SSH signing (cryptographically verified) |
+| Conventional format | `feat:`, `fix:`, `docs:` prefixes |
+| Co-author attribution | AI contributions attributed |
+
+### Cryptographic Identity Verification (ALCOA: Attributable)
+
+For SOC 2 compliance, the "Attributable" principle requires that all changes are linked to a **verified cryptographic identity**, not just a username.
+
+**Enforcement layers:**
+
+| Layer | Mechanism | Status |
+|-------|-----------|--------|
+| Local | Pre-push hook blocks unsigned commits | Enforced |
+| CI | `compliance-guard.yml` verifies signatures | Advisory |
+| GitHub | Branch protection (optional) | Configurable |
+
+**Pre-push hook location:** `scripts/git-hooks/pre-push`
+
+```bash
+# The hook verifies each commit before push:
+for c in $(git rev-list "$range"); do
+  if ! git verify-commit "$c" >/dev/null 2>&1; then
+    echo "Blocked: unsigned commit $c"
+    exit 1
+  fi
+done
+```
+
+**Setup signing:**
+
+```bash
+# SSH signing (recommended)
+git config --global gpg.format ssh
+git config --global user.signingkey ~/.ssh/id_ed25519.pub
+git config --global commit.gpgsign true
+
+# GPG signing (alternative)
+git config --global user.signingkey <YOUR_GPG_KEY_ID>
+git config --global commit.gpgsign true
+
+# Or use the dotfiles alias:
+enable-signing ssh  # or: enable-signing gpg
+```
+
+**Install pre-push hook:**
+
+```bash
+cp scripts/git-hooks/pre-push .git/hooks/pre-push
+chmod +x .git/hooks/pre-push
+```
+
+**GitHub Branch Protection (recommended):**
+
+Enable "Require signed commits" in repository settings:
+`Settings > Branches > Branch protection rules > Require signed commits`
+
+---
+
+## Test Coverage
+
+### Current Metrics
+
+| Category | Count | Coverage |
+|----------|-------|----------|
+| Documentation files | 63 | Audited |
+| Executable shell surfaces | 205 | Audited |
+| Unit test files | 425 | Tested |
+| Integration test files | 11 | Tested |
+| **Total test files** | **436** | **Module coverage: 100% (threshold >=95%)** |
+| **Named tests (`test_start`)** | **2149** | **Pass rate: 100%** |
+
+### Test Framework
+
+```text
+tests/
+├── framework/
+│   ├── assertions.sh    # 16 assertion functions
+│   ├── mocks.sh         # Mock utilities
+│   └── test_runner.sh   # Test executor
+├── unit/
+│   └── test_*.sh        # 378 unit test files
+├── integration/
+│   └── test_*.sh        # 9 integration test files
+└── performance/
+    └── benchmark_runner.sh
+```
+
+### Running Tests
+
+```bash
+# Run all tests
+./tests/framework/test_runner.sh
+
+# Run specific test
+bash tests/unit/test_dot_commands_apply.sh
+```
+
+---
+
+## Security Documentation
+
+### Required Files
+
+| File | Purpose | Location |
+|------|---------|----------|
+| SECURITY.md | Vulnerability reporting | `.github/SECURITY.md` |
+| CONTRIBUTING.md | Contribution guidelines | `.github/CONTRIBUTING.md` |
+| CODEOWNERS | Code ownership | `.github/CODEOWNERS` |
+| INCIDENT_RESPONSE.md | Incident response plan | `docs/security/` |
+| FMEA.md | Failure Mode & Effects Analysis | `docs/security/` |
+| VERIFICATION_VALIDATION.md | ISO 13485-style V&V report | `docs/security/` |
+| .editorconfig | Editor settings | Root |
+| .gitattributes | Git attributes | Root |
+
+### Vulnerability Response SLA
+
+| Severity | Initial Response | Resolution Target |
+|----------|------------------|-------------------|
+| Critical | 24 hours | 48 hours |
+| High | 72 hours | 7 days |
+| Medium | 5 business days | 30 days |
+| Low | 10 business days | 90 days |
+
+---
+
+## Audit & Forensics
+
+### Immutability
+
+Lock critical configuration files:
+
+```bash
+lock-configs  # Sets chflags uchg (macOS) or chattr +i (Linux)
+```
+
+### Audit Trail
+
+```bash
+# View dotfiles operations log
+dot audit
+
+# Log location
+~/.local/share/dotfiles.log
+```
+
+### Supply Chain Security
+
+| Control | Implementation |
+|---------|----------------|
+| SBOM | Generated for every release (SPDX) |
+| Provenance | SLSA Level 3 build attestation |
+| Dependencies | Pinned versions, weekly updates |
+
+---
+
+## Verification Commands
+
+### Manual Verification
+
+```bash
+# Run all pre-commit hooks
+pre-commit run --all-files
+
+# Run unit tests
+./tests/framework/test_runner.sh
+
+# Check for insecure patterns
+grep -rn --include="*.sh" -E 'curl.*-k|wget.*--no-check' .
+
+# Validate .gitattributes
+grep "text=auto" .gitattributes && echo "OK"
+```
+
+### Automated Verification
+
+| Schedule | Check |
+|----------|-------|
+| Every PR | compliance-guard, cross-platform-test |
+| Weekly | Full security scan, CodeQL |
+| Nightly | Tool version checks |
+
+---
+
+## References
+
+- [SOC 2 Type II](https://www.aicpa.org/soc2)
+- [ISO 27001:2022](https://www.iso.org/standard/27001)
+- [OWASP Top 10](https://owasp.org/Top10/)
+- [Google Shell Style Guide](https://google.github.io/styleguide/shellguide.html)
+- [ShellCheck Wiki](https://www.shellcheck.net/wiki/)
+- [SLSA Framework](https://slsa.dev/)

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

@@ -0,0 +1,57 @@
+---
+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..."
+```