Lab Guide: Introducing supply chain security with ansible-sign

Learn how to sign content by using ansible-sign and apply supply-chain security measures, a major Dev Tools capability.

Learning objectives

After completing this module, you will be able to:

Create a GPG key for signing Ansible content
Define a MANIFEST.in to specify files for signing
Sign and verify an Ansible project using ansible-sign
Understand how signed content integrates with Ansible Automation Platform

Lab briefing

ansible-sign: Utility for signing and verifying Ansible project directory contents.

Project signing and verification lets you sign files in your project directory, then verify whether or not that content has changed in any way, or files have been added or removed from the project unexpectedly. To do this, you require a private key for signing and a matching public key for verifying.

Lab guide: Hands-on tasks

The Workflow for Signing Ansible Automation Platform (AAP) Projects:

Sign your project directory containing playbooks, rulebooks, roles, etc.
Sync the signed project to AAP’s Project Sync
AAP verifies the signature before execution
Only validated, trusted content runs

Using ansible-sign together with the Automation Hub collection signing feature allows to secure the supply chain end-to-end from content development to production.

In this lab we will only cover the workstation side of the content signing. You can apply what you learned here to verify content on your own AAP instance later.

Task 1: Create a GPG key

To use ansible-sign your workstation needs to have a GNU Privacy Guard (GPG) key available to cryptographically sign the content. Although it exceeds the scope of this workshop, we will create one quickly to show the end to end steps.

Install pinentry-curses, a dependency for gpg:
```
sudo dnf install pinentry-curses -y
```

Create a GPG batch file in VS Code: In the VS Code file explorer sidebar, right-click on the workspace root (ansible-dev-tools-workspace) and select New File. Name it:

gpg.txt

Paste the following content:

%echo Generating a basic OpenPGP key
Key-Type: default
Key-Length: 4096
Subkey-Type: default
Subkey-Length: default
Name-Real: workshop
Name-Comment: with no passphrase
Name-Email: student@localhost
Expire-Date: 0
%no-ask-passphrase
%no-protection
%commit
%echo done

Save the file.

Generate the gpg key:

gpg --batch --gen-key /projects/ansible-dev-tools-workspace/gpg.txt

Verify the key is created:
```
gpg --list-secret-keys
```

Task 2: Prepare the project for signing

ansible-sign checksums every file in the project directory and compares them against the MANIFEST.in. To keep the signing clean and avoid checksum mismatches from development artifacts, we will create a dedicated directory with only the files we want to sign.

Create the signed playbook directory. In the VS Code file explorer sidebar, right-click on the workspace root (ansible-dev-tools-workspace) and select New Folder. Name it:
```
mysignedplaybook
```
Copy the playbook file. In the VS Code file explorer, expand mynamespace.mycollection > playbooks, right-click on mycowsay.yml and select Copy. Then right-click on the mysignedplaybook folder and select Paste, or use the terminal command below:
```
cp /projects/ansible-dev-tools-workspace/mynamespace.mycollection/playbooks/mycowsay.yml /projects/ansible-dev-tools-workspace/mysignedplaybook/
```
Create a README.md file. Right-click on the mysignedplaybook folder and select New File. Name it README.md and add a short description:
```
# My Signed Playbook

This project contains the signed mycowsay playbook.
```
Save the file.

Task 3: Create a MANIFEST.in file

In VS Code, create a new file called MANIFEST.in in the mysignedplaybook directory by right-clicking on the folder and selecting New File. This file controls which files are included in the checksum manifest that ansible-sign creates and verifies.

For this lab, we will sign just two files to keep the output simple. In a production environment, you would include all project files to ensure full supply chain integrity.
```
# Exclude development artifacts
global-exclude .git
global-exclude .git/*
prune .git

# Include files to sign
include README.md
include mycowsay.yml
```

Internally, ansible-sign makes use of the distlib.manifest module of Python’s distlib library, and thus MANIFEST.in must follow the syntax that this library specifies. Check the Python Packaging User Guide for an explanation of the MANIFEST.in file directives.

Task 4: Sign the project with ansible-sign

Navigate to the signed playbook directory:

cd /projects/ansible-dev-tools-workspace/mysignedplaybook

Now we can sign the files listed in the MANIFEST.in: The way that ansible-sign protects content from tampering is by taking checksums (sha256) of all of the secured files in the project, compiling those into a checksum manifest file, and then finally signing that manifest file.
```
ansible-sign project gpg-sign .
```
The output of the command above should look like this:
```
[OK   ] GPG signing successful!
[NOTE ] Checksum manifest: ./.ansible-sign/sha256sum.txt
[NOTE ] GPG summary: signature created
```

Task 5: Verify the content with ansible-sign

Confirm the files in MANIFEST.in got checksums:
```
cat .ansible-sign/sha256sum.txt
```

Verify your signed files have the correct checksum:

ansible-sign project gpg-verify .

[OK   ] GPG signature verification succeeded.
[NOTE ] Checksum manifest: ./.ansible-sign/sha256sum.txt
[NOTE ] GPG summary: valid signature

Task 6: Enable verification in AAP executions

We won’t cover this here, but the next steps would be:
1. Create a credential with our GPG Public Key
2. Push our project to a git repository
3. Create a project in AAP to pull from that repository and assign our GPG credential
4. AAP will verify the content of the project at every sync

Next steps

You have successfully signed and verified your playbook, ensuring that it can’t be tampered with and continue to run unnoticed. Please click the Next button below to proceed to the Conclusion.