stemedb/applications/aphoria/docs/guides/enterprise-quick-start.md

Enterprise Quick-Start Guide

Get from "git clone" to enforcing security standards in 5 minutes.

Overview

Aphoria enables a single security team to define authoritative standards that are automatically enforced across all development teams - with zero configuration required from developers.

What You Get

• Cryptographic Attribution - Every conflict traces back to a specific policy pack and issuer
• Full Audit Trail - Know exactly which standard flagged which violation
• Zero Dev Team Configuration - Import policy URL, scanning just works
• "Git for Truth" - Conflicting assertions coexist, resolved at query time

---

For Security Teams

1. Create a Standards Project

mkdir security-standards && cd security-standards
cat > aphoria.toml << 'EOF'
[project]
name = "security-standards"

[episteme]
data_dir = ".aphoria/db"
EOF

2. Bless Authoritative Standards

# Require TLS certificate verification
aphoria bless "code://standard/tls/cert_verification" \
  --predicate enabled --value true \
  --reason "Certificate verification required per OWASP ASVS 9.1.1"

# Require TLS 1.2 minimum
aphoria bless "code://standard/tls/min_version" \
  --predicate version --value "1.2" \
  --reason "TLS 1.2 minimum per RFC 8446"

# Require JWT audience validation
aphoria bless "code://standard/jwt/audience_validation" \
  --predicate enabled --value true \
  --reason "JWT aud claim must be validated per RFC 7519"

3. Export Trust Pack

aphoria policy export \
  --name "Acme-Security-Standards" \
  --output acme-security-v1.0.pack

4. Distribute to Teams

Share the .pack file via:

• Internal artifact repository (Artifactory, Nexus)
• Git LFS in a shared policies repo
• S3/GCS bucket with team access
• Direct Slack/email for small teams

---

For Development Teams

1. Import Trust Pack (One Command)

aphoria policy import path/to/acme-security-v1.0.pack

That's it. The policy is now active.

2. Run Scan

# Quick check (no persistence)
aphoria scan

# Full scan with persistence and JSON output
aphoria scan --persist --format json

3. Review Conflicts

Conflicts appear with full attribution:

{
  "concept_path": "code://config/myservice/tls/cert_verification",
  "value": false,
  "verdict": "BLOCK",
  "sources": [
    {
      "path": "code://standard/tls/cert_verification",
      "value": true,
      "policy_source": {
        "pack_name": "Acme-Security-Standards",
        "pack_version": "1.0.0",
        "issuer_hex": "a1b2c3d4"
      }
    }
  ]
}

4. Fix or Acknowledge

Fix the violation:

# config/tls.yaml
tls:
  verify: true  # Fixed

Or acknowledge as intentional:

aphoria acknowledge "code://config/myservice/tls/cert_verification" \
  --reason "Legacy integration requires cert bypass, tracked in JIRA-1234"

---

CI/CD Integration

GitHub Actions

name: Security Scan
on: [push, pull_request]

jobs:
  aphoria:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Aphoria
        run: cargo install aphoria

      - name: Import Security Policy
        run: |
          curl -sL ${{ secrets.SECURITY_PACK_URL }} -o policy.pack
          aphoria policy import policy.pack          

      - name: Run Scan
        run: aphoria scan --persist --exit-code --format sarif > results.sarif

      - name: Upload SARIF
        uses: github/codeql-action/upload-sarif@v2
        with:
          sarif_file: results.sarif

Exit Codes

Code	Meaning
0	No BLOCK-level conflicts
1	One or more BLOCK-level conflicts found

Use --exit-code flag to enable CI blocking.

---

Conflict Verdicts

Verdict	Description	CI Behavior
BLOCK	High-confidence conflict with Tier 0-1 authority (RFC, OWASP)	Fails CI with --exit-code
FLAG	Moderate-confidence conflict	Passes CI, visible in report
ACK	Acknowledged conflict	Passes CI, tracked for audit
PASS	No conflict	-

---

Output Formats

# Human-readable table (default)
aphoria scan --format table

# Machine-readable JSON
aphoria scan --format json

# Documentation-ready Markdown
aphoria scan --format markdown

# GitHub Security tab integration
aphoria scan --format sarif

---

Troubleshooting

"No conflicts found" but expected violations

1. Check extractor coverage - Aphoria detects patterns in config files (YAML, TOML, JSON) and language-specific code patterns
2. Verify concept paths match - Policy paths use tail-path matching (tls/cert_verification matches code://*/tls/cert_verification)
3. Check file extensions - Ensure config files have correct extensions (.yaml, .yml, .toml, .json)

"Pack import failed"

1. Verify pack signature - Pack may be corrupted or tampered
2. Check pack version - Ensure Aphoria version is compatible
3. Verify file permissions - Import creates .aphoria/db directory

"Scan is slow"

Use ephemeral mode for quick checks:

aphoria scan  # Fast, no persistence

Use persistent mode only when needed:

aphoria scan --persist  # Slower, enables drift detection

---

Next Steps

• See extractors documentation for supported patterns
• See policy export reference for advanced options
• See conflict resolution guide for remediation strategies