# Security Policy

`mgf-tele-teltonika` is a federation sibling of [`mgf-common`](https://pypi.org/project/mgf-common/),
shipping a Teltonika Codec 8 / 8 Extended decoder and a
`TelematicsProvider` implementation built on `mgf-tele-core`. A
vulnerability here may affect every consumer that ingests
Teltonika device traffic through this library, 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.

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

## Reporting a vulnerability

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

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

### What to include

- A description of the vulnerability and its impact.
- Steps to reproduce — a minimal failing test is ideal.
  For decoder issues, the exact wire bytes that triggered the
  malformed-frame / CRC / overflow condition matter.
- The version(s) of `mgf-tele-teltonika`, `mgf-tele-core`, and
  `mgf-common` affected.
- Python version + OS.

### 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 |

90-day default embargo. After expiry (or after a patch ships),
the vulnerability is disclosed in the [`CHANGELOG.md`](CHANGELOG.md)
entry for the fixing release.

## Scope

**In scope:**

- Code in `src/mgf/tele/teltonika/` (the published
  `mgf-tele-teltonika` package). Specifically: the AVL decoders
  (`decode_avl_packet` / `decode_codec8` / `decode_codec8e`) and
  the `TeltonikaProvider` session lifecycle — the unauthenticated
  ingest socket is the load-bearing security boundary. The 64 KiB
  frame cap (SH-04) bounds the socket against a hostile
  `data_field_length`.
- Build / release infrastructure (`pyproject.toml`, the manual
  release flow specified in
  [`mgf-standard/docs/standards/RELEASING.md`](https://codeberg.org/magogi-admin/mgf_common/src/branch/main/docs/standards/RELEASING.md)).

**Out of scope:**

- Vulnerabilities in `mgf-tele-core` itself — report to
  [`mgf-tele-core/SECURITY.md`](https://codeberg.org/magogi-admin/mgf-tele-core/src/branch/main/SECURITY.md).
- Vulnerabilities in `mgf-common` itself — report to
  [`mgf-common/SECURITY.md`](https://codeberg.org/magogi-admin/mgf_common/src/branch/main/SECURITY.md).
- Teltonika device-firmware vulnerabilities or misconfiguration
  on the device / network side — that's deployment hardening,
  not library scope.

## Hardening recommendations for consumers

Consumers of `mgf-tele-teltonika` adopt the
[`mgf-standard/docs/standards/SECURITY_STANDARD.md`](https://codeberg.org/magogi-admin/mgf_common/src/branch/main/docs/standards/SECURITY_STANDARD.md)
engineering standard as their baseline.

Particular attention paid to:
- **IMEI authorisation on every session.** The provider's
  `imei_authoriser` hook is necessary but not sufficient — wire
  it to a real registry lookup so an unknown tracker is rejected
  at handshake. Treat the ingest socket as fully untrusted until
  the IMEI handshake completes.
- **Frame-size bounds.** Do NOT raise the 64 KiB frame cap
  (SH-04) without a clear reason — it is the defence against a
  hostile `data_field_length` exhausting memory on the
  unauthenticated socket.
- **Typed error handling.** Every malformed-frame / CRC /
  unsupported-codec / handshake / unknown-tracker / peer-close
  condition surfaces as a typed `mgf.tele.core.TelematicsError`
  subclass (rule EH-02). Catch the seam type, not bare
  `Exception`, so a hostile frame can never be mistaken for an
  internal bug.

## A note on the standards

`mgf-tele-teltonika` is a **federation sibling** under the
project-shape taxonomy from
[`mgf-standard/docs/standards/DOCUMENTATION.md`](https://codeberg.org/magogi-admin/mgf_common/src/branch/main/docs/standards/DOCUMENTATION.md) §2.0.
The cross-project engineering standards live in `mgf-common`;
this project inherits them. See
[`docs/standards/README.md`](docs/standards/README.md) for the
pointer.
