waftester/waftester-action
GitHub: waftester/waftester-action
一个将 WAFtester 安全测试能力集成到 GitHub Actions 工作流中的 Action，支持 WAF 指纹识别、绕过测试和 SARIF 报告自动上传。
Stars: 0 | Forks: 0
# WAFtester Action
直接在您的 GitHub Actions 工作流中测试、指纹识别和绕过 Web Application Firewalls。
[](https://github.com/marketplace/actions/waftester-waf-security-testing)
[](https://waftester.com)
[](https://github.com/waftester/waftester/releases/tag/v2.9.47)
[](LICENSE)
[](https://github.com/waftester/waftester-action/actions/workflows/test-action.yml)
## 快速开始
```
permissions:
security-events: write # Required for SARIF upload to Security tab
steps:
- uses: waftester/waftester-action@v1
with:
target: https://app.example.com
```
就是这样。该 action 会下载二进制文件，运行扫描，
生成 SARIF 报告，并自动将其上传到
**Security → Code scanning**。
## 它的作用
1. 从最新的 [GitHub Release](https://github.com/waftester/waftester/releases) **下载** WAFtester Go 二进制文件。
2. **验证** 下载归档文件的 SHA-256 校验和。
3. 针对您的目标 URL **运行** 选定的扫描类型。
4. **生成** 包含 ruleId、CWE、严重性和位置的 SARIF 报告
针对每项发现。
5. **上传** SARIF 文件到 GitHub Code Scanning
(Security tab) — 可配置。
6. **写入** 包含发现表格、状态表情符号和可折叠修复指南的
丰富的 Markdown 作业摘要。
7. **设置输出** (`exit-code`、`bypass-count`、`sarif-file`、
`summary`、`version`) 供下游步骤使用。
支持 **Linux**、**macOS** 和 **Windows** 运行器
(x86_64 和 ARM64)。
## 使用示例
### 基础扫描
```
name: WAF Security Scan
on: [push, pull_request]
permissions:
security-events: write
jobs:
waf-scan:
runs-on: ubuntu-latest
steps:
- uses: waftester/waftester-action@v1
with:
target: https://app.example.com
```
### 完全自动评估
```
- uses: waftester/waftester-action@v1
id: waf
with:
target: https://app.example.com
scan-type: auto
fail-on-bypass: true
- if: steps.waf.outputs.bypass-count != '0'
run: |
echo "::error::${{ steps.waf.outputs.bypass-count }} WAF bypasses found"
echo "${{ steps.waf.outputs.summary }}"
```
### WAF 厂商检测
```
- uses: waftester/waftester-action@v1
with:
target: https://app.example.com
scan-type: vendor
```
### 特定攻击类别
```
- uses: waftester/waftester-action@v1
with:
target: https://app.example.com
args: '-types sqli,xss,cmdi --smart'
```
### 绕过发现
```
- uses: waftester/waftester-action@v1
with:
target: https://app.example.com
scan-type: bypass
args: '--smart --tamper-auto'
fail-on-bypass: true
```
### API Spec 扫描 (v2.9.1)
扫描 OpenAPI、Swagger、Postman、HAR、AsyncAPI、gRPC 或 GraphQL 规范中定义的每个端点：
```
# OpenAPI / Swagger
- uses: waftester/waftester-action@v1
with:
target: https://api.example.com
args: '--spec openapi.yaml'
# 带环境的 Postman Collection
- uses: waftester/waftester-action@v1
with:
target: https://api.example.com
args: '--spec collection.postman_collection.json --env staging.postman_environment.json'
# 来自 DevTools 的 HAR 记录
- uses: waftester/waftester-action@v1
with:
target: https://api.example.com
args: '--spec recording.har --intensity high'
# Dry-run 以预览扫描内容
- uses: waftester/waftester-action@v1
with:
target: https://api.example.com
args: '--spec openapi.yaml --dry-run'
```
### 计划每周审计
```
name: Weekly WAF Audit
on:
schedule:
- cron: '0 6 * * 1' # Every Monday 06:00 UTC
permissions:
security-events: write
jobs:
audit:
strategy:
matrix:
include:
- name: app
url: https://app.example.com
- name: api
url: https://api.example.com
runs-on: ubuntu-latest
steps:
- uses: waftester/waftester-action@v1
with:
target: ${{ matrix.url }}
scan-type: assess
sarif-category: 'waf-${{ matrix.name }}'
args: '-fp'
```
### 带评论的 PR 门禁
```
- uses: waftester/waftester-action@v1
id: waf
with:
target: https://staging.example.com
scan-type: auto
fail-on-bypass: true
- if: always() && github.event_name == 'pull_request'
uses: actions/github-script@v7
env:
BYPASS_COUNT: ${{ steps.waf.outputs.bypass-count }}
WAF_SUMMARY: ${{ steps.waf.outputs.summary }}
with:
script: |
const count = process.env.BYPASS_COUNT;
const summary = process.env.WAF_SUMMARY;
const status = count === '0' ? ':white_check_mark:' : ':red_circle:';
github.rest.issues.createComment({
owner: context.repo.owner,
repo: context.repo.repo,
issue_number: context.issue.number,
body: `## ${status} WAF Scan Results\n\n` +
`**Bypasses:** ${count}\n\n` +
summary
});
```
### JSON 输出 (无 SARIF)
```
- uses: waftester/waftester-action@v1
with:
target: https://app.example.com
format: json
output: results.json
upload-sarif: false
```
### 多目标矩阵
```
jobs:
scan:
strategy:
fail-fast: false
matrix:
include:
- target: https://staging.example.com
env: staging
- target: https://prod.example.com
env: production
runs-on: ubuntu-latest
steps:
- uses: waftester/waftester-action@v1
with:
target: ${{ matrix.target }}
sarif-category: 'waf-${{ matrix.env }}'
```
### 仅信息展示 (永不失败)
```
- uses: waftester/waftester-action@v1
with:
target: https://app.example.com
fail-on-bypass: false
fail-on-error: false
```
## 输入
| Input | Description | Required | Default |
|-------|-------------|----------|---------|
| `target` | 要扫描的目标 URL | **Yes** | — |
| `scan-type` | 扫描类型 (见下表) | No | `scan` |
| `version` | 要安装的 WAFtester 版本 | No | `latest` |
| `format` | 输出格式 (`sarif`, `json`, `jsonl`, `csv`, `md`, `html`, `pdf`)。对于 JUnit/CycloneDX/SonarQube/GitLab SAST，请使用 `args` 配合专用的导出标志。 | No | `sarif` |
| `output` | 输出文件路径 | No | `waftester-results.sarif` |
| `args` | 额外的 CLI 标志 (例如：`--smart --tamper-auto -types sqli,xss`) | No | — |
| `fail-on-bypass` | 发现绕过时失败步骤 (退出代码 1) | No | `false` |
| `fail-on-error` | 基础设施错误时失败步骤 (退出代码 2–6) | No | `true` |
| `upload-sarif` | 上传 SARIF 到 GitHub Code Scanning (Security tab) | No | `true` |
| `sarif-category` | SARIF 上传的类别 — 在 Security tab 中对结果进行分组 | No | `waftester` |
| `token` | 用于下载 releases 和上传 SARIF 的 GitHub token。默认的 `GITHUB_TOKEN` 用于 release 下载时的 API 速率限制和 SARIF 上传。仅当 WAFtester releases 仓库变为私有或受限时，才使用 PAT 覆盖。 | No | `${{ github.token }}` |
### 扫描类型
| `scan-type` | CLI Command | Description |
|-------------|-------------|-------------|
| `scan` | `waf-tester scan` | 标准 payload 扫描 (默认) |
| `auto` | `waf-tester auto` | 完全自动评估 |
| `bypass` | `waf-tester bypass` | 使用 tampers 进行绕过发现 |
| `assess` | `waf-tester assess` | 企业指标 (F1, MCC, FPR) |
| `vendor` | `waf-tester vendor` | WAF 指纹识别 (197 个签名) |
| `discover` | `waf-tester discover` | 端点发现与爬取 |
| `fuzz` | `waf-tester fuzz` | 内容/目录 fuzzing |
| `nuclei` | `waf-tester template` | 兼容 Nuclei 的模板扫描 |
| `custom` | (来自 `args`) | 通过 `args` 传递完整命令 |
## 输出
| Output | Description | Example |
|--------|-------------|---------|
| `exit-code` | WAFtester 退出代码 (见下表) | `0` |
| `bypass-count` | 发现的 WAF 绕过数量 | `12` |
| `sarif-file` | 生成的 SARIF 文件路径 | `waftester-results.sarif` |
| `summary` | 单行人类可读摘要 | `WAFtester found 12 WAF bypass(es)...` |
| `version` | 已安装的 WAFtester 版本 | `2.9.47` |
## 退出代码
该 action 保留了 WAFtester 的 7 个语义退出代码：
| Code | Meaning | `fail-on-bypass` | `fail-on-error` |
|------|---------|:-:|:-:|
| 0 | Clean — 未发现问题 | Pass | Pass |
| 1 | 发现绕过 | **Fail** (如果为 true) | Pass |
| 2 | 错误过多 (超过阈值) | Pass | **Fail** (如果为 true) |
| 3 | 配置错误 | Pass | **Fail** (如果为 true) |
| 4 | 目标不可达 | Pass | **Fail** (如果为 true) |
| 5 | 被中断 (超时/信号) | Pass | **Fail** (如果为 true) |
| 6 | 许可证违规 | Pass | **Fail** (如果为 true) |
默认情况下，`fail-on-bypass` 为 `false` (仅信息展示)，
`fail-on-error` 为 `true` (基础设施问题时失败)。将两者都设为
`true` 以进行严格的质量门禁。
## SARIF 集成
当 `upload-sarif` 为 `true` (默认) 且 `format` 为
`sarif` 时，该 action 会自动将结果上传到
**GitHub Code Scanning**，使用
[`github/codeql-action/upload-sarif@v4`](https://github.com/github/codeql-action)。
结果会出现在 **Security → Code scanning alerts** 下，包含：
- 规则 ID (例如：`sqli-SQLI003`, `xss-XSS001`)
- CWE 引用 (18 个映射类别)
- 严重级别 (error, warning, note)
- 包含请求/响应摘录的发现位置
- 用于跨运行去重的指纹
### 要求
- 仓库必须启用 **GitHub Advanced Security**
(公开仓库免费；私有仓库需要 GHAS 许可证)。
- 工作流必须声明 `permissions: security-events: write`。
- SARIF 文件必须小于 **10 MB**。大型扫描
(包含完整响应体的 2,800+ 个 payload) 可能会超过
此限制。通过限制 payload 类型
`-types sqli,xss` 或使用 `--smart` 模式来缓解。
### 经过认证的目标
对于身份验证后的目标，通过 `args` 传递 headers：
```
- uses: waftester/waftester-action@v1
with:
target: https://app.example.com
args: '-H "Authorization: Bearer ${{ secrets.TARGET_TOKEN }}"'
```
### 禁用 SARIF 上传
```
- uses: waftester/waftester-action@v1
with:
target: https://app.example.com
upload-sarif: false
```
### 不使用 GitHub Code Scanning
SARIF 上传需要
[GitHub Advanced Security](https://docs.github.com/en/get-started/learning-about-github/about-github-advanced-security)
(GHAS)。公开仓库免费获得此功能。私有仓库需要
GHAS 许可证 — 没有它，SARIF 上传会静默失败。
**如果您的仓库未启用 Code Scanning：**
```
- uses: waftester/waftester-action@v1
with:
target: https://app.example.com
upload-sarif: false # disable SARIF upload
format: sarif # still generates the file
fail-on-bypass: true # fail the workflow on bypasses
```
结果仍可通过以下方式获取：
- **Job Summary** — 总是写入工作流运行页面
(在 Actions → run → Summary 下可见)
- **SARIF artifact** — 下载原始文件以供本地审查
或导入第三方工具
- **Output variables** — `exit-code`、`bypass-count`、
`summary`，用于下游步骤
将 SARIF 保存为可下载的 artifact：
```
- uses: waftester/waftester-action@v1
id: waf
with:
target: https://app.example.com
upload-sarif: false
- uses: actions/upload-artifact@v4
if: always()
with:
name: waf-results
path: ${{ steps.waf.outputs.sarif-file }}
```
## 版本固定
```
# 推荐：floating major tag (获取最新的 v1.x.x)
- uses: waftester/waftester-action@v1
# 锁定到精确的 action release
- uses: waftester/waftester-action@v1.0.55
# 锁定 WAFtester binary version (action 自动下载)
- uses: waftester/waftester-action@v1
with:
version: '2.9.47'
# 锁定到 commit SHA (最高安全性)
# 替换为来自以下命令的实际 SHA：git rev-parse v1.0.55
- uses: waftester/waftester-action@
```
## 支持的运行器
| Runner | Architecture | Status |
|--------|-------------|--------|
| `ubuntu-latest` | x86_64 | Fully tested |
| `ubuntu-24.04` | x86_64 | Fully tested |
| `macos-latest` | ARM64 | Fully tested |
| `macos-13` | x86_64 | Supported |
| `windows-latest` | x86_64 | Fully tested |
| Self-hosted Linux | x86_64, ARM64 | Supported |
| Self-hosted macOS | ARM64 | Supported |
| Self-hosted Windows | x86_64 | Supported |
**要求：** `bash`, `curl`, `sha256sum` (或 `shasum`)。
所有 GitHub 托管的运行器默认都包含这些。
## 其他安装方式
此 GitHub Action 是运行 WAFtester 的几种方式之一：
| Method | Command | Best For |
|--------|---------|----------|
| **GitHub Action** | `- uses: waftester/waftester-action@v1` | CI/CD pipelines |
| **npm** | `npx @waftester/cli scan -u URL` | Quick install, MCP server |
| **Docker** | `docker run ghcr.io/waftester/waftester scan -u URL` | Containers |
| **Binary** | [Download from Releases](https://github.com/waftester/waftester/releases) | Direct install |
## 链接
- [**WAFtester CLI**](https://github.com/waftester/waftester)
— 包含完整文档的主项目
- [**Examples**](./examples/) — 6 个即用型工作流文件
- [**Changelog**](./CHANGELOG.md)
— action 发布说明和版本历史
- [**Security Policy**](./SECURITY.md)
— 漏洞报告
- [**npm Package**](https://www.npmjs.com/package/@waftester/cli)
— `npx @waftester/cli` 替代方案
## 许可证
[BSL 1.1](LICENSE) — 请参阅
[main project](https://github.com/waftester/waftester)
获取完整许可条款。将于
2030 年 1 月 31 日变更为 Apache 2.0。
标签：AppImage, C2日志可视化, CI/CD安全, CISA项目, DevSecOps, DOE合作, GitHub Action, GitHub项目, Go语言, Llama, Markdown报告, SARIF, WAF测试, WAF绕过, Web应用防火墙, 上游代理, 二进制校验, 安全扫描, 应用安全, 指纹识别, 日志审计, 时序注入, 程序破解, 结构化查询, 自动化安全