From dcc7892ae96c0b7d907dd99f01ad1af58c1a0d51 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Wed, 18 Nov 2026 10:55:06 +0800 Subject: [PATCH 1/3] ci: require local link-check tools and disable persisted credentials --- .github/workflows/ci.yaml | 10 +++++ scripts/test-safer-defaults.py | 71 ++++++++++++++++++++++++++++++++++ scripts/verify-link-anchors.sh | 20 ++++------ scripts/verify-links.sh | 21 ++++------ 4 files changed, 97 insertions(+), 25 deletions(-) diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index a60a4adbcd141..5f7a9ce036ccb 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -15,6 +15,8 @@ jobs: steps: - name: Check out uses: actions/checkout@v6 + with: + persist-credentials: false - name: Verify duplicated file names run: ./scripts/verify-duplicated-file-name.sh - name: Verify safer defaults @@ -30,6 +32,8 @@ jobs: steps: - name: Check out uses: actions/checkout@v6 + with: + persist-credentials: false - uses: actions/setup-node@v6 with: node-version: "18" @@ -45,6 +49,8 @@ jobs: steps: - name: Check out uses: actions/checkout@v6 + with: + persist-credentials: false - uses: actions/setup-node@v6 with: node-version: "18" @@ -60,6 +66,8 @@ jobs: steps: - name: Check out uses: actions/checkout@v6 + with: + persist-credentials: false - uses: actions/setup-node@v6 with: node-version: "18" @@ -75,6 +83,8 @@ jobs: steps: - name: Checkout uses: actions/checkout@v6 + with: + persist-credentials: false - name: Vale Linter uses: errata-ai/vale-action@518a9136acc6e6668ce7c00d367051e0941e87ff # reviewdog with: diff --git a/scripts/test-safer-defaults.py b/scripts/test-safer-defaults.py index 0caa611176b4e..2f20c01889e5a 100644 --- a/scripts/test-safer-defaults.py +++ b/scripts/test-safer-defaults.py @@ -1,14 +1,28 @@ """Regression checks for repository and documentation defaults.""" import ast +import os from pathlib import Path import re +import shutil +import subprocess +import tempfile ROOT = Path(__file__).resolve().parents[1] ci_workflow = (ROOT / ".github/workflows/ci.yaml").read_text() +assert "on: [pull_request]" in ci_workflow +assert "permissions:\n contents: read\n" in ci_workflow +checkout_steps = re.findall( + r"^ uses: actions/checkout@[^\n]+\n(.*?)(?=^ -|\Z)", + ci_workflow, + re.MULTILINE | re.DOTALL, +) +assert checkout_steps +assert all("persist-credentials: false" in step for step in checkout_steps) + install_commands = [ line.split("#", 1)[0] for line in ci_workflow.splitlines() @@ -21,6 +35,63 @@ ) assert all("--include=dev" in command for command in install_commands) + +# Exercise tool selection in an isolated fixture, without running npm or network calls. +with tempfile.TemporaryDirectory(prefix="docs-tool-check-") as directory: + fixture = Path(directory) / "repo with spaces" + scripts = fixture / "scripts" + scripts.mkdir(parents=True) + local_bin = fixture / "node_modules/.bin" + local_bin.mkdir(parents=True) + (fixture / "test.md").write_text("# Test\n") + (scripts / "markdown-link-check.tpl").write_text("{}\n") + + global_bin = Path(directory) / "bin" + global_bin.mkdir() + forbidden_marker = Path(directory) / "global-tool-ran" + local_marker = Path(directory) / "local-tool-ran" + env = dict(os.environ, PATH=f"{global_bin}{os.pathsep}{os.environ['PATH']}") + env["FORBIDDEN_TOOL_MARKER"] = str(forbidden_marker) + env["LOCAL_TOOL_MARKER"] = str(local_marker) + for binary in ("markdown-link-check", "remark", "npx"): + tool = global_bin / binary + tool.write_text('#!/bin/sh\nprintf ran > "$FORBIDDEN_TOOL_MARKER"\nexit 99\n') + tool.chmod(0o755) + + for filename, binary in ( + ("verify-links.sh", "markdown-link-check"), + ("verify-link-anchors.sh", "remark"), + ): + script = scripts / filename + shutil.copyfile(ROOT / "scripts" / filename, script) + tool = local_bin / binary + + def run_check(): + return subprocess.run( + ["bash", str(script)], cwd=directory, env=env, + capture_output=True, text=True, timeout=30, + ) + + # Neither a missing nor a non-executable local tool may trigger a fallback. + for state in ("missing", "not executable"): + if state == "not executable": + tool.write_text('#!/bin/sh\nexit 0\n') + tool.chmod(0o644) + result = run_check() + assert result.returncode != 0, (filename, state, result) + assert "npm ci --ignore-scripts --include=dev" in result.stderr + assert not forbidden_marker.exists(), (filename, state) + + tool.write_text('#!/bin/sh\nprintf "%s\\n" "$@" > "$LOCAL_TOOL_MARKER"\n') + tool.chmod(0o755) + result = run_check() + assert result.returncode == 0, (filename, result) + assert local_marker.exists(), filename + arguments = local_marker.read_text().splitlines() + assert ("./test.md" if binary == "markdown-link-check" else "--frail") in arguments + assert not forbidden_marker.exists(), filename + local_marker.unlink() + deployment = (ROOT / "check-before-deployment.md").read_text() permission_commands = [ line.strip() diff --git a/scripts/verify-link-anchors.sh b/scripts/verify-link-anchors.sh index 469e68b505ff8..8fee3ebc94c72 100755 --- a/scripts/verify-link-anchors.sh +++ b/scripts/verify-link-anchors.sh @@ -2,21 +2,17 @@ # # In addition to verify-links.sh, this script additionally check anchors. # -# See https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally if you meet permission problems when executing npm install. +# Install the pinned local tools with `npm ci --ignore-scripts --include=dev`. -ROOT=$(unset CDPATH && cd $(dirname "${BASH_SOURCE[0]}")/.. && pwd) -cd $ROOT +ROOT=$(unset CDPATH && cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd) +cd "$ROOT" || exit 1 -REMARK_CMD=() -if [ -x "$ROOT/node_modules/.bin/remark" ]; then - # Prefer the repo-local pinned version (installed by `npm ci`). - REMARK_CMD=("$ROOT/node_modules/.bin/remark") -elif command -v remark >/dev/null 2>&1; then - # Fall back to a globally-installed version (less reproducible). - REMARK_CMD=(remark) -else - REMARK_CMD=(npx --no-install remark) +# Require the repo-local version installed from package-lock.json. +if [ ! -x "$ROOT/node_modules/.bin/remark" ]; then + echo "error: local remark is missing or not executable. Run npm ci --ignore-scripts --include=dev." >&2 + exit 1 fi +REMARK_CMD=("$ROOT/node_modules/.bin/remark") echo "info: checking links anchors under $ROOT directory..." diff --git a/scripts/verify-links.sh b/scripts/verify-links.sh index 1cb3d7b156ac4..db1cabd59f455 100755 --- a/scripts/verify-links.sh +++ b/scripts/verify-links.sh @@ -10,22 +10,17 @@ # - When a file was moved, all other references are required to be updated for now, even if alias are given # - This is recommended because of less redirects and better anchors support. # -# See https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally if you meet permission problems when executing npm install. +# Install the pinned local tools with `npm ci --ignore-scripts --include=dev`. -ROOT=$(unset CDPATH && cd $(dirname "${BASH_SOURCE[0]}")/.. && pwd) -cd $ROOT +ROOT=$(unset CDPATH && cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd) +cd "$ROOT" || exit 1 -MLC_CMD=() -if [ -x "$ROOT/node_modules/.bin/markdown-link-check" ]; then - # Prefer the repo-local pinned version (installed by `npm ci`). - MLC_CMD=("$ROOT/node_modules/.bin/markdown-link-check") -elif command -v markdown-link-check >/dev/null 2>&1; then - # Fall back to a globally-installed version (less reproducible). - MLC_CMD=(markdown-link-check) -else - # As a last resort, rely on `npx` without installing. - MLC_CMD=(npx --no-install markdown-link-check) +# Require the repo-local version installed from package-lock.json. +if [ ! -x "$ROOT/node_modules/.bin/markdown-link-check" ]; then + echo "error: local markdown-link-check is missing or not executable. Run npm ci --ignore-scripts --include=dev." >&2 + exit 1 fi +MLC_CMD=("$ROOT/node_modules/.bin/markdown-link-check") VERBOSE=${VERBOSE:-} CONFIG_TMP=$(mktemp) From 44c003400e7eb83aa1107fb0bbfd8d1aada04f6b Mon Sep 17 00:00:00 2001 From: qiancai Date: Wed, 18 Nov 2026 11:20:05 +0800 Subject: [PATCH 2/3] test: validate CI checkout credentials structurally --- .github/workflows/ci.yaml | 3 ++- scripts/test-safer-defaults.py | 19 +++++++++++++------ 2 files changed, 15 insertions(+), 7 deletions(-) diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 5f7a9ce036ccb..b182813fa55b2 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -19,11 +19,12 @@ jobs: persist-credentials: false - name: Verify duplicated file names run: ./scripts/verify-duplicated-file-name.sh + - name: Install Python test dependencies + run: python3 -m pip install --disable-pip-version-check --no-deps PyYAML==6.0.3 - name: Verify safer defaults run: python3 scripts/test-safer-defaults.py - name: Verify media workflow run: | - python3 -m pip install --disable-pip-version-check --no-deps PyYAML==6.0.3 python3 scripts/test-media-workflow.py python3 scripts/test-privileged-workflow-actors.py diff --git a/scripts/test-safer-defaults.py b/scripts/test-safer-defaults.py index 2f20c01889e5a..04c06503a86f8 100644 --- a/scripts/test-safer-defaults.py +++ b/scripts/test-safer-defaults.py @@ -8,6 +8,8 @@ import subprocess import tempfile +import yaml + ROOT = Path(__file__).resolve().parents[1] @@ -15,13 +17,18 @@ ci_workflow = (ROOT / ".github/workflows/ci.yaml").read_text() assert "on: [pull_request]" in ci_workflow assert "permissions:\n contents: read\n" in ci_workflow -checkout_steps = re.findall( - r"^ uses: actions/checkout@[^\n]+\n(.*?)(?=^ -|\Z)", - ci_workflow, - re.MULTILINE | re.DOTALL, -) +workflow = yaml.safe_load(ci_workflow) +checkout_steps = [ + step + for job in workflow["jobs"].values() + for step in job.get("steps", []) + if step.get("uses", "").startswith("actions/checkout@") +] assert checkout_steps -assert all("persist-credentials: false" in step for step in checkout_steps) +assert all( + step.get("with", {}).get("persist-credentials") is False + for step in checkout_steps +) install_commands = [ line.split("#", 1)[0] From 8218379f45b84b4a4ab3562b50264ab4143f38b5 Mon Sep 17 00:00:00 2001 From: qiancai Date: Wed, 18 Nov 2026 13:51:05 +0800 Subject: [PATCH 3/3] test: validate parsed CI triggers and permissions --- scripts/test-safer-defaults.py | 30 +++++++++++++++++++++++++++--- 1 file changed, 27 insertions(+), 3 deletions(-) diff --git a/scripts/test-safer-defaults.py b/scripts/test-safer-defaults.py index 04c06503a86f8..a9e518605c002 100644 --- a/scripts/test-safer-defaults.py +++ b/scripts/test-safer-defaults.py @@ -14,10 +14,34 @@ ROOT = Path(__file__).resolve().parents[1] +def check_ci_security(content): + workflow = yaml.safe_load(content) + # PyYAML treats the unquoted "on" key as True under YAML 1.1. + trigger = workflow.get("on", workflow.get(True)) + assert trigger == ["pull_request"], trigger + assert workflow.get("permissions") == {"contents": "read"} + return workflow + + ci_workflow = (ROOT / ".github/workflows/ci.yaml").read_text() -assert "on: [pull_request]" in ci_workflow -assert "permissions:\n contents: read\n" in ci_workflow -workflow = yaml.safe_load(ci_workflow) +workflow = check_ci_security(ci_workflow) + +# Comments must not hide changes to the active trigger or permissions. +for unsafe_workflow in ( + ci_workflow.replace( + "on: [pull_request]", + "# on: [pull_request]\non: [pull_request_target]", + 1, + ), + ci_workflow.replace("contents: read", "contents: write", 1), +): + try: + check_ci_security(unsafe_workflow) + except AssertionError: + pass + else: + raise AssertionError("Unsafe CI configuration was accepted") + checkout_steps = [ step for job in workflow["jobs"].values()