mitre/inspec_tools

InspecTools

镜像概述和主要用途

InspecTools提供多个命令行工具，用于InSpec格式之间的相互转换及安全结果数据处理。该工具集支持多种格式转换（如XCCDF、CSV、CKL、PDF、XLSX与InSpec之间的双向转换），并包含可在Ruby应用中使用的API，适用于安全合规检查、基准测试结果处理等场景。

核心功能和特性

• 多格式转换模块：支持generate_map、generate_ckl_metadata、generate_inspec_metadata、compliance、summary、csv2inspec、inspec2csv、xccdf2inspec、inspec2xccdf、inspec2ckl、pdf2inspec、xlsx2inspec等13个功能模块
• Ruby API：提供Ruby编程接口，可在Ruby应用中集成InSpec结果转换功能
• 合规性检查：解析InSpec结果JSON，验证是否满足指定的合规阈值
• 结果汇总：生成InSpec测试结果的详细汇总报告，支持多种输出格式
• 跨平台支持：可通过Docker容器在Linux、Mac和Windows系统中运行

使用场景和适用范围

• 安全合规审计人员：将STIG XCCDF、CIS基准PDF/XLSX等转换为InSpec配置文件
• 安全测试工程师：将InSpec测试结果转换为CKL检查表、CSV报告或XCCDF文档
• 开发人员：通过Ruby API在应用中集成安全结果处理功能
• 系统管理员：验证系统合规性是否达到指定阈值，生成可读性强的汇总报告

使用方法和配置说明

Docker使用前提

所有Docker命令会挂载当前目录到容器中，使用前需导航至待处理文件所在目录。

Docker运行命令

• Linux和Mac：

  bash
  docker run -it -v$(pwd):/share docker.xuanyuan.run/mitre/inspec_tools
  

• Windows CMD：

  cmd
  docker run -it -v%cd%:/share docker.xuanyuan.run/mitre/inspec_tools
  

命令行基础用法

查看所有命令：

bash
inspec_tools help

查看特定命令帮助：

bash
inspec_tools help [COMMAND]
# 或
inspec_tools [COMMAND] -h

主要模块详细说明

generate_map

生成可用于csv2inspec命令的mapping.xml映射文件。

bash
USAGE: inspec_tools generate_map

generate_ckl_metadata

生成可用于inspec2ckl命令的metadata.json元数据文件。

bash
USAGE: inspec_tools generate_ckl_metadata

generate_inspec_metadata

生成可用于xccdf2inspec命令的metadata.json元数据文件。

bash
USAGE: inspec_tools generate_inspec_metadata

compliance

解析InSpec结果JSON，检查合规水平是否满足指定阈值。若不满足，返回错误码(1)及不合规元素。合规分数向下取整（如77.3显示为77）。

bash
USAGE:  inspec_tools compliance [OPTIONS] -j <inspec-json> -i <threshold-inline>
        inspec_tools compliance [OPTIONS] -j <inspec-json> -f <threshold-file>
FLAGS:
        -j --inspec-json <inspec-json>          : InSpec结果JSON文件路径
        -i --template-inline <threshold-inline> : 内联合规阈值定义
        -f --template-file <threshold-file>     : 包含合规阈值定义的YAML文件

示例：

bash
# 内联阈值定义
inspec_tools compliance -j examples/sample_json/rhel-simp.json -i '{compliance.min: 80, failed.critical.max: 0, failed.high.max: 0}'

# 文件阈值定义
inspec_tools compliance -j examples/sample_json/rhel-simp.json -f examples/sample_yaml/threshold.yaml

阈值定义格式：

• YAML文件示例：

  yaml
  failed:
    critical:
      max: 0
    high:
      max: 1
  compliance:
    min: 81
  

  或

  yaml
  compliance.min: 81
  failed.critical.max: 1
  failed.high.max: 1
  

• 内联示例：

  json
  {compliance: {min: 90}, failed: {critical: {max: 0}, high: {max: 0}}}
  

  或

  json
  {compliance.min: 81, failed.critical.max: 0, failed.high.max: 0}
  

summary

解析InSpec结果JSON，显示所有测试的执行信息。默认输出示例：

Overall compliance: 77%

failed
	total : 41
	critical : 0
	high : 3
	medium : 33
	low : 5
passed
	total : 174
	critical : 0
	high : 21
	medium : 147
	low : 6
...

bash
USAGE: inspec_tools summary [OPTIONS] -j <inspec-json>
FLAGS:
  -j --inspec-json <inspec-json>   : InSpec结果JSON文件路径
  -V --verbose                     : 打印详细调试输出
  -f --json-full                   : 以JSON格式输出完整汇总
  -k --json-counts                 : 以JSON格式输出结果状态计数

示例：

bash
inspec_tools summary -j examples/sample_json/rhel-simp.json -f

xccdf2inspec

将STIG XCCDF文件转换为InSpec配置文件。

bash
USAGE: inspec_tools xccdf2inspec [OPTIONS] -x <xccdf-file>
FLAGS:
        -x --xccdf <xccdf-file>            : DISA STIG XCCDF文件路径
        -a --attributes <xccdf-attr-yml>   : 保存XCCDF特有属性的YAML文件路径（可选）
        -o --output <profile-path>         : InSpec配置文件输出路径（默认：profile）
        -f --format [ruby | hash]          : 输出格式（默认：ruby）
        -s --separate-files [true | false] : 是否将控制项输出为多个文件（默认：true）
        -m --metadata <metadata-json>      : inspec.yml的额外元数据JSON文件路径（可选）
        -r --replace-tags <array>          : 需替换为$的标签列表（区分大小写，空格分隔，可选）

示例：

bash
inspec_tools xccdf2inspec -x xccdf_file.xml -a attributes.yml -o myprofile -f ruby -s false

inspec2xccdf

将JSON格式的InSpec配置文件转换为STIG XCCDF文档。

bash
USAGE: inspec_tools inspec2xccdf [OPTIONS] -j <inspec-json> -a <xccdf-attr-yml> -o <xccdf-xml>
FLAGS:
        -j --inspec-json <inspec-json>   : InSpec JSON文件路径（使用`inspec json <profile> > example.json`生成）
        -a --attributes <xccdf-attr-yml> : 提供XCCDF文档所需属性的YAML文件路径
        -o --output <xccdf-xml>          : XCCDF文件输出路径及名称
        -V --verbose                     : 详细模式（可选）

示例：

bash
inspec_tools inspec2xccdf -j example.json -a attributes.yml -o xccdf.xml

csv2inspec

将STIG控制项CSV电子表格转换为InSpec配置文件。

bash
USAGE: inspec_tools csv2inspec [OPTIONS] -c <stig-csv> -m <map-yml>
FLAGS:
        -c --csv <stig-csv>                : DISA STIG风格CSV文件路径
        -m --mapping <map-yml>             : CSV到InSpec控制项的映射YAML文件路径
        -V --verbose                       : 详细模式（可选）
        -o --output <profile-path>         : InSpec配置文件输出路径（默认：profile）
        -f --format [ruby | hash]          : 输出格式（默认：ruby）
        -s --separate-files [true | false] : 是否将控制项输出为多个文件（默认：true）

示例：

bash
inspec_tools csv2inspec -c examples/csv2inspec/stig.csv -m examples/csv2inspec/mapping.yml -o mydir -f ruby -s true

inspec2csv

将JSON格式的InSpec配置文件转换为安全控制项CSV电子表格。

bash
USAGE: inspec_tools inspec2csv [OPTIONS] -j <inspec-json> -o <profile-csv>
FLAGS:
        -j --inspec-json <inspec-json> : InSpec JSON文件路径
        -o --output <profile-csv>      : CSV输出文件路径
        -V --verbose                   : 详细模式（可选）

示例：

bash
inspec_tools inspec2csv -j inspec_profile.json -o mycsv.csv

inspec2ckl

将InSpec结果JSON转换为STIG检查表（CKL）。

bash
USAGE: inspec_tools inspec2ckl [OPTIONS] -j <inspec-json> -o <results-ckl>
FLAGS:
        -j --inspec-json <inspec-json> : InSpec结果JSON文件路径
        -o --output <results-ckl>      : 检查表输出文件路径
        -m --metadata <metadata-json>  : 检查表额外元数据JSON文件路径（可选）
        -V --verbose                   : 详细模式（可选）

示例：

bash
inspec_tools inspec2ckl -j results.json -o output.ckl

pdf2inspec

将包含CIS基准的PDF文件转换为InSpec配置文件。

bash
USAGE: inspec_tools pdf2inspec [OPTIONS] -p <cis-benchmark>
FLAGS:
        -p --pdf <cis-benchmark>           : CIS基准PDF文件路径
        -o --output <profile-path>         : InSpec配置文件输出路径（默认：profile）
        -f --format [ruby | hash]          : 输出格式（默认：ruby）
        -s --separate-files [true | false] : 是否将控制项输出为多个文件（默认：true）
        -d --debug                         : 调试模式（可选）

示例：

bash
inspec_tools pdf2inspec -p benchmark.pdf -o /path/to/myprofile -f ruby -s true

xlsx2inspec

将XLSX格式的CIS基准转换为InSpec控制项。

bash
Usage:
  inspec_tools xlsx2inspec -m, --mapping=MAPPING -p, --control-name-prefix=CONTROL_NAME_PREFIX -x, --xlsx=XLSX

Options:
  -x, --xlsx=XLSX                          : XLSX文件路径
  -m, --mapping=MAPPING                    : 映射文件路径
  -p, --control-name-prefix=CONTROL_NAME_PREFIX : 控制项名称前缀
  -V, [--verbose]                          : 详细模式
  -o, [--output=OUTPUT]                    : 输出路径（默认：profile）
  -f, [--format=FORMAT]                    : 输出格式（默认：ruby，可选：ruby、hash）
  -s, [--separate-files]                   : 是否分离文件（默认：true）
      [--log-level=LOG_LEVEL]              : 日志级别（debug、info、warn、error、fatal）
      [--log-location=LOG_LOCATION]        : 日志输出位置（默认：标准输出）
  l, [--log-directory=LOG_DIRECTORY]       : 日志目录

示例：

bash
bundle exec inspec_tools xlsx2inspec -m examples/xlsx2inspec/mapping.cis.yml -p azure-cis-foundations -x examples/cis.xlsx

version

打印工具版本信息。

bash
USAGE: inspec_tools version

Ruby API使用方法

1. 在Ruby文件中引入库：

   ruby
   require 'inspec_tools'
   

2. 创建InspecTools实例并转换结果：

   ruby
   # 初始化工具实例
   tool = InspecTools::Inspec.new(results_json)
   
   # 转换为CKL格式
   ckl_results = tool.to_ckl
   
   # 转换为CSV格式
   csv_results = tool.to_csv
   
   # 转换为XCCDF格式（需提供属性JSON）
   # 属性JSON示例见：examples/attribute.json
   xccdf_results = tool.to_xccdf(attribs_json)
   

输入输出文件格式

InspecTools会尽力转换输入文件中的各种遗留术语和值。若遇到不支持的术语，请提交issue反馈。

工具生成的配置文件遵循最新的NIST（美国国家标准与技术研究院）术语和值标准，如通用漏洞评分系统（CVSS）。

有关支持的输入格式和预期输出格式的详细信息，请参阅项目wiki：

• https://github.com/mitre/inspec_tools/wiki/Expected-Input
• https://github.com/mitre/inspec_tools/wiki/Expected-Output