README.md

# Heimdall Tools

Heimdall Tools supplies several methods to convert output from various tools to "Heimdall Data Format"(HDF) format to be viewable in Heimdall. The current converters are:

- **sonarqube_mapper** - open-source static code analysis tool
- **fortify_mapper** - commercial static code analysis tool
- **zap_mapper** - OWASP ZAP - open-source dynamic code analysis tool
- **burpsuite_mapper** - commercial dynamic analysis tool
- **nessus_mapper** - commercial vulnerability scanner
- **snyk_mapper** - commercial package vulnerability scanner
- **nikto_mapper** - open-source web server scanner
- **jfrog_xray_mapper** - package vulnerability scanner
- **dbprotect_mapper** - database vulnerability scanner
- **aws_config_mapper** - assess, audit, and evaluate AWS resources
- **netsparker_mapper** - web application security scanner


## Command line Usage

On the Command Line, `heimdall_tools help` will print a listing of all the command with a short description.
For detailed help on any command, run `heimdall_tools help [COMMAND]`. Help can also be called with the `-h, --help` flags after any command, like `heimdall_tools fortify_mapper -h`.

For Docker usage, replace the `heimdall_tools` command with the correct Docker command below for your operating system:

- **On Linux and Mac:** `docker run -it -v$(pwd):/share mitre/heimdall_tools`
- **On Windows CMD:** `docker run -it -v%cd%:/share mitre/heimdall_tools`

Note that all of the above Docker commands will mount your current directory on the Docker container. Ensure that you have navigated to the directory you intend to convert files in before executing the command.

## sonarqube_mapper

sonarqube_mapper pulls SonarQube results, for the specified project, from the API and outputs in HDF format Json to be viewed on Heimdall

```
USAGE: heimdall_tools sonarqube_mapper [OPTIONS] -n <project-name> -u <api-url> -o <scan-results.json>

FLAGS:
    -n --name <project-key>         : Project Key of the project in SonarQube
    -u --api_url <api-url>           : url of the SonarQube Server API. Typically ends with /api.
    --auth <credentials>              : username:password or token [optional].
    -o --output <scan-results>       : path to output scan-results json.
    -V --verbose                     : verbose run [optional].

example:

heimdall_tools sonarqube_mapper -n sonar_project_key -u http://sonar:9000/api -o scan_results.json

heimdall_tools sonarqube_mapper -n sonar_project_key -u http://sonar:9000/api --auth admin:admin -o scan_results.json
```

## fortify_mapper

fortify_mapper translates an Fortify results FVDL file into HDF format json to be viewable in Heimdall

```
USAGE: heimdall_tools fortify_mapper [OPTIONS] -f <fortify-fvdl> -o <scan-results.json>

FLAGS:
	-f --fvdl <fortify-fvdl>         : path to Fortify Scan FVDL file.
	-o --output <scan-results>       : path to output scan-results json.
	-V --verbose                     : verbose run [optional].

example: heimdall_tools fortify_mapper -f audit.fvdl -o scan_results.json
```

## zap_mapper

zap_mapper translates OWASP ZAP results Json to HDF format Json be viewed on Heimdall

```
USAGE: heimdall_tools zap_mapper [OPTIONS] -j <zap-json> -n <site-name> -o <scan-results.json>

FLAGS:
    -j --json <zap-json>             : path to OWASP ZAP results JSON file.
    -n --name <site-name>            : URL of the site being evaluated.
    -o --output <scan-results>       : path to output scan-results json.
    -V --verbose                     : verbose run [optional].

example: heimdall_tools zap_mapper -j zap_results.json -n site_name -o scan_results.json
```

## burpsuite_mapper

burpsuite_mapper translates an BurpSuite Pro exported XML results file into HDF format json to be viewable in Heimdall

```
USAGE: heimdall_tools burpsuite_mapper [OPTIONS] -x <burpsuite-xml> -o <scan-results.json>

FLAGS:
    -x <burpsuite_xml>               : path to BurpSuitePro exported XML results file.
    -o --output <scan-results>       : path to output scan-results json.
    -V --verbose                     : verbose run [optional].

example: heimdall_tools burpsuite_mapper -x burpsuite_results.xml -o scan_results.json
```

## nessus_mapper

nessus_mapper translates a Nessus-exported XML results file into HDF format json to be viewable in Heimdall

Note: A separate HDF JSON file is generated for each host reported in the Nessus Report.

```
USAGE: heimdall_tools nessus_mapper [OPTIONS] -x <nessus-results-xml> -o <hdf-file-prefix>

FLAGS:
    -x <nessus-results-xml>          : path to Nessus-exported XML results file.
    -o --output_prefix <prefix>      : path to output scan-results json.
    -V --verbose                     : verbose run [optional].

example: heimdall_tools nessus_mapper -x nessus-results.xml -o test-env
```

## snyk_mapper

snyk_mapper translates an Snyk results JSON file into HDF format json to be viewable in Heimdall

Note: A separate HDF JSON is generated for each project reported in the Snyk Report.

```
USAGE: heimdall_tools snyk_mapper [OPTIONS] -x <snyk-results-json> -o <hdf-file-prefix>

FLAGS:
    -j <snyk_results_jsonl>          : path to Snyk results JSON file.
    -o --output_prefix <prefix>      : path to output scan-results json.
    -V --verbose                     : verbose run [optional].

example: heimdall_tools snyk_mapper -j snyk_results.json -o output-file-prefix
```

## nikto_mapper

nikto_mapper translates an Nikto results JSON file into HDF format JSON to be viewable in Heimdall

Note: Current this mapper only support single target Nikto Scans.

```
USAGE: heimdall_tools nikto_mapper [OPTIONS] -x <nikto-results-json> -o <hdf-scan-results.json>

FLAGS:
    -j <nikto_results_json>          : path to Nikto results JSON file.
    -o --output_prefix <prefix>      : path to output scan-results json.
    -V --verbose                     : verbose run [optional].

example: heimdall_tools nikto_mapper -j nikto_results.json -o nikto_results.json
```

## jfrog_xray_mapper

jfrog_xray_mapper translates an JFrog Xray results JSON file into HDF format JSON to be viewable in Heimdall

```
USAGE: heimdall_tools jfrog_xray_mapper [OPTIONS] -j <xray-results-json> -o <hdf-scan-results.json>

FLAGS:
    -j <xray_results_json>           : path to xray results JSON file.
    -o --output <scan-results>       : path to output scan-results json.
    -V --verbose                     : verbose run [optional].

example: heimdall_tools jfrog_xray_mapper -j xray_results.json -o xray_results_hdf.json
```

## dbprotect_mapper

dbprotect_mapper translates DBProtect report in `Check Results Details` format XML to HDF format JSON be viewed on Heimdall.

```
USAGE: heimdall_tools dbprotect_mapper [OPTIONS] -x <check_results_details_report_xml> -o <db_protect_hdf.json>

FLAGS:
    -x <check_results_details_report_xml>           : path to DBProtect report XML file.
    -o --output <scan-results>       : path to output scan-results json.
    -V --verbose                     : verbose run [optional].

example: heimdall_tools dbprotect_mapper -x check_results_details_report.xml -o db_protect_hdf.json
```

## aws_config_mapper

aws_config_mapper pulls Ruby AWS SDK data to translate AWS Config Rule results into HDF format json to be viewable in Heimdall

### AWS Config Rule Mapping:
  The mapping of AWS Config Rules to 800-53 Controls was sourced from [this link](https://docs.aws.amazon.com/config/latest/developerguide/operational-best-practices-for-nist-800-53_rev_4.html).

### Authentication with AWS:
  [Developer Guide for configuring Ruby AWS SDK for authentication](https://docs.aws.amazon.com/sdk-for-ruby/v3/developer-guide/setup-config.html)

```
USAGE: heimdall_tools aws_config_mapper [OPTIONS] -o <hdf-scan-results.json>

FLAGS:
    -o --output <scan-results>       : path to output scan-results json.
    -V --verbose                     : verbose run [optional].

example: heimdall_tools aws_config_mapper -o aws_config_results_hdf.json
```

## netsparker_mapper

netsparker_mapper translates an Netsparker XML results file into HDF format JSON to be viewable in Heimdall.

  The current iteration only works with Netsparker Enterprise Vulnerabilities Scan.

```
USAGE: heimdall_tools netsparker_mapper [OPTIONS] -x <netsparker_results_xml> -o <hdf-scan-results.json>

FLAGS:
    -x <netsparker_results_xml>      : path to netsparker results XML file.
    -o --output <scan-results>       : path to output scan-results json.
    -V --verbose                     : verbose run [optional].

example: heimdall_tools netsparker_mapper -x netsparker_results.xml -o netsparker_hdf.json
```

## version

Prints out the gem version

```
USAGE: heimdall_tools version
```