End-to-End Workflows¶
Real-world scenarios with complete commands and expected outcomes
Documentation Path
You are here: User Guide > End-to-End Workflows
- For command syntax: See Commands Reference
- For term definitions: See Glossary
Overview¶
This guide shows complete workflows for common use cases. Each scenario includes:
- Context - Who you are and what you need
- Prerequisites - What you need before starting
- Commands - Complete CLI commands (copy-paste ready)
- Expected Output - What success looks like
- Validation - How to verify it worked
- Troubleshooting - Common issues
All examples use real benchmark IDs from CIS WorkBench.
Scenario 1: Export AlmaLinux 10 for OpenSCAP Scanning¶
Context: You're a security engineer setting up OpenSCAP compliance scanning for AlmaLinux 10 servers. You need the CIS Benchmark in XCCDF format.
Prerequisites:
- AlmaLinux 10 servers to scan
- OpenSCAP installed (
yum install openscap-scanner) - CIS WorkBench account
Step 1: Setup (One-Time)¶
# Install cis-bench
pip install -e .
# Login to CIS WorkBench
cis-bench auth login --browser chrome
# Build catalog
cis-bench catalog refresh
Expected:
Logged in
Session saved to ~/.cis-bench/session.cookies
Catalog refresh complete!
Benchmarks: 1,343
Pages: 67
Step 2: Find AlmaLinux 10 Benchmark¶
Expected Output:
╭─────────────┬──────────────────────────────────────┬─────────┬───────────╮
│ Benchmark │ Title │ Version │ Status │
│ ID │ │ │ │
├─────────────┼──────────────────────────────────────┼─────────┼───────────┤
│ 23598 │ CIS AlmaLinux OS 10 Benchmark │ v1.0.0 │ Published │
╰─────────────┴──────────────────────────────────────┴─────────┴───────────╯
Note: Benchmark ID is 23598
Step 3: Download and Export to XCCDF¶
# Download benchmark
cis-bench download 23598
# Export to CIS-style XCCDF
cis-bench export 23598 --format xccdf --style cis -o almalinux10-cis.xml
Expected:
Downloading benchmark 23598...
AlmaLinux OS 10 Benchmark v1.0.0
Downloading 322 recommendations ━━━━━━━━━━ 100%
Downloaded: almalinux10.json
Exporting to XCCDF (CIS style)...
Exported: almalinux10-cis.xml (1.8 MB, 322 rules)
Step 4: Validate XCCDF¶
# Check file exists
ls -lh almalinux10-cis.xml
# Validate XML structure
xmllint --noout almalinux10-cis.xml && echo "Valid XML"
# Check rule count
xmllint --xpath "count(//Rule)" almalinux10-cis.xml
# Expected: 322
Step 5: Run OpenSCAP Scan¶
# Run compliance scan
sudo oscap xccdf eval \
--profile "Level 1 - Server" \
--results scan-results.xml \
--report scan-report.html \
almalinux10-cis.xml
# View results
open scan-report.html
Expected:
- HTML report showing pass/fail for each rule
- XML results file for remediation tracking
Troubleshooting¶
Issue: "Download failed - authentication required"
# Check auth status
cis-bench auth status
# Re-login if needed
cis-bench auth login --browser chrome
Issue: "OpenSCAP can't parse XCCDF"
# Verify XCCDF structure
xmllint --schema schemas/xccdf-1.2.xsd almalinux10-cis.xml
# Try DISA style instead (XCCDF 1.1.4, more compatible)
cis-bench export 23598 --format xccdf --style disa -o almalinux10-disa.xml
Scenario 2: Create Compliance Tracking Spreadsheet¶
Context: You're a compliance officer tracking Oracle Cloud Infrastructure security controls. You need a CSV spreadsheet for status tracking.
Benchmark: Oracle Cloud Infrastructure Foundations (ID: 24008)
Complete Workflow¶
# 1. Setup (if not done)
cis-bench auth login --browser chrome
cis-bench catalog refresh
# 2. Search and download
cis-bench search "oracle cloud foundations"
# Shows: Benchmark ID 24008
cis-bench download 24008
# 3. Export to CSV
cis-bench export 24008 --format csv -o oci-compliance.csv
# 4. Open in spreadsheet
open oci-compliance.csv # macOS
# Or: libreoffice oci-compliance.csv # Linux
CSV Output Includes:
ref,title,assessment_status,profiles,audit,remediation,cis_controls,nist_controls
1.1,Ensure service admin is set,Automated,"Level 1",Check IAM policy...,Set IAM policy...,"[4.1, 5.4]","[AC-2, AC-3]"
1.2,Ensure password policy requires...,Automated,"Level 1",Check password settings...,Configure password...,"[5.2]","[IA-5]"
Add Status Tracking Column¶
Edit CSV to add tracking:
- Open in Excel/Numbers/Google Sheets
- Add column: "Implementation Status"
- Add column: "Assigned To"
- Add column: "Target Date"
- Add column: "Notes"
Use for:
- Track implementation progress
- Assign controls to team members
- Report to management
- Audit evidence
Scenario 3: Batch Export All Cloud Benchmarks¶
Context: You manage cloud security across AWS, Azure, GCP, and Oracle Cloud. You need XCCDF files for all cloud platforms.
Complete Workflow¶
# 1. Find all cloud benchmarks
cis-bench search --platform-type cloud --latest --output-format json > cloud-benchmarks.json
# View what we found
jq -r '.[] | "\(.benchmark_id): \(.title)"' cloud-benchmarks.json
# 2. Download all cloud benchmarks
jq -r '.[].benchmark_id' cloud-benchmarks.json | \
head -10 | \
xargs -I {} cis-bench download {}
# 3. Create output directory
mkdir -p xccdf-cloud-benchmarks
# 4. Export all to XCCDF (DISA format for SCC)
cis-bench list --output-format json | \
jq -r 'select(.benchmark_id) | .benchmark_id' | \
while read id; do
cis-bench export "$id" \
--format xccdf \
--style disa \
-o "xccdf-cloud-benchmarks/benchmark-${id}-disa.xml"
echo "Exported: $id"
done
# 5. Verify
ls -lh xccdf-cloud-benchmarks/
Expected Output:
xccdf-cloud-benchmarks/
├── benchmark-12345-disa.xml (AWS Foundations)
├── benchmark-12346-disa.xml (Azure Foundations)
├── benchmark-12347-disa.xml (Google Cloud)
├── benchmark-24008-disa.xml (Oracle Cloud)
└── ...
Use with SCAP Compliance Checker (SCC)¶
# Import all XCCDFs into SCC
for xccdf in xccdf-cloud-benchmarks/*.xml; do
echo "Importing: $xccdf"
# SCC import process (tool-specific)
done
Scenario 4: Generate InSpec Profile from CIS Benchmark¶
Context: You need to create an InSpec compliance profile from a CIS Benchmark for automated testing.
Benchmark: Ubuntu 22.04 LTS (ID: 22162)
Complete Workflow¶
# 1. Download and export to XCCDF
cis-bench auth login --browser chrome
cis-bench download 22162
cis-bench export 22162 --format xccdf --style cis -o ubuntu2204-cis.xml
# 2. Use SAF CLI to convert XCCDF InSpec
npm install -g @mitre/saf
saf generate xccdf_benchmark2inspec_stub \
-X ubuntu2204-cis.xml \
-o ubuntu2204-inspec \
--idType cis
# 3. Verify InSpec profile
cd ubuntu2204-inspec
inspec check .
# 4. Run compliance scan
inspec exec . -t ssh://user@server --reporter cli json:results.json
# 5. View results
inspec_tools summary -j results.json
Expected InSpec Profile:
ubuntu2204-inspec/
├── inspec.yml # Profile metadata
├── controls/
│ ├── 1_1_1.rb # Recommendation 1.1.1
│ ├── 1_1_2.rb # Recommendation 1.1.2
│ └── ... # 200+ control files
└── libraries/
└── helper.rb # Shared code
Each control file contains:
control '1_1_1' do
title 'Ensure mounting of cramfs filesystems is disabled'
desc 'The cramfs filesystem type is a compressed...'
impact 0.7 # From XCCDF severity
tag cis_controls: ['4.8']
tag nist: ['CM-7', 'CM-7(1)']
describe command('modprobe -n -v cramfs') do
its('stdout') { should match /install \/bin\/true/ }
end
end
Scenario 5: Compare Benchmark Versions¶
Context: CIS updated the AlmaLinux 8 benchmark from v3.0.0 to v4.0.0. You need to see what changed.
Benchmarks:
- AlmaLinux 8 v3.0.0 (ID: 15287)
- AlmaLinux 8 v4.0.0 (ID: 23598)
Complete Workflow¶
# 1. Download both versions
cis-bench download 15287 23598
# 2. Export both to JSON (full data)
cis-bench export 15287 --format json -o alma8-v3.json
cis-bench export 23598 --format json -o alma8-v4.json
# 3. Compare recommendation counts
jq '.total_recommendations' alma8-v3.json
jq '.total_recommendations' alma8-v4.json
# 4. Extract recommendation refs
jq -r '.recommendations[].ref' alma8-v3.json | sort > v3-refs.txt
jq -r '.recommendations[].ref' alma8-v4.json | sort > v4-refs.txt
# 5. Find differences
comm -23 v3-refs.txt v4-refs.txt > removed.txt # In v3, not in v4
comm -13 v3-refs.txt v4-refs.txt > added.txt # In v4, not in v3
comm -12 v3-refs.txt v4-refs.txt > common.txt # In both
# 6. Summary
echo "Removed: $(wc -l < removed.txt) recommendations"
echo "Added: $(wc -l < added.txt) recommendations"
echo "Common: $(wc -l < common.txt) recommendations"
# 7. Detail on new recommendations
echo "New recommendations in v4.0.0:"
cat added.txt | while read ref; do
jq -r ".recommendations[] | select(.ref==\"$ref\") | .title" alma8-v4.json
done
Expected Output:
Removed: 5 recommendations
Added: 12 recommendations
Common: 310 recommendations
New recommendations in v4.0.0:
1.1.28 Ensure bootloader password is set
1.2.15 Ensure system-wide crypto policy is configured
...
Scenario 6: Automated CI/CD Integration¶
Context: You want to automatically download and export benchmarks in your CI/CD pipeline to keep compliance docs up-to-date.
GitHub Actions Workflow¶
# .github/workflows/update-compliance-docs.yml
name: Update Compliance Documentation
on:
schedule:
- cron: '0 0 * * 1' # Weekly on Monday
workflow_dispatch:
jobs:
update-benchmarks:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Setup Python
uses: actions/setup-python@v4
with:
python-version: '3.11'
- name: Install cis-bench
run: |
pip install -e .
- name: Login with cookies
run: |
echo "${{ secrets.CIS_COOKIES }}" > cookies.txt
cis-bench auth login --cookies cookies.txt
- name: Download benchmarks
run: |
cis-bench download 23598 # AlmaLinux 10
cis-bench download 22162 # Ubuntu 22.04
cis-bench download 24008 # Oracle Cloud
- name: Export to Markdown
run: |
mkdir -p docs/compliance
cis-bench export 23598 --format markdown -o docs/compliance/almalinux10.md
cis-bench export 22162 --format markdown -o docs/compliance/ubuntu2204.md
cis-bench export 24008 --format markdown -o docs/compliance/oracle-cloud.md
- name: Commit updates
run: |
git config user.name "GitHub Actions"
git config user.email "actions@github.com"
git add docs/compliance/
git commit -m "docs: update CIS benchmarks [skip ci]" || true
git push
Result: Compliance documentation automatically updated weekly.
Scenario 7: Multi-Format Export for Different Stakeholders¶
Context: You need to share Ubuntu 22.04 benchmark with different teams:
- Security team - Needs XCCDF for scanning
- Management - Needs CSV for tracking
- Documentation team - Needs Markdown for wiki
Benchmark: Ubuntu 22.04 LTS Server (ID: 22162)
Complete Workflow¶
# 1. Download once
cis-bench download 22162
# 2. Export to all formats
mkdir -p exports/ubuntu2204
# XCCDF for OpenSCAP/SCC
cis-bench export 22162 --format xccdf --style disa \
-o exports/ubuntu2204/ubuntu-2204-disa.xml
# CSV for tracking
cis-bench export 22162 --format csv \
-o exports/ubuntu2204/ubuntu-2204-controls.csv
# Markdown for wiki
cis-bench export 22162 --format markdown \
-o exports/ubuntu2204/ubuntu-2204-guide.md
# YAML for automation (Ansible/Chef)
cis-bench export 22162 --format yaml \
-o exports/ubuntu2204/ubuntu-2204-data.yaml
# JSON for scripting
cis-bench export 22162 --format json \
-o exports/ubuntu2204/ubuntu-2204-structured.json
# 3. Verify all exports
ls -lh exports/ubuntu2204/
Expected:
total 12M
-rw-r--r-- 1 user group 1.8M ubuntu-2204-disa.xml (SCAP scanning)
-rw-r--r-- 1 user group 450K ubuntu-2204-controls.csv (Excel tracking)
-rw-r--r-- 1 user group 2.1M ubuntu-2204-guide.md (Documentation)
-rw-r--r-- 1 user group 1.2M ubuntu-2204-data.yaml (Automation)
-rw-r--r-- 1 user group 980K ubuntu-2204-structured.json (APIs/Scripts)
Distribution¶
# Share with teams
cp exports/ubuntu2204/ubuntu-2204-disa.xml /shared/security/
cp exports/ubuntu2204/ubuntu-2204-controls.csv /shared/management/
cp exports/ubuntu2204/ubuntu-2204-guide.md /shared/wiki/
Scenario 8: Validate XCCDF Before Importing to SCC¶
Context: You're importing CIS benchmarks into DISA SCC (SCAP Compliance Checker). SCC is picky about XCCDF format and will reject invalid files.
Benchmark: RHEL 9 (ID: 18208)
Complete Workflow with Validation¶
# 1. Download and export
cis-bench download 18208
cis-bench export 18208 --format xccdf --style disa -o rhel9-disa.xml
# 2. Validate XML syntax
xmllint --noout rhel9-disa.xml
if [ $? -eq 0 ]; then
echo " Valid XML syntax"
else
echo " XML syntax error"
exit 1
fi
# 3. Validate against XCCDF schema
xmllint --schema schemas/xccdf-1.1.4.xsd --noout rhel9-disa.xml
if [ $? -eq 0 ]; then
echo " Valid XCCDF 1.1.4 structure"
else
echo " XCCDF schema validation failed"
exit 1
fi
# 4. Check DISA conventions
python3 << EOF
from cis_bench.validators.disa_conventions import validate_disa_conventions
issues = validate_disa_conventions('rhel9-disa.xml')
if not issues:
print(" DISA conventions validated")
else:
print(f"WARNING: {len(issues)} convention issues found:")
for issue in issues:
print(f" - {issue}")
EOF
# 5. Verify CCI count (should be reasonable)
cci_count=$(xmllint --xpath "count(//ident)" rhel9-disa.xml)
echo "Total CCIs: $cci_count"
# Sanity check (should be ~500-1500 for typical benchmark)
if [ "$cci_count" -gt 100 ] && [ "$cci_count" -lt 5000 ]; then
echo " CCI count reasonable"
else
echo "WARNING: Unusual CCI count (expected 500-1500)"
fi
# 6. Check for required STIG elements
required_elements="VulnDiscussion FalsePositives"
for elem in $required_elements; do
count=$(xmllint --xpath "count(//*[local-name()='$elem'])" rhel9-disa.xml)
echo "$elem elements: $count"
done
# 7. If all validations pass, import to SCC
echo " All validations passed - ready for SCC import"
# Import to SCC (tool-specific steps)
Scenario 9: Search and Filter for Specific Platforms¶
Context: You support multiple platforms and need to find all relevant CIS benchmarks.
Find All Database Benchmarks¶
# Search by category
cis-bench search --platform-type database --output-format table
# Export to JSON for processing
cis-bench search --platform-type database --output-format json > databases.json
# Extract specific platforms
jq -r '.[] | select(.platform == "oracle-database") | "\(.benchmark_id): \(.title) \(.version)"' databases.json
jq -r '.[] | select(.platform == "mysql") | "\(.benchmark_id): \(.title) \(.version)"' databases.json
jq -r '.[] | select(.platform == "postgresql") | "\(.benchmark_id): \(.title) \(.version)"' databases.json
Find All Container/Kubernetes Benchmarks¶
Shows:
╭─────────────┬──────────────────────────────────────┬─────────╮
│ Benchmark │ Title │ Version │
├─────────────┼──────────────────────────────────────┼─────────┤
│ 6467 │ CIS Kubernetes Benchmark │ v1.9.0 │
│ 7533 │ CIS Docker Benchmark │ v1.7.0 │
│ 8034 │ CIS Amazon EKS Benchmark │ v1.5.0 │
│ 12696 │ CIS Azure AKS Benchmark │ v1.6.0 │
╰─────────────┴──────────────────────────────────────┴─────────╯
Download Specific Platform¶
# Download all Kubernetes-related
cis-bench search "kubernetes" --output-format json | \
jq -r '.[].benchmark_id' | \
xargs -I {} cis-bench download {}
Scenario 10: Quick Lookup and Get¶
Context: You need a specific benchmark fast and don't remember the ID.
Using the Unified get Command¶
# Search and export in one command
cis-bench get "ubuntu 22" --format xccdf --style cis
# What happens:
# 1. Searches catalog for "ubuntu 22"
# 2. If multiple matches, shows interactive selection
# 3. Downloads benchmark (or uses cache)
# 4. Exports to XCCDF CIS style
# 5. Outputs file path
Interactive Selection:
Found 3 matching benchmarks:
? Select benchmark:
❯ CIS Ubuntu Linux 22.04 LTS Benchmark v2.0.0 (22162)
CIS Ubuntu Linux 22.04 LTS Server Benchmark v1.0.0 (18208)
CIS Ubuntu Linux 20.04 LTS Benchmark v2.0.1 (23595)
Downloading: 22162
Downloaded (from cache)
Exporting to XCCDF (CIS style)...
Exported: ubuntu-22-04-cis.xml
Non-Interactive Mode:
# Skip interactive selection, show table instead
cis-bench get "ubuntu 22" --format xccdf --style cis --non-interactive
Scenario 11: Scripting with JSON Output¶
Context: You're building automation and need machine-readable output.
Search to JSON Pipeline¶
# Find all latest OS benchmarks
cis-bench search --platform-type os --latest --output-format json | \
jq -r '.[] | {
id: .benchmark_id,
title: .title,
version: .version,
platform: .platform
}'
# Download IDs from JSON
cis-bench search --platform-type os --latest --output-format json | \
jq -r '.[].benchmark_id' | \
xargs -I {} cis-bench download {}
Check Auth Status Programmatically¶
# Get auth status as JSON
auth_status=$(cis-bench auth status --output-format json)
# Parse with jq
is_logged_in=$(echo "$auth_status" | jq -r '.logged_in')
if [ "$is_logged_in" = "true" ]; then
echo "Already logged in"
else
echo "Need to login"
cis-bench auth login --browser chrome
fi
List Downloaded Benchmarks as JSON¶
# Get all downloaded benchmarks
cis-bench list --output-format json > inventory.json
# Extract specific fields
jq -r '.[] | "\(.benchmark_id),\(.title),\(.version)"' inventory.json > inventory.csv
# Count by platform
jq -r '.[] | .title' inventory.json | \
grep -o "AlmaLinux\|Ubuntu\|RHEL" | \
sort | uniq -c
Scenario 12: Update Catalog and Re-Export¶
Context: You downloaded benchmarks 6 months ago. CIS has released updates. You need to check for and download new versions.
Complete Workflow¶
# 1. Check what you have
cis-bench list --output-format table
# 2. Update catalog (quick - page 1 only)
cis-bench catalog update
# 3. Check for updates to your downloaded benchmarks
cis-bench catalog check-updates
# Expected output:
# Checking 12 downloaded benchmarks...
# Updates available:
# 23598: AlmaLinux 10 v1.0.0 v1.1.0
# 22162: Ubuntu 22.04 v2.0.0 v2.0.1
# No updates: 10 benchmarks
# 4. Download updates
cis-bench download 23598 --force # Force re-download
cis-bench download 22162 --force
# 5. Re-export to XCCDF
cis-bench export 23598 --format xccdf --style disa -o almalinux10-v1.1.xml
cis-bench export 22162 --format xccdf --style disa -o ubuntu2204-v2.0.1.xml
# 6. Update your OpenSCAP/SCC configuration with new files
Scenario 13: Corporate Environment with SSL Issues¶
Context: You're behind a corporate proxy with custom SSL certificates. Standard commands fail with SSL errors.
Setup for Corporate Environment¶
# Option 1: Disable SSL verification (not recommended for production)
export CIS_BENCH_VERIFY_SSL=false
cis-bench auth login --browser chrome
cis-bench catalog refresh
# Option 2: Use corporate certificate bundle
export REQUESTS_CA_BUNDLE=/etc/ssl/corporate-ca-bundle.crt
cis-bench auth login --browser chrome
cis-bench catalog refresh
# Option 3: Per-command flag
cis-bench auth login --browser chrome --no-verify-ssl
cis-bench download 23598 # Uses saved session settings
Verify SSL Settings:
Scenario 14: Offline Mode (Work from Cache)¶
Context: You're on a plane without internet. You need to work with benchmarks you've already downloaded.
Prepare Before Going Offline¶
# 1. Download everything you'll need
cis-bench download 23598 22162 24008 18208
# 2. Verify cache
cis-bench list
Work Offline¶
# All these work offline (use cache):
cis-bench list
cis-bench info 23598
cis-bench export 23598 --format xccdf --style cis
cis-bench export 22162 --format csv
cis-bench search "ubuntu" # Works if catalog cached
# These REQUIRE internet (will fail offline):
cis-bench download 12345 # New download
cis-bench catalog refresh # Network required
Common Command Combinations¶
Quick Reference Table¶
| Task | Command |
|---|---|
| Setup | cis-bench auth login --browser chrome && cis-bench catalog refresh |
| Search | cis-bench search "platform name" |
| Get XCCDF | cis-bench get "query" --format xccdf --style cis |
| Download by ID | cis-bench download XXXXX |
| Export cached | cis-bench export XXXXX --format xccdf --style disa |
| List downloaded | cis-bench list |
| Check updates | cis-bench catalog check-updates |
| Batch export | cis-bench list --output-format json \| jq -r '.[].benchmark_id' \| xargs -I {} cis-bench export {} --format xccdf |
Benchmark ID Reference¶
Common Benchmarks (as of Dec 2025):
| ID | Platform | Version |
|---|---|---|
| 23598 | AlmaLinux 10 | v1.0.0 |
| 15287 | AlmaLinux 8 | v3.0.0 |
| 22162 | Ubuntu 22.04 LTS Server | v2.0.0 |
| 23595 | Ubuntu 20.04 LTS | v2.0.1 |
| 18208 | RHEL 9 | v2.0.0 |
| 24008 | Oracle Cloud Infrastructure | v3.0.0 |
| 6467 | Kubernetes | v1.9.0 |
| 7533 | Docker | v1.7.0 |
Find more: