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

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

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

### 2. Bless Authoritative Standards

```bash
# 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

```bash
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)

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

That's it. The policy is now active.

### 2. Run Scan

```bash
# 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:

```json
{
  "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:**
```yaml
# config/tls.yaml
tls:
  verify: true  # Fixed
```

**Or acknowledge as intentional:**
```bash
aphoria acknowledge "code://config/myservice/tls/cert_verification" \
  --reason "Legacy integration requires cert bypass, tracked in JIRA-1234"
```

---

## CI/CD Integration

### GitHub Actions

```yaml
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

```bash
# 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:
```bash
aphoria scan  # Fast, no persistence
```

Use persistent mode only when needed:
```bash
aphoria scan --persist  # Slower, enables drift detection
```

---

## Next Steps

- See [extractors documentation](../extractors.md) for supported patterns
- See [policy export reference](../policy-export.md) for advanced options
- See [conflict resolution guide](../conflict-resolution.md) for remediation strategies