@sebastienrousseau/dotfiles 0.2.519 → 0.2.521

package/docs/security/COMPLIANCE.md

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

@@ -1,86 +0,0 @@
----
-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 `main`, 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
-
-- [`tools/ci/check-deps-dev.sh`](https://github.com/sebastienrousseau/dotfiles/blob/main/tools/ci/check-deps-dev.sh) — the scanner.
-- [`.github/workflows/deps-dev-validation.yml`](https://github.com/sebastienrousseau/dotfiles/blob/main/.github/workflows/deps-dev-validation.yml) — CI wiring.
-- [`tests/unit/security/test_check_deps_dev.sh`](https://github.com/sebastienrousseau/dotfiles/blob/main/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/DISCLOSURE.md

@@ -1,130 +0,0 @@
-# Encrypted Security Disclosure — Reporter Workflow
-
-This document is for **external security researchers** who have found
-an issue in this repository and want to report it without exposing
-sensitive details (PII, exploit chains, internal infrastructure) in
-transit or at rest on third-party servers.
-
-If your report doesn't need encryption, please use
-[GitHub Security Advisories](https://github.com/sebastienrousseau/dotfiles/security/advisories)
-instead — it's faster and the GitHub-side audit trail is stronger.
-
-## 1. Fetch the maintainer's public key
-
-```sh
-# Web Key Directory is the modern recommendation.
-gpg --auto-key-locate clear,wkd \
-    --locate-keys security@sebastienrousseau.com
-```
-
-If WKD fails (offline keyserver, corporate proxy), download directly:
-
-```sh
-curl -fsSL \
-  https://sebastienrousseau.com/.well-known/openpgpkey/hu/qpzqfwauiwxnu1xrf5h47bunsho44p6f \
-  | gpg --import
-```
-
-## 2. Verify the fingerprint
-
-**Do not skip this step.** A MITM attacker can serve their own key.
-
-```sh
-gpg --fingerprint security@sebastienrousseau.com
-```
-
-The fingerprint must match the one published in
-[`.github/SECURITY.md`](https://github.com/sebastienrousseau/dotfiles/blob/main/.github/SECURITY.md). Cross-verify
-against the SSH signing key in `dot_config/git/allowed_signers.tmpl`
-— the maintainer signs commits with the same identity, so both
-fingerprints derive from the same identity claim.
-
-If the two fingerprints don't match, **stop**. Open a private
-[Security Advisory](https://github.com/sebastienrousseau/dotfiles/security/advisories/new)
-and ask the maintainer to confirm the key out-of-band.
-
-## 3. Encrypt your report
-
-```sh
-cat <<EOF | gpg --encrypt --armor \
-  --recipient security@sebastienrousseau.com \
-  --output disclosure.asc
-Subject: <short description of the issue>
-
-<full details — repro steps, affected versions, exploit, screenshots
-referenced by base64-encoded attachments, contact info for follow-up>
-EOF
-```
-
-Verify the output is an ASCII-armored OpenPGP message before sending:
-
-```sh
-head -1 disclosure.asc
-# Expected: -----BEGIN PGP MESSAGE-----
-```
-
-## 4. Send
-
-Attach `disclosure.asc` to an email to
-**<security@sebastienrousseau.com>**.
-
-Subject line: `[dotfiles] <severity>: <short description>` (no
-encryption-sensitive content in the subject; mail relays log
-subjects in plain text).
-
-## 5. Acknowledgement
-
-You should receive an acknowledgement within the SLA in
-[`.github/SECURITY.md`](https://github.com/sebastienrousseau/dotfiles/blob/main/.github/SECURITY.md):
-
-| Severity | Initial response |
-|---|---|
-| Critical | 24 hours |
-| High | 72 hours |
-| Medium | 5 business days |
-| Low | 10 business days |
-
-The acknowledgement will be signed with the same key you encrypted
-to. Verify the signature:
-
-```sh
-gpg --verify response.asc
-```
-
-If you don't receive an acknowledgement in the SLA window, or the
-acknowledgement signature doesn't verify, escalate by:
-
-1. Opening a private GitHub Security Advisory.
-2. DM-ing the maintainer on Mastodon: `@sebastienrousseau@hachyderm.io`.
-
-## 6. After disclosure
-
-The maintainer commits to:
-
-- A fix timeline communicated within the SLA.
-- A CVE assignment when severity ≥ Medium and the issue affects
-  published releases (npm package, release tarballs).
-- Public credit at fix time in the release notes (unless you
-  request anonymity at report time).
-- A backport to any actively-supported release line listed in
-  `.github/SECURITY.md`.
-
-## What NOT to do
-
-- Don't post details in a public issue, even a "I found a bug, ping
-  me for details" placeholder — every public reference is a tip-off
-  to attackers monitoring the repo.
-- Don't disclose to third parties (other dotfile maintainers,
-  security mailing lists, blog posts) before the embargo lifts.
-- Don't access data or systems you don't own.
-- Don't run automated scans against `*.sebastienrousseau.com` that
-  exceed normal browser-like traffic.
-
-## See also
-
-- [`.github/SECURITY.md`](https://github.com/sebastienrousseau/dotfiles/blob/main/.github/SECURITY.md) — policy
-  overview + fingerprint.
-- [`docs/security/KEY_ROTATION.md`](KEY_ROTATION.md) — schedule for
-  when the disclosure key is rotated.
-- [`docs/security/AUDIT_BYPASS.md`](AUDIT_BYPASS.md) — separate flow
-  for the pre-push audit bypass (not for disclosure).