cpeoples/ansible-security-scanner
GitHub: cpeoples/ansible-security-scanner
一款专注于Ansible代码的静态安全扫描器，用于在开发阶段检测恶意代码、硬编码凭据和供应链风险等威胁。
Stars: 2 | Forks: 0
针对 Ansible Playbook、Role、Collection、任务文件、变量和清单的静态 SAST 扫描器。检测恶意代码、远程代码执行、命令与模板注入、硬编码凭据、供应链风险、未授权的云访问、横向移动以及反向 Shell。输出 SARIF、CycloneDX SBOM、GitLab SAST、JUnit、JSON、HTML 和 Markdown 格式的报告，并提供修复指导。检查结果映射至 CWE、OWASP Top 10、OWASP ASVS、MITRE ATT&CK、NIST 和 CIS。CI 原生支持，具备自动修复能力，DevSecOps 就绪。
**1091 条规则**，涵盖 **31 个类别** —— 全部通过 YAML 模式插件自动发现。
**412 严重**，528 高，131 中等，19 低。[在仪表板上查看按类别的细分。](https://cpeoples.github.io/ansible-security-scanner/dashboard/)
## 目录
- [安装](#installation)
- [快速开始](#quick-start)
- [检测内容](#what-it-detects)
- [项目结构](#project-structure)
- [文档](#documentation)
- [要求](#requirements)
- [常见问题](#faq)
- [贡献](#contributing)
- [安全](#security)
- [许可证与署名](#license--attribution)
### 构建方式
## 安装
```
pip install ansible-security-scanner
```
需要 Python 3.11+。它将在您的 PATH 上安装一个 `ansible-security-scanner` 命令。
## 快速开始
运行 `pip install ansible-security-scanner` 后，尝试以下示例：
```
# autofix - emit a unified diff of the changes the scanner would make
ansible-security-scanner
# 7. CI/CD: post a concise findings comment on the current PR / MR
ansible-security-scanner --directory ansible/ --output results.sarif
# (auto-detects GitHub Actions vs. GitLab CI; works on self-hosted).
ansible-security-scanner --directory ansible/ --output gl-sast-report.json
# Full list of flags & examples:
ansible-security-scanner --directory ansible/ --output-per-file --format markdown
# Generate content
ansible-security-scanner --directory ansible/ --compliance CIS-Secrets
# Download theme (first time only)
ansible-security-scanner --files site.yml --fix --fix-output fixes.patch
# Serve locally
# Now, counting the lines:
ansible-security-scanner --gh-comment # inside a pull_request workflow
ansible-security-scanner --gl-comment # inside a merge_request_event pipeline
# Line 1: "Scan the current directory, print a Markdown report to the terminal"
ansible-security-scanner --help
```
**智能默认值**
- **未指定 `--format`？** 如果您传入 `--output report.sarif`，格式将从扩展名推断（`.sarif` -> SARIF，`.json` -> JSON，`.md`/`.markdown` -> Markdown，`.html`/`.htm` -> HTML，`.xml` -> XML，`.yml`/`.yaml` -> YAML，`.csv` -> CSV）。显式的 `--format` 总是优先；如果两者不一致，扫描器会记录警告，以便管道配置错误时明显失败。
- **未指定 `--output` 但指定了 `--output-per-file`？** 报告将放置在 `./security-reports/` 目录下（一个自文档化目录；可将其添加到 `.gitignore`）。
- **`--output` 会覆盖输入文件？** 扫描器会拒绝并以退出码 2 退出 - 当在格式推断为 `.yml` 时运行 `--files site.yml --output site.yml`，这是一个常见的易错点。
**从源代码签出？** 请使用 `python main.py ...` 而不是已安装的 CLI - 它只是围绕相同入口点的一个薄封装。
## 检测内容
扫描器自带 1091 条规则，涵盖 31 个自动发现的类别。亮点：
**恶意代码与后渗透利用**
- 反向 Shell、Web Shell 部署、系统攻陷、横向移动
- 反取证、混淆与规避、隧道技术、攻击性工具
**代码执行与注入**
- 命令注入、模板注入、变量注入
- Jinja 查找 RCE、危险的 Ansible 模块、二进制投放
**密钥与供应链**
- 硬编码凭据和 API 密钥
- 供应链风险（Galaxy Collection、临时下载、不受信任的 URL）
- 数据泄露、Webhook 暴露、外部 URL 通信
**云、IaC 和平台加固**
- 未授权的云访问、Kubernetes 不安全规格
- 权限提升、不安全权限、环境劫持
- 不安全通信（TLS、SSH、明文协议）
**AI/ML 与运维规范**
- AI/ML 供应链和提示注入风险
- Ansible 运维规范、Ansible 特定反模式、运维安全
每条规则都包含严重性、框架映射（CWE、OWASP Top 10、OWASP ASVS、MITRE ATT&CK、NIST、CIS Controls）、漏洞示例和修复示例以及修复指导。检查结果通过跨文件污染跟踪在文件间进行去重。请在[规则仪表板](https://cpeoples.github.io/ansible-security-scanner/dashboard/)上查看按类别和严重性的细分。
## 项目结构
```
ansible-security-scanner/ # repo root (hyphenated - matches PyPI)
├── pyproject.toml # packaging + pytest + hatch-vcs
├── README.md
├── CONTRIBUTING.md
├── RELEASING.md # maintainer release runbook
├── LICENSE / NOTICE # Apache-2.0 + attribution terms
├── main.py # local dev entry point (py main.py ...)
├── .github/workflows/ # CI, release, docs workflows
├── .hugo/ # Hugo documentation site
│ ├── scripts/build_docs.py # Generates Hugo content from docs/ + patterns
│ └── content/ # Generated .md pages (do not edit by hand)
├── docs/ # Long-form prose docs (source of truth)
│ ├── assets/ # Images & SVGs the README references
│ ├── cli.md # CLI Reference (and exit codes, suppressions, dedup)
│ ├── environment.md # Environment Variables
│ ├── api.md # Programmatic API
│ ├── output-formats.md
│ ├── allowlist.md
│ ├── ci-cd.md
│ ├── mr-pr-comments.md
│ ├── custom-patterns.md
│ ├── scoring.md
│ ├── testing.md
│ ├── limitations.md
│ └── releasing.md
├── src/
│ └── ansible_security_scanner/ # the Python package
│ ├── cli.py # CLI (--directory, --fix, --compliance, ...)
│ ├── scanner.py # Multi-pass orchestrator
│ ├── file_scanner.py # Per-file rules (line patterns, AST walkers)
│ ├── taint_tracker.py # Cross-file taint analysis
│ ├── fix_proposer.py # Dry-run unified-diff patch generator
│ ├── dependency_collector.py # SBOM inventory
│ ├── suppressions.py # Inline `# nosec` parser
│ ├── models.py # SecurityFinding, ScanReport, SecurityScore
│ ├── score_calculator.py # Severity-weighted scoring
│ ├── patterns_manager.py # Loads pattern YAML plugins
│ ├── patterns/ # 29+ YAML pattern plugins (auto-discovered)
│ ├── remediations/ # One module per category
│ └── formatters/ # markdown, json, xml, yaml, csv, html, junit, sarif, gitlab_sast, cyclonedx
└── tests/
├── test_integration.py # End-to-end scanner tests
├── test_formatters.py # Formatter unit tests
├── test_remediations.py # Remediation generator unit tests
└── playbooks/
├── bad_example.yml # Triggers every rule (100% coverage)
├── clean_example.yml # Zero findings (false-positive guard)
├── multi_example_bad/ # 6-file role fixture (cross-file taint)
└── multi_example_clean/ # 6-file hardened role fixture (zero findings)
```
## 文档
长篇文档按主题划分。每个页面都是 [`docs/`](docs/) 目录下的独立 Markdown 文件 - GitHub 会内联渲染它们，而 [GitHub Pages](#documentation-site) 上的 Hugo 站点使用导航侧边栏和搜索提供相同内容。
| 主题 | 来源 |
|---|---|
| **CLI 标志、退出码、抑制、跨文件去重** | [`docs/cli.md`](docs/cli.md) |
| **环境变量（认证、默认值、`--changed-files`）** | [`docs/environment.md`](docs/environment.md) |
| **Python API 编程接口** | [`docs/api.md`](docs/api.md) |
| **输出格式（Markdown、JSON、SARIF、GL-SAST、SBOM 等）** | [`docs/output-formats.md`](docs/output-formats.md) |
| **允许列表 / 抑制检查结果** | [`docs/allowlist.md`](docs/allowlist.md) |
| **CI/CD 集成（GitLab CI、GitHub Actions）** | [`docs/ci-cd.md`](docs/ci-cd.md) |
| **MR / PR 评论（自动检测，支持自托管）** | [`docs/mr-pr-comments.md`](docs/mr-pr-comments.md) |
| **添加自定义模式** | [`docs/custom-patterns.md`](docs/custom-patterns.md) |
| **安全评分模型** | [`docs/scoring.md`](docs/scoring.md) |
| **测试** | [`docs/testing.md`](docs/testing.md) |
| **静态分析的局限性** | [`docs/limitations.md`](docs/limitations.md) |
| **发布** | [`docs/releasing.md`](docs/releasing.md) |
### 文档站点
完整文档是从 [`docs/`](docs/) 下的 Markdown 文件加上模式 YAML 插件自动生成的，并在每次推送到 `main` 分支时通过 Hugo + GitHub Pages 发布。
构建流水线 (`.github/workflows/scanner-docs.yml`) 执行：
1. `build_docs.py` - 将每个 `docs/
.md` 文件复制到 Hugo 的 `content/` 目录，并添加适当的 front-matter，并为每个模式类别生成一个规则表页面。
2. Hugo 使用 [Relearn](https://mcshelby.github.io/hugo-theme-relearn/) 主题构建静态站点。
3. 站点部署到 GitHub Pages。
要进行本地预览：
```
# Line 2: "Scan a project and write a SARIF report for GitHub Code Scanning"
python .hugo/scripts/build_docs.py
# Line 3: "CI/CD: emit a GitLab SAST report (auto-populates the Security Dashboard)"
cd .hugo
curl -sL https://github.com/McShelby/hugo-theme-relearn/archive/refs/heads/main.tar.gz | tar -xz -C themes/
mv themes/hugo-theme-relearn-main themes/hugo-theme-relearn
# Line 4: "One Markdown report per scanned playbook (lands under ./security-reports/)"
hugo server
```
## 要求
- Python 3.11+
- PyYAML >= 6.0
- Jinja2 >= 3.0
- httpx >= 0.27 （仅 `--github-comment` / `--gitlab-comment` 使用）
从源代码进行开发工作：
```
pip install -e ".[dev]"
```
## 常见问题
**Ansible Security Scanner 扫描什么？**
Ansible Playbook、Role、Collection、任务文件、变量和清单。它检测恶意代码、远程代码执行、命令与模板注入、硬编码凭据、供应链风险、未授权的云访问、横向移动以及反向 Shell。
**这与 `ansible-lint` 有何不同？**
`ansible-lint` 关注风格和最佳实践。Ansible Security Scanner 是一个专注于安全信号的 SAST 工具：数据流污染跟踪、供应链风险、密钥以及映射到 OWASP、CWE、NIST、CIS 和 MITRE ATT&CK 的已知攻击模式。
**它可以在 CI/CD 中运行吗？**
可以。它输出 SARIF、CycloneDX SBOM、GitLab SAST、JUnit、JSON、HTML 和 Markdown。支持 GitHub Actions、GitLab CI 和 Jenkins，并且可以自动发布 PR/MR 评论。
**它是免费使用的吗？**
是的。Ansible Security Scanner 采用 Apache-2.0 许可，可免费用于商业用途。
## 安全
本仓库在每次推送和拉取请求时运行三项 GitHub 原生安全检查：
- **Dependabot** ([`.github/dependabot.yml`](.github/dependabot.yml)) - 每周为 `pip` 和 `github-actions` 生态系统提交更新 PR，加上带外安全公告。
- **CodeQL**（默认设置，在仓库设置中配置）- 对 `src/ansible_security_scanner/` 中的 Python 代码进行 SAST。
- **密钥扫描 + 推送保护** - 对跟踪文件中的凭据类字符串发出警报。
### 为什么某些路径被排除在密钥扫描之外
因为这*就是*一个安全扫描器，所以仓库中包含了两个在结构上必需、但看起来像真实密钥的语料库：
1. **精心策划的负例测试用例** (`tests/playbooks/bad_example.yml` 和 `tests/playbooks/multi_example_bad/**`) - 集成测试将这些喂给扫描器以断言每条规则类正确触发。它们包含故意设置的硬编码凭据、虚假的 AWS 密钥和嵌入的 SQS URL；这里没有真实的凭据。
2. **模式包 `vulnerable_examples:` 块** (`src/ansible_security_scanner/patterns/**`) - 规则定义按设计记录了每条规则旨在匹配的字面字符串。这些块被渲染到发布在 的生成规则文档中。
这两个表面都通过 [`.github/secret_scanning.yml`](.github/secret_scanning.yml) 被排除，其中每个条目都标注了其存在的结构原因。
### 隐私
扫描器在本地运行，不会向外发送数据。没有遥测、没有分析、没有使用情况 ping、也没有远程规则获取。发布评论是唯一的出站网络调用，并且仅在您明确传递 `--mr-comment`（或等效参数）和显式 token 时才触发；目标主机是您指向的 GitLab 或 GitHub 实例。
### 报告漏洞
请通过 [安全](https://github.com/cpeoples/ansible-security-scanner/security/advisories/new) 标签页而非公开 issue 开启一个私密的安全公告。扫描器本身的漏洞（例如，允许攻击者通过 MR 评论泄露未脱敏密钥的代码路径）在范围内；而*被扫描器检测到的 Ansible Playbook 中的漏洞*不在范围内 - 这些属于 Playbook 的维护者。
## 许可证与署名
本项目采用 [Apache License, Version 2.0](。
- 项目名称 **"Ansible Security Scanner"** / `ansible-security-scanner` 是原始作者的保留标识（Apache-2.0 §6）。欢迎您 fork - 但请使用不同的名称。
- Apache-2.0 包含明确的 **专利授权** 和 **报复条款**：如果您就与该软件相关的专利起诉本项目或其贡献者，您在许可证下的权利将自动终止。
有关完整的署名条款，请参见 [`NOTICE`](NOTICE)；有关 Apache-2.0 许可证文本，请参见 [`LICENSE`](LICENSE)。
## AI 辅助声明
本项目遵循 [Ansible 社区 AI 政策](https://docs.ansible.com/projects/ansible/latest/community/ai_policy.html)。
LLM 工具已帮助完成了脚手架搭建、重构、测试生成和文档编写。所有这些内容在提交前都经过人工审查、编辑和测试。规则、威胁模型和设计决策是我的，并且每个 PR 在合并前都运行完整的测试、代码检查和安全检查。 标签：AMSI绕过, Ansible, Ansible playbook安全, CI/CD安全, CycloneDX SBOM, DevSecOps, GitLab SAST, Llama, OpenSSF, SARIF, SAST, URL收集, 上游代理, 基础设施即代码安全, 威胁检测, 安全合规, 安全扫描, 安全报告, 安全最佳实践, 安全测试, 开源框架, 持续集成, 攻击性安全, 时序注入, 盲注攻击, 硬编码凭证检测, 结构化查询, 网络代理, 自动化安全, 跌倒检测, 软件物料清单, 远程代码执行检测, 逆向工具, 静态应用安全测试
