stemedb/applications/aphoria/docs/guides/solo-developer-guide.md

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)

cd /path/to/stemedb/applications/aphoria
cargo install --path .

Verify:

aphoria --version

Expected output:

aphoria 0.1.0

---

Step 2: Initialize Your Project (30 seconds)

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)

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:

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

# Quick check (fast, no persistence)
aphoria scan

Before Commits

# Check only staged files
aphoria scan --staged --exit-code

Before Releases

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

# 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:

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:

aphoria bless "code://local/tls/min_version" \
  --predicate version --value "1.3" \
  --reason "This project requires TLS 1.3 minimum"

---

Output Formats

# 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

# Normal (fast)
aphoria scan

# With history (slower)
aphoria scan --persist

Check Before Deploys

Add to your deploy script:

#!/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:

# Rebuild corpus with latest sources
aphoria corpus build

# List available sources
aphoria corpus list

---

Troubleshooting

"Corpus database not found"

# 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)

# 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:

# 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 section above.

Option B: Learn by Example

Follow the complete Database Connection Pool Example 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 - Detailed walkthrough
• Pre-Flight Checks - CI integration
• CLI Reference - All commands and options
• Comparison Modes - How conflicts are evaluated