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 the Cortex

Before scanning, Aphoria needs to know "the truth." It needs a corpus of authoritative assertions (RFCs, OWASP cheat sheets, vendor docs).

$ aphoria init
Initializing Aphoria...
Ingested 1,240 authoritative assertions.
Ready.

This downloads strict security requirements (RFC 7519 for JWT, RFC 5246 for TLS, etc.) into your project database (.aphoria/db).

Note: By default, each project has its own isolated database. To share a database across all projects on your machine, set data_dir = "~/.aphoria/db" in aphoria.toml.

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.