jordan/stemedb
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add solo developer and enterprise pilot guides

Browse Source 
- 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 <noreply@anthropic.com>
This commit is contained in:
jordan 2026-02-07 07:45:56 -07:00
parent f2ffb63f79
commit 0ece696f5d
4 changed files with 863 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

164
applications/aphoria/README.md Normal file
View File

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

12
applications/aphoria/docs/guides/README.md
View File

@ -4,11 +4,13 @@ Quick-start guides and workflows for Aphoria users.
## Getting Started ## Getting Started
| Guide | Description | | Guide | Audience | Description |
|-------|-------------| |-------|----------|-------------|
| [Enterprise Quick Start](./enterprise-quick-start.md) | 5-minute path from git clone to enforcing security standards | | [Solo Developer Guide](./solo-developer-guide.md) | Individual developers | Get immediate value on personal or side projects |
| [The First Scan](./the-first-scan.md) | Your first Aphoria scan walkthrough | | [Enterprise Pilot Guide](./enterprise-pilot-guide.md) | Security teams | Run a measurable pilot with stakeholder buy-in |
| [Pre-Flight Checks](./pre-flight-checks.md) | Pre-commit and CI integration | | [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 ## Core Workflows

437
applications/aphoria/docs/guides/enterprise-pilot-guide.md Normal file
View File

@ -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 <pattern-id>
# Approve (security team)
aphoria governance approve <request-id> --comment "LGTM, aligns with RFC"
# Or reject
aphoria governance reject <request-id> --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 <pattern-id>
```
---
## 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

255
applications/aphoria/docs/guides/solo-developer-guide.md Normal file
View File

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