From cc600f29e997ffdc5bace70a4a1814d8a1647f74 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 27 May 2026 05:49:46 +0000 Subject: [PATCH] docs: reframe foreseeable misuse as a priority harms list Replace the loosely-grouped misuse bullets in the security model's IPFRU section with four acknowledged priority harms (credential exfiltration, resource exhaustion, vulnerable-code introduction, file destruction), deferring threats and responses to the threat models. Scope the AGENTS.md changelog guidance to the dfetch product/program so documentation-only changes do not require a changelog entry. https://claude.ai/code/session_019hWsatpqt4FfNA6Vwh2mxk --- AGENTS.md | 4 +++- doc/explanation/security.rst | 37 ++++++++++++++++++------------------ 2 files changed, 22 insertions(+), 19 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 1705fe88a..d4294df35 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -103,9 +103,11 @@ Implement the abstract interfaces in `dfetch/project/subproject.py` and `dfetch/ Every change must be reflected in the documentation. Depending on the nature of the change: - **User-visible behaviour** (new feature, changed CLI, new option) → update the relevant `doc/how-to/` or `doc/reference/` page -- **Notable fix or change** → add an entry to the changelog (`doc/changelog/`) +- **Notable change to the dfetch product/program** (feature, fix, behaviour change) → add an entry to the changelog (`doc/changelog/`) - **Architecture change** → update `doc/explanation/architecture.rst` +The changelog tracks the dfetch product/program only. Documentation-only changes (wording, structure, new explanatory pages) do not require a changelog entry. + Documentation lives in `doc/` and is built with Sphinx. ### Tone of voice diff --git a/doc/explanation/security.rst b/doc/explanation/security.rst index ee3e161dc..ddf542e75 100644 --- a/doc/explanation/security.rst +++ b/doc/explanation/security.rst @@ -83,24 +83,25 @@ up-to-date checks. non-interactively inside CI/CD pipelines (GitHub Actions, GitLab CI, Jenkins, etc.) to reproduce a deterministic dependency state. -*Reasonably foreseeable misuse*: - -- A manifest crafted with a malicious ``dst:`` path could attempt to write - files outside the project root (path traversal). dfetch mitigates this through - `check_no_path_traversal()` applied to all file system write operations. -- A manifest pointing to an attacker-controlled upstream may introduce malicious - source code into the build pipeline. This is a primary supply-chain risk; the - optional `integrity.hash` field can be used as a mitigation for archive-based - sources to provide content integrity validation. -- Execution in CI environments with insufficient network or secret isolation may - allow exfiltration risks if upstream sources are compromised or intentionally - malicious. - -.. note:: - - dfetch warns during dependency update/check operations when a project URL uses a plaintext - transport scheme (``http://``, ``git://``, or ``svn://``). Use ``https://`` - or SSH (e.g. ``svn+ssh://``) to protect dependency fetches against interception. +*Reasonably foreseeable misuse*: the following are the principal harms *dfetch* +aims to protect against. They are acknowledged here as priorities; the specific +threats that realise them and the corresponding responses are modelled in the +threat models below. + +- **Credential and secret exfiltration in CI/CD.** When *dfetch* runs + non-interactively in a pipeline holding registry tokens, signing keys, or cloud + credentials, a compromised or intentionally malicious upstream source could read + and exfiltrate those secrets. +- **Resource exhaustion from hostile archives.** A crafted archive (for example a + decompression bomb) can expand to an extreme size or member count on extraction, + exhausting disk or memory and denying service to the developer or build host. +- **Introduction of vulnerable or malicious code into the superproject.** More + subtle than denial of service: an attacker-controlled upstream may ship source + carrying latent vulnerabilities or backdoors that are vendored into the consuming + project and propagated into downstream products. +- **Destruction or overwrite of files outside the destination folder.** A malicious + manifest destination path, or hostile archive entries, could write, overwrite, or + delete files outside the intended vendoring directory on the end-user machine. Threat Models -------------