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 |
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:
# 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"
| 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.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 |
References