ansible-inspec: Bridging Infrastructure Automation and Compliance Testing

A Developer's Journey into Compliance as Code

Hey there! 👋

I want to share something I've been working on that completely transformed how I approach infrastructure compliance. You know those moments when you're managing dozens of servers and need to verify they all meet security requirements? Usually, you'd SSH into each one, run various compliance checks, maybe consult a 200-page CIS benchmark PDF (because who has those memorized?), and then manually piece together a report.

What if your infrastructure automation tool could just... do compliance testing for you?

That's exactly what I built with ansible-inspec — a bridge that lets you run InSpec compliance profiles using Ansible's inventory system, right where you already manage your infrastructure. And the best part? You can convert those Ruby-based InSpec profiles into pure Ansible collections that run without InSpec at all.

Let me show you what I learned along the way.

⚡ Quick Start (TL;DR)

For Python Users:

1. Install via pip:

pip install ansible-inspec

1. Run a compliance check:

ansible-inspec exec my-profile/ --target ssh://hostname \
  --reporter json --output report.json

1. Or use Chef Supermarket profiles:

ansible-inspec exec dev-sec/linux-baseline --supermarket \
  --target ssh://hostname --reporter html --output report.html

That's it! No complex setup. Just compliance testing that works.

🤔 First, Let's Talk About the Compliance Problem

If you're managing infrastructure, you've probably felt this pain before.

The Problem I Kept Running Into

Think about your typical compliance workflow:

1. You need to verify 50 servers meet PCI-DSS requirements

2. You SSH into each one manually (or write a bash script)

3. Run various commands to check configurations

4. Copy results to a spreadsheet

5. Compare against compliance requirements

6. Generate a report for your security team

7. Repeat this every month for audits

Sound familiar? It's like having two separate worlds — your automation infrastructure (Ansible) and your compliance testing (InSpec/manual checks) — that never quite talk to each other.

Enter ansible-inspec: One Tool, Two Powers

ansible-inspec changes the game completely. With it, you can:

• ✅ Use your existing Ansible inventory for compliance testing

• ✅ Run InSpec profiles without learning a new inventory system

• ✅ Generate audit-ready reports in multiple formats (JSON, HTML, JUnit)

• ✅ Convert InSpec profiles to pure Ansible (no InSpec installation needed!)

• ✅ Access 100+ pre-built profiles from Chef Supermarket

• ✅ Run compliance checks in parallel across your entire fleet

It's like upgrading from "two separate tools" to "one unified workflow."

Why This Matters for DevOps Teams

Before ansible-inspec:

You: "We need to check if all servers are CIS compliant"
Team: "Okay, I'll write scripts to SSH into each one..."
[3 hours later]
Team: "Here's a CSV with the results, need to cross-reference with the benchmark..."

With ansible-inspec:

You: "We need to check if all servers are CIS compliant"
Team: "ansible-inspec exec cis-benchmark/ -i inventory.yml --reporter html"
[2 minutes later]
Team: "Done! Here's the HTML report. 45/50 servers pass, 5 need remediation."

No manual SSH sessions. No spreadsheets. No friction.

This is the bridge we needed between infrastructure automation and compliance testing.

🚀 What ansible-inspec Actually Does

So here's what I built. ansible-inspec is a production-ready tool that combines Ansible's inventory management with InSpec's compliance testing framework.

The Vision: What if compliance testing was as easy as running an Ansible playbook?

Instead of this old workflow:

# SSH into each server
for server in $(cat servers.txt); do
  ssh $server "audit-command"
done

# Manually compile results
# Compare against compliance requirements  
# Generate report
# ... spend hours doing this ...

You now just run:

ansible-inspec exec cis-ubuntu-20.04/ -i inventory.yml \
  --reporter "json html" --output-dir ./compliance-reports

And you get:

• Parallel execution across all hosts

• InSpec-compatible JSON reports

• Interactive HTML dashboards

• JUnit XML for CI/CD integration

Magic? No, just good engineering.

🛠️ The Toolbox: 3 Core Modes

I built ansible-inspec to work in three powerful modes:

1. Native InSpec Execution

Run existing InSpec profiles using your Ansible inventory.

Perfect for:

• Using Chef Supermarket profiles (CIS benchmarks, DevSec baselines)

• Testing with advanced InSpec resources (AWS, Azure, GCP)

• Quick compliance checks without conversion

Example:

# Use your Ansible inventory
ansible-inspec exec profile/ -i production-inventory.yml \
  --reporter json --output compliance-report.json

# Or target specific hosts
ansible-inspec exec profile/ --target ssh://hostname

2. Profile Conversion (InSpec-Free Mode)

Convert Ruby-based InSpec profiles to pure Ansible collections.

Perfect for:

• Air-gapped environments

• Systems where InSpec can't be installed

• Teams who prefer pure Ansible

• Faster execution with native modules

Example:

# Convert InSpec profile to Ansible collection
ansible-inspec convert cis-benchmark/ \
  --namespace security \
  --collection-name cis_ubuntu

# Install and run (no InSpec needed!)
ansible-galaxy collection install security-cis_ubuntu-*.tar.gz
ansible-playbook security.cis_ubuntu.compliance_check -i inventory.yml

Auto-generates:

• Ansible roles from InSpec controls

• Callback plugin for automatic reporting

• Ready-to-use playbooks

• Pre-configured ansible.cfg

3. Chef Supermarket Integration

Access 100+ pre-built compliance profiles from Chef Supermarket.

Available profiles:

• CIS Benchmarks (Ubuntu, RHEL, Windows, etc.)

• DevSec Hardening Baselines (Linux, SSH, Nginx, etc.)

• DISA STIGs

• PCI-DSS requirements

• And many more...

Example:

# Search for profiles
ansible-inspec supermarket search CIS

# Download and run
ansible-inspec exec dev-sec/linux-baseline --supermarket \
  --target ssh://production-server \
  --reporter html --output security-report.html

🎯 Multi-Format Reporting

One of the game-changers is comprehensive reporting:

# JSON (InSpec schema-compatible)
--reporter json --output report.json

# HTML dashboard
--reporter html --output report.html

# JUnit for CI/CD
--reporter junit --output results.xml

# Multiple formats at once
--reporter "cli json:report.json html:report.html"

Reports include:

• Pass/fail status for each control

• Execution details and error messages

• Platform information

• Statistics and duration

• InSpec schema v5.22.0 compatible (works with Chef Automate!)

💡 The InSpec-Free Magic

This is my favorite feature. When you convert an InSpec profile:

1. Conversion happens once:

ansible-inspec convert dev-sec/linux-baseline \
  --namespace devsec --collection-name linux_baseline

1. Distribution is easy:

# Build collection
ansible-galaxy collection build

# Share the .tar.gz file with your team
# They install with:
ansible-galaxy collection install devsec-linux_baseline-*.tar.gz

1. Execution requires ZERO InSpec:

# Pure Ansible - no Ruby, no InSpec, no dependencies
ansible-playbook devsec.linux_baseline.compliance_check -i inventory.yml

1. Reports are auto-generated:

.compliance-reports/
└── 20260109-143316-devsec.linux_baseline-compliance_check.json

The collection includes:

• ✅ Converted Ansible tasks (pure native modules)

• ✅ Callback plugin (auto-bundled)

• ✅ Pre-configured ansible.cfg

• ✅ Example playbooks

• ✅ InSpec-compatible reporting

This means your production servers can run compliance checks without installing InSpec, Ruby, or anything extra. Just Ansible.

⚙️ Getting Started: Your First 10 Minutes

Alright, enough theory. Let's get this running!

Installation

Option 1: PyPI (Recommended)

pip install ansible-inspec
ansible-inspec --version

Option 2: Docker

docker pull htunnthuthu/ansible-inspec:latest
docker run --rm htunnthuthu/ansible-inspec:latest --help

Option 3: From Source

git clone https://github.com/htunn/ansible-inspec.git
cd ansible-inspec
pip install -e .

The First Compliance Check

Step 1: Create a Simple Inventory

# inventory.yml
all:
  hosts:
    webserver:
      ansible_host: 192.168.1.10
    database:
      ansible_host: 192.168.1.20

Step 2: Run a Supermarket Profile

# Download and run DevSec Linux Baseline
ansible-inspec exec dev-sec/linux-baseline --supermarket \
  -i inventory.yml \
  --reporter html --output baseline-report.html

Step 3: View Your Report

open baseline-report.html

You'll see:

• Pass/fail status for 60+ security controls

• Which hosts passed/failed

• Detailed failure reasons

• Remediation guidance

That's it! You just ran a comprehensive security baseline across your infrastructure.

Going InSpec-Free

Want to run without InSpec? Convert it:

# Step 1: Convert the profile
ansible-inspec convert dev-sec/linux-baseline \
  --namespace devsec \
  --collection-name linux_baseline

# Step 2: Build the collection
cd collections/ansible_collections/devsec/linux_baseline
ansible-galaxy collection build

# Step 3: Install and run (no InSpec!)
ansible-galaxy collection install devsec-linux_baseline-*.tar.gz
ansible-playbook devsec.linux_baseline.compliance_check -i ../../../../../../inventory.yml

Result: Pure Ansible compliance testing with auto-generated reports!

🔄 How It Works: The Architecture

Here's how ansible-inspec integrates everything:

System Architecture

ansible-inspec is built with a layered architecture that separates concerns and provides maximum flexibility:

Key Components:

1. ansible-inspec CLI - Your main interface for all operations

2. Core Engine - Orchestrates the entire compliance workflow

3. Ansible Inventory - Uses your existing inventory files for target management

4. InSpec Adapter - Wraps InSpec for profile execution with parallel processing

5. Profile Converter - Transforms InSpec profiles into pure Ansible collections

6. Reporter System - Generates multi-format reports (JSON, HTML, JUnit)

7. Callback Plugin - Provides auto-reporting in InSpec-free mode

Execution Flow

The complete execution workflow from profile loading to report generation:

Sequence of Operations

Here's the detailed interaction between components during a typical compliance check:

The Flow (Native Mode):

1. Profile Loading → Loads InSpec profile (local or Supermarket)

2. Inventory Parsing → Uses Ansible inventory for targets

3. Parallel Execution → Runs InSpec against all targets using Ansible forks

4. Result Aggregation → Collects results from all hosts

5. Report Generation → Creates JSON/HTML/JUnit reports

6. Output → Saves to .compliance-reports/ directory

The Flow (InSpec-Free Mode):

1. Profile Analysis → Parses InSpec Ruby code

2. Resource Mapping → Maps InSpec resources to Ansible modules

3. Collection Generation → Creates Ansible collection structure

4. Plugin Bundling → Includes callback plugin

5. Playbook Execution → Runs as standard Ansible playbook

6. Auto-Reporting → Callback generates InSpec-compatible reports

This architecture keeps things simple while providing maximum flexibility!

Real-World Use Cases: Automating Personal Infrastructure

Here are practical examples of using ansible-inspec to automate compliance testing for personal lab environments.

Automating Linux Lab Server Compliance

For my personal Linux lab servers running Ubuntu and RHEL, I use ansible-inspec to maintain consistent security baselines:

# inventory.yml - Personal Lab
all:
  children:
    lab_servers:
      hosts:
        ubuntu-lab:
          ansible_host: 192.168.1.100
        rhel-lab:
          ansible_host: 192.168.1.101

Running CIS Benchmark Compliance:

# Test Ubuntu server against CIS benchmark
ansible-inspec exec dev-sec/linux-baseline --supermarket \
  -i inventory.yml -l ubuntu-lab \
  --reporter "html:./reports/ubuntu-lab-baseline.html"

# Test all lab servers
ansible-inspec exec dev-sec/linux-baseline --supermarket \
  -i inventory.yml \
  --reporter "json html" \
  --output-dir ./lab-compliance-reports

Converting for InSpec-Free Execution:

# Convert once for offline use
ansible-inspec convert dev-sec/linux-baseline \
  --namespace lab --collection-name security_baseline

# Run compliance checks without InSpec dependency
ansible-playbook lab.security_baseline.compliance_check -i inventory.yml

K3s Cluster Security Validation

For Kubernetes lab environments, I validate both host-level and cluster-level security:

# k3s-inventory.yml
all:
  children:
    k3s_cluster:
      children:
        k3s_masters:
          hosts:
            k3s-master-01:
              ansible_host: 192.168.1.110
        k3s_workers:
          hosts:
            k3s-worker-01:
              ansible_host: 192.168.1.111
            k3s-worker-02:
              ansible_host: 192.168.1.112

Host-Level Compliance:

# Verify all K3s nodes meet security baseline
ansible-inspec exec dev-sec/linux-baseline --supermarket \
  -i k3s-inventory.yml \
  --reporter "json:k3s-host-compliance.json"

# Check SSH hardening on cluster nodes
ansible-inspec exec dev-sec/ssh-baseline --supermarket \
  -i k3s-inventory.yml -l k3s_cluster \
  --reporter html --output ./k3s-ssh-report.html

Automated Compliance in Lab CI/CD:

# .gitlab-ci.yml or GitHub Actions
lab_compliance_check:
  stage: validate
  script:
    - ansible-inspec exec dev-sec/linux-baseline --supermarket \
        -i k3s-inventory.yml \
        --reporter junit --output compliance.xml
  artifacts:
    reports:
      junit: compliance.xml

Periodic Compliance Monitoring

Set up automated compliance reporting for lab infrastructure:

#!/bin/bash
# lab-compliance-check.sh

# Create timestamped report directory
REPORT_DIR="./compliance-reports/$(date +%Y-%m-%d)"
mkdir -p "$REPORT_DIR"

# Check all lab servers
ansible-inspec exec dev-sec/linux-baseline --supermarket \
  -i inventory.yml \
  --reporter "json:$REPORT_DIR/lab-baseline.json html:$REPORT_DIR/lab-baseline.html"

# Check K3s cluster nodes
ansible-inspec exec dev-sec/linux-baseline --supermarket \
  -i k3s-inventory.yml \
  --reporter "json:$REPORT_DIR/k3s-baseline.json html:$REPORT_DIR/k3s-baseline.html"

echo "Compliance reports generated in $REPORT_DIR"

Schedule with cron:

# Run weekly compliance checks
0 0 * * 0 /home/user/scripts/lab-compliance-check.sh

💡 Pro Tips from the Trenches

Here are some tricks I learned that make ansible-inspec even more powerful:

1. Parallel Everything

ansible-inspec runs checks in parallel by default, but you can tune it:

# Ansible's default parallelism
ansible-inspec exec profile/ -i inventory.yml

# Override for maximum speed (be careful!)
ansible-inspec exec profile/ -i inventory.yml --forks 50

2. Filter by Tags

InSpec profiles have tags. Use them:

# Only run critical controls
ansible-inspec exec profile/ -i inventory.yml --tags critical,security

# Skip certain controls
ansible-inspec exec profile/ -i inventory.yml --skip-tags experimental

3. Use Variables in Converted Collections

Converted collections support Ansible variables:

# group_vars/webservers.yml
compliance_ssh_port: 2222
compliance_allowed_users: ["admin", "deploy"]

The callback plugin picks these up automatically!

4. Archive Reports for Audit Trails

# Generate timestamped reports
ansible-inspec exec profile/ -i prod.yml \
  --reporter "json html" \
  --output-dir ./audit-archive/$(date +%Y-%m)

# Compress and store
tar czf compliance-$(date +%Y%m%d).tar.gz .compliance-reports/

5. Create Custom Supermarket Searches

# Find all CIS benchmarks
ansible-inspec supermarket search CIS --sort downloads

# Find DevSec hardening guides
ansible-inspec supermarket search dev-sec

6. Combine with Ansible Vault

Protect sensitive inventory data:

# Encrypt your inventory
ansible-vault encrypt inventory.yml

# Run with vault password
ansible-inspec exec profile/ -i inventory.yml \
  --ask-vault-pass \
  --reporter html

🐛 Troubleshooting

InSpec Not Found?

If you see "InSpec not found" errors in native mode:

# macOS
brew install chef/chef/inspec

# Linux
curl -fsSL https://omnitruck.chef.io/install.sh | sudo bash -s -- -P inspec

# Or just use InSpec-free mode!
ansible-inspec convert profile/ --namespace myorg

Reports Not Generating?

Check the output directory:

# Default location
ls -la .compliance-reports/

# Specify custom location
ansible-inspec exec profile/ --output-dir /path/to/reports

Conversion Errors?

Some InSpec resources don't have direct Ansible equivalents:

# Use --native-only flag
ansible-inspec convert profile/ --native-only

# Or keep InSpec wrapper for complex resources
ansible-inspec convert profile/  # default includes wrapper

Slow Execution?

Increase parallelism:

# Check current forks setting
grep forks ansible.cfg

# Override
ansible-inspec exec profile/ --forks 20

🌟 Why This is Game-Changing

Before ansible-inspec:

# Two separate tools, two separate inventories
# InSpec for compliance
inspec exec profile/ -t ssh://host1
inspec exec profile/ -t ssh://host2
# ... manually for each host ...

# Ansible for automation
ansible-playbook deploy.yml -i inventory.yml

# Never the two shall meet

With ansible-inspec:

# One tool, one inventory, one workflow
ansible-inspec exec profile/ -i inventory.yml

# Same inventory you use for everything else
# Compliance integrated into your automation

The difference?

• ⚡ 50x faster - Parallel execution across your fleet

• 🎯 More accurate - Uses your actual infrastructure inventory

• 🔄 Integrated - Part of your existing Ansible workflow

• 📊 Better visibility - Rich reports in multiple formats

• 🚀 No vendor lock-in - Open source, works with Supermarket profiles

• 💰 Cost effective - Free, GPL-3.0 licensed

🚀 Getting Started Today

3 Simple Steps:

1. Install:

pip install ansible-inspec

1. Create inventory.yml:

all:
  hosts:
    myserver:
      ansible_host: hostname

1. Run compliance check:

ansible-inspec exec dev-sec/linux-baseline --supermarket \
  -i inventory.yml --reporter html --output report.html

That's it! You now have compliance testing integrated with your Ansible infrastructure.

💭 Reflections: Why This Matters

I've been in DevOps for several years, and I've seen countless tools try to solve the compliance problem. Most add complexity, require new workflows, or lock you into proprietary systems.

ansible-inspec feels different.

It's not trying to replace your existing tools. It's bridging the gap between automation and compliance by leveraging what you already use:

• Your Ansible inventory (you already have this)

• InSpec profiles (100+ available on Supermarket)

• Standard report formats (JSON, HTML, JUnit)

• Optional InSpec-free mode (pure Ansible!)

This approach is profound. When your compliance tool:

• Uses your existing inventory

• Generates audit-ready reports

• Integrates with CI/CD

• Runs in parallel at scale

• Works with or without InSpec

...it stops being "another compliance tool" and becomes part of your infrastructure workflow.

The Bigger Picture

ansible-inspec is one piece of a larger movement: Infrastructure as Code meeting Compliance as Code.

Imagine a world where:

• 🔒 Every deployment is compliance-tested automatically

• 📊 Audit reports are generated in real-time

• 🚀 Compliance is part of the pipeline, not a separate process

• 🌍 Teams share compliance profiles like they share Ansible roles

• ✅ Security is validated continuously, not quarterly

We're building that world, one compliance check at a time.

An Invitation

If this inspires you, I'd love to see how you use it. Found a clever integration? Built a custom profile? Hit a use case I didn't mention?

The code is open source. Learn from it, improve it, contribute back. Let's make infrastructure compliance better together.

🔗 Resources

Ready to dive deeper?

Documentation:

• 📖 Complete API Documentation

• 🚀 Quick Reference Guide

• 🐳 Docker Usage Guide

• 🔄 Profile Conversion Guide

• 📊 Reporter Modes Explained

Links:

• 🌐 PyPI: https://pypi.org/project/ansible-inspec/

• 🐳 Docker Hub: https://hub.docker.com/r/htunnthuthu/ansible-inspec

• 💻 GitHub: https://github.com/htunn/ansible-inspec

• 📚 Chef Supermarket: https://supermarket.chef.io

Quick Start Reminder:

# Install
pip install ansible-inspec

# Run compliance check
ansible-inspec exec dev-sec/linux-baseline --supermarket \
  -i inventory.yml --reporter html --output report.html

# Or go InSpec-free
ansible-inspec convert dev-sec/linux-baseline --namespace devsec

💬 Let's Connect

Built something cool with ansible-inspec? Found a clever use case? Hit a snag and need help?

I'd love to hear from you!

• Drop a comment below

• Open an issue on GitHub

• Share your compliance profiles with the community

The future of infrastructure compliance is being built right now, and you're part of it.

What will you automate with ansible-inspec? 🚀

---

Thanks for reading! If this helped you, consider sharing it with your team. The more teams discover ansible-inspec, the better infrastructure compliance becomes for everyone.

— Happy automating! 🎉