docs: add draft threat model + SECURITY.md/AGENTS.md discoverability

[potiuk]

What this is

A draft threat model for Apache Fory, proposed by the ASF Security team for the Fory PMC to review, correct, or reject. It is a starting point for discussion, not a finished document.

This PR:

• adds THREAT_MODEL.md — the draft model, following the ASF Security threat-model rubric;
• adds SECURITY.md — a short security policy that links the threat model;
• appends a ## Security section to AGENTS.md, so the chain AGENTS.md → SECURITY.md → THREAT_MODEL.md is mechanically discoverable by automated security scanners.

How to read it

Every claim is provenance-tagged: (documented) (from Fory's own docs/repo), (inferred) (reasoned from the architecture, not yet confirmed), (maintainer) (confirmed by the PMC). This v0 is ~20 documented / ~26 inferred. The §14 Open questions section collects every inferred claim into waves for the PMC to confirm or correct — that is where review time is best spent. The highest-impact ones:

• whether "under the default requireClassRegistration(true), only registered types are instantiated from untrusted bytes" is a committed property, and whether findings that require requireClassRegistration(false) are out-of-model / non-default (wave 1);
• per-language memory safety on malformed input — in particular the C++ decoder (wave 2);
• the cross-language (xlang) peer-trust assumption and the resource/DoS line beyond maxDepth (waves 2).

Nothing here is a requirement — the model is for the PMC to own. Comment inline, edit the branch, or reply on the email thread.

AI Usage Disclosure

• Substantial AI assistance: yes.
• What: THREAT_MODEL.md was drafted by the ASF Security team's threat-model tooling (Claude) from Apache Fory's public documentation and repository, following the Scovetta rubric. SECURITY.md and the AGENTS.md Security section are templated scaffolding.
• Review model: the document is deliberately presented as a draft for line-by-line maintainer review — every claim carries a provenance tag, and all unverified (inferred) claims are surfaced as explicit open questions (§14) for the PMC to ratify, correct, or strike. It is not offered as finished or authoritative content.
• Provenance / licensing: content is original to this engagement, carries the ASF license header, and is intended to comply with the ASF Generative Tooling Guidance.

[chaokunyang]

Row Format is out of scope of untrusted data, it must be used with trusted data. In https://github.com/apache/fory/blob/main/docs/security/deserialization.md, we clarify for usage for trusted data only.

[chaokunyang]

We have https://github.com/apache/fory/blob/main/docs/security/deserialization.md now, could the THREAD_MODEL.md be moved into docs/security/threat-model.md ?

[chaokunyang]

Disabling class registration should take arbitrary class/gadget materialization out of the model, but not every security outcome. The current deserialization model still treats runtime safety, disproportionate allocation, cleanup/retained state, and explicit policy bypasses as security boundaries for untrusted bytes. A crash, OOM, retained-state bug, or native memory-safety issue should not become out-of-model only because the reproducer uses registration disabled.

[chaokunyang]

This is stale against the current security doc. docs/security/deserialization.md now draws the resource line: no disproportionate allocation before bytes are supplied or proven readable, no stream buffer growth to attacker-declared sizes before exact read/skip, and proportional checks before collection preallocation. I would replace this open question with a link to that model, otherwise future triage will treat an already-settled rule as undefined.

[chaokunyang]

Since main now has docs/security/, I would avoid making a new top-level threat model the only policy link from SECURITY.md. Root SECURITY.md is the right place for the private reporting channel and GitHub discoverability; the model entry point should be docs/security/index.md, with the detailed deserialization rules under docs/security/deserialization.md. That keeps scanners and humans on one security-doc hierarchy instead of splitting authority between root and docs/security.

[chaokunyang]

@potiuk I think we can remove duplciate/stale content with deserialization.md, then move THREAT_MODEL.md into docs/security//thread-model.md? Will it still work for security scan and discoverability?

[potiuk]

Both changes are fine — go for it.

The scan agent doesn't care where the file physically lives; what it follows is the discoverability chain: AGENTS.md -> SECURITY.md -> the threat model. So moving the file under docs/security/ works as long as the pointer in SECURITY.md is updated to the new path. Since AGENTS.md already lists docs/security/deserialization.md as loadable guidance, adding the threat-model path there too is the natural home for it.

On the dedup: removing content that just restates deserialization.md is good hygiene — that doc can stay the authoritative source for the untrusted-deserialization boundary, and the threat model can reference it rather than duplicate it. The thing to keep in the threat model is the project-level framing the scan needs: what Fory considers in vs. out of scope, the trust boundaries and user roles, and the known false-positives — i.e. the parts deserialization.md doesn't already cover.

One tiny thing: the path you wrote is "thread-model.md" — I'm assuming that's a typo for "threat-model.md". Whatever filename you settle on is fine, just keep SECURITY.md pointing at it.

Happy to update the PR to match once you've decided on the final layout, or you can push directly — either works.