# Security Policy

> **Scope.** This document covers how to report a vulnerability in `mgf-hrb`. For the *design-level* threat model — what `mgf-hrb` is built to withstand, how, and where the boundaries are — see [`hrb-design/mgf-hrb-survivability-review.md`](hrb-design/mgf-hrb-survivability-review.md) (the standalone Part 12 of the complete design). The survivability review establishes the **S1–S5 guarantees** (crash-safety upward · fault-containment downward · tenant isolation · self-fault containment · bounded-everything), the threat model (untrusted clients above, untrusted hardware below, mutually-untrusted concurrent tenants), and the prioritised hardening roadmap.

---

## Reporting a vulnerability

**Do not** file a public issue or open a PR for a suspected vulnerability. Instead:

- **Email**: `bassam@magogi.org` with the subject prefix `[mgf-hrb security]`.
- Include: a description of the issue, the affected component (e.g., `mgf-hrb-core`, `mgf-hrb-cap`, the broker server, the privileged helper), a proof-of-concept where possible, and the impact you observed.
- The maintainer aims to acknowledge within **5 business days** and to land a fix or a documented mitigation within **30 days** for confirmed, exploitable issues. Coordinated disclosure timelines are negotiated case-by-case.

For non-security friction (a design call you'd push back on, a missing primitive, an awkward contract), file a paper in [`FEEDBACK.md`](FEEDBACK.md) — that is the public, designed-for-friction channel.

---

## Security model — read these first

| You want to understand… | Read |
|---|---|
| The full threat model, S1–S5 guarantees, and adversarial review | [`hrb-design/mgf-hrb-survivability-review.md`](hrb-design/mgf-hrb-survivability-review.md) |
| The capability spine (unforgeable, attenuable, revocable) | [`hrb-design/mgf-hrb-complete-design.md`](hrb-design/mgf-hrb-complete-design.md) Part 4 |
| Privilege separation (separate helper process per worker — D-031) | [`hrb-design/mgf-hrb-privileged-core-hardening.md`](hrb-design/mgf-hrb-privileged-core-hardening.md) |
| The kabi survivability contract (deadlines, totality, no silent lies, revocability) | [`hrb-code/src/kabi.zig`](hrb-code/src/kabi.zig) header block |

The four load-bearing security primitives the survivability review converges on are: **deadlines** (no downward call hangs the broker), **quarantine** (uncertain hardware never re-granted), **revocation below the fd** (tear down the IOMMU mapping, render delegated access inert), and **the trust gate** (validate every client byte before it becomes a typed request).

---

## In-scope / out-of-scope

**In scope (we want to hear about):**

- Memory-safety bugs in the Zig broker / facade / workers / privileged helper.
- Capability-model bypasses (forgery, confusion, attenuation widening, monotone-shrink violations).
- Trust-gate bypasses on the upward boundary (parser panic, type-confusion crash, oversized-input DoS, slowloris, capability presented over wrong connection).
- Ghost ownership / lease-table inconsistencies (a granted resource the backend doesn't hold, or vice versa).
- Privilege-helper IPC abuses (a compromised unprivileged worker reaching beyond its attenuated authority).
- Cross-tenant isolation breaks (one tenant observing or affecting another's resources beyond policy).
- Shared-memory escapes (the broker reading client-writable shm fields without bounds-checking).
- Use-after-release on raw channels (revocation that doesn't reach below the delegated fd).

**Out of scope:**

- Vulnerabilities in dependencies — report those to the upstream project; if the dependency is a federation sibling (`mgf-common`, `mgf-http`, etc.) report there.
- Microarchitectural side channels (Spectre-class, power, EM) — see Part 12 §1.3 of the survivability review. We address only the cases where `mgf-hrb`'s own design widens them (e.g., per-tenant private shared-memory regions, per Stage 5.5).
- Issues that require pre-existing root or `cap_sys_admin` on the host — those are upstream-kernel concerns; the broker assumes a trusted-enough kernel per Part 12 §1.3.

---

## Cross-references

- `mgf-common` security standards: `mgf-common standards security` (or `mgf-common standards SECURITY_STANDARD`).
- Federation-wide security primitives are reused where they apply to the Python siblings (SDK / policy / tools). The Zig majority is governed by the kabi survivability contract and the design's priority order.
