---
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/)