Skip to content

Add SECURITY.md - #2

Merged
AlyxSharkBite merged 1 commit into
mainfrom
docs/security-policy
Aug 28, 2026
Merged

AlyxSharkBite merged 1 commit into
mainfrom
docs/security-policy

Conversation

@AlyxSharkBite

Copy link
Copy Markdown
Owner

Closes the OpenSSF Scorecard Security-Policy finding (medium), which scored 0 because no policy file was present.

What it covers

  • Private reporting via GitHub's private vulnerability reporting, which is already enabled on this repo, so the link works today.
  • Response targets — acknowledgement in 3 business days, assessment in 7, fix or mitigation in 30 — stated as honest targets for a spare-time project rather than an SLA, with explicit permission to disclose if they slip.
  • Supported versions — 1.0.x.
  • Threat model — streams reaching Exploder are assumed attacker controlled, since this is the compression used inside MPQ and similar containers. In scope: memory safety, non-termination, any exception other than PkLibException escaping, and incorrect output.

The part worth reading

The format allows a decompression bomb, and that is a property of the format rather than a defect, so it is documented instead of "fixed".

Both figures in the policy were measured against this implementation, not estimated:

Measurement Result
Max expansion ratio 137.6:1, stable from 1 MB to 10 MB of input
Worked example 72,680 compressed bytes to 10,000,000 bytes

The byte[]-returning overloads accumulate the whole result in memory with no size limit, so the policy says plainly not to use them on hostile input, and gives the callback pattern with a caller-enforced cap instead.

I verified that mitigation actually behaves as advertised before documenting it. Throwing from the write callback aborts promptly: with a 1 MB cap against the bomb above, it stopped after 1,003,520 bytes written — within one 4096-byte block of the cap — having read only 8,192 of the 72,680 compressed bytes. It does not finish the work and fail at the end.

Also noted

  • Crc32 is error detection, not a cryptographic hash, and the format has no integrity or authenticity guarantees. Called out explicitly so nobody mistakes it for tamper detection.
  • A flaw in the shared algorithm, as opposed to this C# translation, likely affects upstream PKLib and every other port. Reporters are asked to flag that so it can be coordinated with StormLib.

Note on process

Opened as a PR rather than pushed straight to main, so it goes through the review requirement just configured — and it gives the Scorecard Code-Review check its first approved changeset.

No code changes; documentation only.

Documents the private reporting channel, response targets and supported
versions, and states the threat model explicitly: streams handed to
Exploder are assumed attacker controlled, since this is the compression
used inside MPQ and similar container formats.

Records the one security-relevant limitation of the format. Maximum
expansion measured against this implementation is roughly 137:1, stable
across input sizes, so a 72,680 byte stream expands to 10,000,000 bytes.
The byte[] returning overloads are unbounded; the callback overload with
a caller-enforced cap aborts promptly, after reading only a fraction of
the input rather than completing the work first. Both figures and the
abort behaviour were measured, not estimated.

Also notes that a flaw in the shared algorithm rather than this
translation of it likely affects upstream PKLib and every other port,
and should be flagged as such for coordinated disclosure.

Closes the Scorecard Security-Policy finding.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@AlyxSharkBite
AlyxSharkBite merged commit dd51d80 into main Aug 28, 2026
8 checks passed
@AlyxSharkBite
AlyxSharkBite deleted the docs/security-policy branch August 28, 2026 20:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant