From dc0a149a893f6efe42e9a5f5c40d8586ed5a1b3f Mon Sep 17 00:00:00 2001
From: fullsend-code
 <278716306+fullsend-ai-coder[bot]@users.noreply.github.com>
Date: Mon, 10 Aug 2026 19:12:49 +0000
Subject: [PATCH] docs(#3229): add scripts/ directory threat model guidance to
 AGENTS.md

Add a new "Scripts Directory" section to AGENTS.md documenting
the deployment context, threat model, and review calibration
guidance for the repo-root scripts/ directory. This addresses
repeated false-positive security findings (path injection,
command injection, TOCTOU races) on local-only developer CLI
tools and CI pipeline scripts that were evaluated against
server-side heuristics.

The new section covers:
- Purpose: scripts/ contains developer-facing CLI tools and CI
  pipeline scripts, not deployed application code
- Threat model: all scripts run locally by engineers or in
  trusted CI; operators are trusted users providing intentional
  input
- Contents: categorized table of build infrastructure, coverage
  tooling, developer CLI tools, and CI helpers
- Review calibration: which security findings to downgrade
  (path/command injection, TOCTOU on local tools) vs. which
  remain relevant (correctness, data integrity, CI reliability,
  actual secret exposure)
- Cross-references to complementary open issues #3182
  (upstream/midstream architecture) and #2893 (build
  infrastructure review priorities)

Closes #3229
---
 AGENTS.md | 45 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 45 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index df288d6b5a..b664ecf00a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -101,6 +101,51 @@ git config core.hooksPath .githooks
 
 The hook only triggers when `workspaces/*/e2e-tests/**` files are staged — zero overhead otherwise. It uses the same shared script (`scripts/e2e-code-quality.sh`) as the CI workflow, so checks are always in sync. See `.githooks/README.md` for details on combining with existing hooks.
 
+## Scripts Directory
+
+The repo-root `scripts/` directory contains **developer-facing CLI tools** and **CI pipeline scripts** — not deployed application code. Nothing in `scripts/` runs as part of a user-facing service or is packaged into OCI images.
+
+### Execution Context and Threat Model
+
+Scripts in this directory run in two contexts, both trusted:
+
+1. **Local developer workstations** — CLI tools run manually by engineers on their own git checkouts (e.g., `npx`-invoked TypeScript tools for generating patches).
+2. **CI pipelines** — Automation scripts executed by GitHub Actions workflows in a controlled environment with pre-defined inputs.
+
+In both contexts, the operator is a trusted user providing intentional input (filesystem paths, git refs, workspace names). These scripts are **not** exposed to untrusted network input, user-submitted data, or adversarial callers.
+
+### What lives here
+
+| Category | Examples | Purpose |
+|----------|----------|---------|
+| **Build infrastructure** | `generateCatalogIndex.py`, `generatePluginBuildInfo.py`, `generateDynamicPluginsDefaultYaml.sh` | OCI resolution, metadata sync, DPDY generation |
+| **Coverage tooling** | `upload-coverage.sh`, `seed-main-coverage.sh`, `refresh-coverage-snapshot.sh`, `remap-coverage.cjs` | E2E plugin coverage collection and reporting |
+| **Developer CLI tools** | `scripts/yarnlock-backport/` (when present), `scripts/validate-app-config-examples/` | Local-only tools run via `npx` for specific dev tasks |
+| **CI helpers** | `e2e-code-quality.sh`, `update-index.sh`, `bootstrapPluginBuilds.py` | Workflow support scripts |
+
+### Review Calibration for Security Findings
+
+When reviewing changes to `scripts/`, evaluate security findings against the local-execution and trusted-CI context described above — not against server-side heuristics designed for untrusted-input surfaces.
+
+**Findings that should be downgraded or skipped:**
+
+- **Path injection / path traversal** on CLI tools that accept filesystem paths as operator input. These tools intentionally accept absolute paths (e.g., `--overlay-workspace`, `--plugins-repo`) as designed operator input. Existing guards like `pathUnderBase` provide correctness checks, not adversarial-input defenses.
+- **Command injection** on scripts that construct shell commands from operator-provided arguments (workspace names, git refs). The caller is the engineer or CI pipeline, not an untrusted user.
+- **TOCTOU (time-of-check-time-of-use) races** on local file operations. These tools run single-user on local checkouts; concurrent adversarial modification is not a realistic threat.
+
+**Findings that remain relevant:**
+
+- **Correctness bugs** — Does the tool produce correct output? Are regex capture groups consistent? Does structural refactoring change execution conditions?
+- **Data integrity** — Could a bug silently produce wrong patches, corrupt `yarn.lock`, or generate incorrect metadata?
+- **CI reliability** — Could a failure mode cause silent CI passes or mask real issues?
+- **Actual secret exposure** — Hardcoded credentials, tokens, or API keys (as opposed to path handling patterns).
+
+### Relationship to Other Guidance
+
+This section covers the **deployment context and threat model** dimension for `scripts/`. Related open issues cover complementary dimensions:
+- Issue #3182 — upstream/midstream two-repo architecture (which scripts exist only in the GitLab midstream)
+- Issue #2893 — build infrastructure review priorities (behavioral changes, regex groups, multi-format support)
+
 ## Working with Workspaces
 
 ### Adding a New Workspace