Creating and Managing InSpec Profiles – A Practical Guide for DevSecOps Learners

InSpec is the de‑facto standard for automated compliance testing in modern DevSecOps pipelines. Whether you’re troubleshooting a failing control, building a custom profile for a lab, or simply understanding the role of the inspec.yml metadata file, this article walks you through the essential steps, best‑practice tips, and manual remediation techniques you need to succeed.

1. Manually Fixing InSpec Control Failures

Automated remediation is ideal, but there are times when you must address a failure by hand—especially during labs or when a quick fix is required on a remote host. The exact steps depend on the type of control that failed.

1.1 Common Failure Types & Manual Fixes

1.2 Remote Remediation Workflow

1. Identify the target host – note the hostname or IP from the InSpec run output.

2. SSH into the host:

   ssh user@target-host
   

3. Execute the appropriate command (see table above).

4. Re‑run the InSpec profile to confirm the issue is resolved:

   inspec exec /path/to/profile -t ssh://user@target-host
   

2. Building a Custom InSpec Profile – Lab 8.5 Walk‑through

The “8.5 Lab – How to Create a Custom InSpec Profile” asks you to create a profile named Challenge and later add it to a GitLab repository. Below is a concise step‑by‑step guide.

2.1 Initialise the Profile

inspec init profile Challenge

The command generates a directory structure similar to:

Challenge/
├─ controls/
│  └─ example.rb
├─ inspec.yml
└─ README.md

2.2 Add Variables and Target Host

In the lab you used two variables (e.g., app_user and app_port). Define them in controls/example.rb or a dedicated attributes.yml file:

# controls/example.rb
app_user = input('app_user', value: 'myapp')
app_port = input('app_port', value: 8080)

describe user(app_user) do
  it { should exist }
end

describe port(app_port) do
  it { should be_listening }
end

When you run the profile, pass the variables via the CLI or a yaml file:

inspec exec Challenge -t ssh://user@host \
  --input app_user=deploy --input app_port=9090

2.3 Understanding the “Hint” – No Explicit Target

The lab hint uses the check and exec methods inside the Challenge profile. Those methods are generic; they do not embed a specific host. Instead, the target host is supplied at runtime by the GitLab CI job (.gitlab-ci.yml). The CI pipeline defines the INSPEC_TARGET variable, and the job runs:

inspec exec Challenge -t $INSPEC_TARGET

Therefore, the profile will be evaluated against any host you configure in the pipeline, not just a hard‑coded target.

2.4 Commit and Push to GitLab

git add .
git commit -m "Add Challenge profile"
git push origin main

The profile is now part of the repository and will be automatically executed by the compliance job defined in .gitlab-ci.yml.

3. The Role of inspec.yml

Every InSpec profile includes an inspec.yml file that stores metadata and configuration. It is the profile’s “identity card” and is used by InSpec, the InSpec Marketplace, and CI/CD tools.

3.1 Core Fields

3.2 Why It Matters

• Discovery – Tools like the InSpec Marketplace list profiles based on these fields.

• Versioning – CI pipelines can enforce a minimum version (>= 1.0.0).

• Dependency Management – depends ensures required sub‑profiles are fetched automatically.

• Documentation – Readers instantly understand the profile’s purpose without digging into the code.

4. Common Questions & Quick Tips

Q1: Can I fix a failing control without writing a script?

A: Yes. Use the manual commands listed in Section 1.1. After fixing, re‑run the profile to verify.

Q2: Do I need to hard‑code the target host inside the profile?

A: No. Provide the target at runtime (CLI, CI variable, or inspec exec -t <target>). This keeps the profile reusable across environments.

Q3: What happens if I omit inspec.yml?

A: InSpec will still run, but you lose metadata, versioning, and dependency resolution. Publishing to the Marketplace will also fail.

Q4: Where can I find more detailed remediation guides?

A:

• Official InSpec docs – https://www.inspec.io/docs/

• Chef InSpec GitHub Wiki – https://github.com/inspec/inspec/wiki

• CIS Benchmarks (PDFs) – https://www.cisecurity.org/cis-benchmarks/

5. Bottom Line

Creating robust InSpec profiles and manually addressing control failures are core skills for any DevSecOps practitioner. By understanding the metadata in inspec.yml, leveraging variables, and knowing exactly how to remediate common failures, you can accelerate lab work, pass certification exams, and bring real‑world compliance automation to production environments.

Happy testing!