Secure development practices

This page indexes secure development practices for Ansible projects. Follow the linked documentation for full details.

For vulnerability reporting and disclosure processes, see the Ansible security policy and the Ansible vulnerability management and incident response policy. For the complete Developer Guide, see the Ansible developer documentation.

Secure module and plugin development 

Follow these guidelines when developing Ansible modules and plugins to avoid common security pitfalls.

Following Ansible conventions covers secure command execution (run_command instead of subprocess), masking sensitive data with no_log, and input validation.
Argument spec covers defining and validating module arguments to enforce type safety and reject unexpected input.
Ansible Reference: Module Utilities documents secure utilities including fetch_url for TLS-verified HTTP requests and run_command for safe shell execution.
Conventions, tips, and pitfalls covers conventions for error handling, return values, and idempotent operations.
Developing plugins covers plugin development guidelines for all plugin types.
Handling secrets in modules and plugins covers registering secrets so they are masked in Ansible output, marking plugin options as secret, and callback plugin responsibilities.

Developing collections covers collection development, including namespace requirements and packaging.
Collection structure documents the required file structure for collections.

Protecting sensitive data with Ansible vault covers encrypting sensitive data such as passwords, keys, and credentials with Ansible Vault.

See GitHub supply chain security for background on dependency graphs, advisories, and SBOM generation.

Integrate automated vulnerability scanning (such as Dependabot) into CI/CD pipelines.
Pin dependencies by hash in build and release pipelines to prevent supply-chain substitution attacks.
Maintain a Software Bill of Materials (SBOM) for all released artifacts.
Address Critical and High severity dependency vulnerabilities within the same timelines as first-party code.

See Security hardening for GitHub Actions for the full GitHub guide on securing workflows.

Pin GitHub Actions by commit SHA, not by mutable tag, to prevent supply-chain attacks through compromised actions.
Use restricted permissions (least privilege) on workflow tokens by setting explicit permissions: blocks.
Configure GitHub Rulesets (replacement for branch protections) and mandatory code review on all release branches.

See GitHub artifact attestations for GitHub’s built-in SLSA provenance support.

Follow SLSA Level 1 or higher practices for build artifact provenance.
Execute builds in hosted, ephemeral environments and generate provenance metadata alongside artifacts.
Sign all releases with project-controlled keys.
Collections should be built using automation, such as GitHub Actions or Zuul, and triggered by Git tag events. Do not build manually.
Enable GitHub immutable releases.

Maintain a SECURITY.md file in the root directory of all project repositories documenting the vulnerability reporting process. Use the SECURITY.md template from the ansible-community/project-template repository.
Pursue OpenSSF Best Practices Badge certification for ansible-core and key collections.
Run OpenSSF Scorecard regularly and address findings to maintain a strong security posture.
Follow the OpenSSF CRA Readiness Guide for practical security practices aligned with the EU Cyber Resilience Act.

For discussion about the EU Cyber Resilience Act and how it applies to the Ansible ecosystem, see the CRA tag on Ansible Forum.

To follow changes and suggest improvements to Ansible security practices, see the infra-and-security tag on Ansible Forum.