CI/CD 資安
GitHub Actions 資安:強化工作流程的檢查清單
GitHub Actions 工作流程會以您儲存庫的權杖、您的機密,以及一條通往正式環境的路徑,執行來自許多作者的程式碼。保護它的控制措施大多內建於 GitHub,但預設狀態下不是關閉、過於寬鬆,就是容易設定錯誤。本檢查清單逐一說明:該如何設定、為何重要,以及缺少它時會發生什麼事的真實事件。
更新日期
檢查清單一覽
| 項目 | 能阻止什麼 |
|---|---|
最小權限的 GITHUB_TOKEN |
遭挾持的步驟推送程式碼、發布版本或觸發其他工作流程 |
| 釘選或鎖定第三方 actions | 被移動的標籤在您的作業中執行攻擊者的程式碼 |
將 pull_request_target 與 workflow_run 視為具特權 |
Pwn request:分支(fork)的程式碼以您的機密執行 |
不讓事件資料進入 run 腳本 |
透過標題、分支名稱與留言進行的腳本注入 |
| 以 OIDC 取代儲存的雲端金鑰 | 外洩後仍可使用多年的長期憑證 |
| 設有必要審查者的環境 | 任何分支或工作流程讀取正式環境的機密 |
.github/workflows 的程式碼擁有者 |
未經審查就變更管線所執行的內容 |
| 允許的 actions 政策 | 組織內任何地方出現未知或未釘選的 actions |
| 公開儲存庫不使用自架執行器 | 陌生人在您的機器上執行程式碼 |
| 快取與建置產物的衛生管理 | 遭汙染的快取,以及透過上傳外洩的權杖 |
| 執行器的對外連線控制 | 遭竊的機密被傳送到攻擊者的伺服器 |
| 每次執行的紀錄 | 不知道哪些建置執行了遭入侵的 action 或套件 |
工作流程程式碼
1. 給予 GITHUB_TOKEN 最小權限
每個作業都會取得一個 GITHUB_TOKEN,作業中的任何步驟都能使用它。2023 年 2 月之前建立的儲存庫與組織,預設仍可能對每項權限都具有讀寫權。請在
Settings → Actions → General → Workflow permissions 將預設值設為唯讀,再依作業授予寫入權限:
permissions:
contents: read
jobs:
release:
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- uses: actions/checkout@<full-commit-sha>
未列出的權限都會變成 none。各項權限的說明以及常見工作所需的權限,請參閱
GITHUB_TOKEN 權限:為每個工作流程落實最小權限。
2. 將第三方 actions 釘選到 commit,或加以鎖定
像 @v4 這樣的標籤只是一個指標,action 的擁有者或任何竊得其存取權的人都能移動它。以下兩起事件說明了這代表什麼:
- tj-actions/changed-files,2025 年 3 月。攻擊者 變更了既有的版本標籤,使其指向惡意 commit(CVE-2025-30066)。該 action 被超過 23,000 個儲存庫使用,而惡意酬載會將執行器記憶體中的機密印到工作流程記錄中;在公開儲存庫上,任何人都能讀取這些記錄。
- aquasecurity/trivy-action,2026 年 3 月。Aqua Security 的 資安公告 (CVE-2026-33634)指出,該 action 的 77 個版本標籤中有 76 個被強制推送到惡意 commit。注入的程式碼在真正的掃描之前執行,從執行器記憶體讀取機密,加密後傳送到攻擊者的基礎設施。
參照完整 commit SHA 的工作流程,則繼續執行原本的程式碼。請將版本保留為註解:
steps:
# Mutable: whoever controls the tag decides what runs
- uses: tj-actions/changed-files@v45
# Immutable: a full commit SHA, with the version as a comment
- uses: tj-actions/changed-files@<full-commit-sha> # v46.0.1
請確認 SHA 來自 action 本身的儲存庫,而不是分支(fork)。GitHub 現在提供了更強的機制:
工作流程相依性鎖定檔(workflow dependency lockfiles),自 2026 年 10 月 28 日起正式推出。gh actions-lock CLI 擴充功能會寫入 .github/workflows/actions.lock,記錄您的工作流程所用每個 action 的確切 commit,包括這些 action 所呼叫的 actions;GitHub 會在執行時檢查每個來源儲存庫是否仍是您鎖定的那一個。可重複使用工作流程(reusable workflow)的呼叫不在涵蓋範圍內,因此請以 SHA 釘選它們。管理員可以透過政策要求使用鎖定檔。無論釘選或鎖定檔,都無法讓 action 變得安全:請審查您鎖定的內容。
釘選的 actions 不會自行更新。請讓 Dependabot 提出更新,並設定冷卻期,讓新版本在送到您手上之前有幾天時間被發現問題:
# .github/dependabot.yml
version: 2
updates:
- package-ecosystem: "github-actions"
directory: "/"
schedule:
interval: "weekly"
cooldown:
default-days: 7
3. 將 pull_request_target 與 workflow_run 視為具特權
來自分支的 pull_request 工作流程會取得唯讀權杖,且沒有機密。pull_request_target
工作流程則在基礎儲存庫的情境中執行,具備其機密與可寫入的權杖,即使 pull request 來自分支也一樣。只有在工作流程從不執行 pull request 中的程式碼時,這才是安全的。一旦簽出 pull request 的 head 並加以建置,該 pull request 中的每個安裝腳本與測試都會以您的機密執行。GitHub Security Lab 將這種情況稱為
pwn
request。
- 凡是建置或測試外部貢獻程式碼的工作,都使用
pull_request。 -
如果後續必須執行具特權的步驟(例如在 pull request 上留言),請將其拆開:由不具特權的
pull_request工作流程將結果上傳為建置產物,再由workflow_run工作流程據以處理。請將這些建置產物視為不受信任的輸入,絕不可當作程式碼執行。 -
在沒有事件政策的公開儲存庫中,GitHub 自 2026 年 12 月 2 日起
預設封鎖
pull_request_target。如果您重新允許它,請只允許需要它的工作流程。
2026 年 5 月的 TanStack 入侵事件正是這樣開始的:一個 pull_request_target 工作流程執行了分支的程式碼,汙染了某個發布工作流程稍後還原的快取,而從執行器記憶體讀取的 OIDC 權杖被用來發布
42 個套件的 84 個惡意版本。
4. 不讓事件資料進入 run 腳本
運算式會在 shell 執行前展開,因此放在 run 中的 pull request 標題、分支名稱、issue 內文或 commit 訊息,都會成為腳本的一部分。任何能開啟 pull request 或 issue 的人,都能因此在您的作業中執行命令。請透過環境變數傳遞該值,讓 shell 將其視為資料:
# Vulnerable: the title is pasted into the script before the shell runs
- run: echo "Checking ${{ github.event.pull_request.title }}"
# Safe: the shell reads the title as data
- env:
PR_TITLE: ${{ github.event.pull_request.title }}
run: echo "Checking $PR_TITLE"
同樣的原則也適用於 actions/github-script 以及寫入 GITHUB_ENV 的值。工作流程中的 AI 代理讓同一個問題出現了新形式:issue 中的文字可以操控代理,而不是 shell。請參閱
提示注入。
機密與部署
5. 以 OIDC 取代長期有效的雲端金鑰
以機密形式儲存的雲端存取金鑰,在有人輪換之前都能使用,而外洩之後往往為時已晚。使用 OpenID Connect 時,作業會向 GitHub 要求短期權杖,再與 AWS、Azure 或 Google Cloud 交換;由這些雲端的信任政策決定哪個儲存庫、分支或環境可以擔任該角色:
jobs:
deploy:
runs-on: ubuntu-latest
environment: production
permissions:
contents: read
id-token: write
steps:
- uses: aws-actions/configure-aws-credentials@<full-commit-sha>
with:
role-to-assume: arn:aws:iam::123456789012:role/deploy
aws-region: us-east-1
短期權杖仍可能從執行中的作業被竊取,TanStack 事件就是例證,但它的價值遠低於永不過期的金鑰。您仍保留的機密,請只傳給需要它的步驟,而不是整個作業,讓作業中的其他 actions 無法讀取。機密如何外洩以及其他控制措施,請參閱 GitHub Actions 機密:如何外洩,以及如何加以鎖定。
6. 將正式環境置於設有必要審查者的環境之後
環境擁有自己的機密,指定該環境的作業必須等必要審查者核准執行後,才能讀取這些機密。部署分支規則則限制哪些分支可以使用該環境。如此一來,功能分支上的工作流程或由 pull request 觸發的工作流程,就沒有任何途徑能取得正式環境的憑證。
治理
7. 工作流程檔案須經程式碼擁有者審查
工作流程檔案決定了什麼會以您的機密執行,因此對它的變更,應與變更正式環境存取權一樣接受審查。請將該資料夾加入 CODEOWNERS,並在分支規則集中要求程式碼擁有者審查:
/.github/workflows/ @example-org/platform-security
/.github/actions/ @example-org/platform-security
8. 限制可執行的 actions
在企業、組織或儲存庫層級,允許的 actions 政策可以將 actions 限制為來自 GitHub、經驗證的建立者,或您維護的清單。自
2025 年
8 月起,它也可以要求 SHA 釘選,讓使用未釘選 action 的工作流程失敗,並以 ! 項目封鎖特定 action 或版本;當您使用的 action 被通報遭入侵時,這項功能就很有幫助。
執行器、快取與建置產物
9. 公開儲存庫不使用自架執行器
GitHub 的安全使用參考文件指出,公開儲存庫幾乎永遠不應使用自架執行器,因為任何人都能開啟 pull request 並在上面執行程式碼。在私有儲存庫上,請使用每個作業都重新啟動的執行器:長期存在的執行器會把一個作業留下的任何東西保留給下一個作業,包括後門。Shai-Hulud npm 蠕蟲正是因此將受感染的機器註冊為自架執行器。請參閱 託管與自架執行器比較。
10. 保護快取免於汙染
快取依分支劃分範圍,而在預設分支上儲存的快取,可以被其他所有分支還原。因此,在預設分支上任何工作流程中執行的程式碼,都能寫入發布工作流程稍後會還原的快取項目,而不需要寫入權杖。請讓不受信任的程式碼遠離預設分支的工作流程,避免在發布與發佈套件的作業中還原快取,改為在其中依鎖定檔重新建置。請參閱 GitHub Actions 快取的運作方式。
11. 將建置產物視為不受信任
除非您將其關閉,否則 actions/checkout 會將權杖保留在磁碟上,供之後的 git 命令使用。過去曾發生將工作區上傳為建置產物而外洩該權杖的情況。請在不需推送的簽出步驟設定 persist-credentials: false,只上傳需要的路徑,並且絕不在具特權的工作流程中執行來自 pull request 的建置產物:
- uses: actions/checkout@<full-commit-sha>
with:
persist-credentials: false
網路與紀錄
12. 控制作業可以連線的對象
GitHub 託管的執行器不限制對外流量,因此作業中的程式碼可以將它讀到的內容傳送到任何地方。大多數作業只需要一小份目的地清單:套件庫、容器登錄庫、原始碼主機與少數 API。允許這些、封鎖其餘,遭竊的機密便無處可送,即使是前所未見的攻擊也一樣。對外連線政策無法阻止被印到記錄中的機密(如 tj-actions 事件),因此它應與釘選並用,而不是取而代之。請參閱對外連線政策如何阻止從 GitHub Actions 竊取資料。
13. 記錄每次執行所使用的 actions 與套件
當下一個遭入侵的 action 或套件被公布時,第一個問題是:您的哪些執行使用了它?工作流程檔案說明的是執行原本打算使用什麼。標籤、版本範圍或快取命中都可能讓答案不同,而能下定論的紀錄,是作業執行當下所記錄的那一份:每個 action 的 commit、所取得或從快取還原的每個套件,以及作業建立的連線。請參閱 GitHub Actions 中的 SBOM。
稽核工作流程的免費工具
上述大多數工作流程項目都可以自動檢查。這些工具讀取工作流程檔案;它們不會在作業執行時加以監看。
| 工具 | 檢查內容 |
|---|---|
| zizmor | 針對 GitHub Actions、Dependabot 與 pre-commit 設定的靜態分析:範本注入、危險的觸發條件、過多的權限、未釘選的 actions、冒名 commit、快取汙染,以及 checkout 遺留的憑證 |
| actionlint |
檢查工作流程語法與運作式的 linter,也會標記用於內嵌腳本中的不受信任值,並對 run 步驟執行 shellcheck
|
| OpenSSF Scorecard | 儲存庫檢查,包括 Dangerous-Workflow(不受信任的簽出與腳本注入)、Token-Permissions 與 Pinned-Dependencies |
| poutine | BoostSecurity 的開源建置管線掃描工具,涵蓋 GitHub Actions、GitLab、Azure DevOps 與 Tekton,並能掃描組織中的每個儲存庫 |
| CodeQL | GitHub 的程式碼掃描,自 2025 年起即分析工作流程中的注入與 pwn request 模式 |
請在變更 .github/ 的 pull request 中執行其中一項工具。關於這些工具如何與執行器控制及態勢管理工具搭配,請參閱 CI/CD 資安工具比較與
CI/CD 資安。若需要涵蓋整條管線、而不只是 GitHub Actions 設定的檢查清單,請參閱 CI/CD 管線資安檢查清單。
CRACI 如何協助
CRACI 取代的是執行器,而不是 GitHub Actions:您將 runs-on 改為 craci,工作流程、機密、權杖權限與執行記錄都留在 GitHub。它涵蓋本清單的最後幾項,也就是在作業執行期間發生的事:
- 對外連線控制。對外連線政策決定作業可以連線到哪些套件來源、登錄庫與主機。政策會在作業開始前經過驗證,在執行器上強制執行,並採失效即封鎖(fail closed);連線被封鎖時會發出警示。
-
每次執行的紀錄。作業的 SBOM 會將它執行的 GitHub Actions 列為
pkg:github元件,並釘選到實際使用的 commit;也會列出它取得的每個套件(包括從快取還原的套件),並附上其網路連線的追蹤記錄。當 action 的標籤被移動時,您可以看出每次執行實際執行的是哪個 commit。 - 政策關卡。引入具有已知漏洞套件(包括特定 CVE)的建置可以被攔下。
- 隔離。每個作業都在自己的虛擬機器中執行,因此不會有任何東西延續到下一個作業。
CRACI 不會稽核您的工作流程檔案、不掃描原始碼,也不掃描機密,因此這些工作請繼續使用 zizmor 等工作流程 linter、GitHub 的機密掃描以及您的 SAST 工具。CRACI 在 Linux 上執行 GitHub Actions 作業,其他 CI 系統已列入產品藍圖。
GitHub Actions 資安:常見問題
如何保護 GitHub Actions?
將 GITHUB_TOKEN 設為唯讀並依作業授予寫入權限、釘選或鎖定第三方 actions、避免在 pull_request_target 工作流程中執行 pull request 的程式碼、透過環境變數將事件資料傳給腳本、以 OIDC 取代儲存的雲端金鑰、將正式環境的機密置於環境之後、要求審查工作流程檔案,並控制作業可以連線的對象。
應該將 GitHub Actions 釘選到 commit SHA 嗎?
第三方 actions 應該這麼做。標籤可以被移到其他程式碼,2025 年的 tj-actions/changed-files 與 2026 年的 trivy-action 都發生過這種事,而完整的 commit SHA 則無法被移動。GitHub 的工作流程鎖定檔更進一步,連您的 actions 所呼叫的 actions 也一併鎖定。
pull_request_target 危險嗎?
只有在工作流程從不執行 pull request 中的程式碼時,它才是安全的。即使來自分支,它也會以基礎儲存庫的機密與寫入權杖執行,因此在其中建置分支的程式碼,就等於把兩者都交給開啟 pull request 的人。自 2026 年 12 月 2 日起,GitHub 會在沒有事件政策的公開儲存庫中預設封鎖它。
什麼是 pwn request?
這是 GitHub Security Lab 的用語,指的是具特權的工作流程(通常由 pull_request_target 觸發)簽出並執行來自 pull request 的不受信任程式碼,讓作者得以存取該工作流程的機密與權杖。
工作流程鎖定檔比 SHA 釘選更好嗎?
它們更強。鎖定檔會記錄工作流程所用每個 action 的 commit(包括遞移的 actions),GitHub 也會在執行時檢查來源儲存庫的身分。可重複使用工作流程的呼叫不在涵蓋範圍內,因此請以 SHA 釘選它們。
有哪些免費工具可以檢查 GitHub Actions 工作流程的資安問題?
zizmor、actionlint、OpenSSF Scorecard 與 poutine 都是免費的,CodeQL 也能在 GitHub 程式碼掃描中分析工作流程。它們讀取工作流程檔案;不會控制作業執行時的行為。