Skip to main content

A Python module to parse DISA STIG (XCCDF) Files

Project description


Logo

Explore the docs »

Report Bug · Request Feature

GitHub last commit PyPi GitHub Workflow Status GitHub Open Issues GitHub Open PRs Python Versions GitHub License LinkedIN Profile

NOTE: As of version 1.1.0, the JSON output fields have been renamed and CamelCased. This was an effort to standardize the variables being used. When using Versions less than 1.1.0, please ensure you update your field names prior to updating.

About

A basic Python package to parse DISA STIGs (XCCDF) into a readable JSON format.

Installation

To install stig-parser, simple run the following command:

pip install stig-parser

Version Updates

The table below briefly describes each update. For more information, view the releases page.

Version Description
1.0.0 Initial Creation of stig-parser
1.0.1 Updated to handle change to STIG schema (Issue #3)
1.0.2 Added Additional Fields to Output JSON. View Release Notes for Full Details (Issue #9)
1.1.0 Added Additional Fields to Output JSON, Included BETA release of CKL creation and added the ability to parse a STIG directly from the ZIP file. View Release Notes for Full Details
1.1.1 Resolved Issues Concerning STIG Rules with Multiple CCIs. Credit: @gregelin

Documentation

Documentation hasn't been created at this time. For the current development documentation, please visit the repository.

Testing

This project leverages GitHub Actions for its CI/CD workflow. During a Push to any branch, with the exception of Master and Dev, the workflow will perform Unit Testing and Linting.

For manual testing, run the following commands;

## START PYTHON DEV CONTAINER
docker run -it --rm -v $(PWD):/stig-parser python /bin/bash

## INSTALL DEPENDENCIES
pip install pytest pytest-cov xmltodict

## CHANGE WORKING DIRECTORY
cd stig-parser

## RUN PYTEST
pytest -v

## RUN PYTEST COVERAGE
pytest --cov src

Usage

This module contains the following functions;

Function Description Parameters
convert_stig(STIG_FILE) This function will extract the STIG from a ZIP archive, and parse the results into a JSON object STIG_FILE == Path to STIG ZIP File
convert_xccdf(STIG_XML) This function will parse a raw bytes of a STIG file (XML) and return a JSON object STIG_XML == Bytes object of STIG xccdf.xml File
generate_stig_json(STIG_JSON, EXPORT_PATH) This function will write the STIG JSON object to a File STIG_JSON == JSON Object of STIG, EXPORT_PATH == Path to create JSON File
generate_ckl(STIGFILE, CHECKLIST_INFO) This function will generate an XML Object of a CKL based upon a passed STIG STIG_FILE == Path to STIG ZIP File , CHECKLIST_INFO == JSON Object of additional information needed (see below)
generate_ckl_file(CKL, EXPORT_PATH) This function will write the CKL XML Object to a File CKL == XML Object of CKL , EXPORT_PATH == Path to create CKL File

When creating a Checklist (CKL), additional information is required. This information is added to the CKL but is required to be defined prior to creation. For an example of usage, please see the examples below.

{
  "ROLE": "None",
  "ASSET_TYPE": "Computing",
  "HOST_NAME": "Test_Host",
  "HOST_IP": "1.2.3.4",
  "HOST_MAC": "",
  "HOST_FQDN": "test.hostname.dev",
  "TARGET_COMMENT": "",
  "TECH_AREA": "",
  "TARGET_KEY": "3425",
  "WEB_OR_DATABASE": "false",
  "WEB_DB_SITE": "",
  "WEB_DB_INSTANCE": ""
}

Examples

This module has several use cases that will either generate a JSON object of a STIG file, or an XML object of a CKL file.

STIGs

To convert a STIG file to a JSON object, you can utilize the following example.

## LOAD PYTHON MODULE
from stig_parser import convert_stig

## PARSE STIG ZIP FILE
## ASSUMES ZIP FILE IS IN CURRENT WORKING DIRECTORY
json_results = convert_stig('./U_Docker_Enterprise_2-x_Linux-UNIX_V1R1_STIG.zip')

Additionally, this example demonstrates how to generate the STIG JSON object from an xccdf file.

## LOAD PYTHON MODULE
from stig_parser import convert_xccdf

## LOAD XML FILE (OPTIONAL)
import os

with open("U_Docker_Enterprise_2-x_Linux-UNIX_STIG_V1R1_Manual-xccdf.xml", "r") as fh:
    raw_file = fh.read()

## PARSE XCCDF(XML) to JSON
json_results = convert_xccdf(raw_file)

Checklists (CKL)

To generate a CKL from a given STIG, you can utilize the following example;

## LOAD PYTHON MODULE
from stig_parser import generate_ckl, generate_ckl_file

## DEFINE STIG FILE LOCATION
## ASSUMES ZIP FILE IS IN CURRENT WORKING DIRECTORY
STIG = './U_Docker_Enterprise_2-x_Linux-UNIX_V1R1_STIG.zip'

## DEFINE EXPORT LOCATION
EXPORT = './ myCKL.ckl'

## DEFINE ADDITIONAL CHECKLIST INFORMATION
CHECKLIST_INFO ={
  "ROLE": "None",
  "ASSET_TYPE": "Computing",
  "HOST_NAME": "Test_Host",
  "HOST_IP": "1.2.3.4",
  "HOST_MAC": "",
  "HOST_FQDN": "test.hostname.dev",
  "TARGET_COMMENT": "",
  "TECH_AREA": "",
  "TARGET_KEY": "3425",
  "WEB_OR_DATABASE": "false",
  "WEB_DB_SITE": "",
  "WEB_DB_INSTANCE": ""
}


## GENERATE CKL XML OBJECT
RAW_CKL = generate_ckl(STIG, CHECKLIST_INFO)

## SAVE CHECKLIST TO FILE
generate_ckl_file(RAW_CKL, EXPORT)

Output

Outlined below is the expected JSON output:

{
  "Title": "xxxxxxx",
  "Description": "xxxxxxx",
  "Version": "x",
  "Release": "x ",
  "BenchmarkDate": "xxxxxxx",
  "ReleaseInfo": "xxxxxxx",
  "Source": "xxxxxxx",
  "Notice": "xxxxxxx",
  "Rules": [
    {
      "VulnID": "xxxxxxx",
      "RuleID": "xxxxxxx",
      "StigID": "xxxxxxx",
      "Severity": "high | medium | low",
      "Cat": "CAT I | CAT II | CAT III",
      "Classification": "",
      "GroupTitle": "xxxxxxx",
      "RuleTitle": "xxxxxxx",
      "Description": "xxxxxxx",
      "VulnDiscussion": "xxxxxxx",
      "FalsePositives": "xxxxxxx",
      "FalseNegatives": "xxxxxxx",
      "Documentable": "xxxxxxx",
      "Mitigations": "xxxxxxx",
      "SeverityOverrideGuidance": "xxxxxxx",
      "PotentialImpacts": "xxxxxxx",
      "ThirdPartyTools": "xxxxxxx",
      "MitigationControl": "xxxxxxx",
      "Responsibility": "xxxxxxx",
      "IAControls": "xxxxxxx",
      "CheckText": "xxxxxxx",
      "FixText": "xxxxxxx",
      "CCI": "xxxxxxx"
    }
  ]
}

Dependencies

The following packages are required for this package:

Package Name Reason
xmltodict This converts the raw XML file to a python dictionary for ease of processing

Comments, Concerns and Gripes

If you have any comments, concerns and/or gripes, please feel free to submit an issue on the repository.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

stig_parser-1.1.1.tar.gz (12.7 kB view hashes)

Uploaded source

Built Distribution

stig_parser-1.1.1-py3-none-any.whl (10.2 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page