# Security Policy

`mgf-test-supervisor` is a federation sibling of [`mgf-common`](https://pypi.org/project/mgf-common/),
shipping a budget-aware, crash-survivable test supervisor that drives
`pytest` from the outside. It is a **development / CI tool** (a dev
dependency, never shipped into a consumer's runtime), but it executes
the consumer's test subprocesses, reads/writes run state under
`.gates/`, and writes diagnostic bundles — so we take security reports
seriously.

## Supported versions

In the 0.x window, **only the latest MINOR receives security
patches.** Per [SemVer 0.x](https://semver.org/#spec-item-4) and
rule **AP-03** from `mgf-standard/docs/standards/API_DESIGN.md`,
each MINOR release MAY break the public API; we do not
branch-and-backport across minors. Security fixes ship as the
next PATCH on the latest MINOR.

| Version | Supported |
|---------|-----------|
| `0.1.x`  | ✅ — latest MINOR; security patches ship as `0.1.Y` |

When a security fix lands, the [`CHANGELOG.md`](CHANGELOG.md)
entry for the fixing release names the affected versions and
the upgrade path.

## Reporting a vulnerability

**Please do not open a public issue or pull request** until we have
had a chance to triage and patch.

To report a vulnerability privately, choose one of:

- **Email:** `bassam@magogi.org` with subject prefix
  `[mgf-test-supervisor security]`.
- **Codeberg private security advisory:** open a private
  vulnerability report via
  [the repository's Security tab](https://codeberg.org/magogi-admin/mgf-test-supervisor/security).

### What to include

- A description of the vulnerability and its impact.
- Steps to reproduce — a minimal failing test or a `run.jsonl` /
  `.gates/` transcript is ideal. For state-file or diagnostic-bundle
  issues, the exact on-disk shape matters.
- The version(s) of `mgf-test-supervisor` affected, plus the Python
  and `pytest` / `pytest-timeout` versions.
- Python version + OS.
- Any suggested mitigations or patches you have in mind.

### What to expect

| Stage | Timeline |
|---|---|
| Acknowledgement | within 3 business days |
| Initial assessment + severity rating | within 7 business days |
| Patch + release | within 30 days for high-severity, 90 days for medium |
| Credit + public disclosure | coordinated with the reporter |

We follow a **90-day default embargo**. After expiry (or after a
patch ships, whichever is first), the vulnerability is disclosed
in the [`CHANGELOG.md`](CHANGELOG.md) entry for the fixing
release, with credit to the reporter unless declined.

## Scope

**In scope:**

- Code in `src/mgf/test_supervisor/` (the published
  `mgf-test-supervisor` package). Specifically: subprocess
  invocation + signal handling (SIGTERM → SIGKILL escalation),
  atomic state writes under `.gates/`, the diagnostic-bundle
  environment fingerprint (must not leak secrets into a `.txt`),
  and JSONL outcome serialization.
- Build / release infrastructure (`pyproject.toml`, the manual
  release flow specified in
  [`mgf-standard/docs/standards/RELEASING.md`](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/RELEASING.md)).

**Out of scope:**

- Vulnerabilities in `mgf-common` itself — report to
  [`mgf-common/SECURITY.md`](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/SECURITY.md).
- Vulnerabilities in `pytest`, `pytest-timeout`, or other tools the
  supervisor invokes / consumers install — report to the upstream
  project.
- Self-inflicted issues: running untrusted test code under the
  supervisor (it faithfully executes whatever `pytest` collects),
  committing `.gates/` to version control against guidance, or
  leaking secrets into test output the diagnostic bundle then
  captures.

## Hardening recommendations for consumers

Consumers of `mgf-test-supervisor` adopt the
[`mgf-standard/docs/standards/SECURITY_STANDARD.md`](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/SECURITY_STANDARD.md)
engineering standard as their baseline. The Rules box at the top
of that document is the bar; the §15 mechanical-enforcement matrix
is the contract for what every consumer's CI should check.

Particular attention paid to:
- **Keep `.gates/` out of version control.** Run state and
  diagnostic bundles may capture environment detail; `.gates/`
  belongs in `.gitignore` (see README §"Adopting in your project").
- **Treat test output as potentially sensitive.** Per-failure
  diagnostic bundles capture pytest stdout/stderr and an environment
  fingerprint — scrub secrets from your test logs upstream.
- **Run the supervisor only over trusted test suites.** It executes
  collected tests as real subprocesses by design.

## A note on the standards

`mgf-test-supervisor` is a **federation sibling** under the
project-shape taxonomy from
[`mgf-standard/docs/standards/DOCUMENTATION.md`](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/DOCUMENTATION.md) §2.0.
The cross-project engineering standards live in `mgf-common`; this
project inherits them. See
[`docs/inprogress/MGF_STANDARDS_CONFORMANCE.md`](docs/inprogress/MGF_STANDARDS_CONFORMANCE.md)
for the declared conformance level + per-rule audit.
