APERION Compass — local AI governance self-assessment

What it is

Compass turns a governance framework into a runnable check. You fill in compass-assessment.yaml (interactive questionnaire, or hand-edit and commit it), attach evidence you already export, and compass report scores the lot. Claim a tamper-evident log, hand it a chain that fails verification, and that control turns red — with a non-zero CI exit code.

No account, no telemetry, no upload. The binary never phones home. If you have no evidence files yet, a questionnaire-only run still produces a full report; those controls are marked self-attested.

How a run works

# 1. Answer the questionnaire (writes compass-assessment.yaml)
compass assess --framework eu-ai-act,imda

# 2. Attach evidence you already export (all optional)
compass ingest \
  --vas         logs.jsonl \
  --chain       audit-chain.jsonl --chain-hmac-key file:hmac.key \
  --approvals   approvals.jsonl \
  --credentials agents.jsonl --jwks issuer-jwks.json

# 3. Score it
compass report --out report --format html,md,json,junit,sarif

# ...or explore live in the browser
compass serve --port 8787

# 4. Seal a signed, offline-verifiable attestation
compass attest generate --out compass-attestation.json
compass attest verify   --bundle compass-attestation.json

Don't have governance-grade logs? That's the normal starting point. Convert a provider export, or put compass record in front of the model endpoint for a while.

compass ingest --from openai   --input openai-export.json
compass ingest --from litellm  --input litellm-logs.jsonl
compass ingest --from bedrock  --input bedrock-invocations.jsonl
compass ingest --from csv-approvals --input approvals.csv

compass record --upstream https://api.openai.com --out compass-record.jsonl
compass doctor

Install

Pick whichever route you already use. All three produce the same compass binary. The crate is not on crates.io — if you want to compile it, clone the repo and cargo build --release.

brew install AperionAI/tap/aperion-compass

# already on 0.4:
brew update
brew upgrade aperion-compass

docker run --rm -v "$PWD:/work" -w /work \
  ghcr.io/aperionai/compass:latest \
  report --out report.html

CI

compass-assessment.yaml is meant to be committed. Diffable, re-runnable, reviewable in a pull request.

# .github/workflows/governance.yml (excerpt)
- run: compass report --out report --format html,junit,sarif --threshold 80
  # exit 0 = at/above threshold · 1 = below · 2 = evidence integrity failure
- uses: actions/upload-artifact@v4
  if: always()
  with:
    name: compass-report
    path: |
      report.html
      report.junit.xml
      report.sarif

EU AI Act catalog (28 controls)

Catalog follows Regulation (EU) 2024/1689, including Digital Omnibus adjustments. This is a preparation aid, not a conformity assessment and not a substitute for a notified body.

Every EU control carries an effective_date. The report badges Binding now vs Prepare by 02 Dec 2027. Deferred Annex III high-risk duties (Arts. 9–15, 17, 26, 72, 73) stay in the score so you can work them; the badge stops the report from implying they are due today.

Art. 50(2) machine-readable marking: systems placed on the market before 2 Aug 2026 get until 2 Dec 2026; new systems must comply immediately. The incident-reporting control id stays art_79_incident_reporting so existing answer files don't break; the text points at Art. 73.

For the runtime side of the Act (enforcement on the request path, Conformity Console, sealed audit), see APERION for the EU AI Act.

IMDA agentic catalog (32 controls)

Seeded from the IMDA / AI Verify Foundation Model AI Governance Framework for Agentic AI v1.5 (20 May 2026, updated 5 June 2026). The framework's claim is that governance belongs in a deterministic layer between the agent and the systems it touches, not in prompts.

v0.4 added the v1.5 delta: systemic / multi-agent risk, memory poisoning, and the platform-provider vs system-provider split. Identity, authorization, oversight effectiveness, MCP whitelisting, sandboxed execution, tamper-evident logging, and change management were already there.

The IMDA dimensions as a runtime story are on Governing Agentic AI, by Design. Compass scores the same topics from files. Smartflow enforces them on the hot path.

EU ↔ IMDA crosswalk

Shipped in 0.5. When you score both frameworks, an unanswered control can inherit a native answer from a mapped peer. Groups live in catalogs/crosswalk.yaml inside the repo. Native answers always win. The scorecard notes when a verdict was inherited so nobody mistakes it for a second independent answer.

Mappings are conservative — only where the duty is the same kind of control. Examples: Art. 12 logging ↔ IMDA log_all_interactions; Art. 14 oversight effectiveness ↔ override-rate / response-time / outlier-reviewer checks; Art. 50 disclosure ↔ inform_users_actions.

NIST AI RMF is not in the binary yet. When that catalog lands, the same crosswalk file grows to cover it.

Ingest & doctor

compass ingest registers evidence files, or converts a native export first:

compass doctor lists which automated checks have evidence and, for every gap, the step to close it. Gaps are findings, not failures. Per-platform export playbooks live in the repo under docs/evidence/.

What the automated checks actually do, once files are attached:

• Audit-chain integrity — HMAC-SHA256 hash chain (seq / prev_hash / entry_hmac) with only the key.
• Human oversight — override rate, approval latency, outlier reviewers from exported tickets.
• Action-risk coverage — tiers tool calls T1/T2/T3 and reports how many irreversible actions had an approval.
• Agent identity — Ed25519 credentials offline against a public key / JWKS. HMAC credentials are reported as unverifiable, not valid — they can't be checked without the secret.
• Logging completeness — field-presence stats (identity, risk tier, decisions, perimeter).

Record — HTTPS + SSE (v0.5)

compass record is a localhost OpenAI-compatible proxy. Point your SDK at it. Every call is written as hash-chained JSONL.

compass record --upstream https://api.openai.com --out compass-record.jsonl
# then set the SDK base_url to http://127.0.0.1:<port>

http and https both work. HTTPS uses rustls with Mozilla's webpki roots. A corporate TLS intercept whose CA isn't in that set will fail; putting LiteLLM (or another proxy that already trusts the intercept) in front is the usual workaround.

Streaming responses are passed through as they arrive. Compass still seals a copy into the chain, so the client sees SSE and you still get an evidence file.

Signed attestation

A report is something you produce. An attestation is something an auditor or customer can verify without trusting you. compass attest generate packs the scored posture, every evidence-check outcome, and a cryptographic anchor of the audit-chain tail into one JSON payload and Ed25519-signs it. compass attest verify recomputes the canonical payload and checks the signature offline against a published public key / JWKS. Nudging a score, dropping an integrity failure, or swapping a framework breaks verification with a non-zero exit.

The signing key defaults to ~/.aperion-compass/attest-ed25519.key (created on first run), or pass your own with --signing-key file:…|base64:…|hex:…|env:…. generate also writes the public key as <out>.jwks.json, so a verifier needs nothing but the bundle and that key.

HTML / JUnit / SARIF

compass report writes whatever you list in --format:

compass serve --port 8787 is the same dashboard on localhost, with a re-scan button.

Compass vs Smartflow vs Shield

Three different jobs. Don't mix them up on a slide.

Remediation text in Compass reports points at the governance patterns on this docs site. Smartflow is one implementation of those patterns, not the only one.

Honest limitations

• It assesses; it does not enforce. A passing report says your evidence and answers look good at a point in time. It cannot stop a bad action.
• Verification is only as good as the export. Compass cannot know the export is complete, that the HMAC key is the real one, or that a log wasn't filtered before export.
• HMAC credentials aren't offline-verifiable. Only Ed25519 (public key) credentials can be checked without a secret.
• Not legal advice. Not a notified-body assessment. The catalogs are our reading of the frameworks; verdicts are conservative but opinionated.
• v1 scope. EU AI Act + IMDA agentic today. NIST AI RMF is next. PDF export is print-to-PDF from the HTML.

License

Free to run. Source is inspectable on GitHub. Compiled binaries and images are under the Binary License Agreement — this is not an open-source license. See the LICENSE in the repo.

Source & releases

• github.com/AperionAI/compass — source, issues, catalogs
• compass-v0.5.0 — current binaries
• ghcr.io/aperionai/compass:latest — Docker image (0.5.0)
• brew install AperionAI/tap/aperion-compass
• EU AI Act / Digital Omnibus — runtime enforcement on Smartflow
• Governing Agentic AI, by Design — IMDA 8-of-8 on Smartflow
• APERION Shield — local MCP guardrails