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 security_policy and the vulnerability_management_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.

• module_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.
• module_utils documents secure utilities including fetch_url for TLS-verified HTTP requests and run_command for safe shell execution.
• developing_modules_best_practices covers conventions for error handling, return values, and idempotent operations.
• developing_plugins covers plugin development guidelines for all plugin types.
• developing_secret_masking covers registering secrets so they are masked in Ansible output, marking plugin options as secret, and callback plugin responsibilities.

Secure collections

• developing_collections covers collection development, including namespace requirements and packaging.
• collection_structure documents the required file structure for collections.

Secure playbooks and roles

• vault_guide_index covers encrypting sensitive data such as passwords, keys, and credentials with Ansible Vault.

Dependency management

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.

GitHub workflow security

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.

Build and release integrity

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.

Project security posture

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

Community

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.