# Security Policy

`mgf-common` is the cornerstone library for the MGF project family.
A vulnerability here may affect every consumer that depends on it,
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**, 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.15.x`         | ✅ — latest MINOR; security patches ship as `0.15.Y` |
| `0.13.x`–`0.14.x` | ❌ — superseded; upgrade to `0.15.x` |
| `< 0.13`         | ❌ — pre-CHANGELOG; upgrade to `0.15.x` |

When a security fix lands, the [`CHANGELOG.md`](CHANGELOG.md)
entry for the fixing release names the affected versions and
the upgrade path. The 0.x policy exists to make API churn
possible while early consumers shape the surface (see
[`docs/internal/EXTRACTION_HISTORY.md`](docs/internal/EXTRACTION_HISTORY.md)
§8.5). Once v1.0 is released, supported-version policy will
move to "the two most recent MINOR releases."

## 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.alsanie@gmail.com` with subject prefix
  `[mgf-common security]`.
- **Codeberg private security advisory:** open a private
  vulnerability report via
  [the repository's Security tab](https://codeberg.org/magogi-admin/mgf_common/security)
  (Settings → Security → Report a vulnerability).

### What to include

- A description of the vulnerability and its impact.
- Steps to reproduce — a minimal failing test or shell transcript
  is ideal.
- The version(s) of `mgf-common` affected.
- The Python version, OS, and any optional extras (`[observability]`)
  involved.
- 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**, extendable by mutual
agreement if a patch is not yet ready. After the embargo expires
(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.

For vulnerabilities with severity ≥ medium, we file a
[GitHub-format security advisory](https://codeberg.org/magogi-admin/mgf_common/security)
and request a CVE so PyPI auto-yanks affected versions.

## Scope

**In scope:**

- Code in `src/mgf/common/` (the published `mgf-common` package).
- Documentation that prescribes a security-relevant pattern (the
  [`docs/standards/SECURITY_STANDARD.md`](docs/standards/SECURITY_STANDARD.md)
  standard itself, and the security-relevant rules in the other
  standards docs).
- Build / release infrastructure (`.woodpecker.yml`, the
  manual-twine-upload workflow specified in
  [`docs/standards/RELEASING.md`](docs/standards/RELEASING.md)).

**Out of scope:**

- Vulnerabilities in transitive dependencies (`pydantic`,
  `pyyaml`, `opentelemetry-*`, `sentry-sdk`) — please report to the
  upstream project. We will bump our pinned version as soon as a
  patched release is available.
- Vulnerabilities in the [VManager](https://codeberg.org/magogi-admin/VManager)
  reference consumer that do not stem from `mgf-common` code —
  please report there.
- Self-inflicted DoS (running with `--no-verify` style operator
  flags or with vault disabled).
- Issues requiring physical access to a user's machine.
- Issues requiring an attacker who already has root on the host.

## Hardening recommendations for consumers

Consumers of `mgf-common` adopt the
[`docs/standards/SECURITY_STANDARD.md`](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.

## A note on the standards

The [`docs/standards/`](docs/standards/) folder is the
**cross-project engineering security standard**. This file you are
reading is the **vulnerability-reporting policy** for the
`mgf-common` package itself. Both documents are part of the SC-12
contract — every MGF-family project ships both.
