Secure development practices

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

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.

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.
Enable branch protection 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.

Maintain a SECURITY.md file in 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.