Declared
Configured agent surfaces, instruction files, MCP config, project roots, and install signals.
Documentation · Policy Pack
BeProof Policy Pack v1.2.2
A versioned set of AI governance rules used by BeProof to evaluate declared tools, granted access, observed usage, MCP risk, audit completeness, privacy consent, and evidence trust.
What This Pack Decides
Policy Pack v1.2.2 defines whether each rule is Active, Approved, Exception, Passed, or N/A for a specific audit. It is not the app version; it is the version of the rule catalog used to interpret the evidence in a report.
Granted
Credential references, keychain consent, cloud grants, OAuth/GitHub scopes, and grant edges.
Observed
Local/cloud usage events, runtime signals, observed undeclared activity, and correlations.
MCP Risk
Local command execution, network access, environment credentials, and first-seen server review.
Audit Quality
Coverage gaps, audit freshness, exportability, evidence integrity, and trust controls.
Outcome Statuses
| Status | Meaning |
|---|---|
| Active | Requires action: remediation, policy decision, or documented exception. |
| Approved | Visible and allowed by policy allowlist with a review reference. |
| Exception | Temporarily accepted by a time-bounded exception. |
| Passed | Evaluated successfully for the current dataset. |
| N/A | Not applicable to the current dataset, audit mode, or unavailable connector context. |
Baseline Rules
The baseline 20 rules are the core macOS audit checks. Missing required data must surface as a coverage gap or N/A decision, not as a silent pass.
| Rule | Policy | Layer | Severity | Signal | State | Notes |
|---|---|---|---|---|---|---|
| POL-D01 | Every endpoint with AI tools must have a declared surface inventory scope | Declared | Medium | `surfacesCount`, `AgentInventorySnapshot`, `scan_scope` gaps | Auto-evaluable | Missing or unreadable scope is a coverage gap, not a clean pass. |
| POL-D02 | Active Codex automations must appear in inventory | Declared | High | `SurfaceKind.codexAutomation` + `AgentOperationalStatus.active` | Auto-evaluable | Confirms active automations are inventoried. |
| POL-D03 | Agent surfaces in vendor/build paths require exception | Declared | Medium | Paths under `.build/`, `DerivedData`, `node_modules`, `SourcePackages/checkouts` | Auto-evaluable | Use allowlist or move config into project source. |
| POL-D04 | MCP config must live under an approved project root | Declared | High | `SurfaceKind.mcpConfig`, finding evidence refs | Conditional | Evaluates when approved scan roots are configured. |
| POL-G01 | AI provider credentials must be inventory-visible for review | Granted | Medium | `CredentialRef.provider` for OpenAI, Anthropic, Cursor | Auto-evaluable | Metadata only; raw secrets are not stored. |
| POL-G02 | Keychain scan only with explicit user consent | Granted | Low | `CoverageGap(keychain_metadata)`, `ConsentRecord` ledger | Auto-evaluable | Consent is persisted in `.beproof/consent-records.json`. |
| POL-G03 | Cloud grants enumerated for org AI accounts where applicable | Granted | Medium | `cloudGrantsCount`, `CloudGrant.provider` | Auto-evaluable | N/A or explicit coverage gap when org tokens are absent. |
| POL-G04 | Duplicate credential refs require justification | Granted | Low | Multiple `CredentialRef` entries per provider | Partial | Rule engine flags duplicates; review expected duplication patterns. |
| POL-O01 | Declared automations should have observed usage or an explicit gap | Observed | Medium | `ObservedUsageSignal.unusedConfigured`, `.noUsageData` | Auto-evaluable | Helps separate configured-but-unused from missing telemetry. |
| POL-O02 | Audit incomplete if declared data exists but no usage layer | Observed | High | `usageEventsCount == 0` with declared surfaces | Auto-evaluable | Prevents false clean results without observed evidence. |
| POL-O03 | Org with cloud AI contracts should load cloud usage | Observed | Medium | `cloudUsageCount == 0` when tokens are available | Auto-evaluable | N/A or explicit coverage gap when connector context is missing. |
| POL-O04 | Local and cloud usage should be correlated when both exist | Observed | Low | `correlationsCount`, min confidence policy | Auto-evaluable | Uses allowlist correlation threshold, default 0.65. |
| POL-O05 | Paused automation with recent runs requires review | Observed | Medium | `operationalStatus == paused` + observed runs | Partial | Requires human decision when paused automations still have run history. |
| POL-F01 | No unapproved MCP local command execution | MCP Risk | Critical | Finding `category: mcp_local_command` | Auto-evaluable | Review shell/npx execution and approved server list. |
| POL-F02 | No unapproved MCP network endpoints | MCP Risk | High | Finding `category: mcp_network_access` | Auto-evaluable | Confirm endpoint/domain approval. |
| POL-F03 | MCP environment credentials require review | MCP Risk | Medium | Finding `category: mcp_env_credentials` | Auto-evaluable | Verify least privilege and non-committed credential handling. |
| POL-F04 | Open MCP finding older than 30 days escalates | MCP Risk | Medium | `Finding.status == open`, `createdAt` | Auto-evaluable | Resolve, approve, or time-bound exception. |
| POL-M01 | No coverage gaps before treating audit as complete | Audit Quality | High | `coverageGapsCount > 0` | Auto-evaluable | No silent pass: missing evidence blocks audit completeness. |
| POL-M02 | Full audit run at least every N days | Audit Quality | Low | `AuditRunRecord.finishedAt` | Auto-evaluable | Keeps audit history fresh enough for review. |
| POL-M03 | Audit evidence exportable for GRC / sharing | Audit Quality | Low | `AuditReportDocument` JSON/Markdown | Auto-evaluable | Ensures evidence can leave the endpoint in reviewable form. |
POL-X Extension Controls
POL-X controls track shipped and target-state capabilities beyond the baseline 20 rules. Audit-trust controls POL-X11 and POL-X12 are shipped on macOS. POL-X13 release trust is shipped in the public release pipeline; enterprise release controls remain partial — see Trust Center.
| Rule | Control | Layer | State | Notes |
|---|---|---|---|---|
| POL-X01 | Installed agent inventory must include package-manager and extension ecosystems | Declared | Supported | Homebrew Cellar, npm/pnpm global prefixes, VS Code/Cursor/Windsurf extension metadata. |
| POL-X02 | Managed settings and policy overlays must be visible in endpoint inventory | Declared | Supported | ManagedSettingsScanner (Claude managed-settings, org overlay, MDM plist metadata); auto managed mode; export section. |
| POL-X03 | Cloud agent declarations must be represented in declared inventory | Declared | Shipped | Cloud declarations and Local vs Cloud reconciliation are available. |
| POL-X04 | OAuth/GitHub App scopes and permissions must be reviewable as grant edges | Granted | Shipped | GrantEdge storage + GrantScopeTemplateSettings: org overlay templates in managed mode, policy-allowlist in personal mode; POL-X04 fail-closed when granted layer required without templates. |
| POL-X05 | Personal-account usage inside managed/work contexts must be flagged | Granted/Observed | Shipped | ProviderAccountAttributor classifies OpenAI, Anthropic, Cursor, and GitHub; cloud usage carries accountType/workspaceId; managed POL-X05 and Review Queue personal_account_usage. |
| POL-X06 | Observed usage without declared surface must trigger policy review | Observed | Shipped | Unlinked local usage becomes a policy violation. |
| POL-X07 | Managed mode requires runtime telemetry minimum coverage | Observed | Shipped | Managed mode enforces runtime telemetry minimum in policy evaluation. |
| POL-X08 | Correlations below confidence threshold must not clear policy checks | Observed | Shipped | POL-O04 uses configured correlation minimum confidence. |
| POL-X09 | Unknown MCP server first-seen events require review/approval path | MCP Risk | Shipped | Baseline, review queue, expiring exceptions, and policy linkage are available. |
| POL-X10 | Plaintext/cached auth-state risk in agent stores must be reviewable | MCP/Access | Shipped | `env_file` and `mcp_env` credential refs produce reviewable violations. |
| POL-X11 | Exports must include signed integrity manifest | Audit Trust | Shipped | Ed25519 signing (`ed25519-v1`) with Keychain-bound endpoint key; `verify-export-manifest` verifies artifact SHA256, manifest hash, and signature. Legacy `sha256-only` manifests verify artifact hash only. |
| POL-X12 | Local evidence store must provide tamper-evident journal guarantees | Audit Trust | Shipped | 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 | Release artifacts must be attributable via provenance and SBOM | Audit Trust | Partial | Public release pipeline (shipped): signed/notarized macOS DMG + CLI, published checksum, SPDX SBOM, provenance JSON, CI verify-install gate, Sparkle appcast (disabled in managed mode). Enterprise release controls (partial): fleet-wide verify-install attestation, tenant-private artifact mirror, org-enforced release version policy, automated MDM promotion workflow. |
| POL-X14 | Sensitive-source consent and retention policy must be machine-verifiable | Privacy | Shipped | Consent ledger, POL-G02 evaluation, and export consent section are available. |
Evidence Mapping
Rule outcomes are explainable because each violation links back to inventory, access, usage, finding, coverage, or audit-run records.
| Entity | Key fields |
|---|---|
| Finding | `id`, `severity`, `category`, `agentId`, `status`, `summary`, `evidenceRefs`, `createdAt` |
| CoverageGap | `area`, `reason`, `source`, `createdAt` |
| AgentSurface | `path`, `kind`, `lastModified` |
| CredentialRef | `provider`, `storageType`, `locator`, `fingerprint`, `source` |
| CloudAgentSurface | `provider`, `accountType`, `workspaceId`, `kind`, `coverageStatus`, `grantEdges` |
| UsageEvent | `source`, `provider`, `agentId`, `eventType`, `count`, `timestamp`, `accountType`, `workspaceId` |
| ReviewQueueItem | `kind` (includes `personal_account_usage` for POL-X05), `ruleId`, `subjectId`, `severity`, `status` |
| RuntimeSignal | `source`, `vendor`, `agentSurfaceId`, `timestamp`, `confidence`, `privacyClass`, `consentRecordId` |
| CorrelationEdge | `leftEventId`, `rightEventId`, `confidence`, `reason` |
| AuditRunRecord | `runId`, `mode`, `scanRoot`, `startedAt`, `finishedAt`, policy summary counts |
Version Notes
- Policy Pack v1.2.2 is aligned with contract v0.1.12.
- Baseline rules cover Declared, Granted, Observed, MCP Risk, and Audit Quality layers.
- POL-X11 and POL-X12 audit-trust controls are shipped on macOS. POL-X13 public release pipeline (signed/notarized DMG, SBOM, provenance, verify-install) is shipped; enterprise release controls remain partial.
- Full source documentation lives in
docs/POLICY_PACK_v1.mdin the BeProof repository.