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

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:

# 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¶

compliance-guard.yml
├── insecure-patterns     # TLS, credentials, chmod
├── portability           # ShellCheck, paths, .gitattributes
├── dockerfile-lint       # Hadolint
└── compliance-summary    # Report generation

Cross-Platform Test Jobs¶

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¶

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¶

- [ ] `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

# 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:

# 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:

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¶

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¶

# 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:

lock-configs  # Sets chflags uchg (macOS) or chattr +i (Linux)

Audit Trail¶

# 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¶

# 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