28fc3b5391
Add Language::C variant with file detection (.c, Makefile, CMakeLists.txt) and integration across prompts, regex_gen, and path_mapper. Simplify README and guides to be more concise and scannable. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
127 lines
3.9 KiB
Markdown
127 lines
3.9 KiB
Markdown
# Guide: The First Scan — From Zero to Compliance
|
|
|
|
**Target Audience:** Developers, Tech Leads
|
|
**Time to Value:** 5 minutes
|
|
|
|
---
|
|
|
|
## Introduction
|
|
|
|
Every codebase contains invisible decisions. When you set `verify=false` in a config file, you aren't just toggling a boolean; you are making a claim: *"Certificate verification is not required for this connection."*
|
|
|
|
Authoritative sources (like RFCs and OWASP) disagree. They claim: *"Certificate verification is mandatory."*
|
|
|
|
**Aphoria** detects this disagreement. It is a "truth linter" that finds where your code contradicts authoritative specs. This guide will take you from zero to your first clean scan.
|
|
|
|
---
|
|
|
|
## 1. Installation
|
|
|
|
Aphoria ships as a single binary.
|
|
|
|
```bash
|
|
# From source (assuming you have the repo)
|
|
cd /path/to/stemedb/applications/aphoria
|
|
cargo install --path .
|
|
```
|
|
|
|
Verify it works:
|
|
```bash
|
|
$ aphoria --version
|
|
aphoria 0.1.0
|
|
```
|
|
|
|
## 2. Initialize
|
|
|
|
Aphoria needs a corpus of authoritative assertions (RFCs, OWASP) to scan against.
|
|
|
|
```bash
|
|
$ aphoria init
|
|
```
|
|
|
|
This creates `.aphoria/` in your project and loads the authoritative corpus (RFC 7519, RFC 5246, OWASP guidelines, etc.) into a local database.
|
|
|
|
Each project has its own isolated database by default.
|
|
|
|
## 3. The First Scan
|
|
|
|
Navigate to any project—a Rust backend, a Node.js API, or a Python script.
|
|
|
|
```bash
|
|
$ aphoria scan .
|
|
```
|
|
|
|
You will likely see output like this:
|
|
|
|
```
|
|
Scanning my-project ...
|
|
|
|
BLOCK code://node/server/tls/cert_verification
|
|
Your code: rejectUnauthorized: false (server.js:42)
|
|
RFC 5246: TLS certificate verification MUST be enabled (Tier 0)
|
|
Conflict: 0.92
|
|
|
|
BLOCK code://node/auth/jwt/algorithm
|
|
Your code: algorithms: ["none"] (auth.js:15)
|
|
RFC 7519: 'none' algorithm MUST NOT be accepted (Tier 0)
|
|
Conflict: 0.98
|
|
|
|
2 conflicts found (2 BLOCK).
|
|
```
|
|
|
|
### Interpreting the Output
|
|
|
|
* **BLOCK:** A high-confidence conflict with a Regulatory (Tier 0) or Clinical (Tier 1) source. This is likely a bug or security vulnerability.
|
|
* **FLAG:** A conflict with a lower-tier source (Vendor recommendation, Expert opinion). Worth reviewing, but might be intentional.
|
|
* **Conflict Score:** How strongly the sources disagree (0.0 to 1.0).
|
|
|
|
Notice that Aphoria didn't just say "Error." It cited **RFC 5246**. It told you *why* it's wrong.
|
|
|
|
## 4. Fixing the Drift
|
|
|
|
You have two choices: **Fix** or **Acknowledge**.
|
|
|
|
### Option A: Fix the Code (Compliance)
|
|
|
|
You realize the dev team left `rejectUnauthorized: false` in from a debugging session. You delete the line or set it to `true`.
|
|
|
|
Run the scan again:
|
|
```bash
|
|
$ aphoria scan .
|
|
0 conflicts found.
|
|
```
|
|
Epistemic drift resolved. The code now aligns with the spec.
|
|
|
|
### Option B: Acknowledge the Deviation (Constructive Disagreement)
|
|
|
|
Sometimes, you are right and the RFC is wrong *for your context*.
|
|
* *Scenario:* This is a local test harness. It uses self-signed certs. `rejectUnauthorized: false` is correct here.
|
|
|
|
Instead of ignoring it, you **Acknowledge** it.
|
|
|
|
```bash
|
|
$ aphoria ack "code://node/server/tls/cert_verification" --reason "Local dev harness, self-signed certs OK"
|
|
```
|
|
|
|
Run the scan again:
|
|
```bash
|
|
$ aphoria scan .
|
|
|
|
ACK code://node/server/tls/cert_verification
|
|
Reason: "Local dev harness, self-signed certs OK"
|
|
Status: Acknowledged (passed)
|
|
```
|
|
|
|
### Why this matters
|
|
By acknowledging, you created a **new assertion** in the database: *"In this project context, disabling TLS verify is acceptable."*
|
|
|
|
You didn't just suppress a warning. You created a permanent, signed audit trail of *why* the security rule was broken.
|
|
|
|
## 5. Next Steps
|
|
|
|
You've successfully aligned your code with reality.
|
|
* If you fixed it, you improved security.
|
|
* If you acknowledged it, you improved documentation and auditability.
|
|
|
|
**Next:** Learn how to enforce these rules across your entire company with [Federating Truth](./authoritative-state-per-project.md).
|