ansible-security-scanner 0.1.13

Security scanner for Ansible playbooks - detects malicious code, credential exposure, offensive tooling, data exfiltration, and 500+ other security anti-patterns.

Ansible Security Scanner

A security scanner for Ansible playbooks. Detects malicious code, unauthorized cloud access, offensive tooling, reverse shells, data exfiltration, and 500+ additional security anti-patterns. Generates detailed reports with remediation guidance.

1091 rules across 31 categories -- all auto-discovered from YAML pattern plugins.

[!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 approval gates, execution-environment lockdown, network egress policy, code review) for full coverage. See Limitations for the specific classes of issue this layer cannot catch on its own.

Contents

• Installation
• Quick Start
• Project Structure
• Documentation
• Requirements
• Contributing
• Security
• License & Attribution

Built with

         

Installation

pip install ansible-security-scanner

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

Quick Start

After pip install ansible-security-scanner, try one of these:

# 1. Scan the current directory, print a Markdown report to the terminal
ansible-security-scanner

# 2. Scan a project and write a SARIF report for GitHub Code Scanning
ansible-security-scanner --directory ansible/ --output results.sarif

# 3. CI/CD: emit a GitLab SAST report (auto-populates the Security Dashboard)
ansible-security-scanner --directory ansible/ --output gl-sast-report.json

# 4. One Markdown report per scanned playbook (lands under ./security-reports/)
ansible-security-scanner --directory ansible/ --output-per-file --format markdown

# 5. Only fail the build on secrets-related findings
ansible-security-scanner --directory ansible/ --compliance CIS-Secrets

# 6. Dry-run autofix - emit a unified diff of the changes the scanner would make
ansible-security-scanner --files site.yml --fix --fix-output fixes.patch

# 7. CI/CD: post a concise findings comment on the current PR / MR
#    (auto-detects GitHub Actions vs. GitLab CI; works on self-hosted).
ansible-security-scanner --gh-comment    # inside a pull_request workflow
ansible-security-scanner --gl-comment    # inside a merge_request_event pipeline

# Full list of flags & examples:
ansible-security-scanner --help

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 overwrite 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.

Project Structure

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)

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 navigation sidebar and search.

Topic	Source
CLI flags, exit codes, suppressions, cross-file dedup	docs/cli.md
Environment variables (auth, defaults, --changed-files)	docs/environment.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:

# Generate content
python .hugo/scripts/build_docs.py

# Download theme (first time only)
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

# Serve locally
hugo server

Requirements

• Python 3.11+
• PyYAML >= 6.0
• Jinja2 >= 3.0
• httpx >= 0.27 (used by --github-comment / --gitlab-comment only)

For development work from source:

pip install -e ".[dev]"

Contributing

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

TL;DR for a first-time clone:

git clone --recurse-submodules https://github.com/cpeoples/ansible-security-scanner.git
cd ansible-security-scanner
python -m venv .venv && source .venv/bin/activate
python task.py install        # editable install + test/lint/build deps
python task.py test           # run the full pytest suite
python task.py scan ./tests/playbooks/bad_example.yml   # try the scanner locally

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 validation 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-native security 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 advisories.
• 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 negative fixtures (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 vulnerable_examples: 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 https://cpeoples.github.io/ansible-security-scanner/.

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

Reporting a vulnerability

Open a private security advisory via the Security tab rather than a public issue. Vulnerabilities in the scanner itself (e.g. a code path that lets an attacker leak unredacted secrets through an MR comment) are in scope; vulnerabilities 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, Version 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 derivative 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: https://github.com/cpeoples/ansible-security-scanner.
• 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.