Security Automation Framework CLI

The MITRE Security Automation Framework (SAF) Command Line Interface (CLI) brings together applications, techniques, libraries, and tools developed by MITRE and the security community to streamline security automation for systems and DevOps pipelines

The SAF CLI is the successor to Heimdall Tools and InSpec Tools.

Terminology

• "Heimdall" - A visualizer for all security result data
• "OASIS Heimdall Data Format (OHDF) - aka HDF" - A common data format to preserve and transform security data

[!NOTE] All mention of HDF in this document refers to the OHDF.

Installation

• Via NPM
  • Update via NPM
• Via Brew
  • Update via Brew
• Via Docker
  • Update via Docker
• Via Windows Installer
  • Update via Windows Installer

Developers

For detailed information about development, testing , and contributing to the SAF project refer to MITRE SAF Development

Usage

Attest HDF Data

• Attest
  • Create Attestations
  • Apply Attestations

Get Help with Convert Command

Convert HDF to Other Formats

• Convert From HDF
  • HDF to ASFF
  • HDF to Splunk
  • HDF to XCCDF Results
  • HDF to Checklist
  • HDF to CSV
  • HDF to Condensed JSON

Convert Other Formats to HDF

• Convert To HDF
  • Anchore Grype to HDF
  • ASFF to HDF
  • AWS Config to HDF
  • Burp Suite to HDF
  • CKL to POA&M
  • CycloneDX SBOM to HDF
  • DBProtect to HDF
  • Dependency-Track to HDF
  • Fortify to HDF
  • gosec to HDF
  • Ion Channel 2 HDF
  • JFrog Xray to HDF
  • Tenable Nessus to HDF
  • Microsoft Secure Score to HDF
  • Netsparker to HDF
  • NeuVector to HDF
  • Nikto to HDF
  • Prisma to HDF
  • Prowler to HDF
  • Sarif to HDF
  • Scoutsuite to HDF
  • Snyk to HDF
  • SonarQube to HDF
  • Splunk to HDF
  • Trivy to HDF
  • Trufflehog to HDF
  • Twistlock to HDF
  • Veracode to HDF
  • XCCDF Results to HDF
  • OWASP ZAP to HDF

eMASSer Client

• eMASSer API CLI

View HDF Summaries and Data

• View
  • Heimdall
  • Summary

Validate HDF Thresholds

• Validate
  • Thresholds

Generate Data Reports and More

• Generate
  • Delta
  • Delta Supporting Commands
  • CKL Templates
  • InSpec Metadata
  • Inspec Profile
  • Thresholds
  • Spreadsheet (csv/xlsx) to InSpec
    • DoD Stub vs CIS Stub Formatting
  • Mapping Files

Enhance and Supplement HDF Data

• Supplement
  • Passthrough
    • Read
    • Write
  • Target
    • Read
    • Write

License and Authors

• License and Author

---

Installation

---

Installation via NPM

The SAF CLI can be installed and kept up to date using npm, which is included with most versions of NodeJS.

npm install -g @mitre/saf

Update via NPM

To update the SAF CLI with npm:

npm update -g @mitre/saf

top

---

Installation via Brew

The SAF CLI can be installed and kept up to date using brew.

brew install mitre/saf/saf-cli

Update via Brew

To update the SAF CLI with brew:

brew upgrade mitre/saf/saf-cli

top

---

Installation via Docker

On Linux and Mac:

The docker command below can be used to run the SAF CLI one time, where arguments contains the command and flags you want to run. For ex: --version or view summary -i hdf-results.json.

docker run -it -v$(pwd):/share mitre/saf <arguments>

To run the SAF CLI with a persistent shell for one or more commands, use the following, then run each full command. For ex: saf --version or saf view summary -i hdf-results.json. You can change the entrypoint you wish to use. For example, run with --entrypoint sh to open in a shell terminal. If the specified entrypoint is not found, try using the path such as --entrypoint /bin/bash.

docker run --rm -it --entrypoint bash -v$(pwd):/share mitre/saf

On Windows:

The docker command below can be used to run the SAF CLI one time, where arguments contains the command and flags you want to run. For ex: --version or view summary -i hdf-results.json.

docker run -it -v%cd%:/share mitre/saf <arguments>

To run the SAF CLI with a persistent shell for one or more commands, use the following, then run each full command. For ex: saf --version or saf view summary -i hdf-results.json. You can change the entrypoint you wish to use. For example, run with --entrypoint sh to open in a shell terminal. If the specified entrypoint is not found, try using the path such as --entrypoint /bin/bash.

docker run --rm -it --entrypoint sh -v%cd%:/share mitre/saf

NOTE:

Remember to use Docker CLI flags as necessary to run the various subcommands.

For example, to run the emasser configure subcommand, you need to pass in a volume that contains your certificates and where you can store the resultant .env. Furthermore, you need to pass in flags for enabling the pseudo-TTY and interactivity.

docker run -it -v "$(pwd)":/share mitre/saf emasser configure

Other commands might not require the -i or -t flags and instead only need a bind-mounted volume, such as a file based convert.

docker run --rm -v "$(pwd)":/share mitre/saf convert -i test/sample_data/trivy/sample_input_report/trivy-image_golang-1.12-alpine_sample.json -o test.json

Other flags exist to open up network ports or pass through environment variables so make sure to use whichever ones are required to successfully run a command.

Update via Docker

To update the SAF CLI with docker:

docker pull mitre/saf:latest

top

---

Installation via Windows Installer

To install the latest release of the SAF CLI on Windows, download and run the most recent installer for your system architecture from the Releases 🌬️ page.

Update via Windows Installer

To update the SAF CLI on Windows, uninstall any existing version from your system and then download and run the most recent installer for your system architecture from the Releases 🌬️ page.

top

Usage

---

Attest

Attest to 'Not Reviewed' controls: sometimes requirements can’t be tested automatically by security tools and hence require manual review, whereby someone interviews people and/or examines a system to confirm (i.e., attest as to) whether the control requirements have been satisfied.

Create Attestations

attest create              Create attestation files for use with `saf attest apply`

USAGE
  $ saf attest create -o <attestation-file> [-i <hdf-json> -t <json | xlsx | yml | yaml>]

FLAGS
  -i, --input=<value>    (optional) An input HDF file to search for controls
  -o, --output=<value>   (required) The output filename
  -t, --format=<option>  [default: json] (optional) The output file type
                         <options: json|xlsx|yml|yaml>

  GLOBAL FLAGS
    -h, --help               Show CLI help
    -L, --logLevel=<option>  [default: info] Specify level for logging (if implemented by the CLI command)
                             <options: info|warn|debug|verbose>
        --interactive        Collect input tags interactively (not available on all CLI commands)

EXAMPLES
  $ saf attest create -o attestation.json -i hdf.json

  $ saf attest create -o attestation.xlsx -t xlsx

top

Apply Attestations

attest apply              Apply one or more attestation files to one or more HDF results sets

USAGE
  $ saf attest apply -i <input-hdf-json>... <attestation>... -o <output-hdf-path>

FLAGS
  -i, --input=<value>...  (required) Your input HDF and Attestation file(s)
  -o, --output=<value>    (required) Output file or folder (for multiple executions)

  GLOBAL FLAGS
    -h, --help               Show CLI help
    -L, --logLevel=<option>  [default: info] Specify level for logging (if implemented by the CLI command)
                             <options: info|warn|debug|verbose>
        --interactive        Collect input t