stemedb/applications/aphoria/docs/guides/the-first-scan.md

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.

# From source (assuming you have the repo)
cd /path/to/stemedb/applications/aphoria
cargo install --path .

Verify it works:

$ aphoria --version
aphoria 0.1.0

2. Initialize

Aphoria needs a corpus of authoritative assertions (RFCs, OWASP) to scan against.

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

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

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

$ aphoria ack "code://node/server/tls/cert_verification" --reason "Local dev harness, self-signed certs OK"

Run the scan again:

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