diff --git a/changelog.d/added-501-copilot-permissions-comparison.md b/changelog.d/added-501-copilot-permissions-comparison.md new file mode 100644 index 00000000..ac672b41 --- /dev/null +++ b/changelog.d/added-501-copilot-permissions-comparison.md @@ -0,0 +1,3 @@ +- The Hive trust levels vs Copilot assisted permissions page is now mirrored at + `/docs/hive/copilot-permissions-comparison` and listed in the Security + sidebar (hivecommons/docs#501). diff --git a/docs/content/hive/copilot-permissions-comparison.md b/docs/content/hive/copilot-permissions-comparison.md new file mode 100644 index 00000000..5b3ebecd --- /dev/null +++ b/docs/content/hive/copilot-permissions-comparison.md @@ -0,0 +1,134 @@ +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/src/docs/copilot-permissions-comparison.md) during the docs build. Edit the canonical source in the Hive repository. + +# Hive trust levels vs GitHub Copilot assisted permissions + +Last reviewed: 2026-10-27 + +GitHub made Copilot "assisted permissions" generally available on 2026-10-26. +This page says what that feature is, what Hive does in the same space, and +where each does something the other does not. It is a comparison, not a +ranking. The two tools answer different questions. + +## What Copilot assisted permissions is + +Source: the GitHub changelog entry of 2026-10-26, +, +and the docs page it links, +. + +- It is a permission mode for one Copilot session in Copilot CLI, the Copilot + app, and VS Code. The three modes are manual approval, assisted, and + unconditional approval (`--allow-all` / `--yolo`). +- When Copilot wants to run a shell command, touch a file path, or open a URL, + a second language model looks at the request. If that model is confident the + action is safe, the action runs with no prompt. If not, the user is asked. +- In non-interactive runs (`copilot -p ... --assisted-approval`, or + `COPILOT_ASSISTED_APPROVAL=true` in CI), there is nobody to ask, so anything + the review model will not clear is denied and the reason is handed back to + Copilot so it can try another route. +- Existing allow and deny rules run first. Enterprise deny rules still apply. + Enterprise admins can block the unconditional mode while leaving assisted + on, disable assisted on its own, and set the default mode for new sessions. +- GitHub's own docs say it "is not a substitute for sandboxing or access + restrictions" and that the review model "can make mistakes and approve + dangerous or unintended actions". + +In short: it decides, per action, inside one developer's session, whether to +show a prompt. It does not know about pull requests, merges, or repositories. + +## What Hive does + +Hive runs fleets of agents against repositories without a person at the +keyboard. Its controls are about what reaches GitHub, not about prompts. + +- **Trust levels (ACMM L1-L6).** The level decides which agents run and in + which policy mode. Advisory agents write nothing to GitHub. Measured agents + may open issues. Hold-gated agents may open PRs, and every PR carries a + `hold` label a human must remove. Full agents may merge on green CI. L1 and + L2 are advisory, L3 and L4 add issues and hold-gated PRs, L5 opens PRs under + `hold`, and only L6 merges. See [ACMM policy matrix](/docs/hive/acmm-policy-matrix). +- **Lanes.** Each piece of work is assigned to a lane, the agent that owns it + (scanner, reviewer, ci-maintainer, and so on). GitHub writes are allowlisted + per lane in `write_surface.allowlist`, and a lane can be listed in + `write_surface.enforce`. See [GitHub write surface](https://github.com/hivecommons/hive/blob/v5/src/docs/github-write-surface.md). +- **The policy proxy.** Every agent's GitHub traffic passes through a + man-in-the-middle proxy (`pkg/proxy`). For an enforced lane it refuses every + REST `POST`, `PUT`, `PATCH`, `DELETE`, every GraphQL mutation, and `git push`, + returns `403`, and writes an `agent_write_refused` audit entry. Reads and + the hive's own relays keep working. The proxy also applies repo pause, agent + repo scope, the auto-merge policy, and the ACMM mode gate. The refusals are + counted. Read on 2026-10-27 from `GET /api/evidence/write-counters` on the + three hosted hives (hivecommons, hivecommons, projectbluefin), since the + counter started on 2026-10-12: 538 direct agent write attempts, 123 refused, + all with reason `mode_denied`. Hub admins see the same counters pooled in + `GET /api/hub/evidence` (`write_counters[]` with `block_rate`). +- **Review gates.** `bin/merge-gate.sh` is deterministic: required CI green, + not a draft, no `hold`, and an approved review for community PRs. The + reviewer swarm adds verdicts after the change; `review.require_approval` + makes a same-head approval required at L6. See [review swarm](https://github.com/hivecommons/hive/blob/v5/src/docs/review-swarm.md) + and [running at level 6](/docs/hive/running-at-level-6). +- **Hold and approval.** Below L6 every agent PR gets `hold`; a human removes + it. `needs-human` parks a PR for a person. At L6 a `reject` or + `changes_requested` verdict still needs a fix or a human merge. See + [labels and control signals](/docs/hive/labels-and-control-signals). +- **Shadow gates.** `governor.review_gate.mode: shadow` (the default) and + `intent.shadow` evaluate a gate and record what it would have held, and never + block. The record is in each evidence bundle under `shadow`. The study that + would turn those records into an accuracy figure is planned and not yet + running ([ablation plan](https://github.com/hivecommons/hive/blob/v5/src/docs/research/ablation-plan-2026-10.md)). Enforcement from + a shadow result is a config switch, not a separate feature. +- **Evidence.** Every mediated merge gets an evidence card; outcomes are + published with n and 95% intervals. See [evidence](https://github.com/hivecommons/hive/blob/v5/src/docs/evidence.md) and + [benchmarks](https://github.com/hivecommons/hive/blob/v5/src/docs/benchmarks/README.md). + +## Comparison + +| Dimension | Copilot assisted permissions | Hive | +|---|---|---| +| Unit of control | One action (command, path, URL) in one session | One GitHub write, one PR, one repository, one lane | +| Who decides | A second model, then the user | Deterministic config: level, lane allowlist, proxy rules, CI, labels | +| Where it runs | Inside the Copilot client | Outside the agent, in the proxy and governor; the agent cannot turn it off | +| Levels | Three modes per session (manual, assisted, allow-all) | Six repository levels, four policy modes per agent | +| Enterprise controls | Block allow-all, disable assisted, set default mode | Hub-managed level, repo pause, per-lane enforce, auto-merge toggle per repo | +| What it protects | The developer's machine and the paths and URLs Copilot touches | The repository's issues, PRs, branches, and merges | +| Unattended runs | Denies what the model will not clear; explanation goes back to the agent | Refuses at the proxy with `403` and a reason; audit entry written | +| Merge authority | None; Copilot has no view of merges | Only at L6, only on green CI, only in eligible lanes | +| Human approval step | A prompt per uncleared action | `hold` label and `needs-human` per PR; batch review | +| Measurement | None published | Refusal counters per tier, evidence cards, shadow-gate records | +| Model risk | The review model can approve a dangerous action (GitHub's own caveat) | Review verdicts come from models, but every merge still needs deterministic gates | +| Scope of engines | Copilot only | 15 CLIs through Crux, including Copilot CLI | + +## What Copilot does that Hive does not + +- Judge a shell command, file path, or URL before it runs. Hive sandboxes the + agent and limits network egress, but it does not score individual commands. +- Reduce prompts for a developer sitting at a terminal. Hive has no interactive + prompt step; its agents run unattended. +- Enterprise-managed defaults that apply to every developer's local session. +- Ship inside the editor and CLI people already use, with no deployment. + +## What Hive does that Copilot does not + +- Tie autonomy to repository maturity with a level a team can raise or lower. +- Refuse a GitHub write at the network layer so an agent cannot talk its way + past the rule; the proxy is not a model and does not take explanations. +- Separate "may open a PR" from "may merge", and gate the merge on CI and + review, not on a session mode. +- Put a `hold` on every agent PR below L6 so humans review in batches. +- Count refusals and publish merge outcomes with intervals. +- Run many agents from many vendors under one policy. + +## How they fit together + +Copilot CLI is one of the engines Hive drives (`copilot` in Crux +`CLIBackends`). An operator can run Copilot CLI inside Hive with +`--assisted-approval` for the command-level check, and still have every GitHub +write go through Hive's proxy and gates. The two layers do not overlap: one +watches commands, the other watches the repository. + +## What this page does not claim + +Hive has not measured how often Copilot's review model approves a dangerous +action, and GitHub does not publish that figure. The 123 refusals above are +counts from three hives over 15 days, not a rate for anyone else's fleet. +Neither tool stops a determined person with repository write access. diff --git a/docs/content/hive/documentation-map.md b/docs/content/hive/documentation-map.md index 1e41e661..2a9efc38 100644 --- a/docs/content/hive/documentation-map.md +++ b/docs/content/hive/documentation-map.md @@ -218,6 +218,7 @@ Some documents describe planned or design-only work rather than live features. T - [Securing your hive: a first-time operator's guide](/docs/hive/securing-your-hive) — decision-oriented walkthrough of ACMM level, reporter trust, and repo scope: starting postures, the #9758/#9762 real-world walk-through, Q&A, a pre-L6 checklist, and a glossary. - [Security model — agent safety inventory](/docs/hive/security-model) — threat/control/verification table; runtime, context, credential, code-admission, contributor, detection, platform and human-control layers; residual gaps and running-hive audit steps. +- [Hive trust levels vs Copilot assisted permissions](/docs/hive/copilot-permissions-comparison) — GitHub Copilot's assisted permissions (GA 2026-10-26) explained from the changelog and docs, next to Hive's ACMM levels, lanes, policy proxy with measured refusal counts, review gates, hold flow and record-only shadow gates; a dimension-by-dimension table and what each side does that the other does not. - [Compliance controls](https://github.com/hivecommons/hive/blob/v5/src/docs/compliance.md) — the control registry: framework profiles (SOC 2 Type II, FedRAMP Moderate subset, ISO 27001 Annex A) mapping controls to Hive settings, `GET /api/compliance/status` with meets/deviates/off/not_covered per control, the generated per-framework mapping tables, posture checks, exports and attestations as designed, and the gaps Hive does not cover. Not a certification. - [Security threat model](/docs/hive/security-threat-model) — actors, boundaries, layered defenses, known gaps, and reporting. - [OSS Scanner threat model](https://github.com/hivecommons/hive/blob/v5/.oss-scanner/threat_model.md) — the scanner-facing companion kept at the repository root with [its Dockerfile](https://github.com/hivecommons/hive/blob/v5/.oss-scanner/Dockerfile): where untrusted input enters, which packages matter most, how to exercise a hive offline, and the severity rubric used to triage findings from [Anthropic's OSS Scanner](https://red.anthropic.com/oss-scanner/). diff --git a/docs/content/hive/readme.md b/docs/content/hive/readme.md index 204de76a..1952913d 100644 --- a/docs/content/hive/readme.md +++ b/docs/content/hive/readme.md @@ -52,6 +52,7 @@ Start with [Zero to Automation: Getting Started with Hive](/docs/hive/getting-st or assignment helpers. - [Release channels](/docs/hive/release-channels) — what `stable`, `candidate`, and `edge` each mean and what to expect from them. - [Security model](/docs/hive/security-model) — agent safety control inventory, threats, enforcement modes, residual gaps and operator audit checklist. +- [Hive trust levels vs Copilot assisted permissions](/docs/hive/copilot-permissions-comparison) — what GitHub's per-action permission mode (GA 2026-10-26) does, what Hive's levels, lanes, proxy and gates do, and where each covers ground the other does not. - Security docs rule: `SECURITY.md` and every `src/docs/security*.md` / `ioscan*.md` page, plus `landscape.md`, must score Flesch-Kincaid grade 11 or lower (CI: `src/scripts/check-security-docs-readability.sh`). - Security docs rot rule: the same pages carry a `Last reviewed: YYYY-MM-DD` line in their first 15 lines, no older than 120 days, and may not say an item is "tracked in" / "in progress" / "planned" against an issue that is already closed (CI: `src/scripts/check-security-docs-rot.sh`). - [Data collection and telemetry](https://github.com/hivecommons/hive/blob/v5/src/docs/telemetry.md) diff --git a/scripts/sync-hive-docs.ts b/scripts/sync-hive-docs.ts index 4d10c432..e904b4aa 100644 --- a/scripts/sync-hive-docs.ts +++ b/scripts/sync-hive-docs.ts @@ -59,6 +59,7 @@ const files: Array<{ source: string; target?: string; route?: string }> = [ { source: "integrations/clanker-flue.md" }, { source: "integrations/spektacular.md" }, { source: "public-knowledge-mcp.md" }, + { source: "copilot-permissions-comparison.md" }, { source: "adr/README.md", target: "adr/readme.md" }, { source: "adr/0001-record-architecture-decisions.md" }, { source: "adr/0002-mitm-proxy-network-enforcement.md" }, diff --git a/src/app/docs/page-map.ts b/src/app/docs/page-map.ts index da54766a..57baef19 100644 --- a/src/app/docs/page-map.ts +++ b/src/app/docs/page-map.ts @@ -153,6 +153,7 @@ const NAV_STRUCTURE_HIVE: Array<{ title: string; items: NavItem[] }> = [ { 'Securing your hive': 'securing-your-hive.md' }, { 'Security model': 'security-model.md' }, { 'Security threat model': 'security-threat-model.md' }, + { 'Hive trust levels vs Copilot assisted permissions': 'copilot-permissions-comparison.md' }, { 'ACMM policy matrix': 'acmm-policy-matrix.md' }, ] },