9bfa626203
Major documentation restructure to improve discoverability and reduce duplication. ## Changes **Deleted (Archived/Consolidated)**: - Removed duplicate getting started guides - Archived outdated planning documents - Consolidated corpus and configuration docs - Removed obsolete vision/spec files (superseded by vision.md) - Cleaned up scrapyard and old PDFs **New Structure**: - docs/about/ - Project overview and introduction - docs/guides/ - User guides (moved from root) - docs/specs/ - Technical specifications - docs/sdk/ - SDK documentation (Go) - docs/references/ - API references - docs/archive/ - Archived historical docs - applications/aphoria/docs/advanced/ - Advanced topics - applications/aphoria/docs/reference/ - CLI reference - applications/aphoria/docs/archive/ - Archived aphoria docs **Updated**: - README.md - New root README with clear navigation - CONTRIBUTING.md - Contribution guidelines - CLAUDE.md - Updated paths to new structure - roadmap.md - Added recent completions ## Files Changed - 57 files changed - 1,977 insertions(+) - 961 deletions(-) **Net change**: +1,016 lines (added CONTRIBUTING.md, README.md, reorganized content) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
349 lines
8.5 KiB
Markdown
349 lines
8.5 KiB
Markdown
# 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)
|
|
|
|
### Step 1: Install (30 seconds)
|
|
|
|
```bash
|
|
cd /path/to/stemedb/applications/aphoria
|
|
cargo install --path .
|
|
```
|
|
|
|
Verify:
|
|
```bash
|
|
aphoria --version
|
|
```
|
|
|
|
**Expected output:**
|
|
```
|
|
aphoria 0.1.0
|
|
```
|
|
|
|
---
|
|
|
|
### Step 2: Initialize Your Project (30 seconds)
|
|
|
|
```bash
|
|
cd /path/to/your-project
|
|
aphoria init
|
|
```
|
|
|
|
This creates `.aphoria/config.toml` and loads the authoritative corpus (RFCs, OWASP) into your local database.
|
|
|
|
**Expected output:**
|
|
```
|
|
✓ Created .aphoria/config.toml
|
|
✓ Loaded 247 authoritative claims from corpus
|
|
✓ Project initialized: your-project
|
|
```
|
|
|
|
---
|
|
|
|
### Step 3: Run Your First Scan (30 seconds)
|
|
|
|
```bash
|
|
aphoria scan
|
|
```
|
|
|
|
**Expected output (if violations found):**
|
|
```
|
|
┌──────────────────────┬──────┬─────────┬──────────────────────────────────────────┐
|
|
│ File │ Line │ Verdict │ Explanation │
|
|
├──────────────────────┼──────┼─────────┼──────────────────────────────────────────┤
|
|
│ api/client.py │ 42 │ BLOCK │ TLS cert verification disabled │
|
|
│ │ │ │ (RFC 5246: MUST verify, confidence: 0.92)│
|
|
├──────────────────────┼──────┼─────────┼──────────────────────────────────────────┤
|
|
│ config/settings.py │ 18 │ FLAG │ DEBUG=True in production config │
|
|
│ │ │ │ (OWASP: SHOULD disable, confidence: 0.68)│
|
|
└──────────────────────┴──────┴─────────┴──────────────────────────────────────────┘
|
|
|
|
Summary: 1 BLOCK, 1 FLAG, 0 PASS
|
|
Scan completed in 0.24s
|
|
```
|
|
|
|
**Expected output (if clean):**
|
|
```
|
|
✓ No violations found
|
|
```
|
|
|
|
---
|
|
|
|
### Step 4: Understand the Results
|
|
|
|
#### Verdicts
|
|
|
|
| Verdict | Meaning | Confidence Threshold |
|
|
|---------|---------|---------------------|
|
|
| **BLOCK** | Critical violation - production risk | ≥ 0.7 |
|
|
| **FLAG** | Warning - best practice violation | ≥ 0.5 |
|
|
| **PASS** | No conflict with authoritative sources | < 0.5 |
|
|
|
|
---
|
|
|
|
## 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
|
|
```
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### "Corpus database not found"
|
|
|
|
```bash
|
|
# Initialize project first
|
|
aphoria init
|
|
|
|
# Or specify corpus DB location
|
|
export STEMEDB_CORPUS_DB_DIR=/path/to/corpus-db
|
|
```
|
|
|
|
### "No violations found" (but you expected some)
|
|
|
|
```bash
|
|
# Enable debug logging to see what extractors are doing
|
|
RUST_LOG=aphoria=debug aphoria scan
|
|
|
|
# Check which extractors ran
|
|
aphoria scan --show-observations
|
|
```
|
|
|
|
### "Scan is slow"
|
|
|
|
Ephemeral mode (default) should be fast (< 0.3s). If slow:
|
|
|
|
```bash
|
|
# Check file count
|
|
find . -name "*.rs" -o -name "*.py" | wc -l
|
|
|
|
# Exclude large directories
|
|
# Edit .aphoria/config.toml:
|
|
[scan]
|
|
exclude = ["target/", "node_modules/", "venv/"]
|
|
```
|
|
|
|
---
|
|
|
|
## 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
|
|
|
|
### Option A: Add Pre-Commit Hook (Recommended)
|
|
|
|
Block insecure code before it reaches your repo - see [Pre-Commit Hook](#pre-commit-hook) section above.
|
|
|
|
### Option B: Learn by Example
|
|
|
|
Follow the complete [Database Connection Pool Example](../../dogfood/dbpool/) to see:
|
|
- How to extract claims from technical documentation (HikariCP, PostgreSQL)
|
|
- How Aphoria catches violations (7-8 real examples)
|
|
- How to fix violations incrementally
|
|
- How to validate your environment is working
|
|
|
|
**Time:** 20 minutes to read, optional 5-day hands-on exercise
|
|
|
|
### Option C: Dive Deeper
|
|
|
|
- [The First Scan](./the-first-scan.md) - Detailed walkthrough
|
|
- [Pre-Flight Checks](./pre-flight-checks.md) - CI integration
|
|
- [CLI Reference](../reference/cli-reference.md) - All commands and options
|
|
- [Comparison Modes](../reference/comparison-modes.md) - How conflicts are evaluated
|