BeProof
DocsPilot
Documentation · macOS · MDM

Managed deployment

Deploy BeProof through MDM/UEM: signed PKG, Privacy Preferences (PPPC), and org-policy overlay at a system-managed path. BeProof remains a local-first evidence plane — MDM delivers install and policy context; it does not replace EDR, SIEM, or your existing security stack.

macOS Admin Guide

Org-policy overlay (MDM path)

When distributed through MDM, place the overlay at:

/Library/Application Support/BeProof/org-policy-overlay.json

BeProof resolves overlay precedence: CLI --org-policy-overlay → system MDM path → local .beproof/org-policy-overlay.json. When the system path is used, audit runs record scanScopeSource: mdm_profile and auto-enter managed audit mode. Managed overlays should include requiredCloudConnectors, approvedScanRoots, and — when requiredSources includes granted — org-approved approvedGrantScopes for POL-X04.

Recommended deployment order

  1. Control plane — org admin creates a one-time enrollment token (admin console → Enrollment or ops script).
  2. Pilot ring — verify verify-install and a sample export on one device.
  3. PPPC profile — deploy signed mobileconfig (customize Team ID + UUIDs).
  4. App — PKG via MDM or notarized DMG for manual installs.
  5. Fleet enroll — run BeProofCLI fleet enroll with the admin-issued token (managed mode).
  6. Org overlay — JSON at the system path; confirm managed mode in export.
  7. CLI (optional) — Homebrew tap or tarball; note terminal TCC inheritance.

Fleet enrollment (control plane)

Managed Macs must enroll with a one-time token issued by an org admin. Sign in to the admin console, open Enrollment, and create a token. See the Admin Console Guide · Enrollment for screenshots and role requirements.

cd apps/macos
swift run BeProofCLI fleet enroll \
  --token '<enrollment-token-from-admin-console>' \
  --control-plane-url 'https://YOUR_CONTROL_PLANE_URL' \
  --audit-mode managed \
  --db ~/.beproof/beproof.db

After enroll, open BeProofApp.app and run a managed audit. Post-audit sync uploads heartbeat and a signed fleet summary to the control plane — no raw SQLite leaves the device.

Build MDM PKG

From a signed and notarized BeProofApp.app bundle:

./scripts/build_mdm_pkg.sh \
  --app dist/app/BeProofApp.app \
  --version 1.0.5 \
  --output dist/app/BeProofApp-macos.pkg \
  --signing-identity "Developer ID Installer: Your Org (TEAMID)"

Validate on a pilot endpoint

beproof verify-install --app /Applications/BeProofApp.app --format json
beproof scan --root ~/Projects
beproof enumerate-cloud-declarations --providers openai,github
beproof list-cloud-surfaces | jq '.cloudAgentSurfaces[] | {provider, accountType, workspaceId}'
beproof list-grant-edges | jq '.grantEdges[] | {provider, scope}'
beproof evaluate-policy --format json | jq '{mode, scanScopeSource, orgPolicyId, x04: [.violations[] | select(.ruleId=="POL-X04")], x05: [.violations[] | select(.ruleId=="POL-X05")]}'
beproof export-report --format json | jq '.policyEvaluation.grantScopePolicy'

Expected with MDM overlay: mode is managed and scanScopeSource is mdm_profile. Connector surfaces should classify required providers as org or surface POL-X05 / provider_attribution coverage gaps when tokens are missing or inconclusive. When requiredSources includes granted, export policyEvaluation.grantScopePolicy.source should be org_policy_overlay and POL-X04 should not fail with missing templates unless the overlay omits approvedGrantScopes.

Provider account attribution (POL-X05)

Managed deployments should treat cloud provider account type as part of sign-off, not only grant enumeration. BeProof runs ProviderAccountAttributor during enumerate-cloud-declarations and stores accountType / workspaceId on connector surfaces and cloud usage events. POL-X05 flags personal or unclassified usage in managed mode; decisions land in Review Queue under Provider Accounts.

Pilot operators need org admin keys (not personal project keys) for required connectors. Export tokens through your secret-distribution path, restart BeProof or the shell session, then run cloud declaration enumeration before policy evaluation. See the macOS guide · Provider account attribution section for probe behavior and CLI verification commands.

Grant scope templates (POL-X04)

Managed deployments should publish org-approved OAuth and GitHub App scope templates in the MDM-delivered overlay as approvedGrantScopes. BeProof resolves templates from the overlay only in managed mode — local .beproof/policy-allowlist.json does not override MDM policy. When requiredSources includes granted and grant edges exist but templates are empty, POL-X04 fails closed and Review Queue surfaces Cloud Grants items instead of silently passing.

Include provider keys such as github with the exact scope strings your org approves for agent connectors. After cloud grant enumeration, compare list-grant-edges output against the overlay and resolve POL-X04 violations or Cloud Grants review items before pilot sign-off. See the macOS guide · Grant scope templates section for precedence rules and CLI verification commands.

Platform runbooks

Step-by-step guides for the top MDM platforms:

Templates and configuration files

PPPC guidance

TCC pre-approval matrix, app vs CLI context, template customization.

Open

Org-policy overlay example

Managed-mode policy contract JSON for MDM file delivery, including approvedGrantScopes for POL-X04.

Open

PPPC mobileconfig template

Reference Privacy Preferences profile for com.beproof.app.

Open

Pilot acceptance criteria

  • BeProofApp.app passes beproof verify-install on a pilot Mac
  • Org-policy overlay installed at the system MDM path and audits report managed mode (scanScopeSource: mdm_profile)
  • Export includes managed overlay surfaces for your MDM-delivered policy
  • Cloud declaration enumeration completes for requiredCloudConnectors and connector surfaces show accountType (not unknown) where tokens are valid
  • POL-X05 evaluates cleanly or produces explicit Review Queue Provider Accounts items — no silent pass for personal or unclassified cloud usage
  • approvedGrantScopes published in the org-policy overlay when requiredSources includes granted; POL-X04 evaluates cleanly or surfaces Cloud Grants review items — no silent pass for missing templates
  • Keychain approach documented: PPPC plus consent ledger, or an accepted keychain_metadata coverage gap
  • Approved scan roots listed in the org-policy overlay
  • In-app Sparkle updates disabled on managed endpoints (automatic when org overlay is present)

BeProof disables in-app Sparkle updates when managed mode is active (org-policy overlay present). Promote versions through MDM PKG per pilot ring. Additional provider-specific managed settings paths remain on the product roadmap.

Related