ci(security): pin every GitHub Action to an immutable commit SHA [@Raydikalx]

A major tag such as `v4` is mutable: the action's owner can repoint it, so the
code that executes in CI can change while not a single byte of this repository
does. This workflow runs with `permissions: contents: write` and the repository
token, so that substituted code would be allowed to write to `main`. All five
`uses:` now name a 40-hex commit SHA, with the human-readable version kept in a
trailing comment — the form Dependabot understands, so upgrades are still
proposed as ordinary PRs.

  actions/checkout         11d5960a326750d5838078e36cf38b85af677262  v4.4.0
  actions/setup-python     a26af69be951a213d495a4c3e4e4022e16d87065  v5.6.0
  actions/cache      (x2)  0057852bfaa89a56745cba8c7296529d2fc39830  v4.3.0
  actions/upload-artifact  ea165f8d65b6e75b540449e92b4886f43607fa02  v4.6.2

Each SHA was resolved from the upstream repository and checked to be the commit
its version tag actually points at. The pins deliberately stay on the current
majors: this commit is about integrity, not about upgrading.

test_pipeline.py — `test_workflow_downloads_and_caches_the_geoip_database`
asserted the literal string `actions/cache@v4`, so it failed the moment the
workflow became *safer*. It now parses `uses:` out of the YAML and asserts the
cache step exists regardless of how its version is written. A new gate,
`test_every_workflow_action_is_pinned_to_an_immutable_commit_sha`, stops the
pins being undone in a drive-by change; it carries a self-test of its own SHA
matcher, because a check that cannot fail is not a check. Suite: 289/289.

SECURITY.md — the supply-chain row for Actions now reads "yes, a SHA is
immutable" where it read "no", and the three citations of aggregate.yml line
numbers shift +6 in lockstep with the comment inserted above the checkout step.

CONTRIBUTING.md — the sample runner output said 288/288; there are now 289.

Author: 0xRadikal

.github/workflows/aggregate.yml

@@ -112,7 +112,13 @@ jobs:
     timeout-minutes: 15
     steps:
       - name: ⬇️ Checkout
-        uses: actions/checkout@v4
+        # ★ SHA-pinned, not a moving tag ★
+        #   A major tag such as `v4` is mutable: the owner can repoint it, so the
+        #   bytes that execute in CI can change while this file does not. Pinning
+        #   the commit SHA makes the executed code immutable. The trailing comment
+        #   keeps the human-readable version visible and is the form Dependabot
+        #   understands, so version bumps are still proposed as normal PRs.
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
 
       # ── دروازهٔ زمانی: اگر به‌تازگی آپدیت شده، زود خارج شو ──────────────
       - name: ⏱️ Freshness gate
@@ -202,7 +208,7 @@ jobs:
       # ══════════════════════════════════════════════════════════════════════
       - name: 🐍 Setup Python
         if: steps.gate.outputs.should_run == 'true'
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
         with:
           python-version: "3.12"
           cache: pip
@@ -239,7 +245,7 @@ jobs:
       - name: 🌍 Restore GeoIP database cache
         if: steps.gate.outputs.should_run == 'true'
         id: geoip_cache
-        uses: actions/cache@v4
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
         with:
           path: .cache/dbip-country-lite.mmdb
           key: dbip-country-lite-${{ steps.geoip_key.outputs.ym }}
@@ -381,7 +387,7 @@ jobs:
       # می‌کند و هیچ گامِ دستی‌ای فراموش نمی‌شود.
       - name: 📦 Restore xray-knife cache
         if: steps.gate.outputs.should_run == 'true'
-        uses: actions/cache@v4
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
         with:
           path: .cache/xray-knife
           # نسخه و checksum هر دو در کلید هستند: اگر یکی عوض شود، cacheِ
@@ -498,7 +504,7 @@ jobs:
 
       - name: 📎 Upload validation report on failure
         if: failure() && steps.gate.outputs.should_run == 'true'
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
         with:
           name: validation-report
           path: |

CONTRIBUTING.md

@@ -59,7 +59,7 @@ It prints one line per test and a summary, and exits non-zero if anything failed
 ```
   ✅ test_state_history_growth_is_bounded
   …
-  288/288 passed
+  289/289 passed
 ```
 
 Notes that matter:
@@ -227,7 +227,7 @@ please check that file before claiming a source works.
   step uses it to find the last human commit, and a human commit carrying that
   marker would be skipped as if it were bot output.
 - In the PR description, state **what you measured**, not just what you changed.
-  "Ran the suite: 288/288" or "source returned 412 configs, 38 unique after
+  "Ran the suite: 289/289" or "source returned 412 configs, 38 unique after
   dedup" is the expected style.
 
 ### What gets a PR rejected

SECURITY.md

@@ -109,21 +109,21 @@ These are verifiable claims, not assurances:
 | `xray-knife` 10.1.1 | version **and** SHA-256 of both the release archive and the extracted binary, cross-checked against upstream's own `.dgst` file in MD5/SHA-256/SHA-512 | ✅ yes |
 | `sing-box` 1.13.14 | version only | ❌ **no — see below** |
 | `mihomo` v1.19.29 | version only | ❌ **no — see below** |
-| GitHub Actions | major tags (`actions/checkout@v4`, `actions/setup-python@v5`, `actions/cache@v4`, `actions/upload-artifact@v4`) | ❌ not SHA-pinned |
+| GitHub Actions | commit SHAs, with the version in a trailing comment: `checkout` v4.4.0, `setup-python` v5.6.0, `cache` v4.3.0, `upload-artifact` v4.6.2 | ✅ yes — a SHA is immutable |
 | Dependency updates | [`.github/dependabot.yml`](.github/dependabot.yml) — `pip` + `github-actions`, weekly | — |
 
 ### Known gap, stated rather than hidden
 
 `sing-box` and `mihomo` are downloaded from GitHub Releases with the version
 pinned, but **their checksums are not verified**. The workflow itself names this
-asymmetry, in the comment block at lines 370–373, and explains why
+asymmetry, in the comment block at lines 376–379, and explains why
 version-pinning alone is not integrity. That comment is written in Persian; in
 English it says:
 
-<!-- Paraphrase, not a quotation. The comment at aggregate.yml:370-373 reads
+<!-- Paraphrase, not a quotation. The comment at aggregate.yml:376-379 reads
      "فقط pin کردنِ *نسخه* تضمینی نمی‌دهد، چون یک انتشارِ گیت‌هاب قابلِ جای‌گزینی
      است (asset را می‌توان با همان نام دوباره بارگذاری کرد)." Presenting an English
-     rendering of that in blockquote form would invite a reader to go to line 371
+     rendering of that in blockquote form would invite a reader to go to line 377
      expecting these exact words and find something else — a small gap between
      what is advertised and what is delivered, which is the failure mode this
      whole document is written against. -->
@@ -133,7 +133,13 @@ the same asset name can be re-uploaded with different bytes. Pinning only the
 
 `xray-knife` was hardened this way; the two validator binaries were not. This is
 a real, open hardening item, and it is listed here instead of being left for
-someone else to discover. The same applies to SHA-pinning the GitHub Actions.
+someone else to discover.
+
+The GitHub Actions used to carry the same weakness — they were referenced by
+mutable major tags — and that has since been closed: every `uses:` in the
+workflow now names an immutable commit SHA, with the human version kept in a
+trailing comment so Dependabot can still propose upgrades. That is why the row
+above reads ✅ where it previously read ❌.
 
 **Threat model for that gap:** it requires an attacker who can replace an asset
 on the `SagerNet/sing-box` or `MetaCubeX/mihomo` release pages — i.e. a

scripts/test_pipeline.py

@@ -813,7 +813,7 @@ def test_every_workflow_fetch_is_bounded_and_time_capped():
     چرا این تست وجود دارد — با اندازه‌گیریِ واقعی روی همین مخزنِ ۳.۵۵ گیگابایتی،
     نه حدس:
 
-      کلونِ CI (‏actions/checkout@v4) عمق ۱ دارد. مرحلهٔ انتشار خودش force-push
+      کلونِ CI (‏actions/checkout) عمق ۱ دارد. مرحلهٔ انتشار خودش force-push
       است، پس کامیتی که checkout روی آن نشسته، به‌محضِ انتشارِ یک اجرای دیگر
       **از دسترس خارج** می‌شود. در آن لحظه تنها «have»ِ کلونِ shallow دیگر جزوِ
       تاریخِ نوکِ جدید نیست، سرور مبنایی برای بستهٔ کوچک ندارد و کلِ تاریخ را
@@ -1969,14 +1969,70 @@ def _workflow_text() -> str:
         return f.read()
 
 
+def _workflow_uses() -> list[str]:
+    """هر مقدارِ `uses:`ِ ورک‌فلو — از YAMLِ پارس‌شده، نه regex روی متنِ خام.
+
+    دلیلِ پارس‌کردن: مرجعِ هر اکشن یک کامنتِ دنباله‌دار دارد
+    (`…@<sha> # v4.4.0`). regex روی متنِ خام آن کامنت را جزوِ مرجع می‌شمارد و
+    آزمون را الکی سرخ می‌کند؛ YAML کامنت را طبعاً حذف می‌کند.
+    """
+    doc = yaml.safe_load(_workflow_text())
+    out: list[str] = []
+    for job in (doc.get("jobs") or {}).values():
+        for step in (job.get("steps") or []):
+            u = step.get("uses")
+            if isinstance(u, str):
+                out.append(u.strip())
+    return out
+
+
+def _is_sha_pin(ref: str) -> bool:
+    """آیا `ref` یک SHAِ کاملِ ۴۰ رقمیِ hex است (و نه تگِ متحرکی مثل `v4`)؟"""
+    return len(ref) == 40 and all(c in "0123456789abcdef" for c in ref.lower())
+
+
 def test_workflow_downloads_and_caches_the_geoip_database():
     """بدونِ این مرحله، خط‌لوله در CI بی‌صدا به برچسب‌گذاریِ ضعیف برمی‌گردد."""
     wf = _workflow_text()
     assert "download.db-ip.com" in wf, "the workflow must fetch the DB-IP database"
-    assert "actions/cache@v4" in wf, "the database must be cached, not re-downloaded 96×/day"
+    # ⚠️ این ادعا عمداً به رشتهٔ `actions/cache@v4` گره نمی‌خورد. نسخهٔ قبلی همین
+    #    کار را می‌کرد و درست در لحظه‌ای شکست که ورک‌فلو *امن‌تر* شد: پین‌شدنِ
+    #    اکشن‌ها به SHA، رشتهٔ `@v4` را حذف کرد و این تست سرخ شد در حالی که
+    #    مرحلهٔ cache هنوز سرِ جایش بود. یک آزمون باید به «رفتار» گره بخورد
+    #    (اینکه cache وجود دارد) نه به «نگارشِ نسخه».
+    caches = [u for u in _workflow_uses() if u.split("@", 1)[0] == "actions/cache"]
+    assert caches, "the database must be cached, not re-downloaded 96×/day"
     assert "dbip-country-lite.mmdb" in wf
 
 
+def test_every_workflow_action_is_pinned_to_an_immutable_commit_sha():
+    """تگِ متحرک قابلِ جابه‌جایی است؛ SHA نیست.
+
+    مالکِ یک اکشن می‌تواند تگِ `v4` را به کامیتِ دیگری repoint کند. آن‌وقت کدی
+    که در CI **اجرا** می‌شود عوض می‌شود بدون آن‌که حتی یک بایت از این مخزن
+    تغییر کند — و این ورک‌فلو با `permissions: contents: write` و توکنِ مخزن
+    اجرا می‌شود، پس آن کدِ عوض‌شده اجازهٔ نوشتن روی `main` را دارد. پین‌کردنِ
+    SHA این مسیر را می‌بندد، و این آزمون نمی‌گذارد کسی در یک PRِ گذری آن را
+    باز کند.
+    """
+    # ① گاردِ خودِ ابزار: سنجه‌ای که نتواند سرخ شود، سنجه نیست. اگر `_is_sha_pin`
+    #    روزی همه‌چیز را «پین‌شده» بخواند، ادعای پایین بی‌معنا می‌شود.
+    assert _is_sha_pin("11d5960a326750d5838078e36cf38b85af677262") is True
+    for bogus in ("v4", "v4.4.0", "main", "", "11d5960", "z" * 40,
+                  "11d5960a326750d5838078e36cf38b85af6772620"):
+        assert _is_sha_pin(bogus) is False, f"matcher wrongly accepted {bogus!r}"
+
+    uses = _workflow_uses()
+    # ② گاردِ پارسر: لیستِ خالی هم «هیچ اکشنِ پین‌نشده‌ای نیست» را راست می‌کند.
+    assert len(uses) >= 4, f"parsed only {len(uses)} `uses:` — parser looks broken"
+
+    # اکشن‌های محلی (`./…`) و `docker://` مرجعِ گیت ندارند و پین نمی‌شوند.
+    remote = [u for u in uses if not u.startswith("./") and not u.startswith("docker://")]
+    unpinned = [u for u in remote
+                if "@" not in u or not _is_sha_pin(u.split("@", 1)[1])]
+    assert not unpinned, f"these actions are not pinned to a SHA: {unpinned}"
+
+
 def _workflow_run_text() -> str:
     """فقط بدنهٔ `run:`های ورک‌فلو — یعنی چیزی که *اجرا* می‌شود.