0ece696f5d
- 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>
165 lines
3.9 KiB
Markdown
165 lines
3.9 KiB
Markdown
# 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.
|