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

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