cis-bench 0.5.0

CLI tool for fetching and managing CIS benchmarks from CIS WorkBench

CIS Benchmark CLI

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

---

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

• Getting Started - Installation and first steps
• End-to-End Workflows - Real-world scenarios
• Commands Reference - Complete command syntax and options
• Catalog Guide - Search and discovery workflows
• XCCDF Export Guide - SCAP compliance export
• Configuration - Environment variables and settings
• Troubleshooting - Common issues and solutions

For Developers

• Architecture Overview - System design and components
• Data Flow Pipeline - Complete transformation pipeline
• MappingEngine Guide - Working with YAML configs
• Contributing Guide - Code standards and development workflow
• Testing Guide - Running and writing tests
• How to Add XCCDF Style - Extending XCCDF export

Technical Reference

• Data Model - Pydantic models and field definitions
• Mapping Engine Design - Technical architecture
• XCCDF Styles - DISA vs CIS format comparison
• YAML Config Reference - Mapping configuration syntax

---

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

From PyPI (Recommended)

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

---

Quick Links

User Documentation:

• Getting Started
• End-to-End Workflows
• Commands Reference - Complete command syntax
• XCCDF Guide

Developer Documentation:

• Architecture
• Data Flow Pipeline
• MappingEngine Guide
• Contributing
• Testing

Need Help?

• Check Troubleshooting Guide
• Review Configuration Options
• Browse Full Documentation