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)

1. Install

cd applications/aphoria
cargo install --path .

Verify:

aphoria --version

2. Initialize

cd your-project
aphoria init

This loads the authoritative corpus (RFCs, OWASP guidelines) into your local database.

3. Scan

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:

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

---

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 - Detailed walkthrough
• Pre-Flight Checks - CI integration
• Read the main README for command reference