From 0ece696f5d6856e0616faf097ba5a753ee009f96 Mon Sep 17 00:00:00 2001 From: jordan Date: Sat, 7 Feb 2026 07:45:56 -0700 Subject: [PATCH] docs: add solo developer and enterprise pilot guides - Created solo-developer-guide.md for individual/side projects - Created enterprise-pilot-guide.md with 7-phase pilot methodology - Updated guides/README.md with new guide references - Updated main README.md with guides table and time estimates Co-Authored-By: Claude Opus 4.5 --- applications/aphoria/README.md | 164 +++++++ applications/aphoria/docs/guides/README.md | 12 +- .../docs/guides/enterprise-pilot-guide.md | 437 ++++++++++++++++++ .../docs/guides/solo-developer-guide.md | 255 ++++++++++ 4 files changed, 863 insertions(+), 5 deletions(-) create mode 100644 applications/aphoria/README.md create mode 100644 applications/aphoria/docs/guides/enterprise-pilot-guide.md create mode 100644 applications/aphoria/docs/guides/solo-developer-guide.md diff --git a/applications/aphoria/README.md b/applications/aphoria/README.md new file mode 100644 index 0000000..c5b4600 --- /dev/null +++ b/applications/aphoria/README.md @@ -0,0 +1,164 @@ +# Aphoria + +**A code-level truth linter powered by Episteme.** + +Aphoria scans your codebase for configuration patterns that contradict authoritative technical standards (RFCs, OWASP, vendor docs). Unlike linters that check syntax or SAST tools that find vulnerability patterns, Aphoria validates **intent against authority**. + +```bash +$ aphoria scan . + +BLOCK code://python/requests/tls/cert_verification + Your code: verify=False (api/client.py:42) + RFC 5246: TLS certificate verification MUST be enabled + Conflict: 0.92 + +1 conflict found (1 BLOCK). +``` + +--- + +## Quick Start + +### Install + +```bash +# From source +cd applications/aphoria +cargo install --path . + +# Verify +aphoria --version +``` + +### Initialize + +```bash +aphoria init +``` + +This loads the authoritative corpus (RFCs, OWASP guidelines) into your local database. + +### Scan + +```bash +# Quick scan (ephemeral, fast) +aphoria scan . + +# With persistence (enables diff/baseline) +aphoria scan --persist + +# CI mode (exit code 1 on BLOCK) +aphoria scan --exit-code + +# Pre-commit (staged files only) +aphoria scan --staged --exit-code +``` + +### Handle Conflicts + +**Fix the code:** +```python +# Before: verify=False +# After: +requests.get(url, verify=True) +``` + +**Or acknowledge intentionally:** +```bash +aphoria ack "code://python/requests/tls/cert_verification" \ + --reason "Local dev environment with self-signed certs" +``` + +--- + +## Output Formats + +```bash +aphoria scan --format table # Human-readable (default) +aphoria scan --format json # Machine-readable +aphoria scan --format sarif # GitHub Security tab +aphoria scan --format markdown # Documentation +``` + +--- + +## Pre-commit Integration + +```yaml +# .pre-commit-config.yaml +repos: + - repo: local + hooks: + - id: aphoria + name: Aphoria truth check + entry: aphoria scan --staged --exit-code + language: system + pass_filenames: false +``` + +--- + +## CI Integration (GitHub Actions) + +```yaml +- name: Install Aphoria + run: cargo install --path applications/aphoria + +- name: Run Aphoria Scan + run: aphoria scan --exit-code --format sarif > results.sarif + +- name: Upload SARIF + uses: github/codeql-action/upload-sarif@v2 + with: + sarif_file: results.sarif +``` + +--- + +## Key Commands + +| Command | Description | +|---------|-------------| +| `aphoria scan` | Scan for conflicts with authoritative sources | +| `aphoria ack` | Acknowledge a conflict as intentional | +| `aphoria bless` | Define a pattern as your authoritative standard | +| `aphoria policy export` | Export standards as a Trust Pack | +| `aphoria policy import` | Import a Trust Pack from your security team | +| `aphoria governance pending` | List approval requests (Phase 14) | +| `aphoria audit export` | Export audit trail for SOC 2 compliance | + +--- + +## Conflict Verdicts + +| Verdict | Description | CI Behavior | +|---------|-------------|-------------| +| **BLOCK** | High-confidence conflict with RFC/OWASP | Fails with `--exit-code` | +| **FLAG** | Moderate-confidence conflict | Passes, visible in report | +| **ACK** | Acknowledged conflict | Passes, tracked for audit | +| **PASS** | No conflict | - | + +--- + +## Guides + +| Guide | Audience | Time | +|-------|----------|------| +| [Solo Developer Guide](docs/guides/solo-developer-guide.md) | Individual developers, side projects | 2 min | +| [Enterprise Pilot Guide](docs/guides/enterprise-pilot-guide.md) | Security teams running pilots | 4 weeks | +| [Enterprise Quick Start](docs/guides/enterprise-quick-start.md) | Platform engineering | 5 min | +| [The First Scan](docs/guides/the-first-scan.md) | Everyone | 10 min | + +--- + +## What Aphoria Is Not + +- **Not a linter.** Linters check syntax. Aphoria checks decisions against authoritative sources. +- **Not SAST.** SAST finds vulnerability patterns. Aphoria finds contradictions to specific standards. +- **Not AI autocomplete.** Copilot suggests code from the internet. Aphoria surfaces *your org's* decisions at the moment you contradict them. + +--- + +## License + +See [LICENSE](../../LICENSE) for details. diff --git a/applications/aphoria/docs/guides/README.md b/applications/aphoria/docs/guides/README.md index 073a828..a69dd9b 100644 --- a/applications/aphoria/docs/guides/README.md +++ b/applications/aphoria/docs/guides/README.md @@ -4,11 +4,13 @@ Quick-start guides and workflows for Aphoria users. ## Getting Started -| Guide | Description | -|-------|-------------| -| [Enterprise Quick Start](./enterprise-quick-start.md) | 5-minute path from git clone to enforcing security standards | -| [The First Scan](./the-first-scan.md) | Your first Aphoria scan walkthrough | -| [Pre-Flight Checks](./pre-flight-checks.md) | Pre-commit and CI integration | +| Guide | Audience | Description | +|-------|----------|-------------| +| [Solo Developer Guide](./solo-developer-guide.md) | Individual developers | Get immediate value on personal or side projects | +| [Enterprise Pilot Guide](./enterprise-pilot-guide.md) | Security teams | Run a measurable pilot with stakeholder buy-in | +| [Enterprise Quick Start](./enterprise-quick-start.md) | Platform engineering | 5-minute path from git clone to enforcing standards | +| [The First Scan](./the-first-scan.md) | Everyone | Your first Aphoria scan walkthrough | +| [Pre-Flight Checks](./pre-flight-checks.md) | DevOps | Pre-commit and CI integration | ## Core Workflows diff --git a/applications/aphoria/docs/guides/enterprise-pilot-guide.md b/applications/aphoria/docs/guides/enterprise-pilot-guide.md new file mode 100644 index 0000000..7e77d06 --- /dev/null +++ b/applications/aphoria/docs/guides/enterprise-pilot-guide.md @@ -0,0 +1,437 @@ +# Enterprise Pilot Guide + +Run a successful Aphoria pilot with measurable outcomes for stakeholders. + +## Who This Guide Is For + +- **Security Teams** evaluating Aphoria for organizational adoption +- **Platform Engineering** considering Aphoria for developer experience +- **Compliance Officers** assessing audit trail capabilities + +--- + +## Pilot Goals + +Define success before you start. Common pilot objectives: + +| Objective | Metric | Target | +|-----------|--------|--------| +| Find existing violations | Conflicts detected across pilot projects | >50 findings in first week | +| Reduce time-to-detection | Days between code merge and violation detection | <1 day (shift left) | +| Validate audit trail | SOC 2 auditor acceptance of Aphoria reports | Pass audit review | +| Developer acceptance | Post-pilot NPS from pilot team developers | >7/10 | + +--- + +## Phase 1: Environment Setup (Day 1) + +### 1.1 Install Aphoria + +```bash +git clone https://github.com/orchard9/stemedb.git +cd stemedb/applications/aphoria +cargo install --path . +``` + +### 1.2 Create Standards Repository + +Dedicated repo for your organization's security standards: + +```bash +mkdir acme-security-standards && cd acme-security-standards +git init + +cat > aphoria.toml << 'EOF' +[project] +name = "acme-security-standards" +version = "1.0.0" + +[episteme] +data_dir = ".aphoria/db" + +[governance] +enabled = true +default_workflow = "standard_review" + +[[governance.workflows]] +name = "standard_review" +description = "Standard pattern review for production" +overall_timeout_hours = 168 + +[[governance.workflows.stages]] +name = "security_review" +label = "Security Review" +required_approvers = ["security-team"] +min_approvals = 1 +timeout_hours = 48 + +[[governance.workflows.stages]] +name = "architecture_review" +label = "Architecture Review" +required_approvers = ["arch-team"] +min_approvals = 1 +EOF + +aphoria init +git add . && git commit -m "Initial security standards setup" +``` + +### 1.3 Define Initial Standards + +Start with high-value, low-controversy standards: + +```bash +# TLS certificate verification (universally required) +aphoria bless "code://standard/tls/cert_verification" \ + --predicate enabled --value true \ + --reason "Certificate verification required per OWASP ASVS 9.1.1" + +# TLS minimum version (clear RFC guidance) +aphoria bless "code://standard/tls/min_version" \ + --predicate version --value "1.2" \ + --reason "TLS 1.2 minimum per NIST SP 800-52 Rev 2" + +# JWT audience validation (common vulnerability) +aphoria bless "code://standard/jwt/audience_validation" \ + --predicate enabled --value true \ + --reason "JWT aud claim must be validated per RFC 7519" + +# Debug mode in production +aphoria bless "code://standard/debug/production" \ + --predicate enabled --value false \ + --reason "Debug mode must be disabled in production per OWASP" +``` + +### 1.4 Export Trust Pack + +```bash +aphoria policy export \ + --name "Acme-Security-Standards-Pilot" \ + --output acme-pilot-v1.0.pack +``` + +--- + +## Phase 2: Pilot Team Selection (Day 2-3) + +### Selection Criteria + +Choose 2-3 teams that: +- Have active development (commits weekly) +- Mix of languages/frameworks (Python + JavaScript, for example) +- Include at least one team with known security debt +- Have supportive tech leads (early adopters) + +### Pilot Team Onboarding + +For each pilot team: + +```bash +cd pilot-project +aphoria policy import path/to/acme-pilot-v1.0.pack +aphoria scan +``` + +### Initial Scan Results + +Capture baseline metrics: +- Total conflicts detected +- BLOCK vs FLAG breakdown +- Top 5 conflict types + +--- + +## Phase 3: Integration (Week 1) + +### 3.1 Pre-Commit Hooks + +Add to each pilot project's `.pre-commit-config.yaml`: + +```yaml +repos: + - repo: local + hooks: + - id: aphoria + name: Aphoria security check + entry: aphoria scan --staged --exit-code + language: system + pass_filenames: false +``` + +### 3.2 CI/CD Integration + +GitHub Actions example: + +```yaml +name: Security Scan +on: [push, pull_request] + +jobs: + aphoria: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Install Aphoria + run: cargo install aphoria + + - name: Import Security Policy + env: + SECURITY_PACK_URL: ${{ secrets.SECURITY_PACK_URL }} + run: | + curl -sL "$SECURITY_PACK_URL" -o policy.pack + aphoria policy import policy.pack + + - name: Run Scan + run: aphoria scan --persist --exit-code --format sarif > results.sarif + + - name: Upload SARIF + uses: github/codeql-action/upload-sarif@v2 + with: + sarif_file: results.sarif +``` + +### 3.3 Daily Standup Check + +Run scans centrally and report trends: + +```bash +#!/bin/bash +# daily-security-report.sh + +for project in project-a project-b project-c; do + cd "$project" + echo "=== $project ===" + aphoria scan --format json | jq '.summary' + cd .. +done +``` + +--- + +## Phase 4: Governance Workflows (Week 2) + +### 4.1 Enable Governance + +Update `aphoria.toml` in each pilot project: + +```toml +[governance] +enabled = true +``` + +### 4.2 Pattern Promotion Flow + +When Aphoria learns a new pattern from code: + +```bash +# View pending approvals +aphoria governance pending + +# Review a specific request +aphoria governance status --pattern + +# Approve (security team) +aphoria governance approve --comment "LGTM, aligns with RFC" + +# Or reject +aphoria governance reject --reason "Conflicts with existing standard" +``` + +### 4.3 Audit Trail Export + +For compliance review: + +```bash +# Export full audit trail +aphoria audit export -o governance-audit.json -f json + +# View specific pattern history +aphoria audit trail --pattern +``` + +--- + +## Phase 5: Measurement (Week 3-4) + +### Key Metrics + +| Metric | How to Measure | Target | +|--------|----------------|--------| +| **Detection Rate** | Conflicts found / week | Trending down (good) | +| **Fix Rate** | Conflicts resolved / conflicts found | >80% | +| **False Positive Rate** | ACKs that were unnecessary / total ACKs | <10% | +| **Time to Resolution** | Days from detection to fix/ack | <3 days | +| **Developer Friction** | Survey: "Did Aphoria slow you down?" | <20% "yes" | + +### Weekly Report Template + +```markdown +## Aphoria Pilot Week N Report + +### Summary +- Projects scanned: 3 +- Total conflicts: 47 (down from 62 last week) +- New conflicts this week: 8 +- Resolved this week: 23 + +### By Category +| Category | Count | Trend | +|----------|-------|-------| +| TLS | 12 | -5 | +| JWT | 8 | -2 | +| Debug | 3 | -1 | + +### Top Issues +1. `verify=False` in API client (3 instances) +2. JWT validation disabled in dev config (leaked to prod) +3. TLS 1.0 still accepted in legacy service + +### Developer Feedback +- "Caught a real bug before it shipped" - Team A +- "Pre-commit hook is fast" - Team B +- "Would like more context on why this is a conflict" - Team C +``` + +--- + +## Phase 6: Remediation Tracking + +### Track Fix Progress + +```bash +# Set current scan as baseline +aphoria baseline + +# After fixes, show changes +aphoria diff +``` + +### Remediation Workflow + +1. **Triage**: Daily standup reviews new conflicts +2. **Assign**: Security team assigns to owning team +3. **Fix or ACK**: Dev team has 3 days to resolve or acknowledge +4. **Verify**: Next scan confirms resolution + +### Escalation Path + +``` +Day 0: Conflict detected +Day 3: Reminder to owning team +Day 7: Escalate to security team +Day 14: Escalate to engineering leadership +``` + +--- + +## Phase 7: SOC 2 Validation + +### Auditor Evidence Package + +Generate for your SOC 2 auditor: + +```bash +# Full audit trail export +aphoria audit export -o soc2-evidence/governance-trail.json -f json + +# Convert to CSV for spreadsheet review +aphoria audit export -o soc2-evidence/governance-trail.csv -f csv + +# Policy snapshot +aphoria policy export --name "Audit-Snapshot-$(date +%Y%m%d)" \ + --output soc2-evidence/policy-snapshot.pack +``` + +### Evidence Contents + +The export includes: +- All approval requests with timestamps +- Approver identities and decisions +- Comments and reasons +- Pattern promotion history +- Exception acknowledgments with justifications + +### Auditor Presentation + +Key points for your auditor: +1. **Continuous enforcement** - Scans run on every commit +2. **Cryptographic attribution** - Every conflict traces to specific policy +3. **Approval workflow** - Multi-stage review before pattern promotion +4. **Immutable audit log** - Append-only, JSONL format + +--- + +## Go/No-Go Decision + +### Success Criteria + +Mark as **GO** if: +- [ ] Detection rate > 50 findings in pilot period +- [ ] Fix rate > 80% +- [ ] False positive rate < 10% +- [ ] Developer NPS > 7/10 +- [ ] SOC 2 auditor accepted evidence format +- [ ] No blocking performance issues + +### Rollout Phases + +1. **Pilot Complete**: 2-3 teams, 4 weeks +2. **Early Adopter**: 10 teams, 8 weeks +3. **General Availability**: All teams, ongoing + +--- + +## Common Pilot Issues + +### "Too many false positives" + +Tune sensitivity: +```bash +# Use strict mode for high-confidence only +aphoria scan --strict +``` + +Or acknowledge legitimately different patterns: +```bash +aphoria ack "code://..." --reason "Legacy system, tracked in JIRA-1234" +``` + +### "Scans are too slow" + +Use ephemeral mode for quick checks: +```bash +aphoria scan # Fast, no persistence +``` + +Only use `--persist` for baseline comparisons. + +### "Developers don't understand conflicts" + +Enable debug output for education: +```bash +aphoria scan --debug +``` + +Shows full conflict resolution trace. + +### "Standards need updating" + +Update your Trust Pack and redistribute: +```bash +# In standards repo +aphoria bless "code://standard/new/pattern" ... +aphoria policy export --name "Acme-v1.1" --output acme-v1.1.pack + +# In each project +aphoria policy import acme-v1.1.pack +``` + +--- + +## Next Steps + +After successful pilot: +1. [Multi-Team Policy Governance](./multi-team-policy-governance.md) - Scale to multiple teams +2. [Policy Audit Trails](./policy-audit-trails.md) - Compliance workflows +3. [Federating Truth](./federating-truth.md) - Cross-organization standards diff --git a/applications/aphoria/docs/guides/solo-developer-guide.md b/applications/aphoria/docs/guides/solo-developer-guide.md new file mode 100644 index 0000000..5500855 --- /dev/null +++ b/applications/aphoria/docs/guides/solo-developer-guide.md @@ -0,0 +1,255 @@ +# Solo Developer Guide + +Get immediate value from Aphoria on your personal or side projects. + +## Why Aphoria for Solo Projects? + +You don't need enterprise workflows. You need to know when your code contradicts RFCs or security best practices—before it becomes a CVE. + +**What you get:** +- Catch `verify=False`, weak TLS, disabled auth—patterns you'd miss in code review +- No team coordination, no policy packs, no approval workflows +- Pre-commit hooks that stop insecure code before it ships + +--- + +## Quick Start (2 Minutes) + +### 1. Install + +```bash +cd applications/aphoria +cargo install --path . +``` + +Verify: +```bash +aphoria --version +``` + +### 2. Initialize + +```bash +cd your-project +aphoria init +``` + +This loads the authoritative corpus (RFCs, OWASP guidelines) into your local database. + +### 3. Scan + +```bash +aphoria scan +``` + +That's it. You'll see output like: + +``` +BLOCK code://python/requests/tls/cert_verification + Your code: verify=False (api/client.py:42) + RFC 5246: TLS certificate verification MUST be enabled + Conflict: 0.92 + +1 conflict found (1 BLOCK). +``` + +--- + +## Pre-Commit Hook + +Add to your `.pre-commit-config.yaml`: + +```yaml +repos: + - repo: local + hooks: + - id: aphoria + name: Aphoria truth check + entry: aphoria scan --staged --exit-code + language: system + pass_filenames: false +``` + +Now insecure code is blocked before it reaches your repo. + +--- + +## What Aphoria Catches + +| Category | Examples | +|----------|----------| +| **TLS/SSL** | Disabled cert verification, weak protocols, insecure ciphers | +| **Authentication** | Missing token validation, disabled auth checks | +| **Configuration** | Debug mode in production, exposed secrets, unsafe defaults | +| **Framework-Specific** | Django DEBUG=True, Flask CSRF disabled, Express without helmet | + +--- + +## Common Workflows + +### Daily Development + +```bash +# Quick check (fast, no persistence) +aphoria scan +``` + +### Before Commits + +```bash +# Check only staged files +aphoria scan --staged --exit-code +``` + +### Before Releases + +```bash +# Full scan with report +aphoria scan --format markdown > SECURITY_AUDIT.md +``` + +--- + +## Handling Conflicts + +### Option 1: Fix the Code + +The best response. If Aphoria says `verify=False` is insecure, enable verification. + +```python +# Before +response = requests.get(url, verify=False) + +# After +response = requests.get(url, verify=True) +``` + +### Option 2: Acknowledge with Reason + +Sometimes insecure patterns are intentional (dev environments, testing). Acknowledge them: + +```bash +aphoria ack "code://python/requests/tls/cert_verification" \ + --reason "Local dev with self-signed certs, not used in production" +``` + +The acknowledgment is tracked. Re-scan and it becomes ACK (pass) instead of BLOCK. + +### Option 3: Bless a Local Standard + +For project-specific decisions that differ from RFCs: + +```bash +aphoria bless "code://local/tls/min_version" \ + --predicate version --value "1.3" \ + --reason "This project requires TLS 1.3 minimum" +``` + +--- + +## Output Formats + +```bash +# Human-readable (default) +aphoria scan --format table + +# JSON for scripting +aphoria scan --format json + +# Markdown for documentation +aphoria scan --format markdown > SECURITY.md + +# SARIF for tool integration +aphoria scan --format sarif > results.sarif +``` + +--- + +## Tips for Solo Projects + +### Keep It Simple + +Don't bother with: +- Trust Packs (enterprise feature) +- Governance workflows (multi-team feature) +- Policy federation (organizational feature) + +Just scan, fix, and occasionally acknowledge. + +### Use Ephemeral Mode + +Default scans are ephemeral—fast with no persistence. That's what you want for quick checks. + +Only use `--persist` if you need: +- Baseline comparison (`aphoria diff`) +- Historical tracking + +```bash +# Normal (fast) +aphoria scan + +# With history (slower) +aphoria scan --persist +``` + +### Check Before Deploys + +Add to your deploy script: + +```bash +#!/bin/bash +set -e + +# Block deploy on security issues +aphoria scan --exit-code + +# Continue with deploy +./deploy.sh +``` + +--- + +## Upgrading Your Corpus + +The authoritative corpus (RFCs, OWASP) updates periodically: + +```bash +# Rebuild corpus with latest sources +aphoria corpus build + +# List available sources +aphoria corpus list +``` + +--- + +## FAQ + +**Q: How is this different from a linter?** + +Linters check syntax and style. Aphoria checks whether your *decisions* contradict *authoritative standards*. ESLint won't tell you that `verify=False` contradicts RFC 5246. + +**Q: How is this different from SAST?** + +SAST finds vulnerability patterns (SQL injection, XSS). Aphoria finds contradictions with specific standards. SAST finds `eval(user_input)`; Aphoria finds "you said TLS 1.1, NIST says TLS 1.2 minimum." + +**Q: Does it require an LLM?** + +No. Core scanning uses pattern matching. LLM extraction is optional and only for complex patterns. Most projects work without it. + +**Q: What languages are supported?** + +Aphoria extracts from: +- Configuration files (YAML, TOML, JSON) +- Python, JavaScript/TypeScript +- Rust, Go (partial) + +See `aphoria extractors list` for current coverage. + +--- + +## Next Steps + +- [The First Scan](./the-first-scan.md) - Detailed walkthrough +- [Pre-Flight Checks](./pre-flight-checks.md) - CI integration +- Read the [main README](../../README.md) for command reference