threat-model-surface

Threat Model — Surface (deep pass on the in-scope surface)

Phase 3.3. The orient pass was minutes; this is hours, and that is expected. Three of the output's most valuable artifacts cannot be produced any other way:

• the per-input-operand trust table (§1.7), which requires reading each in-scope entry point far enough to say which direct parameters and indirect inputs an attacker can reach and what the caller must enforce; and
• the contract-dimension matrix (§1.7-§1.12), which prevents silence about failure behavior, representational limits, executable collaborators, object topology, and lifecycle edge cases from becoming downstream MODEL-GAP findings; and
• the no-surprise side-effects inventory (§1.5) — negative claims about what the project does to its host that cannot be established by reading docs.

Read principles.md and the §1.5 / §1.7 / §1.8 specs in output-structure.md first.

Rules for keeping the cost bounded

• Scope by the recon carve. Read only the entry points of in-model families. Do not read contrib/, examples, or out-of-scope families beyond confirming they are separable.
• Read for contract, not for bugs. At each entry point the question is "which of these parameters can an attacker control, what kind of control is it, and what contract applies at edge conditions?" — not "is this code correct?" Record whether behavior is guaranteed, disclaimed, or unresolved; do not test whether the implementation satisfies it. The moment the reading turns into review, stop and move on.
• Timebox per family. If a family's surface is too large to table in budget (e.g., a service with 100+ routes), table the highest-exposure subset, mark the remainder (inferred, QN) with a coverage note, and raise completing the table as an open question / follow-up — do not silently generalize.
• Record hypotheses as you go, in draft form with provenance tags. Preserve documented provenance for explicit normative public contracts. Code, implementation comments, and tests that merely suggest an unwritten contract remain (inferred, QN) until a maintainer ratifies them.
• Read code as a behavioural oracle, not just as a second-class doc. Mining comments and headers tells you what the project says; it cannot tell you where a guarantee stops. Every security-critical property needs its off-switches found by reading statements: the API call that relaxes a check, the flag that removes one, the mode that trades it for speed. Cite each as <file>:<line> at the statement that implements it. A comment describing the function does not qualify — the check that matters may have no comment at all, which is exactly why comment-harvesting misses it. These are easy to walk past because they are not input operands: no attacker-controlled parameter appears, so an input-shaped reading of the API sees nothing. They are property switches. Grep for names built on validate, undermine, relax, skip, permit, trust, unsafe, strict, and sane, then read what each one assigns.
• Search the whole shipped build, not the files you happen to have open. Scope every switch hunt to the source set the supported build compiles — including the build scripts, which is where platform-conditional and default-on options live. A search restricted to the public header and one implementation file will miss a compile-time switch that replaces an entire function, and it will miss it silently.
• Report a negative as a command plus its result, so the next reader can re-run it in one paste: grep -rn 'PATTERN' <file set> — N hits, all in X. "I searched and found nothing" is not reviewable and has been wrong every time it has been checked.
• Cite harder before tagging inferred. Before marking a row inferred, check the API docs, header comments, Javadoc/package-info, manpage, and README — a fact stated there is (documented, source), not inferred. Turning a false-inferred into a true-documented row is pure accuracy and directly reduces the escalation count.
• Disclaim demonstrably-absent guarantees rather than leaving them open. When the reading shows a family makes no thread-safety, resource-bound, or failure-atomicity guarantee, that absence is verifiable — record the matrix row as disclaimed with (documented, source), routing to §1.12, not as unresolved. Reserve unresolved / inferred for dimensions where a guarantee plausibly exists but you could not confirm it. Where you must reason past the verifiable to a clear safe default, tag (assumption, QN) rather than (inferred, QN).