Complete Guide · macOS

1) Install BeProof on macOS

macOS app (recommended)

Download the signed and notarized DMG from the latest GitHub release, open it, and drag BeProofApp.app to Applications.

Trust artifacts: SHA256, provenance, SBOM. Verify with beproof verify-install --app /Applications/BeProofApp.app after CLI install.

IT admins: see the macOS Admin Guide for support matrix and permissions, and Managed deployment (MDM) for PKG, PPPC, org-policy overlay, and platform runbooks.

CLI (Homebrew, Apple Silicon)

Install the production beproof command for headless scans, policy evaluation, and export without building from source. The public Homebrew tap tracks https://github.com/oxy9en/AgAudit-releases.

brew tap oxy9en/beproof https://github.com/oxy9en/AgAudit-releases
brew install beproof
beproof scan --root .

To update later, run brew update && brew upgrade beproof.

2) Core workflow

1. Run Audit from the Overview toolbar (or execute scan commands via CLI).
2. When coverage gaps remain after the first scan, BeProof opens Evidence Checklist once to show the next local and cloud collection steps.
3. Start with Audit Readiness: check evidence completeness, last run time, and scan scope.
4. Resolve coverage gaps first — without this, the audit remains incomplete.
5. Review Active policy violations and open findings by severity from Overview or the detail tabs.
6. Record approved exceptions through allowlist (approved issues remain visible).
7. Review pending first-seen MCP servers and add to mcpServers after review (POL-X09).
8. In managed mode, confirm provider account classification on Local vs Cloud and resolve POL-X05 items in Review Queue when personal or unclassified cloud usage is detected.
9. In managed mode, publish approvedGrantScopes in the org-policy overlay and resolve POL-X04 / Cloud Grants Review Queue items when grant edges exceed approved templates.
10. Export evidence in JSON/Markdown format, then verify with the appropriate CLI command (see section 13).

Default inventory scope is known agent locations plus the current project root. BeProof does not crawl the entire user home directory or / by default; unreadable or missing scope is reported as a scan_scope coverage gap.

3) Evidence Checklist

Evidence Checklist is a guided status sheet — not an in-app settings panel. It tells you which evidence layers are complete, which operations to run next, and whether cloud connectors are optional or required for the current audit mode. BeProof does not store provider admin keys in the UI; cloud setup happens through shell environment variables followed by restart, then grant, declaration, and usage collection from the checklist or Coverage tab.

Two-step checklist

• Step 1 · Local evidence — declared configuration scan and local usage import from automation and IDE history.
• Step 2 · Cloud evidence — admin tokens, cloud grant enumeration, cloud agent declarations, and cloud usage fetch. Step labels show whether cloud is optional, required by org policy, or already complete.

Dual-mode posture

Managed orgs deploy .beproof/org-policy-overlay.json with requiredCloudConnectors and, when grant evidence is required, approvedGrantScopes. See Managed deployment for overlay delivery, scope templates, and connector expectations.

When the checklist appears

• Auto-opens once after the first scan or audit that leaves coverage gaps
• Overview hero button when local or cloud checklist steps are still incomplete
• Toolbar Evidence Checklist button when checklist steps are incomplete or Local vs Cloud reconciliation is waiting for cloud declarations
• Local vs Cloud warning banner when cloud checking is not configured

When local evidence is already complete and cloud is optional, the checklist is informational. Use Copy cloud setup instructions to copy export commands for provider admin keys. Expand Provider details and Policy evaluability when cloud setup is active to see connector readiness and whether POL-G03, POL-O03, POL-X03, POL-X04, and POL-X05 can evaluate.

For provider account classification after cloud declarations load, see section 4. For org-approved grant scope templates and Cloud Grants review, see section 4b. For row-level reconciliation, continue on the Local vs Cloud tab. For category-level missing checks, use Coverage.

4) Provider account attribution (POL-X05)

BeProof classifies cloud provider connectors as Personal, Organization, or Unknown during cloud declaration enumeration. Classification flows into cloud connector surfaces, cloud usage events, managed policy evaluation (POL-X05), and Review Queue items with kind personal_account_usage. Inconclusive probes create a provider_attribution coverage gap instead of silently passing.

Classification signals

Verify in the app

• Local vs Cloud inspector → Account field on cloud connector surfaces (Personal / Organization / Unknown)
• Policy tab → POL-X05 violated in managed mode when personal or unclassified cloud usage is detected
• Review Queue → Provider Accounts category (kind personal_account_usage)
• Coverage tab → provider_attribution gap when classification probes are inconclusive

Review Queue categories

Use the Categories filter to focus on one item kind. Provider Accounts is the POL-X05 decision lane for managed orgs:

• MCP Servers
• Local Commands
• Credentials
• Duplicate Credentials
• Cloud Grants
• Provider Accounts
• Usage Context
• Paused Automations
• Coverage Gaps

Verify with CLI

Run from a project with .beproof/beproof.db after exporting provider admin keys in the shell (see section 14):

# 1) Classify connector surfaces
beproof enumerate-cloud-declarations --providers openai,anthropic,cursor,github,google
beproof list-cloud-surfaces | jq '.cloudAgentSurfaces[] | {id, provider, accountType, workspaceId}'

# 2) Confirm cloud usage carries account fields
beproof fetch-cloud-usage --providers openai,cursor --lookback-days 7
beproof list-usage | jq '.usageEvents[] | select(.source=="cloud") | {provider, accountType, workspaceId}'

# 3) Evaluate POL-X05 in managed mode
beproof evaluate-policy \
  --audit-mode managed \
  --org-policy-overlay .beproof/org-policy-overlay.json \
  --format json | jq '.violations[] | select(.ruleId=="POL-X05")'

# 4) List review items for provider account decisions
beproof review list --kind personal_account_usage --format json

For managed pilots, copy packages/contracts/examples/org-policy-overlay-managed.json to .beproof/org-policy-overlay.json or deliver it through MDM. See Managed deployment for overlay delivery and acceptance checks.

4b) Grant scope templates (POL-X04)

BeProof compares enumerated cloud grant edges against org-approved scope templates in approvedGrantScopes. Templates resolve through GrantScopeTemplateSettings: managed audits use the org-policy overlay only; personal audits prefer the local policy allowlist and fall back to the overlay. When managed mode requires the granted evidence layer but templates are empty, POL-X04 fails closed with a grant_scope_templates coverage gap instead of silently passing. Individual grant scopes outside the template surface as POL-X04 violations and Review Queue items with kind cloud_grant_over_approved_scope.

Template precedence

Example overlay templates

{
  "version": "1.0",
  "orgPolicyId": "org-default-managed-policy",
  "requiredSources": ["declared", "granted", "observed"],
  "requiredCloudConnectors": ["github", "openai"],
  "approvedGrantScopes": {
    "github": ["repo:read", "pull_requests:write"]
  }
}

Verify in the app

• Policy tab → Grant scope templates caption under rule groups (source, provider count, scope count; "required by org policy" in managed mode)
• Policy tab → POL-X04 violated when grant edges exceed templates or when managed overlay omits required approvedGrantScopes
• Review Queue → Cloud Grants category (kind cloud_grant_over_approved_scope)
• Coverage tab → grant_scope_templates gap when managed requiredSources includes granted but templates are empty

Review Queue: Cloud Grants

Use the Cloud Grants category to review grant edges that exceed approved templates or managed configuration gaps when approvedGrantScopes is missing from the MDM overlay. Decisions include approving an expected grant, marking scope reduced after remediation, or accepting risk temporarily while templates are updated.

Verify with CLI

Run from a project with grant edges loaded after cloud enumeration:

# 1) List enumerated grant edges
beproof list-grant-edges | jq '.grantEdges[] | {provider, scope, grantType}'

# 2) Inspect effective grant scope policy summary (JSON export)
beproof export-report --format json | jq '.policyEvaluation.grantScopePolicy'

# 3) Evaluate POL-X04 violations
beproof evaluate-policy \
  --audit-mode managed \
  --org-policy-overlay .beproof/org-policy-overlay.json \
  --format json | jq '.violations[] | select(.ruleId=="POL-X04")'

# 4) List Cloud Grants review items
beproof review list --kind cloud_grant_over_approved_scope --format json

For managed pilots, deliver approvedGrantScopes through the org-policy overlay at the MDM system path. See Managed deployment for overlay delivery and POL-X04 acceptance checks.

5) Application tabs

Each tab below maps to one operational view in the macOS app. Screenshots are shown inline where the tab has a dedicated capture. Selecting a row in most tabs opens the matching inspector panel documented in section 6.

Overview

Readiness-first audit home: evidence completeness, last run freshness, scan scope, risks by severity, detected agents, and collected evidence.

• Run Audit from the toolbar or follow the primary hero CTA
• Open Evidence Checklist from Overview or the toolbar when evidence collection is incomplete or cloud reconciliation is pendingSee Evidence Checklist
• Confirm evidence readiness, last audit time, and scan scope before trusting results
• Review policy and findings rows by severity; each row opens the detailed tab
• Use Agents Detected and Evidence Collected cards as shortcuts to inspect supporting data

Agents

User-friendly inventory of detected AI tools: which tools are configured, whether automations are active or paused, recent local activity, and items that need attention.

• Start with Agent Status cards such as Active, Paused, Used Recently, Needs Attention, or No Usage Found
• Use Agent Tools chips to focus on providers such as Codex, Cursor, Claude, MCP, or instruction files
• Select an agent row to review tool details, where it applies, recent activity, and policy flagsSee Agents inspector
• Open Configuration Details when you need the underlying source file and deeper evidence mapSee Inspector Actions

Agents inspector →

Findings

Review-first findings workflow that separates security risks from lightweight usage-context confirmations.

• Start with Risks to Review, Context to Confirm, Critical / High, or intent-specific metric cards
• Inspect why an item matters, affected surfaces, observed activity examples, and technical evidence refsSee Findings inspector
• Record decisions such as resolved, accepted risk, false positive, reviewed context, or not relevantSee Review Decision
• Bulk mark usage-context groups reviewed when local activity is expected and no per-item note is needed

Findings inspector →

Policy

AI Governance Rules view for Policy Pack v1.2.2: clickable outcome metrics, rule groups, focus filters, and an inspector with evidence links.

• Click Active, Approved, Exception, Passed, or N/A cards to jump to the matching rules
• Open rule pills such as POL-O05 or POL-X06 to inspect source instances and evidenceSee Policy inspector
• Expand “What are these rules?” for a plain-language explanation of the policy categories
• Read the Correlation policy and Grant scope templates captions under the rule groups when POL-O04 or POL-X04 applySee Grant scope templates
• Use the Policy Pack v1.2.2 link for the full rule catalog, signals, and outcome meanings

Policy inspector →

Review Queue

Review-first decision workflow that separates risks, usage-context confirmations, accepted risks, and completed decisions across MCP, credentials, grants, provider accounts, observed usage, and coverage gaps.

• Start with Risks to Review or Context to Confirm, then narrow by status, item kind, severity, or search
• Use Categories to focus on MCP Servers, Local Commands, Credentials, Cloud Grants, Provider Accounts, Usage Context, or Coverage GapsSee Cloud Grants
• Record a clear decision in the inspector: approve as expected, mark fixed/resolved, or accept risk temporarilySee Review Queue inspector
• Use evidence, history, remediation, and utility actions to validate the decision before rechecking the queueSee Evidence · History

Review Queue inspector →

Surfaces

Actionable evidence map of discovered agent configuration and instruction files, showing how each file connects to observed usage, findings, policy rule matches, and linked evidence.

• Start with Configured, Used Recently, No Matching Usage, Related Risks, or Rule Matches cards to focus the map
• Use Scope, Kind, and search filters to review configuration files by project, file type, path, or usage state
• Select a configuration row to inspect where it was found, what it means, observed usage, related risks, and rule matchesSee Surfaces inspector
• Use Linked Evidence for traceability and Actions to reveal the file, copy its path, scan local usage, or open the related risk/ruleSee Linked Evidence · Actions

Surfaces inspector →

Local vs Cloud

Plain-language reconciliation view that explains whether local AI tools can be confirmed against cloud declarations, and whether the next step is setup, cloud checking, or review.

• Start with Matched and Waiting for Cloud Setup / Cloud Check cards to understand the main reconciliation state
• Use the warning banner to open Evidence Checklist when cloud checking is not configured, or run Cloud Check when the connector is ready but declarations are not loaded yet
• Select a tool row to compare the Local Side, Cloud Side, Account classification, Cloud Check Status, and recommended next stepSee Local vs Cloud inspector
• Copy setup instructions from Evidence Checklist or the inspector when a provider admin key is missing, or run Cloud Check once the connector is configuredSee Inspector Actions

Local vs Cloud inspector →

Access

Plain-language access references: stored references on this Mac, cloud grants, grant scopes, and installed AI tools — metadata only.

• Start with Stored References, Cloud Grants, Needs Review, Grant Scopes, or Installed Tools cards
• Use compact Focus, Provider, and Search controls instead of scanning long provider chip lists
• Treat Unmapped References as stored references that need provider mapping before cloud access can confirm them
• Select a stored reference to review provider status, where it is stored, linked evidence, and the recommended next stepSee Access inspector

Access inspector →

Usage

Review-first map of observed AI activity, runtime evidence, and usage coverage gaps across local and cloud sources.

• Start with Observed Groups, Needs Context, Not Matched, No Recent Use, Cloud Only, or Low Confidence cards
• Use Focus, Provider, Source, and search filters to narrow usage by project, tool, evidence source, or status
• Select a grouped project row to inspect the human summary, matching configuration state, and raw session/evidence countsSee Usage inspector
• Use inspector actions to rescan local usage, fetch cloud usage, or correlate local and cloud evidenceSee Inspector Actions
• Treat usage as metadata-only context unless Findings or Review Queue turns it into a decision item

Usage inspector →

Correlations

Review-first map of cross-layer links between local sessions and cloud API activity, plus unlinked usage rows that still need correlation.

• Start with Cross-Layer Links, Qualifying, Below Threshold, High Confidence, No Cloud Link, or No Local Link cards once both sides are loaded
• When cloud or local usage is missing, use the coverage banner first instead of treating every session as a correlation failureSee Coverage Gap State
• Use Focus, Provider, and search filters to narrow grouped links by provider, project, session, or match signal
• Select a grouped row to inspect local and cloud sessions, match signals, policy threshold, and next stepsSee Correlations inspector
• Run Recompute Correlations after refreshing local usage or cloud usage dataSee Inspector Actions

Correlations inspector →

Coverage

Review-first audit completeness map across settings, access, usage, and audit-trail categories with missing checks surfaced first.

• Read the headline to see how many checks still need data
• Start with Missing, Incomplete, or Complete filters
• Review What's missing in the summary for plain-language reasons
• Expand Scanned folder if you need the full project path
• Select a check to see what BeProof could not find and tap the recommended actionSee Coverage inspector
• Use More actions only when the primary button is not enoughSee Recommended Fix
• Use the Keychain gate when keychain metadata is missing and policy allows consent-based scanning

Coverage inspector →

Privacy

Live consent and data-boundary review: filterable sensitive sources, POL-G02/POL-X14 policy checks, metadata-only counts, scan scope disclosure, and export-ready Consent preview in the inspector.

• Read the headline and Consent Review metrics (Needs Attention, Consented, Planned)
• Use focus filters for sensitive sources only — data boundaries always stay visible
• Review Metadata Stored (metadata only) tiles; open Access, Usage, or Surfaces for drill-down
• Expand Scanned folder to confirm the project path and full audit scope
• Open Policy Checks tiles (Keychain consent, Verifiable ledger) for POL-G02 and POL-X14
• For consent gaps, follow inspector Actions to Coverage; for consented keychain, use Export Preview to copy the JSON or Markdown Consent snippet before GRC handoffSee Inspector Actions · Export Preview

Privacy inspector →

6) Inspector panels

The redesigned screens use inspector panels to keep the main list focused while still exposing decision criteria, evidence, history, and navigation links. Each panel below links back to its tab in section 5. Agents uses the inspector for tool status, recent activity, and configuration drill-down; Findings, Policy, and Review Queue inspectors support review decisions; Surfaces uses the inspector as an evidence map for configuration files, linked usage, related risks, rule matches, and navigation actions; Access explains stored references, cloud grants, grant scopes, and installed tools without storing secret values; Usage explains grouped observed activity, matching configuration state, evidence counts, and next utility actions without turning usage context into a security finding by itself; Correlations explains cross-layer links, match signals, policy threshold status, grouped missing-link rows, and coverage-gap guidance when local or cloud usage is not loaded yet; Coverage explains missing, incomplete, and complete checks by category, plain-language reasons, recommended scan actions, and More actions for follow-up scans; Privacy explains filterable sensitive-source consent (Needs Attention, Consented, Planned), live metadata-only storage counts, scan scope disclosure, policy check tiles with deep links to POL-G02 and POL-X14, separate consent approval vs keychain scan status, Export Preview with JSON/Markdown Consent snippet copy for GRC handoff, and deep links to Coverage, Access, and Policy without duplicating the Keychain gate toggle.

7) Policy statuses

8) Policy Pack v1.2.2 rules (macOS)

Baseline 20 rules: ✅ auto-evaluable today · 🟡 partial · 🔴 requires product work. G03/O03 evaluate when org tokens are configured; otherwise N/A or explicit coverage gaps apply.

In the macOS app these rules appear as AI Governance Rules: the top cards filter and scroll to matching outcomes, rule pills open the related rule group, and the inspector explains the selected violation or rule.

For the complete rule catalog, signals, outcome meanings, and version notes, see Policy Pack v1.2.2.

9) POL-X extension controls (shipped)

Extension controls are tracked separately from the baseline 20 rules. Several are already evaluable in the macOS app and CLI.

POL-X12: Append-only hash-chain journal with `verify-journal`; journal payloads encrypted at rest (AES-256-GCM, Keychain-bound key). Inventory tables are metadata-only but not encrypted in the current release.

POL-X13 (Partial): Public release pipeline (shipped) — Signed/notarized macOS DMG + Apple Silicon CLI on public releases; published checksum (.sha256), SPDX SBOM, and provenance JSON; CI `beproof verify-install` gate before upload; Sparkle appcast metadata (Ed25519-signed, disabled when org overlay present). Enterprise release controls (partial) — Fleet-wide verify-install attestation in control plane, tenant-private or air-gapped artifact mirror, org-enforced minimum release version policy, and automated MDM promotion workflow — manual MDM runbooks today.

10) Allowlist and exceptions

Default allowlist path: .beproof/policy-allowlist.json. Approved exceptions are marked as approved and remain visible in UI/exports with allowlistRef.

{
  "version": "1.0",
  "mcpServers": ["XcodeBuildMCP"],
  "mcpDomains": ["mcp.sentry.dev", "*.sentry.dev"],
  "mcpEnvKeys": [],
  "approvedScanRoots": ["~/Developer/BeProof", "~/work/ai-platform"],
  "correlationMinConfidence": 0.65,
  "approvedGrantScopes": {
    "github": ["read:org", "repo"]
  }
}

mcpServers approves MCP findings and clears first-seen baseline pending state (POL-X09). correlationMinConfidence controls POL-O04 / POL-X08. approvedGrantScopes defines scope templates for POL-X04 in personal mode when present. In managed mode, templates come only from the org-policy overlay — the allowlist field is ignored. See section 4b.

11) Local sidecar files

BeProof stores audit state beside the SQLite database under .beproof/.

12) Core CLI commands

After Homebrew installation, run commands directly as beproof. The CLI writes to .beproof/beproof.db by default unless --db is supplied.

• beproof scan --root .
• beproof analyze-mcp --root .
• beproof scan-credentials --root . [--include-keychain] [--consent-approved-by <name>]
• beproof scan-installs
• beproof scan-local-usage [--home ~]
• beproof enumerate-cloud --providers openai,github,cursor [--fetch-usage]
• beproof enumerate-cloud-declarations --providers openai,anthropic,cursor,github,google
• beproof list-cloud-surfaces
• beproof list-cloud-readiness
• beproof fetch-cloud-usage --providers openai,cursor [--lookback-days 7]
• beproof correlate-usage [--window-seconds 600]
• beproof list-grant-edges
• beproof list-mcp-baseline
• beproof record-audit-run --mode full --audit-mode personal|managed --scan-scope-source user_selected|org_policy|mdm_profile|inferred --org-policy-id <id> --scan-root .
• beproof list-audit-runs
• beproof evaluate-policy --format json|text [--audit-mode personal|managed] [--scan-scope-source user_selected|org_policy|mdm_profile|inferred] [--org-policy-id <id>] [--allowlist .beproof/policy-allowlist.json] [--org-policy-overlay .beproof/org-policy-overlay.json]
• beproof review list [--status <status>] [--kind personal_account_usage] [--format json|text]
• beproof review approve --item <id> --by <actor> [--reason <text>]
• beproof review exception --item <id> --by <actor> --reason <text> --expires-at <iso8601> --scope <scope>
• beproof review expected --item <id> --by <actor> [--reason <text>]
• beproof review resolved --item <id> --by <actor> [--reason <text>]
• beproof review remediation --item <id>
• beproof review recheck
• beproof export-report --format markdown --output audit.md
• beproof verify-journal [--db .beproof/beproof.db]
• beproof verify-export --artifact ./audit.md [--manifest ./audit.md.manifest.json] [--db .beproof/beproof.db]
• beproof verify-export-manifest --artifact ./audit.md [--manifest ./audit.md.manifest.json] [--public-key ./export-signing.pub.json]
• beproof verify-install --app /Applications/BeProofApp.app [--artifact ./BeProofApp-macos.dmg] [--provenance ./BeProofApp-macos.provenance.json] [--format text|json]

13) Verify CLI contract

BeProof exposes four distinct verify commands. They are not interchangeable. Semantics match the Trust Center and Policy Pack verify CLI contract.

• Offline recipient / GRC: verify-export-manifest --artifact <path> — artifact + signed manifest integrity.
• Local auditor trust: verify-export --artifact <path> plus verify-journal — full hash chain and journal payload encryption status on the scanning endpoint.
• Release trust: verify-install --app /Applications/BeProofApp.app with optional --artifact and --provenance for DMG and SBOM checks.

verify-export-manifest does not check journal linkage. verify-export requires journal fields in the manifest and a local database with matching chain head. Use the command that matches your trust boundary.

14) Required environment variables

15) Troubleshooting

• Coverage gap `codex_usage`: rerun Scan Local Usage; if Codex is still holding SQLite state files, close Codex and retry.
• Many `POL-D03` issues: review scan scope and approved roots, or use the hide artifact paths filter to keep focus. (POL-D03)
• Many `POL-G04` issues: these are duplicate credential refs; assess expected duplicates (env + keychain + vendor artifacts) and document the decision. (POL-G04)
• POL-X09 first-seen MCP servers: run analyze-mcp, inspect list-mcp-baseline, then add reviewed server IDs to mcpServers in the allowlist.
• Keychain consent / POL-G02: grant consent in the app Keychain gate or pass --include-keychain --consent-approved-by <name> on CLI before expecting keychain refs in policy evaluation.
• Export integrity: after export-report, use verify-export-manifest --artifact <path> for offline/GRC checks, or verify-export --artifact <path> plus verify-journal on the scanning endpoint for full local chain trust (see section 13).
• Observed Usage shows many Not Matched rows: select Not Matched, read the inspector's matching-configuration explanation, then verify Surfaces/Agents coverage and rerun local usage scans if configuration files were missing from the scan.
• No usage data: run scan-local-usage, then optionally fetch-cloud-usage and correlate-usage.