Skip to content

CIS Benchmark CLI

Professional command-line tool for downloading and managing CIS security benchmarks from CIS WorkBench

PyPI version Python Version CI Code style: ruff License

What is CIS Benchmark CLI?

cis-bench downloads CIS security benchmarks from CIS WorkBench and exports them to multiple formats, including NIST XCCDF for use with SCAP compliance scanners like OpenSCAP, SCC, and Nessus.

Use Cases:

  • Discover - Search 1,300+ CIS benchmarks with platform filtering
  • Download - Fetch benchmarks with browser-based authentication
  • Convert - Export to YAML, CSV, Markdown, or NIST XCCDF
  • Comply - Generate DISA STIG-compatible XCCDF for DoD environments
  • Analyze - Extract 19 fields including CIS Controls, MITRE ATT&CK, NIST mappings

Quick Start

# 1. Install (choose one)
pipx install cis-bench    # Recommended - isolated environment, no PATH issues
uv tool install cis-bench # Alternative - fast, modern
pip install cis-bench     # Not recommended - may have PATH issues

# 2. Login (one-time)
cis-bench auth login --browser chrome

# 3. Build catalog (one-time, ~2 minutes)
cis-bench catalog refresh

# 4. Get a benchmark
cis-bench get "ubuntu 22.04" --format xccdf --style cis

# Done! You have a SCAP-compliant XCCDF file

Get Started Guide for detailed setup

Key Features

Session-Based Authentication

Login once, use everywhere. No more passing --browser on every command.

cis-bench auth login --browser chrome
cis-bench download 23598 # Uses saved session

Searchable Catalog

Fast local search of 1,300+ benchmarks with FTS5 full-text search and platform taxonomy.

cis-bench search "oracle" --platform-type cloud
cis-bench search --platform-type database --latest

Unified Get Command

Search + download + export in one step.

cis-bench get "ubuntu 22" --format xccdf --style cis

Database Caching

Downloaded benchmarks cached in SQLite for instant re-export.

cis-bench export 23598 --format xccdf # Instant (from cache)

Multiple Export Formats

  • YAML - Human-readable structured data
  • CSV - Spreadsheet import
  • Markdown - Documentation
  • JSON - Machine-readable
  • XCCDF - SCAP compliance (DISA STIG or CIS native)

Platform Filtering

Two-level taxonomy: category (cloud/os/database) + specific platform (aws/ubuntu/oracle).

cis-bench search --platform-type cloud # All cloud benchmarks
cis-bench search --platform ubuntu # All Ubuntu versions

Scriptable and Automatable

All commands support JSON output for piping to jq, scripting, CI/CD.

cis-bench search oracle --output-format json | jq -r '.[].benchmark_id'

Performance

  • Parallel catalog scraping (~2 min for 1,300+ benchmarks)
  • Retry logic with exponential backoff
  • Progress bars on long operations

Documentation

📚 Full documentation: https://mitre.github.io/cis-bench/

For Users

For Developers

Technical Reference

Example Workflows

Export AlmaLinux 10 for OpenSCAP Scanning

cis-bench auth login --browser chrome
cis-bench search "almalinux 10"
# Shows: Benchmark ID 23598

cis-bench download 23598
cis-bench export 23598 --format xccdf --style cis -o almalinux10-cis.xml

# Use with OpenSCAP
oscap xccdf eval --profile Level_1 almalinux10-cis.xml

Batch Export All Cloud Benchmarks

# Search and download all cloud benchmarks
cis-bench search --platform-type cloud --output-format json | \
jq -r '.[].benchmark_id' | \
head -5 | \
xargs -I {} cis-bench download {}

# Export all to DISA STIG format
cis-bench list --output-format json | \
jq -r '.[].file' | \
xargs -I {} cis-bench export {} --format xccdf --style disa

Create Compliance Spreadsheet

cis-bench download 24008 # Oracle Cloud Infrastructure
cis-bench export 24008 --format csv -o oci-compliance.csv

# Open in Excel/Numbers for tracking
open oci-compliance.csv

More examples in User Guide

XCCDF Export

Generate NIST XCCDF 1.2 format compatible with SCAP compliance tools:

Two Styles Available:

DISA STIG Style (For DoD/Government)

cis-bench export 23598 --format xccdf --style disa

Features:

  • XCCDF 1.1.4 (DISA standard)
  • CCI mappings (2,161 DoD Control Correlation Identifiers)
  • VulnDiscussion elements
  • STIG-compatible structure

CIS Native Style (For Full Metadata)

cis-bench export 23598 --format xccdf --style cis

Features:

  • XCCDF 1.2 (latest standard)
  • Full CIS Controls v8 metadata (318 controls)
  • MITRE ATT&CK techniques (296 mappings)
  • Enhanced namespace for custom fields

XCCDF Styles Comparison for detailed differences

Architecture

Design Principles

Config-Driven - XCCDF field mappings defined in YAML, not hard-coded Extensible - Strategy pattern for HTML changes, Factory pattern for exporters Validated - xsdata-generated models from NIST XSD schemas Tested - 1,100+ tests with 96% coverage

Component Overview

CIS WorkBench HTML
 (WorkbenchScraper + Strategy Pattern)
Pydantic Models (19 fields)
 (MappingEngine + YAML Config)
xsdata XCCDF Models
 (XML Serialization)
NIST XCCDF Output

Architecture Documentation for complete system design

Project Status

Version: 0.4.0 (Beta) Tests: 1,100+ tests with 96% coverage Python: 3.12+ License: Apache 2.0

Current Features:

  • Session-based authentication
  • Searchable catalog with 1,300+ benchmarks
  • Platform taxonomy (cloud/os/database/container/application)
  • Unified get command
  • Database caching
  • Multiple export formats
  • Batch export (multiple benchmarks at once)
  • XCCDF export (both DISA and CIS styles)
  • Parallel catalog scraping
  • Output formats for scripting (json/csv/yaml)

Future Features:

  • Offline mode
  • Benchmark comparison/diff
  • Recommendation search across benchmarks

Future Features for roadmap

Installation

Per Python Packaging Authority guidelines, CLI tools should be installed with pipx or uv tool, not pip directly.

# RECOMMENDED: pipx (isolated environment, correct PATH)
pipx install cis-bench

# ALTERNATIVE: uv tool (fast, modern)
uv tool install cis-bench

# Verify
cis-bench --version

Why not pip? pip install installs to a directory that may not be in your PATH, causing "command not found" errors. pipx and uv tool handle this correctly.

Using pip anyway? (click to expand) 
pip install cis-bench
If you get `cis-bench: command not found`: 
# Option 1: Use module syntax (always works)
python -m cis_bench --version

# Option 2: Add pip's bin to PATH
export PATH="$HOME/.local/bin:$PATH"  # Add to ~/.bashrc or ~/.zshrc

From Source

git clone https://github.com/mitre/cis-bench.git
cd cis-bench

# Install for development
pipx install -e .
# Or: uv tool install -e .

# Verify
cis-bench --version

Development Install

# Clone and install with dev dependencies
git clone https://github.com/mitre/cis-bench.git
cd cis-bench
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

# Run tests
pytest tests/ -v

Getting Started for detailed installation

Requirements

Runtime:

  • Python 3.12+
  • CIS WorkBench account (free registration at workbench.cisecurity.org)
  • Supported browser (Chrome, Firefox, Edge, or Safari)

Development:

  • All runtime requirements
  • pytest, ruff, bandit, pre-commit (installed via [dev] extras)

Support and Contributing

Found a bug? Open an issue at GitHub Issues

Want to contribute? See Contributing Guide

Questions? Check Documentation or open a discussion

License

Apache License 2.0 - See LICENSE for details

Acknowledgments:

  • Based on proof-of-concept by m-ghonim (Mohamed Ghoneam)
  • CIS WorkBench for providing benchmark data
  • NIST for XCCDF schema specifications
  • DISA for STIG formatting conventions

User Documentation:

Developer Documentation:

Need Help?