ansible-security-scanner - 🛡️ Static security scanner (SAST) for Ansible play

项目说明

<di="center">
<a href="
<picture>
<source media="(prefers-color-scheme: dark)" srcset="
<img src=" alt="Ansible Security Scanner" width="560">
</picture>
</a>
</div>
<!-- BADGES_START - stripped from the Hugo docs build; see .hugo/scripts/build_docs.py -->
<p align="center">
<a href=" src=" alt="CI" /></a>&nbsp;&nbsp;
<a href=" src=" alt="OpenSSF Baseline Level 3" /></a>&nbsp;&nbsp;
<a href=" src=" alt="OpenSSF Scorecard" /></a>&nbsp;&nbsp;
<a href=" src=" alt="CodeQL" /></a>&nbsp;&nbsp;
<a href=" src=" alt="pip-audit" /></a>&nbsp;&nbsp;
<a href=" src=" alt="OWASP Listed" /></a>&nbsp;&nbsp;
<a href=" src=" alt="Listed on Awesome Ansible" /></a>&nbsp;&nbsp;
<a href="src/ansible_security_scanner/patterns"><img src=" alt="Rules" /></a>&nbsp;&nbsp;
<a href=" src=" alt="PyPI" /></a>&nbsp;&nbsp;
<a href=" src=" alt="SLSA Build Level 3" /></a>&nbsp;&nbsp;
<a href=" src=" alt="CycloneDX SBOM" /></a>&nbsp;&nbsp;
<a href=" src=" alt="Sigstore " /></a>
</p>
<!-- BADGES_END -->

Static SAST scanner for Ansible playbooks, roles, collections, task files, vars, and in. Detects malicious code, RCE, command and template injection, hardcoded credentials, supply-chain risk, unauthorized cloud access, lateral mo, and reverse shells. Outputs SARIF, CycloneDX SBOM, GitLab SAST, JUnit, JSON, HTML, and Markdown reports with remediation guidance. Findings map to CWE, OWASP Top 10, OWASP AS ATT&CK, NIST, and CIS. CI-nati, De.

<!--RULES-->1165<!--/RULES--> rules across <!--CATS-->31<!--/CATS--> categories -- all auto-discovered from YAML pattern plugins.

<!--CRIT-->460<!--/CRIT--> critical, <!--HIGH-->551<!--/HIGH--> high, <!--MED-->134<!--/MED--> medium, <!--LOW-->19<!--/LOW--> low. Per-category breakdown on the dashboard.

> [!NOTE]
> Scope. This is a *static, pattern-based* scanner - one layer in a defense-in-depth strategy. Pair it with the runtime controls you already trust (AAP/AWX appro, execution-en lockdown, network egress policy, code review) for full co. See Limitations for the specific classes of issue this layer cannot catch on its own.

Contents

Installation

Quick Start

What it detects

Project Structure

Documentation

Requirements

FAQ

Contributing

Security

License & Attribution

Built with

<di="display:flex !important;flex-wrap:wrap;align-items:center;gap:1.25rem;margin:0.5rem 0 1rem;">
<a href=" title="Python" style="display:inline-flex !important;align-items:center;"><img src="docs/assets/python.svg" alt="Python" height="28" style="display:inline-block;" /></a>
&nbsp;
<a href=" title="YAML" style="display:inline-flex !important;align-items:center;"><img src="docs/assets/yaml.svg" alt="YAML" height="28" style="display:inline-block;" /></a>
&nbsp;
<a href=" title="Pytest" style="display:inline-flex !important;align-items:center;"><img src="docs/assets/pytest.svg" alt="Pytest" height="28" style="display:inline-block;" /></a>
&nbsp;
<a href=" title="Hugo" style="display:inline-flex !important;align-items:center;"><img src="docs/assets/hugo.svg" alt="Hugo" height="28" style="display:inline-block;" /></a>
&nbsp;
<a href=" title="GitLab CI" style="display:inline-flex !important;align-items:center;"><img src="docs/assets/gitlab.svg" alt="GitLab CI" height="28" style="display:inline-block;" /></a>
&nbsp;
<a href=" title="GitHub Actions" style="display:inline-flex !important;align-items:center;"><img src="docs/assets/githubactions.svg" alt="GitHub Actions" height="28" style="display:inline-block;" /></a>
</div>

Installation

Requires Python 3.11+. Installs an ansible-security-scanner command on your PATH.

Homebrew

A via the cpeoples/homebrew-tap Homebrew tap.

Snap

Published to the Snap Store. The snap is strictly confined: it scans content under your home directory out of the box. To scan a mounted dri /mnt or /media, connect the remo interface once:

To scan system paths such as /etc/ansible or /opt, install via pip, pipx, or Homebrew instead.

pre-commit

Add to your .pre-commit-config.yaml:

Two hook IDs are exposed:

ansible-security-scanner — scans only the staged YAML / *.j2 / *.cfg files. Runs on every commit.

ansible-security-scanner-all — scans the full repository tree. Wired to the pre-push and manual stages so it doesn't fire on every commit; trigger it with pre-commit run --hook-stage pre-push ansible-security-scanner-all or in CI.

GitHub Actions

Scan on every push and pull request and surface findings inline in the Security
tab and on the PR diff:

The action installs the pinned release, scans, and uploads SARIF to code
scanning. Set fail-on-findings: false to report without failing the build, or
upload-sarif: false with a format: of your choice to write another report
type. See CI/CD integration for the raw-CLI form and other
platforms.

Quick Start

After installing, try one of these:

Smart defaults

No --format given? If you pass --output report.sarif, the format

is inferred from the extension (.sarif -> SARIF, .json -> JSON,
.md/.markdown -> Markdown, .html/.htm -> HTML, .xml -> XML,
.yml/.yaml -> YAML, .csv -> CSV). An explicit --format always
wins; the scanner logs a warning if the two disagree so pipeline
misconfigurations fail loudly.

No --output given with --output-per-file? Reports land under

./security-reports/ (a self-documenting directory; add it to
.gitignore).

--output would o an input file? The scanner refuses and

exits with code 2 - common footgun when running
--files site.yml --output site.yml with .yml-as-format inference.

Working from a source checkout? Use python main.py ... instead of the
installed CLI - it's a thin shim around the same entry point.

What it detects

The scanner ships <!--RULES-->1165<!--/RULES--> rules across <!--CATS-->31<!--/CATS--> auto-discovered categories. Highlights:

Malicious code and post-exploitation

Reverse shells, webshell deployment, system compromise, lateral mo

Anti-forensics, obfuscation and e, tunneling, offensi

Code execution and injection

Command injection, template injection, injection

Jinja lookup RCE, dangerous Ansible modules, binary planting

Secrets and supply chain

Hardcoded credentials and API keys

Supply-chain risk (Galaxy collections, ad-hoc downloads, untrusted URLs)

Data exfiltration, webhook exposure, external URL contact

Cloud, IaC, and platform hardening

Unauthorized cloud access, Kubernetes insecure specs

Pri escalation, unsafe permissions, en hijacking

Insecure communication (TLS, SSH, plaintext protocols)

AI/ML and operational hygiene

AI/ML supply-chain and prompt-injection risks

Ansible hygiene, Ansible-specific anti-patterns, operational security

Every rule includes se, framework mappings (CWE, OWASP Top 10, OWASP AS ATT&CK, NIST, CIS Controls), and remediated examples, and remediation guidance. Findings are deduplicated across files taint tracking. See the rule dashboard for a per-category, per-se breakdown.

Project Structure

Documentation

The long-form documentation is split by topic. Each page is a standalone
Markdown file in docs/ - GitHub renders them inline, and the
Hugo site at GitHub Pages serves the same content
with a na sidebar and search.

| Topic | Source |
|---|---|
| CLI flags, exit codes, suppressions, cross-file dedup | docs/cli.md |
| En (auth, defaults, --changed-files) | docs/en.md |
| Programmatic Python API | docs/api.md |
| Output formats (Markdown, JSON, SARIF, GL-SAST, SBOM, ...) | docs/output-formats.md |
| Allowlist / suppressing findings | docs/allowlist.md |
| CI/CD integration (GitLab CI, GitHub Actions) | docs/ci-cd.md |
| MR / PR comments (auto-detected, self-hosted-aware) | docs/mr-pr-comments.md |
| Adding custom patterns | docs/custom-patterns.md |
| Security score model | docs/scoring.md |
| Testing | docs/testing.md |
| Limitations of static analysis | docs/limitations.md |
| Releasing | docs/releasing.md |

Documentation site

Full documentation is auto-generated from the docs/ Markdown
files plus the pattern YAML plugins, and published via Hugo + GitHub
Pages on every push to main.

The build pipeline (.github/workflows/scanner-docs.yml) runs:

1. build_docs.py - copies each docs/<slug>.md into Hugo's content/
with appropriate front-matter, and generates one rule-table page per
pattern category.
2. Hugo builds a static site with the
Relearn theme.
3. The site is deployed to GitHub Pages.

To preview locally:

Requirements

Python 3.11+

PyYAML >= 6.0

Jinja2 >= 3.0

httpx >= 0.27 (used by --github-comment / --gitlab-comment only)

For de work from source:

FAQ

What does Ansible Security Scanner scan?

Ansible playbooks, roles, collections, task files, vars, and in. It
detects malicious code, RCE, command and template injection, hardcoded
credentials, supply-chain risk, unauthorized cloud access, lateral mo,
and reverse shells.

How is this different from ansible-lint?

ansible-lint focuses on style and best practices. Ansible Security Scanner
is a SAST tool focused on security signals: dataflow taint tracking,
supply-chain risk, secrets, and known attack patterns mapped to OWASP, CWE,
NIST, CIS, and MITRE ATT&CK.

Does it run in CI/CD?

Yes. It outputs SARIF, CycloneDX SBOM, GitLab SAST, JUnit, JSON, HTML, and
Markdown. GitHub Actions, GitLab CI, and Jenkins are all supported, and
PR/MR comments can be posted automatically.

Is it free to use?

Yes. Ansible Security Scanner is Apache-2.0 licensed and free to use
commercially.

Contributing

See CONTRIBUTING.md for the full de
walkthrough, pattern-authoring guide, and PR checklist.

TL;DR for a first-time clone:

Common contribution paths:

1. Add a security pattern - drop a YAML plugin in
src/ansible_security_scanner/patterns/ (auto-discovered at startup).
See §3 of CONTRIBUTING.md
for the schema and steps.
2. Add a remediation generator - create a module in
src/ansible_security_scanner/remediations/, then wire it into
remediation_generator.py.
3. Add an output formatter - subclass base.BaseFormatter under
src/ansible_security_scanner/formatters/ and register it in
utils.get_formatter_class.
4. Run the gates before opening a PR - python task.py test (full
suite), python task.py lint, python task.py build.

Security

This repository runs three GitHub-nati checks on every push
and pull request:

Dependabot (.github/dependabot.yml) -

weekly update PRs for pip and github-actions ecosystems, plus
out-of-band security ad.

CodeQL (default setup, configured in repo settings) - SAST against

the Python in src/ansible_security_scanner/.

Secret scanning + push protection - alerts on credential-shaped

strings in tracked files.

Why some paths are excluded from secret scanning

Because this *is* a security scanner, the repo ships two structurally
required corpora that look exactly like real secrets:

1. Hand-curated negati (tests/playbooks/bad_example.yml
and tests/playbooks/multi_example_bad/**) - the integration tests
feed these to the scanner to assert each rule class fires correctly.
They contain deliberate hardcoded credentials, fake AWS keys, and
embedded SQS URLs; nothing here is a real credential.
2. Pattern-pack : blocks
(src/ansible_security_scanner/patterns/**) - rule definitions
document, by design, the literal strings each rule is meant to
match. These blocks are rendered into the generated rule docs that
ship at <

Both surfaces are excluded via .github/secret_scanning.yml,
where each entry is annotated with the structural reason it's there.

Privacy

The scanner runs locally and does not phone home. There is no
telemetry, no analytics, no usage pings, and no remote rule fetch.
Comment posting is the only outbound network call, and it only
fires when you pass --mr-comment (or the equi) with an
explicit token; the target host is the GitLab or GitHub instance
you point it at.

Reporting a

Open a private security ad via the
Security tab
rather than a public issue. in the scanner itself
(e.g. a code path that lets an attacker leak unredacted secrets through
an MR comment) are in scope; in *Ansible playbooks
detected by the scanner* are not - those belong to the playbook's
maintainer.

License & Attribution

This project is licensed under the Apache License, 2.0.

**If you use, fork, embed, or build on this project, please retain attribution
to the original repository and contributors.** The NOTICE file at
the repo root spells out exactly what is required.

In plain English:

You can use this scanner commercially, modify it, embed it in larger tools,

or build a paid product on top of it - no fee, no permission needed.

You must keep the LICENSE and NOTICE files in any redistribution.

If you fork this project or ship a deri work (for example, a

rebranded scanner, a hosted service, or a SaaS wrapper), you must state
that it is derived from Ansible Security Scanner by Chris Peoples and
link back to the original repository:
<

The project name "Ansible Security Scanner" / ansible-security-scanner

is a reserved mark of the original author (Apache-2.0 §6). Your fork is
welcome - under a different name.

Apache-2.0 includes an explicit patent grant and a retaliation clause:

if you sue the project or its contributors over a patent related to the
software, your rights under the license terminate automatically.

See NOTICE for the full attribution terms and
LICENSE for the Apache-2.0 text.

AI-assistance disclosure

This project follows the
Ansible community AI policy.
LLM tooling has helped with scaffolding, refactoring, test generation,
and documentation. All of it is re, edited, and tested by a human
before being committed. The rules, threat models, and design decisions
are mine, and every PR runs the full test, lint, and security gate
before merge.

项目信息

开发语言：Python

Star 数：10

技术要点

该项目属于安全软件方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕🛡️ Static security scanner (SAST) for Ansible playbooks, roles, and collections. 1,000+ rules across 30+ categories detecting malicious code, RCE, hardcoded credentials, and supply-chain risk. Outputs SARIF, CycloneDX SBOM, and GitLab SAST. SLSA Build Level 3, Sigstore-signed.展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。