@sebastienrousseau/dotfiles
Version:
The Trusted Shell Platform — Universal dotfiles managed by Chezmoi. Features Bash & Zsh for macOS, Linux & WSL. Rust modern tooling & enterprise-grade security.
459 lines (337 loc) • 13.4 kB
Markdown
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/)