Skip to content

Commit f460839

Browse files
authored
Add a GitHub repository threat model for Ruff (#28395)
Ruff's `AGENTS.md` describes how to review code, but it has no repository threat model for CI and release security reviews. Add the GitHub repository threat model and link it from `AGENTS.md`. It sets out the boundaries for attacker-controlled input, privileged automation, and severity. The Ruff-specific section names pull request benchmark jobs declaring `id-token: write` for CodSpeed and the Docker build declaring `packages: write`. It asks reviewers to check effective authority and artifact flow before reporting a boundary crossing. The generic model is copied from [uv's repository threat model](https://github.com/astral-sh/uv/blob/a7b74d4beda639c0b373456fb93d59fcf1ac98ec/agents/references/repository-threat-model.md).
1 parent d0cf01c commit f460839

2 files changed

Lines changed: 57 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,10 @@ documentation, and architectural conventions in this `AGENTS.md`. Report
2222
meaningful violations introduced by the changes; do not apply agent-only workflow
2323
instructions to PR authors or flag unrelated pre-existing issues.
2424

25+
For security reviews of repository, CI, and release changes, use the
26+
[repository threat model](agents/references/repository-threat-model.md) to assess
27+
trust boundaries and calibrate severity.
28+
2529
## Writing for human readers
2630

2731
Write every mdtest paragraph, code comment, piece of documentation, PR description, and GitHub issue for its eventual reader, not for the current Codex conversation. Determine the reader's knowledge, purpose, and likely questions privately; do not add an audience-analysis section to the artifact.
Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# GitHub repository threat model
2+
3+
## Overview
4+
5+
The GitHub repository holds source code, build and release workflows, and maintainer automation.
6+
7+
The repository-specific section below may add or override trust assumptions and boundaries. When it
8+
differs from a generic section, the repository-specific rule takes precedence for that repository.
9+
10+
A behavior is a security issue only when an independent attacker controls a concrete input,
11+
repository automation uses that input to cross a boundary defined below, and the crossing grants new
12+
power (such as repository write access), exposes publishing credentials or OpenID Connect (OIDC)
13+
tokens, compromises source history or release artifacts, or harms downstream users. Trusted-source
14+
compromise, intended behavior, and correctness defects that give an attacker no new power are not
15+
security issues.
16+
17+
## Trust boundaries and assumptions
18+
19+
Maintainers, their workflow dispatch inputs, reviewed changes, protected refs, repository settings,
20+
configured runners and environments, and explicitly trusted third-party actions are trusted. Changes
21+
from an untrusted contributor remain untrusted when a privileged workflow runs them before review.
22+
23+
First-party repositories used by automation are trusted sources when their relevant branches and
24+
workflow dispatches are restricted to trusted maintainers.
25+
26+
## CI and releases
27+
28+
Privileged workflows do not execute attacker-controlled code or promote attacker-controlled
29+
artifacts before review or explicit authorization. Untrusted code or refs must not run with
30+
privileged permissions or influence artifacts or other output consumed by a privileged step. The
31+
boundary is crossed when this gives the attacker a specific credential, permission, or privileged
32+
action that causes harm. The boundary depends on what starts each workflow, which code and artifacts
33+
each job accepts, and which permissions, credentials, and runners those jobs receive. Unpinned
34+
dependencies, mutable inputs, secret-shaped strings, and broad permissions do not cross it by
35+
themselves.
36+
37+
## Repository-specific additions
38+
39+
## Severity calibration
40+
41+
- **Critical:** With few prerequisites and safe defaults, a remote attacker or actor at a lower
42+
privilege level compromises releases or broad credentials without first compromising a declared
43+
trust root.
44+
- **High:** A complete, demonstrated path from independent attacker input crosses a stated integrity
45+
or privilege boundary, grants material new power, and causes substantial confidentiality or
46+
integrity harm. It cannot depend on a trusted maintainer selecting malicious input, trust-root
47+
compromise, or power the attacker already has. For example, a scheduled workflow automatically
48+
runs mutable third-party code with repository-write, publishing, or equivalent credentials.
49+
- **Medium:** A real but limited boundary crossing, an uncommon realistic setup, or limited
50+
credential or filesystem effect.
51+
- **Low:** A narrow safety gap, limited disclosure, or a robustness problem across a real but weak
52+
boundary.
53+
- **Informational:** A genuine **security** concern with no or negligible current impact.

0 commit comments

Comments
 (0)