Add threat models to docs

[spoorcc]

Summary by CodeRabbit

• Documentation
  • Added comprehensive threat model documentation covering the full supply-chain lifecycle (code contribution through installation) and post-installation package usage, detailing security assumptions, dataflows, implemented controls, and identified gaps.
  • Updated security documentation with integrated threat model sections and references for enhanced transparency.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: a2df299c-4dce-4270-8da8-20a8c48fe78c

📥 Commits

Reviewing files that changed from the base of the PR and between 0bcacff and a65a19d.

📒 Files selected for processing (8)

• doc/conf.py
• doc/explanation/security.rst
• doc/explanation/threat_model_supply_chain.rst
• doc/explanation/threat_model_usage.rst
• security/README.md
• security/report_template.md
• security/report_template.rst
• security/tm_common.py

💤 Files with no reviewable changes (1)

• security/report_template.md

---

Walkthrough

This PR adds auto-generated threat model documentation for dfetch's supply-chain and runtime usage lifecycles, along with the supporting RST template and rendering infrastructure. Threat model content is generated from Python security modules and integrated into the documentation site via a new section in the main security documentation page.

Changes

Threat Model Documentation & Rendering Pipeline

Layer / File(s)	Summary
RST Template and Rendering Implementation security/report_template.rst, security/tm_common.py	A new reStructuredText template defines the threat model document structure (system description, assumptions, dataflows, data dictionary, actors, boundaries, assets, and excluded threats). The tm_common.py module is refactored to emit RST list-table and definition-list formats instead of HTML/Markdown, with per-control formatting and finding rendering that feeds the template.
Auto-Generated Supply-Chain Threat Model doc/explanation/threat_model_supply_chain.rst, security/README.md	A comprehensive threat model page documenting dfetch's pre-install lifecycle (code contribution through PyPI installation), including assumptions, dataflows (PR submission, CI/build/publish, caching), actors, system boundaries, implemented security controls (OIDC trusted publishing, commit-SHA pinning, Sigstore attestations), and known gaps (build-dependency pinning, SLSA governance, MFA/second-approver). The README is updated with the new RST-based generation command.
Auto-Generated Runtime Usage Threat Model doc/explanation/threat_model_usage.rst	A detailed threat model page for the post-install usage lifecycle, covering manifest reading, VCS/archive fetching, patching, and vendoring. Documents trust boundaries, dataflows for each operation, asset definitions, security mitigations (path traversal prevention, decompression protection, integrity verification, subprocess safety), and remaining gaps (archive hash optionality, VCS integrity, TAR setuid/setgid preservation).
Documentation Integration and Configuration doc/explanation/security.rst, doc/conf.py	The security documentation page is extended with a new "Threat Models" section and toctree linking both auto-generated threat-model pages. Sphinx conf.py is updated with additional autosectionlabel suppression patterns to prevent duplicate-label warnings from the generated pages.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~30 minutes

Possibly related PRs

• dfetch-org/dfetch#1182: Refactors security/tm_common.py rendering from HTML/Markdown to RST list-table and definition-list formatting, directly supporting the threat-model report generation pipeline.
• dfetch-org/dfetch#1181: Modifies doc/explanation/security.rst to initially establish the security documentation page that this PR extends with the new "Threat Models" section.
• dfetch-org/dfetch#1130: Updates Sphinx doc/conf.py to manage autosectionlabel duplicate-label warnings during doc builds, addressing the same configuration area for section collision suppression.

Suggested labels

documentation, development

Suggested reviewers

• ben-edna

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately and concisely describes the main objective of the pull request: adding threat model documentation to the docs folder.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch tm-in-docs

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}