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 <noreply@anthropic.com>
This commit is contained in:
jordan
parent
f2ffb63f79
commit
0ece696f5d
164
applications/aphoria/README.md
Normal file
164
applications/aphoria/README.md
Normal 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.
|
||||
@ -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
|
||||
|
||||
|
||||
437
applications/aphoria/docs/guides/enterprise-pilot-guide.md
Normal file
437
applications/aphoria/docs/guides/enterprise-pilot-guide.md
Normal 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
255
applications/aphoria/docs/guides/solo-developer-guide.md
Normal 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
|
||||
Loading…
Reference in New Issue
Block a user