Improve the threat model docs

[spoorcc]

Summary by CodeRabbit

• Documentation

  • Expanded supply-chain and runtime usage threat-model docs with new top-level headings, detailed dataflows/tables, actor/boundary clarifications, updated assets/controls/gaps, and embedded data-flow and sequence diagrams covering contribution, CI/build/fetch, publish/download, integrity-hash handling, attestations, patching, and vendor-copying steps.

• New Features

  • Threat-model report output now includes rendered, embedded data-flow and sequence diagrams.

• Chores

  • CLI permissions allowlist expanded to permit additional security-related commands.

[coderabbitai]

Warning

Rate limit exceeded

@spoorcc has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 34 minutes and 55 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 379cc691-6a09-4713-a036-e6f7fc8a0d06

📥 Commits

Reviewing files that changed from the base of the PR and between 9a74d16 and ffb0e5f.

📒 Files selected for processing (6)

• .claude/settings.json
• doc/explanation/threat_model_supply_chain.rst
• doc/explanation/threat_model_usage.rst
• security/tm_common.py
• security/tm_supply_chain.py
• security/tm_usage.py

Walkthrough

Adds diagram rendering helpers to threat-model reporting, extends supply-chain and usage models to return and connect additional actors/processes/datastores via new completion flows, inserts generated DFD/sequence sections into RST docs, and updates the CLI allowlist to run the new modules.

Changes

Threat-Model Diagram Rendering and Documentation

Layer / File(s)	Summary
Diagram rendering helpers and report integration security/tm_common.py	Adds _fix_pytm_dot_output(), _render_dfd_section(), _render_seq_section(), and updates run_model --report output to include title, report body, DFD, and sequence sections.
Supply-chain model: return elements and completion flows security/tm_supply_chain.py	Builders now return actors/processes/datastores; adds discrete flow constructors (checkout, cache restore/write, build, publish, consumer install) and an orchestrator _make_sc_elements_and_flows; updates asset IDs and control mappings.
Usage model: return elements and completion flows security/tm_usage.py	Builders now return upstream attestation and integrity-hash record datastores; adds integrity, gap-documentation, and cache-copy flows (DF-18..DF-22) and centralizes assembly in _make_usage_elements_and_flows() used by build_model().
Generated documentation (supply-chain) doc/explanation/threat_model_supply_chain.rst	Adds top-level title and inserts generated Data Flow Diagram and Sequence Diagram sections (DOT and PlantUML) and rebuilds the Dataflows table to DF-11..DF-26; updates actors, boundaries, assets, controls, and gap descriptions.
Generated documentation (usage) doc/explanation/threat_model_usage.rst	Adds top-level title and inserts generated Data Flow Diagram and Sequence Diagram sections (DOT and PlantUML) covering integrity-hash flows, upstream VSA publication (gap), patch authoring, and cache-copy to vendor dir.
CLI command allowlist .claude/settings.json	Adds Bash(python -m security.tm_supply_chain:*) and Bash(python -m security.tm_usage:*) to permissions.allow.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• dfetch-org/dfetch#1182: Earlier integration of pytm-based threat models that modified the same security/tm_* modules.

Suggested labels

documentation, enhancement

Suggested reviewers

• ben-edna

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title 'Improve the threat model docs' is vague and generic, using non-descriptive language that doesn't convey what specific improvements were made to the documentation.	Use a more specific title that describes the main improvement, such as 'Add threat model diagrams and dataflow visualizations' or 'Enhance threat model documentation with DFD and sequence diagrams'.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	Docstring coverage is 97.06% which is sufficient. The required threshold is 80.00%.
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 unit tests (beta)

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

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

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.}

[coderabbitai]

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@doc/explanation/threat_model_supply_chain.rst`:
- Line 300: The generated RST contains hardcoded absolute image paths coming
from pytm's diagram output called via run_model() in security/tm_supply_chain.py
and security/tm_usage.py; fix by post-processing the generated RST in the code
path that writes the diagrams (the run_model() caller) to replace absolute
site-package image paths (e.g., "/home/dev/.local/.../pytm/images/*.png") with
portable references (relative paths or data URIs), or add a small monkey-patch
in the module that invokes pytm to override pytm's image path generation before
run_model() is called so the produced DOT/RST uses relative names; ensure the
replacement runs for all occurrences (threat_model_supply_chain.rst and
threat_model_usage.rst) after diagram generation.

In `@doc/explanation/threat_model_usage.rst`:
- Around line 425-557: The DOT output embeds non-portable absolute image paths
for nodes (e.g., datastore_AdfetchManifest_9345ab4c19,
datastore_AFetchedSourceCode_86e4604564,
datastore_AIntegrityHashRecord_b2e5892d06,
datastore_ASBOMOutputCycloneDX_990b886585,
process_SVNExportsvnexport_7eb89910ee, datastore_ALocalVCSCachetemp_ae6e32d09a,
datastore_AAuditCheckReports_d0c0ca0a3b,
externalentity_ARemoteVCSServer_d2006ce1bb), which breaks rendering off your
machine; update the diagram renderer that emits these nodes so it uses portable
Graphviz-native shapes (e.g., cylinder, box, none) or repo-relative/static asset
URLs instead of absolute filesystem paths, then regenerate the DOT output to
remove the /home/.../pytm/images/... references and verify the nodes above now
use the portable styling.

In `@security/tm_common.py`:
- Line 316: The current indentation code assigns indented = "\n".join("   " +
line for line in wrapped.splitlines()), which prepends spaces to blank lines;
update the generator used to build indented (and the similar assignment at the
other occurrence) to only prepend the three-space prefix when the line is not
empty (e.g., use a conditional in the comprehension: prefix + line if line else
"" or check line.strip()), keeping blank lines unindented to avoid trailing
whitespace/linter warnings while preserving existing behavior for non-empty
lines.
- Around line 312-318: The DFD/sequence rendering helpers should avoid emitting
headers and an empty ".. uml::" block when tm.dfd() or tm.seq() returns None or
an empty string; in _render_dfd_section (and likewise in _render_seq_section)
check the output of tm.dfd() / tm.seq() for falsy/whitespace-only content and
return an empty string (or skip rendering) when there's no diagram to display,
otherwise proceed to wrap, indent and return the full section; reference the
functions _render_dfd_section, _render_seq_section and the methods tm.dfd() and
tm.seq() when making the change.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 963f2c4c-7671-4dc3-a9fe-1964ba94a854

📥 Commits

Reviewing files that changed from the base of the PR and between 95ef8d5 and 08fa4e5.

📒 Files selected for processing (4)

• .claude/settings.json
• doc/explanation/threat_model_supply_chain.rst
• doc/explanation/threat_model_usage.rst
• security/tm_common.py

[spoorcc]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@doc/explanation/threat_model_usage.rst`:
- Around line 357-807: The threat_model_usage.rst block is stale: the generated
UML output is missing the injected "skinparam defaultFontSize 16" and the
fullscreen raw-HTML wrapper emitted by security/tm_common.py; fix by
regenerating the usage output with the current renderer (security.tm_usage) so
the DF/Sequence diagram sections include the fullscreen raw-HTML container and
the injected skinparam, or alternatively update the diagram block to match the
output produced by security.tm_common.py (ensure the wrapper and the "skinparam
defaultFontSize 16" appear around the lines corresponding to the DF/Sequence UML
output).

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: b78ea30e-ebb4-47fa-9c24-b97903882fd7

📥 Commits

Reviewing files that changed from the base of the PR and between 8826c7c and 9a74d16.

📒 Files selected for processing (6)

• .claude/settings.json
• doc/explanation/threat_model_supply_chain.rst
• doc/explanation/threat_model_usage.rst
• security/tm_common.py
• security/tm_supply_chain.py
• security/tm_usage.py