diff --git a/README.md b/README.md index 36a29469f..a6a779b73 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ 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](https://github.com/mitre/heimdall_tools) and [InSpec Tools](https://github.com/mitre/inspec_tools). +The SAF CLI is the successor to [Heimdall Tools](https://github.com/mitre/heimdall_tools) and [InSpec Tools](https://github.com/mitre/inspec_tools). ## Terminology: @@ -13,6 +13,7 @@ The SAF CLI is the successor to [Heimdall Tools](https://github.com/mitre/heimda - [SAF CLI Installation](#installation) - [Via NPM](#installation-via-npm) + - [Via Brew](#installation-via-brew) - [Via Docker](#installation-via-docker) - [Via Windows Installer](#installation-via-windows-installer) @@ -61,7 +62,6 @@ npm install -g @mitre/saf ``` - #### Update via NPM To update the SAF CLI with `npm`: @@ -73,15 +73,35 @@ npm update -g @mitre/saf --- +#### 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 saf-cli +``` + +--- + + #### Installation via Docker -**On Linux and Mac:** +**On Linux and Mac:** ``` docker run -it -v$(pwd):/share mitre/saf ``` -**On Windows:** +**On Windows:** ``` docker run -it -v%cd%:/share mitre/saf @@ -162,7 +182,7 @@ convert hdf2asff Translate a Heimdall Data Format JSON file into -C, --certificate=certificate Trusted signing certificate file -I, --insecure Disable SSL verification (WARNING: this is insecure) -u, --upload Upload findings to AWS Security Hub - + EXAMPLES saf convert hdf2asff -i rhel7.scan.json -a 123456789 -r us-east-1 -t rhel7_example_host -o rhel7-asff saf convert hdf2asff -i rhel7.scan.json -a 123456789 -r us-east-1 -t rhel7_example_host -u @@ -207,20 +227,20 @@ HDF Splunk Schema documentation: https://github.com/mitre/heimdall2/blob/master/ ##### Previewing HDF Data Within Splunk: A full raw search query: ```sql -index="<>" meta.subtype=control | stats values(meta.filename) values(meta.filetype) list(meta.profile_sha256) values(meta.hdf_splunk_schema) first(meta.status) list(meta.status) list(meta.is_baseline) values(title) last(code) list(code) values(desc) values(descriptions.*) values(id) values(impact) list(refs{}.*) list(results{}.*) list(source_location{}.*) values(tags.*) by meta.guid id -| join meta.guid - [search index="<>" meta.subtype=header | stats values(meta.filename) values(meta.filetype) values(meta.hdf_splunk_schema) list(statistics.duration) list(platform.*) list(version) by meta.guid] -| join meta.guid - [search index="<>" meta.subtype=profile | stats values(meta.filename) values(meta.filetype) values(meta.hdf_splunk_schema) list(meta.profile_sha256) list(meta.is_baseline) last(summary) list(summary) list(sha256) list(supports{}.*) last(name) list(name) list(copyright) list(maintainer) list(copyright_email) last(version) list(version) list(license) list(title) list(parent_profile) list(depends{}.*) list(controls{}.*) list(attributes{}.*) list(status) by meta.guid] +index="<>" meta.subtype=control | stats values(meta.filename) values(meta.filetype) list(meta.profile_sha256) values(meta.hdf_splunk_schema) first(meta.status) list(meta.status) list(meta.is_baseline) values(title) last(code) list(code) values(desc) values(descriptions.*) values(id) values(impact) list(refs{}.*) list(results{}.*) list(source_location{}.*) values(tags.*) by meta.guid id +| join meta.guid + [search index="<>" meta.subtype=header | stats values(meta.filename) values(meta.filetype) values(meta.hdf_splunk_schema) list(statistics.duration) list(platform.*) list(version) by meta.guid] +| join meta.guid + [search index="<>" meta.subtype=profile | stats values(meta.filename) values(meta.filetype) values(meta.hdf_splunk_schema) list(meta.profile_sha256) list(meta.is_baseline) last(summary) list(summary) list(sha256) list(supports{}.*) last(name) list(name) list(copyright) list(maintainer) list(copyright_email) last(version) list(version) list(license) list(title) list(parent_profile) list(depends{}.*) list(controls{}.*) list(attributes{}.*) list(status) by meta.guid] ``` A formatted table search query: ```sql -index="<>" meta.subtype=control | stats values(meta.filename) values(meta.filetype) list(meta.profile_sha256) values(meta.hdf_splunk_schema) first(meta.status) list(meta.status) list(meta.is_baseline) values(title) last(code) list(code) values(desc) values(descriptions.*) values(id) values(impact) list(refs{}.*) list(results{}.*) list(source_location{}.*) values(tags.*) by meta.guid id -| join meta.guid - [search index="<>" meta.subtype=header | stats values(meta.filename) values(meta.filetype) values(meta.hdf_splunk_schema) list(statistics.duration) list(platform.*) list(version) by meta.guid] -| join meta.guid - [search index="<>" meta.subtype=profile | stats values(meta.filename) values(meta.filetype) values(meta.hdf_splunk_schema) list(meta.profile_sha256) list(meta.is_baseline) last(summary) list(summary) list(sha256) list(supports{}.*) last(name) list(name) list(copyright) list(maintainer) list(copyright_email) last(version) list(version) list(license) list(title) list(parent_profile) list(depends{}.*) list(controls{}.*) list(attributes{}.*) list(status) by meta.guid] +index="<>" meta.subtype=control | stats values(meta.filename) values(meta.filetype) list(meta.profile_sha256) values(meta.hdf_splunk_schema) first(meta.status) list(meta.status) list(meta.is_baseline) values(title) last(code) list(code) values(desc) values(descriptions.*) values(id) values(impact) list(refs{}.*) list(results{}.*) list(source_location{}.*) values(tags.*) by meta.guid id +| join meta.guid + [search index="<>" meta.subtype=header | stats values(meta.filename) values(meta.filetype) values(meta.hdf_splunk_schema) list(statistics.duration) list(platform.*) list(version) by meta.guid] +| join meta.guid + [search index="<>" meta.subtype=profile | stats values(meta.filename) values(meta.filetype) values(meta.hdf_splunk_schema) list(meta.profile_sha256) list(meta.is_baseline) last(summary) list(summary) list(sha256) list(supports{}.*) last(name) list(name) list(copyright) list(maintainer) list(copyright_email) last(version) list(version) list(license) list(title) list(parent_profile) list(depends{}.*) list(controls{}.*) list(attributes{}.*) list(status) by meta.guid] | rename values(meta.filename) AS "Results Set", values(meta.filetype) AS "Scan Type", list(statistics.duration) AS "Scan Duration", first(meta.status) AS "Control Status", list(results{}.status) AS "Test(s) Status", id AS "ID", values(title) AS "Title", values(desc) AS "Description", values(impact) AS "Impact", last(code) AS Code, values(descriptions.check) AS "Check", values(descriptions.fix) AS "Fix", values(tags.cci{}) AS "CCI IDs", list(results{}.code_desc) AS "Results Description", list(results{}.skip_message) AS "Results Skip Message (if applicable)", values(tags.nist{}) AS "NIST SP 800-53 Controls", last(name) AS "Scan (Profile) Name", last(summary) AS "Scan (Profile) Summary", last(version) AS "Scan (Profile) Version" | table meta.guid "Results Set" "Scan Type" "Scan (Profile) Name" ID "NIST SP 800-53 Controls" Title "Control Status" "Test(s) Status" "Results Description" "Results Skip Message (if applicable)" Description Impact Severity Check Fix "CCI IDs" Code "Scan Duration" "Scan (Profile) Summary" "Scan (Profile) Version" ``` @@ -268,7 +288,7 @@ convert hdf2condensed Condensed format used by some community members OPTIONS -i, --input=xml Input HDF file -o, --output=output Output condensed JSON file - + EXAMPLES saf convert hdf2condensed -i rhel7-results.json -o rhel7-condensed.json @@ -343,7 +363,7 @@ convert burpsuite2hdf Translate a BurpSuite Pro XML file into a Heimdall OPTIONS -i, --input=xml Input BurpSuite Pro XML File -o, --output=output Output HDF JSON File - + EXAMPLES saf convert burpsuite2hdf -i burpsuite_results.xml -o output-hdf-name.json @@ -664,7 +684,7 @@ convert zap2hdf Translate a OWASP ZAP results JSON to HDF format Js You can start a local Heimdall Lite instance to visualize your findings with the SAF CLI. To start an instance use the `saf view heimdall` command: ``` -view:heimdall Run an instance of Heimdall Lite to visualize +view:heimdall Run an instance of Heimdall Lite to visualize your data OPTIONS @@ -688,7 +708,7 @@ view:summary Get a quick compliance overview of HDF files -i, --input=FILE (required) Input HDF file(s) -j, --json Output results as JSON -o, --output=output - + EXAMPLE saf view summary -i rhel7-host1-results.json nginx-host1-results.json mysql-host1-results.json ``` @@ -728,7 +748,7 @@ generate ckl_metadata Generate a checklist metadata template for "saf con OPTIONS -o, --output=output (required) Output JSON File - + EXAMPLE saf generate ckl_metadata -o rhel_metadata.json ``` @@ -754,7 +774,7 @@ Threshold files are used in CI to ensure minimum compliance levels and validate See the wiki for more information on [template files](https://github.com/mitre/saf/wiki/Validation-with-Thresholds). ``` -generate threshold Generate a compliance template for "saf validate threshold". +generate threshold Generate a compliance template for "saf validate threshold". Default output states that you must have your current control counts or better (More Passes and/or less Fails/Skips/Not Applicable/No Impact/Errors) @@ -773,10 +793,10 @@ generate threshold Generate a compliance template for "saf validate thresho #### Spreadsheet (csv/xlsx) to InSpec -You can use `saf generate spreadsheet2inspec_stub` to generate an InSpec profile stub from a spreadsheet file. +You can use `saf generate spreadsheet2inspec_stub` to generate an InSpec profile stub from a spreadsheet file. ``` -generate spreadsheet2inspec_stub Generate an InSpec profile stub from a CSV STIGs or CIS XLSX benchmarks +generate spreadsheet2inspec_stub Generate an InSpec profile stub from a CSV STIGs or CIS XLSX benchmarks USAGE $ saf generate spreadsheet2inspec_stub -i, --input= -o, --output=FOLDER @@ -816,7 +836,7 @@ generate xccdf2inspec_stub Generate an InSpec profile stub from a D ``` - + #### Other