This tool makes a security-shaped claim, that a report can be trusted without seeing the repository, and it has no threat model document. The pieces are scattered: the adversarial table in the README, the privacy defaults, the canonical-JSON hash, the fingerprint, the note about what leaves the machine. A reader has to assemble the argument themselves, and a reader who does not bother will over-trust the output.
What to write. One document that states, in order: what is being protected, from whom, what the tool guarantees, and what it does not.
It must cover at least:
- The report author, who has every incentive to inflate and full control of the input. This is the main adversary and it should be named as such rather than implied.
- The reader, who cannot see the repository and must decide how much the hash actually buys them.
- What the hash covers and what it deliberately does not, including why the machine's own state was removed in 0.4.0.
- What the fingerprint proves about repository identity and what it does not.
- What
--emails and the privacy defaults protect, and against whom.
- What a rewritten history does to every figure, since that is cheap and undetectable from a report.
- What the narration sends to a model when it is used, in exact terms.
Done when
- The document exists, is linked from the README, and is written so a security reviewer can disagree with it specifically rather than in general.
- Every claim in it points at the code or the test that backs it.
- Where the honest answer is "this does not protect against that", it says so in those words. A threat model that lists only what a tool defeats is a brochure.
Out of scope. A formal proof, a compliance mapping or a certification.
Why it belongs here. Somebody will eventually publish an argument that this tool's reports can be faked. Far better that the clearest statement of what it cannot do is the one we wrote.
Taking this on: comment and it is yours. Nothing here needs permission first, and a partial answer beats a perfect one that never lands.
What gets a pull request rejected here: a change with no test; a new runtime dependency; or a number written into a README or a document that did not come from a run somebody else can repeat.
This tool makes a security-shaped claim, that a report can be trusted without seeing the repository, and it has no threat model document. The pieces are scattered: the adversarial table in the README, the privacy defaults, the canonical-JSON hash, the fingerprint, the note about what leaves the machine. A reader has to assemble the argument themselves, and a reader who does not bother will over-trust the output.
What to write. One document that states, in order: what is being protected, from whom, what the tool guarantees, and what it does not.
It must cover at least:
--emailsand the privacy defaults protect, and against whom.Done when
Out of scope. A formal proof, a compliance mapping or a certification.
Why it belongs here. Somebody will eventually publish an argument that this tool's reports can be faked. Far better that the clearest statement of what it cannot do is the one we wrote.
Taking this on: comment and it is yours. Nothing here needs permission first, and a partial answer beats a perfect one that never lands.
What gets a pull request rejected here: a change with no test; a new runtime dependency; or a number written into a README or a document that did not come from a run somebody else can repeat.