CI 中的機密、環境變數與安全性
背景脈絡
每條 CI/CD pipeline 都需要處理機密資訊:第三方服務的 API 金鑰、部署用的雲端憑證、整合測試用的資料庫 URL、拉取私有 npm 套件的 token。最直觀的做法是將機密寫入 .env 檔案或直接設定為環境變數並提交進 repository。這已造成軟體史上數起最嚴重的資安事故。提交進 git 的機密是永久的:它存在於每一個 clone、每一個 fork、每一個 git log,以及每一份 GitHub 封存備份中,即使後來刪除了原始檔案也無法消除。
GitGuardian 在 2026 年對公開 GitHub 的機密外洩規模掃描發現,該平台單一年內就暴露了 2,900 萬筆憑證。模式幾乎如出一轍:開發者不小心提交了憑證,往往藏在設定檔或環境變數檔案中,通常只是「暫時的」。攻擊者持續掃描公開 repository 和外洩的資料,尋找憑證格式的特徵。Comparitech 在 2022 年進行的一次蜜罐實驗中,於公開 repository 植入一組真實的 AWS 金鑰,結果發現它在約一分鐘內就被發現並遭到濫用。
前端 CI pipeline 面臨一個特殊的複合風險:Vite 和 Next.js 等建置工具有一個慣例,會將以 VITE_ 或 NEXT_PUBLIC_ 為前綴的環境變數暴露到客戶端 JavaScript bundle 中。任何帶有這類前綴的變數都是刻意公開的:它在建置時被以字串字面值的方式內嵌進傳送到每個瀏覽器的 JavaScript 中。開發者若將私密 API 金鑰放入 VITE_API_SECRET,等同於將該機密傳送給所有使用者。
本文涵蓋機密的存儲與注入、公開變數的區別、secret scanning、透過 OIDC 實現無金鑰雲端認證、相依套件安全性,以及供應鏈完整性,並全程以 GitHub Actions 作為範例。相同的基本元件,加密 secret 存儲與向雲端服務商進行 OIDC 聯合認證,同樣存在於 GitLab CI、CircleCI 和 Buildkite 中。
視覺化
下圖展示正確的機密生命週期:從建立到在 CI 中使用,關鍵限制是機密絕不進入客戶端 JavaScript bundle。
範例
1. GitHub Actions secrets:repository、environment 和 organization 範圍
GitHub Actions 的加密 secrets 有三個範圍:
- Repository secrets:對一個 repository 中的所有 workflow 可用
- Environment secrets:僅對部署到指定 environment(例如
production)的 workflow 可用,且可以要求手動審核 - Organization secrets:對整個組織中選定的 repository 可用
# .github/workflows/deploy.yml
name: Deploy
on:
push:
branches: [main]
jobs:
deploy:
name: Deploy to production
runs-on: ubuntu-latest
# 指定 environment 讓此 job 受 environment protection rules 的管制。
# 在 'production' environment 上定義的 secrets 在此可用。
environment: production
steps:
- uses: actions/checkout@v4
- name: Deploy
env:
# Repository secret — 在所有 workflow 中可用
NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
# Environment secret — 僅在設定 environment: production 時可用
DEPLOY_API_KEY: ${{ secrets.DEPLOY_API_KEY }}
run: |
echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" >> ~/.npmrc
./scripts/deploy.sh在 Actions UI 中,secrets 在 Settings → Secrets and variables → Actions 下設定。Environment secrets 在 Settings → Environments → [environment 名稱] → Secrets 下設定。
Secrets 永遠不會印出在日誌中。如果 workflow 步驟嘗試 echo $SECRET_VALUE,GitHub Actions 會將值遮蔽並印出 ***。這個遮蔽機制只涵蓋對已知機密值的直接 echo。如果機密在印出前經過轉換、編碼、串接,或嵌入到更大的字串中,遮蔽機制就無法偵測到,因此一個組合 URL 或 JSON payload 並包含機密的 script,仍可能繞過遮蔽機制而洩漏機密。
2. 使用 OIDC 無金鑰認證至 AWS
OIDC 消除了儲存 AWS access key 的需求。Workflow 從 GitHub 的 OIDC provider 收到一個短期有效的 JWT,並將其換取臨時的 AWS 憑證。
步驟一:設定 AWS 信任 GitHub 的 OIDC provider(一次性設定,通常透過 Terraform)。
# terraform/github-oidc.tf
resource "aws_iam_openid_connect_provider" "github" {
url = "https://token.actions.githubusercontent.com"
client_id_list = ["sts.amazonaws.com"]
# 自 2023 年 7 月起,AWS 已改為透過其受信任的根 CA 存放區驗證 GitHub
# 的 OIDC provider,不再使用此值來驗證連線。Terraform 的
# aws_iam_openid_connect_provider resource 仍要求提供 thumbprint_list
# 參數,因此這裡保留它僅為了與舊版 provider 相容。
thumbprint_list = ["6938fd4d98bab03faadb97b34396831e3780aea1"]
}
resource "aws_iam_role" "github_actions_deploy" {
name = "github-actions-deploy"
assume_role_policy = jsonencode({
Version = "2012-10-17"
Statement = [{
Effect = "Allow"
Principal = { Federated = aws_iam_openid_connect_provider.github.arn }
Action = "sts:AssumeRoleWithWebIdentity"
Condition = {
StringEquals = {
# audience 必須符合 AWS STS 的 audience;僅憑這項條件
# 並不能限制哪個 repository 可以承擔此角色。
"token.actions.githubusercontent.com:aud" = "sts.amazonaws.com"
}
StringLike = {
# 限制僅限此特定 repository 中 main 分支的推送。
# 省略此條件將允許任何 GitHub repository 承擔此角色。
"token.actions.githubusercontent.com:sub" = "repo:your-org/your-repo:ref:refs/heads/main"
}
}
}]
})
}
resource "aws_iam_role_policy_attachment" "deploy_s3" {
role = aws_iam_role.github_actions_deploy.name
policy_arn = "arn:aws:iam::aws:policy/AmazonS3FullAccess" # 生產環境應縮小範圍
}步驟二:在 GitHub Actions workflow 中使用 OIDC。不需要存儲靜態憑證。
# .github/workflows/deploy.yml
name: Deploy to S3 (OIDC)
on:
push:
branches: [main]
permissions:
id-token: write # 請求 OIDC JWT 所必需
contents: read
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: aws-actions/configure-aws-credentials@v6
with:
role-to-assume: arn:aws:iam::123456789012:role/github-actions-deploy
aws-region: us-east-1
# 不需要 access-key-id 或 secret-access-key。
# 此 action 自動向 GitHub 請求 OIDC token 並換取
# 臨時的 STS 憑證。
- name: Build
run: pnpm build
- name: Deploy to S3
run: aws s3 sync dist/ s3://my-production-bucket --deleteSTS 返回的臨時憑證有效期為一小時,workflow 結束後即無法使用:沒有長期有效的金鑰可供攻擊者竊取。
3. VITE_*:什麼是安全的,什麼是危險的
# .env.production — 這些值「將會」被打包進公開的 JavaScript
# 安全:Stripe publishable key 設計上就是公開的
VITE_STRIPE_PUBLISHABLE_KEY=pk_live_xxxxxxxxxxxx
# 安全:公開的 analytics measurement ID
VITE_GA_MEASUREMENT_ID=G-XXXXXXXXXX
# 安全:公開的 CDN base URL
VITE_CDN_URL=https://cdn.example.com
# 安全:feature flag client key(只讀,公開端點)
VITE_GROWTHBOOK_CLIENT_KEY=sdk-abc123
# ---
# 危險:這「將會」被打包並對所有使用者可見
# VITE_STRIPE_SECRET_KEY=sk_live_xxxxxxxxxxxx <-- 絕對不能這樣做
# 危險:資料庫連線字串出現在公開 bundle 中
# VITE_DATABASE_URL=postgresql://user:pass@host/db <-- 絕對不能這樣做
# 危險:具有伺服器端權限的私有 API 金鑰
# VITE_OPENAI_API_KEY=sk-xxxxxxxxxxxx <-- 絕對不能這樣做對於建置過程在建置時需要的機密(從 CMS 抓取內容、呼叫私有 API 生成靜態頁面),以不帶 VITE_ 前綴的普通環境變數傳遞。它們將在建置期間對建置腳本可用,但不會被納入客戶端 bundle。
# .github/workflows/build.yml
- name: Build
env:
# 在建置腳本和 SSR 程式碼中可用——不會被打包進客戶端 JS
CMS_API_KEY: ${{ secrets.CMS_API_KEY }}
# VITE_PUBLIC_URL 會被打包——刻意公開
VITE_PUBLIC_URL: https://example.com
run: pnpm build4. 使用 gitleaks 進行 secret scanning
gitleaks 掃描 git 歷史中的憑證格式。在 CI 中執行它以在合併前捕捉機密。
# .github/workflows/security.yml
name: Security
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
secret-scan:
name: Secret scanning
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
# 掃描完整歷史,不只是最新的 commit
fetch-depth: 0
- name: Run gitleaks
uses: gitleaks/gitleaks-action@v2
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
# 組織 repository 需要 GITLEAKS_LICENSE(個人帳號的 repository 不需要)
# GITLEAKS_LICENSE: ${{ secrets.GITLEAKS_LICENSE }}Repository 根目錄中的 .gitleaks.toml 檔案允許自定義偵測規則,以及將已知的誤判(測試 fixture、範例值)加入允許清單:
# .gitleaks.toml
[allowlist]
description = "Global allowlist"
# 允許特定檔案(例如包含範例憑證的測試 fixture)
paths = [
"tests/fixtures/",
"docs/examples/",
]
# 允許特定 commit SHA(針對無法重寫而不影響團隊的既有歷史 commit)
commits = [
"abc1234",
]
# 允許已知為非機密的 regex 格式
regexes = [
"example_api_key_here",
"YOUR_API_KEY_HERE",
"sk_test_placeholder",
]GitHub 原生的 push protection(在 repository Settings → Code security → Secret scanning → Push protection 中啟用)會封鎖包含偵測到機密的推送。這能在推送當下就捕捉到意外,機密此時尚未到達遠端。
5. 相依套件安全性:npm audit 與 lockfile 完整性
# .github/workflows/security.yml(續)
dependency-audit:
name: Dependency audit
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: pnpm/action-setup@v4
with:
version: 9
- uses: actions/setup-node@v4
with:
node-version: 20
- name: Install (lockfile 完整性檢查)
# --frozen-lockfile 在 lockfile 與 package.json 不同步時會失敗
# 這防止靜默地安裝與已提交版本不同的套件
run: pnpm install --frozen-lockfile
- name: Audit dependencies
# --audit-level=high 在高嚴重性漏洞時失敗
# 省略 --audit-level 則在任何嚴重性時都失敗
run: pnpm audit --audit-level=high
# 使用 npm 則為:npm audit --audit-level=high對於無法立即修復每個漏洞的專案(沒有可用修補程式的傳遞性相依套件),允許 audit 步驟警告而不阻擋,僅對關鍵嚴重性強制執行:
- name: Audit dependencies (moderate 以上警告,不阻擋)
run: pnpm audit --audit-level=moderate || true
- name: Audit dependencies (critical 阻擋)
run: pnpm audit --audit-level=critical6. 使用 Dependabot 自動更新相依套件
Dependabot 在發布新版本時開啟 pull request 來更新相依套件。結合執行測試和 audit 的 CI pipeline,安全的更新可以以最少的手動工作完成合併。
# .github/dependabot.yml
version: 2
updates:
# 更新 npm 相依套件
- package-ecosystem: "npm"
directory: "/"
schedule:
interval: "weekly"
day: "monday"
time: "09:00"
timezone: "Asia/Taipei"
# 將 minor 和 patch 更新分組到單一 PR 以減少噪音
groups:
non-major:
update-types:
- "minor"
- "patch"
# 同時最多開啟 5 個 PR 以避免讓團隊不堪負荷
open-pull-requests-limit: 5
# 更新 GitHub Actions
- package-ecosystem: "github-actions"
directory: "/"
schedule:
interval: "weekly"Renovate(Dependabot 的替代方案)提供更精密的分組、排程和自動合併邏輯。設定存放在 repository 根目錄的 renovate.json 中。
7. npm provenance、trusted publishing 與 SLSA attestation
npm provenance(自 npm 9.5 / Node 18 起可用)為發布的套件附加一個簽名的 attestation。attestation 將已發布的套件連結到建置它的特定 GitHub Actions 執行、git commit SHA、repository 和分支。任何安裝該套件的使用者都可以驗證 provenance。
npm trusted publishing 已於 2025 年 7 月正式發布(GA),現在是從 GitHub Actions 或 GitLab CI 發布套件的建議做法。在 npmjs.com 上設定套件的 trusted publisher(package settings → Trusted Publisher),使其接受來自特定 repository、workflow 檔名,以及選填 environment 的 id-token: write。設定完成後,workflow 就不再需要存儲 NPM_TOKEN,provenance 也會自動產生:
# .github/workflows/publish.yml(建議做法:trusted publishing,不存儲 token)
name: Publish to npm
on:
release:
types: [published]
permissions:
id-token: write # OIDC 和 provenance 簽名所必需
contents: read
jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
registry-url: 'https://registry.npmjs.org'
- name: Install
run: npm ci
- name: Build
run: npm run build
- name: Publish
run: npm publish --access public
# 不需要 NODE_AUTH_TOKEN。因為已在 npmjs.com 為此 repository 與
# workflow 檔案設定了 trusted publisher,npm 會將此 workflow 的
# OIDC token 換取短期有效的發布憑證。尚未支援 trusted publishing 的 CI 平台,或尚未設定 trusted publisher 時發布的套件,則會退回使用存儲的 token:
- name: Publish with provenance(舊版備援方案:存儲 token)
run: npm publish --provenance --access public
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}發布的套件在 npmjs.com 上會顯示 provenance 驗證,連結到對應的 Actions 執行記錄與 commit SHA。使用者可以驗證它:
# 驗證已安裝套件的 provenance
npm audit signatures
# 輸出(如果 provenance 存在):
# audited 1 package in 0.5s
# 1 package has a verified registry signature
# 1 package has a verified attestationSLSA(Supply-chain Levels for Software Artifacts)是供應鏈安全的更廣泛框架。如上所示,從一般的 GitHub Actions job 執行標準的 npm publish --provenance,產生的是 SLSA Build Level 2 provenance:建置過程被追蹤且 provenance 經過簽名,但建置平台並未與 workflow 自身的建置步驟隔離。SLSA Build Level 3 額外要求執行間隔離(run-to-run isolation)與不可偽造的 provenance,意即簽名素材對使用者可控的建置步驟是不可存取的。要達到 Level 3,需要使用經過強化、隔離的 builder,例如 slsa-framework 專案提供的 SLSA Node.js builder 這類可重複使用 workflow builder,而非一般的 workflow job。actions/attest-build-provenance action(目前主要版本為 v4,本身是對較新的 actions/attest 的輕量包裝,GitHub 建議新專案改用後者)可為任何建置產出物生成 SLSA provenance attestation,不僅限於 npm 套件:
# Job 層級所需權限:id-token: write、attestations: write、
# artifact-metadata: write
- name: Generate SLSA provenance attestation
uses: actions/attest-build-provenance@v4
with:
subject-path: dist/最佳實踐
禁止(MUST NOT)在任何情況下將機密(API 金鑰、token、密碼、憑證)提交進版本控制系統。 git 歷史中的機密應視為已永久洩漏,因為任何在刪除前建立的 clone 都仍保有一份副本。團隊必須(MUST)在發現後立即輪換任何在歷史中被發現的機密,並在第一次 commit 前將所有 .env* 檔案格式加入 .gitignore。
禁止(MUST NOT)將敏感憑證放入 VITE_* 或 NEXT_PUBLIC_* 環境變數中。 這些前綴在建置時執行字串替換:該值作為字面字串內嵌進傳送到每個瀏覽器的 JavaScript bundle 中。團隊必須(MUST)將這些前綴限制用於真正公開的值,例如 Stripe publishable key,並必須(MUST)以不帶前綴的環境變數將機密傳遞給 build 步驟,使其僅在伺服器端存在。
應該(SHOULD)將第三方 GitHub Actions 固定至完整長度的 commit SHA,而非可變動的 tag。 像 @v4 這樣的 tag,可能被該 action 的維護者重新指向不同的程式碼,也可能被入侵了維護者帳號的攻擊者這麼做,而 workflow 所參照的版本字串完全不會改變。Dependabot 可以透過開啟 pull request 來保持 SHA pin 的更新,PR 會附上新的 commit SHA,並在註解中標註對應的版本 tag。
必須(MUST)將 CI 機密存儲於 CI 平台的加密 secret 存儲中,且僅在執行時注入。 GitHub Actions 加密 secrets、GitLab CI variables 以及等效存儲皆為此目的而設計。團隊絕不(MUST NOT)將機密作為明文 workflow 輸入、workflow 環境預設值或 YAML 檔案中的硬編碼值傳遞,因為這些會出現在 log 或 repository 歷史中。
應該(SHOULD)使用 OIDC 進行 CI 與雲端之間的認證,而非長期靜態憑證。 OIDC token 短暫有效(通常 15–60 分鐘)、自動限定於特定的 repository 和分支,並在雲端服務商留下可追蹤的稽核軌跡。團隊應該(SHOULD)設定 AWS、GCP 或 Azure 信任 GitHub 的 OIDC provider,而非將長期有效的存取金鑰存儲為需要手動輪換的 CI secrets。
應該(SHOULD)在 CI 中啟用自動化 secret scanning 和相依套件稽核步驟。 對完整 git 歷史執行 gitleaks 可以捕捉在 push protection 啟用前就已提交的機密。執行 pnpm audit --audit-level=high 可以發現相依套件中已知的高嚴重性漏洞。團隊應該(SHOULD)在重大稽核發現時讓 build 失敗,而非將稽核步驟視為資訊性的。
應該(SHOULD)啟用自動化相依套件更新工具(Dependabot 或 Renovate),以保持 lockfile 更新並縮短漏洞暴露時間。 自動化工具在新版本發布時開啟 pull request;搭配執行測試和稽核的 CI,安全的更新可以以最少的人工投入完成合併。團隊應該(SHOULD)設定更新排程與分組規則,以減少雜訊,同時確保高嚴重性修補能及時套用。
應該(SHOULD)在每次 CI 安裝時使用 --frozen-lockfile 或 npm ci。 沒有 frozen flag,package manager 可能靜默地將依賴範圍解析到比 lockfile 指定的更新版本,產生與 lockfile 不同的安裝結果。lockfile 不同步應該(SHOULD)導致明確的 CI 失敗,而非靜默的自動修復,以確保可重現的 build。
設計思維
為什麼機密一旦進入 git 就是災難性且永久的
Git 在設計上是只增不減的。一個新增檔案的 commit 同時也將檔案內容永久記錄在 object database 中。在後續 commit 中刪除該檔案,只是新增了一個不包含該檔案的 commit,但原始 commit 依然存在。任何在刪除前建立的 clone 都已擁有該機密。任何 fork 該 repository 的人都繼承了這段歷史。任何 git hosting 服務都可能快取或封存了原始 commit 的內容。
標準建議「強制推送以重寫歷史」,對公開 repository 而言是不夠的。GitHub 持續掃描並快取 repository 內容。任何歷史性的暴露都必須視為完全洩漏來處理:立即輪換憑證、稽核洩漏期間的存取日誌,並調查是否發生了未授權的使用。請輪換憑證;重寫歷史並不能消除已經被快取或複製的洩漏。
根本原因幾乎總是為了方便:開發者在本地建立 .env 檔案,.env 不在 .gitignore 中,然後這個檔案就隨著功能一起被提交了。預防措施是結構性的:從專案初始化時就生成包含 .env* 的 .gitignore,使用 secret scanning 在機密到達遠端之前捕捉意外,並使用 CI secret 存儲作為 pipeline 所需任何憑證的標準存放位置。
為什麼 VITE_* 變數是刻意公開設計的
Vite 的 VITE_ 前綴慣例存在是為了明確表達意圖:任何帶有此前綴的變數都是刻意暴露給客戶端程式碼的。Vite 在建置時進行字串替換:import.meta.env.VITE_API_URL 在打包後的 JavaScript 中變成字面字串 "https://api.example.com"。這不是執行時查詢,而是編譯時的文字替換。產生的 JavaScript 傳送給每個瀏覽器,任何人都可以透過 DevTools 的 Sources 面板或下載 bundle 來完整讀取。
這個設計對真正公開的設定來說是正確且有用的:從公開端點讀取的 feature flag、公開的 analytics ID、公開的 CDN URL、公開的客戶端 API 金鑰(如 Stripe publishable key)。但對於任何應該保留在伺服器端的內容來說,這樣做是錯誤的,例如資料庫憑證或私有 API 金鑰。
判斷原則:如果該值具備任何寫入、扣款或讀取私有資料的能力,例如一個可以呼叫付費或需要認證端點的 API 金鑰,就代表它並不適合放進 VITE_*。如果該值僅用於識別一個面向公眾的資源,例如 Stripe publishable key 或公開的 analytics ID,那麼公開它是安全的。
Next.js 使用 NEXT_PUBLIC_ 達到相同目的,限制也相同。沒有這個前綴的變數僅限伺服器端使用,永遠不會被納入客戶端 bundle。
為什麼 OIDC 比靜態憑證更適合 CI 雲端認證
傳統的 CI 雲端認證方式是生成長期有效的 API 金鑰或存取 token(AWS IAM access key、GCP service account key、personal access token),並將其存儲為 CI secret。這個金鑰接著在 pipeline 執行時作為環境變數注入,用於向雲端服務商認證。
這種方式有根本性的問題。金鑰不會自動過期;它在手動輪換前持續有效。它被存儲為 CI platform 中的 secret,產生了一個本身也需要管理、稽核和輪換的機密。每次使用該金鑰的 pipeline 執行都會產生與任何其他持有該金鑰的呼叫者無法區分的活動。如果金鑰洩漏,例如透過受感染的 runner,攻擊者就會取得持久的雲端存取權限。
OIDC(OpenID Connect)完全消除了靜態憑證的需求。當 GitHub Actions workflow 執行時,GitHub 的 OIDC provider 會簽發一個加密簽名的 JWT(JSON Web Token),證明:「這是一次 GitHub Actions 執行,位於 repository org/repo,在 main 分支上,由 push 事件觸發。」雲端服務商(AWS、GCP、Azure)被設定為信任 GitHub 的 OIDC provider,並向符合特定條件(正確的 repository、分支和事件類型)的 token 授予特定 IAM 角色。
workflow 將這個 OIDC token 交換為短期雲端憑證(通常是 15 分鐘到 1 小時有效的 AWS STS token)。沒有靜態金鑰需要存儲、輪換或擔心洩漏。token 在 workflow 結束後自動失效。雲端服務商的稽核紀錄精確顯示哪次 GitHub Actions 執行產生了每個 API 呼叫。將信任關係限制在 refs/heads/main 意味著來自 fork 的 PR 無法承擔生產部署角色。
為什麼 secret scanning 必須自動化
Secret scanning 不能是手動審查步驟。Pull request 審查者無法可靠地發現機密:他們關注的是邏輯變更,而不是逐行掃描憑證格式。掃描面積很大:機密可能出現在原始碼檔案、測試 fixture、shell script、Dockerfile、GitHub Actions workflow 檔案和文件中。
自動化工具使用正規表示式和熵分析來偵測憑證格式。GitHub 的 push protection 自 2024 年起在公開 repository 上免費且預設啟用。在私有 repository 上,則需要 GitHub Advanced Security,該功能已於 2025 年重新包裝為獨立的 GitHub Secret Protection 附加方案。在啟用的情況下,它會掃描每次推送中已知的憑證格式,並在發現匹配時封鎖推送,在機密到達遠端之前就捕捉到意外。
gitleaks 和 trufflehog 等工具會掃描 repository 歷史,讓在啟用 push protection 之前就已提交的機密得以被偵測。在 CI 中執行這些工具,確保以任何形式引入的機密在合併前都能被捕捉到。
為什麼 lockfile 對供應鏈安全至關重要
npm install 和 pnpm install 從公開 registry 下載任意程式碼。沒有 lockfile,安裝器在安裝時將版本範圍(^18.0.0)解析為當時最新的匹配版本。同一個 package.json 在不同天的兩次安裝可能會安裝不同的程式碼。如果相依套件維護者發布了一個帶有惡意程式碼的 patch 版本,所有使用範圍指定符的專案都會在下次安裝時自動安裝該更新。
Lockfile 將每個套件固定到確切的版本和內容雜湊值。npm ci 和 pnpm install --frozen-lockfile 會驗證安裝的套件與 lockfile 完全一致。如果有差異,安裝會失敗,而不是靜默地安裝不同的程式碼,因此遭竄改或版本漂移的相依套件會導致 CI 失敗,而不是一次不被察覺的錯誤安裝。
Lockfile 無法防止固定版本的相依套件本身存在漏洞;這需要 npm audit。但它確實消除了相依套件替換和意外版本漂移的攻擊面。
常見錯誤
在啟用 shell 除錯的 workflow run 步驟中使用機密。 如果 workflow 步驟執行 set -x(shell 命令追蹤),然後在命令中使用機密,追蹤輸出將包含機密值。GitHub Actions 確實會從日誌中遮蔽已知的機密值,但這種遮蔽並不保證涵蓋所有輸出路徑。在處理機密的步驟中永遠不要啟用 shell 追蹤(set -x)。
無意中記錄機密。 某些 CLI 工具在 verbose 或 debug 模式下會印出所有環境變數。在注入了機密的步驟中執行 env 會印出所有機密。使用 --verbose 或 --debug 執行工具可能會印出環境。在 pipeline 步驟中啟用 verbose 輸出且該步驟有存取機密的權限之前,請先確認工具會記錄什麼。
使用過於寬泛的 OIDC 條件。 在設定 OIDC 的 AWS IAM 信任政策時,使用 repo:your-org/*:ref:refs/heads/main 而不是 repo:your-org/your-repo:ref:refs/heads/main 會允許組織中的任何 repository 承擔生產部署角色。將信任條件限定在特定的 repository 和分支。
首次啟用 secret scanning 時未掃描 git 歷史。 GitHub push protection 防止未來的洩漏,但不會回溯偵測 repository 歷史中已有的機密。在現有 repository 上啟用 secret scanning 時,執行 gitleaks git . 或 trufflehog git file://. --since-commit HEAD~500 來掃描歷史 commits。輪換任何發現的機密,即使是舊的 commit 也不例外。
發布套件時不附加 provenance。 npm provenance 是選擇性啟用的,從 GitHub Actions 發布的套件不需要任何額外費用。沒有它,使用者就無法驗證已發布的套件來自預期的來源,且在傳輸過程中未被篡改。對所有套件發布啟用 --provenance,或改用會自動產生它的 trusted publishing。
將第三方 action 固定在可變動的 tag,而非 commit SHA。 2025 年 3 月,tj-actions/changed-files(CVE-2025-30066)遭到入侵:攻擊者將該 action 大部分的版本 tag(包括廣泛使用的版本)回溯性地重新指向一個惡意 commit,該 commit 會將 CI runner 的機密傾印到 build log 中。任何以 tag 參照該 action 的 workflow(例如 tj-actions/changed-files@v46),在下一次執行時就會拉取這段惡意程式碼,而 workflow 檔案本身完全沒有變更;超過 23,000 個 repository 受到影響。將同一個 action 固定至完整 commit SHA 的 workflow,則不受 tag 被重新指向的影響。請將第三方 action 固定在 commit SHA,並使用 Dependabot 的 github-actions ecosystem,在新版本發布時開啟 pull request 更新已固定的 SHA。
延伸閱讀
- FEE-1500: CI/CD & Deployment Overview — 分類概覽和 pipeline 心智模型
- FEE-1501: GitHub Actions for Frontend — GitHub Actions workflow 結構;secrets 注入建構於其上的基礎
- FEE-806: Environment Variables in Vite and Next.js Builds —
VITE_*和NEXT_PUBLIC_*慣例以及建置時替換運作方式的深度探討 - FEE-804: Package Management and npm audit — lockfile 管理、
npm ci,以及相依套件 audit workflow - FEE-1207:SSR 與伺服器元件安全 — NEXT_PUBLIC_ 命名與環境變數衛生,決定哪些變數進入用戶端 bundle、哪些保留在伺服器端
參考資料
- Encrypted secrets — GitHub Docs:GitHub Actions 中 repository、environment 和 organization secrets 的官方文件,包含存取控制和遮蔽行為
- Configuring OpenID Connect in Amazon Web Services — GitHub Docs:設定 GitHub Actions 與 AWS IAM 之間 OIDC 信任的逐步指南,包含信任政策 JSON 和 workflow 設定
- Security hardening for GitHub Actions — GitHub Docs:涵蓋 OIDC、secret 處理、第三方 action 固定版本和 runner 安全性的綜合指南
- gitleaks — GitHub:開源 secret scanning 工具;支援 pre-commit hook、CI 整合,以及透過 TOML 進行自定義規則設定
- npm audit — npm Docs:
npm audit命令、audit 等級和供程式化使用的 JSON 輸出格式參考 - Generating provenance statements — npm Docs:
--provenanceflag 的官方文件,說明哪些資訊被證明,以及使用者如何驗證 provenance - SLSA Framework:Supply-chain Levels for Software Artifacts 規範;涵蓋威脅模型、等級,以及如何使用現有工具達到每個等級
- About secret scanning — GitHub Docs:GitHub 自動 secret scanning 的說明,包含支援的憑證格式、push protection 和通知行為
- GitGuardian, "The State of Secrets Sprawl 2026," GitGuardian (2026). https://blog.gitguardian.com/the-state-of-secrets-sprawl-2026/ — 針對公開 GitHub 的獨立掃描;本文洩漏憑證數量的資料來源
- Comparitech, "It Takes Hackers 1 Minute to Find and Abuse Credentials Exposed on GitHub," Comparitech (2022). https://www.comparitech.com/blog/information-security/github-honeypot/ — 測量洩漏 AWS 金鑰從曝光到遭濫用所需時間的蜜罐實驗
- Michael Meli, Matthew R. McNiece, and Bradley Reaves, "How Bad Can It Git? Characterizing Secret Leakage in Public GitHub Repositories," NDSS Symposium (2019). https://www.ndss-symposium.org/wp-content/uploads/2019/02/ndss2019_04B-3_Meli_paper.pdf — 針對公開 GitHub repository 機密外洩情形的同儕審查長期研究
- Wiz Research, "GitHub Action tj-actions/changed-files Supply Chain Attack (CVE-2025-30066)," Wiz Blog (2025). https://www.wiz.io/blog/github-action-tj-actions-changed-files-supply-chain-attack-cve-2025-30066 — 針對「常見錯誤」中提及之 tag 重新指向入侵事件的獨立事後分析
- npm Docs, "Trusted publishing for npm packages." https://docs.npmjs.com/trusted-publishers/ — 不存儲
NPM_TOKEN、以 OIDC 為基礎發布套件的設定參考 - GitHub Changelog, "Introducing GitHub Secret Protection and GitHub Code Security" (2025). https://github.blog/changelog/2025-03-04-introducing-github-secret-protection-and-github-code-security/ — 「設計思維」中提及 2025 年 Advanced Security 重新包裝的資料來源
- GitHub Changelog, "GitHub Actions – OIDC integration with AWS no longer requires pinning of intermediate TLS certificates" (2023). https://github.blog/changelog/2023-07-13-github-actions-oidc-integration-with-aws-no-longer-requires-pinning-of-intermediate-tls-certificates/ — Terraform 範例中 thumbprint_list 註解的資料來源