Heimdall Interface Connections

Note

Heimdall provides interfaces to several Systems/Applications for the purposes of automation retrieval of Cybersecurity scan results.
Documented here is the how-to establish connectivity with the interfaces provided by the Heimdall infrastructure.

For additional interfaces please contact the SAF team at Request Heimdall Interface Connection

Important

Both Splunk and Tenable.SC require a connection variable containing the external host URL to be properly configured prior of deploying Heimdall.
See External Interface for additional information

Splunk

Splunk Interfacing Guide

Login via Heimdall

Accessing a Splunk instance from Heimdall requires the input of the following information:

username: A qualified username recognized by the referenced Splunk instance.
password: A qualified password recognized by the referenced Splunk instance.
hostname: The domain name for the desired Splunk instance. Include port number if available.
index: A valid index name within the referenced Splunk instance. See section 'Splunk Indexes' for more details

An example of a valid login request in Heimdall:

Splunk Set Up

The default configuration for a Splunk instance can result in data loss or interfacing errors when communicating with Heimdall. It is highly recommended to change these default configurations as specified here.

To use a Splunk Docker Image for the purpose of testing the interface, reference the instructions provided in the Splunk Docker Image section.

Splunk Data

The Splunk platform accepts any type of data. In particular, it works with all IT streaming and historical data. The source of the data can be event logs, web logs, live application logs, network feeds, system metrics, change monitoring, message queues, archive files, and so on.

Splunk Indexes

An index in Splunk serves as a repository for data. When raw data is added to Splunk, it indexes the data (i.e., uses the data to update its indexes) and creates events for later reference.

For uploading or downloading data, Heimdall can only interface with Splunk by interacting with valid user-specified indexes. It is recommended to use a dedicated index (e.g., hdf) specifically for HDF files for easier data management.

To create an index using the Splunk GUI:

Go to Settings

Go to Indexes

Press the New Index button

Fill out the fields for your new index

Press the Save button

Your new index should now appear in the index list

Splunk Docker Image

These instructions are for creating a Splunk Docker Container and connecting to Heimdall Lite for interface testing.

Set Up Heimdall Lite and the Splunk Enterprise Container

To install and run Heimdall Lite in Development Mode following these steps:
- Step 1. Retrieve the repository from GitHub using the following command:
```
git clone https://github.com/mitre/heimdall2
```
- Step 2. Navigate to the Heimdall2 repository directory and run the following command to install the necessary packages:
```
yarn install
```
- Step 3. Use the following command in the Heimdall2 directory to start up Development Mode:
```
yarn start:dev
```
NOTE: For additional instructions reference the official documentation for Heimdall2.
Install Docker.
To set up and run a Splunk Enterprise container follow these steps:
- Step 1. Pull the latest official Splunk Enterprise image using the following command:
```
docker pull splunk/splunk:latest
```
- Step 2. Create a default.yml file with the following content. These custom configurations are used to allow the generated Splunk Enterprise container to connect to the Heimdall Lite instance.
```
splunk:
  conf:
    - key: limits
      value:
        directory: /opt/splunk/etc/system/default
        content:
          kv:
            limit: 10000000
            maxchars: 1000000
    - key: props
      value:
        directory: /opt/splunk/etc/system/default
        content:
          HDF2Splunk:
            SHOULD_LINEMERGE: false
            EVENT_BREAKER_ENABLE: true
            EVENT_BREAKER: ([\n]+)
            TRUNCATE: 0
    - key: server
      value:
        directory: /opt/splunk/etc/system/default
        content:
          httpServer:
            crossOriginSharingPolicy: "*"
            crossOriginSharingHeaders: "*"
            disabled: 0
```
  NOTE: The default.yml content is used to modify the appropriate splunk configuration. The key: tags specify the file to modify and the directory: tag specifies the file location.
- Step 3. Create a Splunk Enterprise container using the following command, replace <PASSWORD> with a Splunk Enterprise compliant password and specify the path to the default.yml file.
  - OSX/Linux:
```
sudo docker run -d -p 8000:8000 -p 8089:8089 -e 'SPLUNK_START_ARGS=--accept-license' -e 'SPLUNK_PASSWORD=<PASSWORD>' -v '/ENTER/PATH/TO/default.yml:/tmp/defaults/default.yml' splunk/splunk:latest
```
  - Windows:
```
docker run -d -p 8000:8000 -p 8089:8089 -e "SPLUNK_START_ARGS=--accept-license" -e "SPLUNK_PASSWORD=<PASSWORD>" -v "ENTER\PATH\TO\default.yml:/tmp/defaults/default.yml" splunk/splunk:latest
```
  Command breakdown:
  - -d start the docker deamon. When combined with docker run -d [other options] <image_name> it runs the container in the background
  - -p 8000:8000 -p 8089:8089 exposes a port mapping from the host's 8000 and 8089 ports to the container's 8000 (user friendly frontend) and 8089 (REST API access) ports respectively.
  - -e 'SPLUNK_START_ARGS=--accept-license' accepts the license agreement. This must be accepted to start up the container.
  - -e 'SPLUNK_PASSWORD=<PASSWORD>' sets the password for the admin user.
  - -v mount a volume (absolute paths needed). We can use %cd% (windows) or $PWD (OSX/Linux) to specify the current directory. In the given example '/ENTER/PATH/TO/default.yml:/tmp/defaults/default.yml' mounts the default.yml file onto the container which then adjusts the default configuration files according to the specified settings in default.yml.
- Step 4. Docker should now be starting up the container. Use the command docker ps to check the status of the container. When the container's status is healthy, it is ready to use.
- Step 5. Access http://localhost:8000 and https://localhost:8089 to ensure that the Splunk Enterprise container is accessible from your host ports. Log in on http://localhost:8000 to access the Splunk Enterprise web interface.
NOTE: For additional instructions reference the official documentation for Splunk in Docker.

Connecting Heimdall Lite to the Splunk Enterprise Container

Disable CORS on your browser. This can be achieved with Google Chrome using the following command to open a CORS-disabled tab:

Windows:

"C:\Program Files\Google\Chrome\Application\chrome.exe" --disable-web-security --disable-gpu --user-data-dir=%LOCALAPPDATA%\Google\chromeTemp

OSX:

open -n -a /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --args --user-data-dir="/tmp/chrome_dev_test" --disable-web-security

Linux:
```
google-chrome --disable-web-security
```

Access Heimdall Lite by going to localhost:8080. Click on the Splunk tab on the left of the interface.
Enter your credentials for the Splunk Enterprise container. Unless you are specifically targeting a certain user, use: username admin, password set in the previous section, and hostname https://localhost:8089.
Heimdall Lite should now connect and display the contents of the Splunk container.

NOTE: If you receive an Error: Login timed out. Please check your CORS configuration or validate you have inputted the correct domain, you most likely have an issue related to CORS. Ensure that CORS is disabled on your browser or recreate your Splunk container using the provided default.yml.

Tenable.SC

Login to Tenable.SC

Accessing a Tenable.sc instance via the Heimdall interface requires API Key Authorization as an authentication method for Tenable.sc API requests.

The Allow API Keys toggle must be enable in the tenable.sc Security Settings to allow users to perform API key authentication. Then, users can generate API keys for themselves or for other users. API keys include an access key and secret key that must be used together for API key authentication. For more information, see Enable API Key Authentication and Generate API Keys.

Once the API Keys are available authenticate to tenable.sc by providing the following information:

Access Token: The user API Key generated by the tenable.sc instances being accessed.
Secret Token: The user API Secret generated by the tenable.sc instances being accessed.
Hostname: The tenable.sc host secure URL follow by the secure port (443).

Import Scans from Tenable.SC

To download scans from the tenable.sc select one of the options Today's, 30 Days, 60 Days, or 90 Days.

To load available scans select the scans and click on the into Heimdall click on the Load Selected icon

Content Security Policy Configuration

Heimdall uses Content Security Policy (CSP) as an added layer of security that helps detect and mitigate Cross-Site Scripting (XSS) and data injection attacks.

For this reason there is a need to explicit specify the Tenable.SC URL in the TENABLE_HOST_URL environment configuration file (.env) during deployment of Heimdall Server.

Tenable.SC CORS Configuration

In order to allow Heimdall to connect to a Tenable.SC instance, the hosting services should be configured with an allowlist that includes the calling domain where Heimdall resides as a trusted domain to perform CORS requests.

For information on how to enable open access across domain boundaries, please reference the CORS Enabled W3C wiki.

To temporarily disable CORS for local development, you can use a browser extension like CORS Unlock.

It is also possible to start Google Chrome on Windows with CORS temporarily disabled by starting the browser with web security disabled.

Create a short cut, in the "Type the location of the item:" text box enter the following command:

  "C:\Program Files (x86)\Google\Chrome\Application\chrome.exe" --user-data-dir="C:/Chrome dev session" --disable-web-security"

AWS S3

Login to AWS

Accessing an AWS S3 bucket via the Heimdall interface requires the input of the following information:

User Account Access Token: The access key for an AWS account.
User Account Secret Token: The secret access key for the same AWS account.
Bucket Region: The region name where the bucket is located, defaults to us-east-1.

You can then choose to log in via one of two different ways:

Basic Login: Allows for the connection to occur without using multi-factor-authentication (MFA) if the account doesn't have MFA set up or if it has the appropriate permissions set.
MFA Login: Allows for the connection to occur while using multi-factor-authentication (MFA).

If you do an MFA login, you will also need to supply the following information:

MFA Token: The MFA token that is generated by your MFA device.
MFA Device ARN: The identifier for the MFA device. Should be in the form of arn:aws:iam::ACCOUNT_NUMBER:mfa/DEVICE_NAME. If you do not supply one, it is assumed that the device's name is the same as the AWS user's name.

Lastly, you will need to provide the bucket name and choose which files to import. After you type in a bucket name and search, you will see files show up in the list so long as the bucket name is correct and contains files.

Bucket name: The bucket name containing scans to be imported into Heimdall

Import Scans from S3

To download scans from the S3 bucket click on the download icon

To load available scans into Heimdall click on the icon next to the appropriate entry

AWS CORS Configuration

In order to allow Heimdall to connect to an AWS S3 bucket, we need to add a Cross-Origin Resource Sharing policy within the AWS Console. Some examples on how to accomplish is provide in the CORS configuration web page

The following rule configuration is sufficient, however the allowed origin attribute (AllowedOrigins) needs to reflect the domain where Heimdall is deployed.

[
    {
        "AllowedHeaders": [
            "*"
        ],
        "AllowedMethods": [
            "GET",
            "HEAD"
        ],
        "AllowedOrigins": [
            "https://heimdall.your.site.here/"
        ],
        "ExposeHeaders": [],
        "MaxAgeSeconds": 3000
    }
]

Helping the overall cybersecurity strength of organizations.

Heimdall©

Security Data Visualization App

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Heimdall Interface Connections

Splunk

Splunk Interfacing Guide

Table of Contents

Login via Heimdall

Splunk Set Up

Splunk Data

Splunk Indexes

Splunk Docker Image

Set Up Heimdall Lite and the Splunk Enterprise Container

Connecting Heimdall Lite to the Splunk Enterprise Container

Tenable.SC

Table of Contents

Login to Tenable.SC

Import Scans from Tenable.SC

Content Security Policy Configuration

Tenable.SC CORS Configuration

AWS S3

Table of Contents

Login to AWS

Import Scans from S3

AWS CORS Configuration

Heimdall©

Table of Contents

Common Instructions

Developers Corner

HDF / Converts / Attestation

Other Documentation

Clone this wiki locally