Heimdall Enterprise Server 2 lets you view, store, and compare automated security control scan results.
This repository contains the source code for Heimdall's Backend, Frontend (AKA Heimdall Lite), OHDF Converters, and InSpecJS.
Heimdall Lite | Heimdall Server
Heimdall Lite
Heimdall Server
There are two ways to deploy the MITRE Heimdall application - Heimdall-Lite and the full Heimdall with Backend Server. Both share the same frontend but have been produced to meet different needs and use-cases.
As a single-page javascript app - you can run Heimdall-Lite from any web-server, a secured S3 bucket or directly via GitHub Pages (as it is here). Heimdall-Lite gives you the ability to easily review and produce reports about your InSpec run, filter the results for easy review and hot-wash, print out reports, and much more.
Heimdall with Backend, or Heimdall Server runs the same front end as Heimdall-Lite, but is supported with a backend database to store persistent data overtime.
Heimdall Lite is published to npmjs.org and is available here.
To run Heimdall Lite locally, just use the npm built-in utility npx:
npm
npx
npx @mitre/heimdall-lite
If you use this tool often and want to have it installed locally, use the following command:
npm install -g @mitre/heimdall-lite
Then, any subsequent npx @mitre/heimdall-lite will use the local version and load much more quickly.
It is also possible to run Heimdall-Lite using Docker, using the following command:
docker run -d -p 8080:80 mitre/heimdall-lite:release-latest
You can then access Heimdall-Lite at http://localhost:8080.
http://localhost:8080
If you would prefer to run the bleeding edge version of Heimdall-Lite, replace mitre/heimdall-lite:release-latest with mitre/heimdall-lite:latest.
mitre/heimdall-lite:release-latest
mitre/heimdall-lite:latest
Given that Heimdall requires at least a database service, we use Docker and Docker Compose to provide a simple deployment experience. This process will also deploy an NGINX webserver in front of Heimdall to handle TLS.
Heimdall's frontend container image is distributed on DockerHub, and on Iron Bank.
Install Docker
Download and extract the most recent Heimdall release from our releases page. Alternatively, you can clone this repository and navigate to the heimdall2 folder.
heimdall2
Navigate to the base folder where docker-compose.yml is located
docker-compose.yml
By default Heimdall will generate self-signed certificates that will last for 7 days. For production use, place your certificate files in ./nginx/certs/ with the names ssl_certificate.crt and ssl_certificate_key.key respectively. For development use, you can use the default generated certificates which means you do not need to put any certificate files in the ./nginx/certs/ folder.
./nginx/certs/
ssl_certificate.crt
ssl_certificate_key.key
NGINX Configuration Note: You can configure NGINX settings by changing values in the nginx/conf/default.conf file.
nginx/conf/default.conf
# For Linux or Mac ./setup-docker-env.sh # For Windows ./setup-docker-env.bat
[!TIP] If you would like to further configure your Docker-based Heimdall deployment, edit the .env file located in the root directory generated after running the setup-docker-env.sh or setup-docker-env.bat scripts
setup-docker-env.sh
setup-docker-env.bat
./certs/
command
certs
# Below is an example of what may be in the ./certs directory, including any scripts or certificates. # ./certs/ # ├── dodcerts.sh # └── my_certificates.pem # For the given example, the ./docker-compose.yml should look like the following: services: ... certs: ... command: sh -c "sh /etc/pki/ca-trust/source/anchors/dodcerts.sh && update-ca-trust && tail -f /dev/null" # NOTE: The `command` attribute only needs to know about scripts not any particular certificates. ... ...
To make the docker-compose.yml aware of additional scripts, add sh /etc/pki/ca-trust/source/anchors/NAME_OF_SCRIPT.sh && to the beginning of the section in quotes. NOTE: The script should make sure to place the certs within /etc/pki/ca-trust/source/anchors/ since it will be run from the container, not the host.
sh /etc/pki/ca-trust/source/anchors/NAME_OF_SCRIPT.sh &&
/etc/pki/ca-trust/source/anchors/
docker-compose up
https://127.0.0.1
Starting with version 2.5.0, Heimdall on Docker uses SSL by default. Place your certificate files in ./nginx/certs/ with the names ssl_certificate.crt and ssl_certificate_key.key respectively.
A new version of the docker container can be retrieved by running:
docker-compose pull docker-compose up -d
This will fetch the latest version of the container, redeploy if a newer version exists, and then apply any database migrations if applicable. No data should be lost by this operation.
From the source directory you started from run:
docker-compose down
https://github.com/mitre/heimdall2-helm
Cloud.gov is a FEDRAMP moderate Platform-as-a-Service (PaaS). This repository includes a sample manifest.yml.example file ready to be pushed and run the latest version of Heimdall2 as a container. Make a copy of the example file and update the key values as appropriate. $ cp manifest.yml.example manifest.yml
$ cp manifest.yml.example manifest.yml
Setup a cloud.gov account - https://cloud.gov/docs/getting-started/accounts/
Install the cf-cli - https://cloud.gov/docs/getting-started/setup/
Run the following commands in a terminal window from the Heimdall source directory.
$ cd ~/Documents/Github/Heimdall2 $ cf login -a api.fr.cloud.gov --sso # Follow the link to copy the Temporary Authentication Code when prompted
$ cf target -o sandbox-rename create-space heimdall2-rename
# Update manifest.yml file to rename application and database key name $ cf marketplace $ cf create-service aws-rds medium-psql heimdall2-rename $ cf create-service-key heimdall2-db-rename heimdall2-db-test-key $ cf push
You should be returned the URL for your new test instance to navigate to.
Note: This is only for demonstration purposes, in order to run a production level federal/FISMA system. You will need to contact the cloud.gov program and consult your organization's security team (for risk assessment and an Authority to Operate).
Heimdall currently provides connectivity to the following services for importing and visualizing scans:
For detail information on how to setup and connect to an AWS S3 bucket see the Heimdall Interface Connection - AWS S3 Wiki
AWS S3
For detail information on how to setup and connect to an Splunk instances (logical or virtual) see the Heimdall Interface Connection - Splunk Wiki
Splunk
For detail information on how to setup and connect to an Tenable.SC instance see the Heimdall Interface Connection - Tenable.SC Wiki
Tenable.SC
API usage only works when using Heimdall Enterprise Server (AKA "Server Mode").
Heimdall API documentation is being compiled and it is located in this wiki page. In the meantime here are quick instructions for uploading evaluations to Heimdall Server.
# To use API Keys, ensure you have set the API_KEY_SECRET environment variable. To create a secret run: openssl rand -hex 33 # Create an API key using the Heimdall frontend (within the edit user profile modal) and upload an evaluation with the following command curl -F "data=@<Path to Evaluation File>" -F "filename=<Filename To Show in Heimdall>" -F "public=true/false" -F "evaluationTags=<tag-name>,<another-tag-name>..." -H "Authorization: Api-Key apikeygoeshere" "http://localhost:3000/evaluations" # You can upload multiple files at once (up to 100) curl -F "data=@<Path to first evaluation File>" -F "data=@<Path to second evaluation File>" ... -F "public=true/false" -F "evaluationTags=<tag-name>,<another-tag-name>..." -H "Authorization: Api-Key apikeygoeshere" "http://localhost:3000/evaluations"
If you would like to change Heimdall to your needs, you can use Heimdall's 'Development Mode' to ease the development process. The benefit to using this mode is that it will automatically rebuild itself and use those changes as soon as you make them. Please note that you should not run development mode when deploying Heimdall for general usage.
Install system dependencies with your system's package manager. NodeJS is required and can be installed via your system's package manager, or an alternative method if desired. Documented below is the installation via your system's package manager.
Ubuntu:
# grab nodesource for recent version of nodejs sudo curl -sL https://deb.nodesource.com/setup_18.x -o /tmp/nodesource_setup.sh sudo bash /tmp/nodesource_setup.sh # use apt to install dependencies sudo apt install postgresql nodejs git sudo apt install nano # recommended installation sudo npm install -g yarn
NOTES
The installation scripts setup_XX.x are no longer supported and are not needed anymore, as the installation process is straightforward for any RPM and DEB distro.
See the Debian and Ubuntu based distributions nodesource for nodejs supported version and additional installation information
OSX:
brew install postgresql node@18 git brew install nano # recommended installation sudo npm install -g yarn
WINDOWS:
Install Node.js via MSI Installer
node --version npm --version
Install Yarn via MSI Installer
yarn --version
Clone this repository:
git clone https://github.com/mitre/heimdall2
Setup the PostgreSQL server:
# Switch to the OS postgres user sudo -u postgres -i # Start the Postgres terminal psql postgres # Create the database user CREATE USER <username> with encrypted password '<password>'; ALTER USER <username> CREATEDB; \q # Switch back to your original OS user exit
# Start the postgres server corresponding to your installation method pg_ctl -D /opt/homebrew/var/postgres start # Alternatively, you may find postgres in another location like the following: pg_ctl -D /usr/local/var/postgres start # Brew method brew services start postgresql@13 # Start the Postgres terminal psql postgres # Create the database user CREATE USER <username> with encrypted password '<password>'; ALTER USER <username> CREATEDB; \q # Switch back to your original OS user exit
net start
net start postgresql-[x32 or x64]-[version]
pg_ctl
pg_ctl -D "C:\[path-to-postgres-installation]\PostgreSQL\[version]\data" start
win key + R
Run
services.msc
OK
Postgresql-[x32 or x64]-[version]
Start/play
# Start the terminal psql -U postgres # Create the database user CREATE USER <username> with encrypted password '<password>'; ALTER USER <username> CREATEDB; \q
Install project dependencies:
cd heimdall2 yarn install # you may need to run yarn install --registry https://registry.npmjs.org
Edit or generate the database environment configuration file (apps/backend/.env) using the provided setup-dev-env.sh or setup-dev-env.bat script. Make sure to set the DATABASE_USERNAME and DATABASE_PASSWORD variables with values used in step 3.
setup-dev-env.sh or setup-dev-env.bat
You can also edit, if exists, the apps/backend/.env file using a text editor and set additional optional configuration values. For more info on configuration values see Environment Variables Configuration.
[!NOTE] The .env file in the root repository is for the Docker deployment of the Heimdall application. Running a local build will use the .env file in the apps/backend directory for the database configurations.
apps/backend
Create and seed the database:
# Windows yarn backend sequelize-cli-windows db:create yarn backend sequelize-cli-windows db:migrate yarn backend sequelize-cli-windows db:seed:all # All other OSs yarn backend sequelize-cli db:create yarn backend sequelize-cli db:migrate yarn backend sequelize-cli db:seed:all
Start Heimdall:
yarn start:dev
This will start both the frontend and backend in development mode, meaning any changes you make to the source code will take effect immediately. Please note we already have a Visual Studio Code workspace file you can use to organize your workspace.
If you are using Visual Studio Code, it is very simple to debug this application locally. First open up the Visual Studio Code workspace and ensure the Node debugger Auto Attach feature in Visual Studio Code is enabled. Next, open the integrated Visual Studio Code terminal and run:
yarn backend start:debug
Visual Studio Code will then automatically attach a debugger and stop and any breakpoints you place in the application.
If you only want to make changes to the frontend (heimdall-lite) use the following command:
yarn frontend start:dev
To validate and lint your code run:
yarn run lint
yarn build
To test your code to make sure everything still works:
# Run Frontend Vue Tests yarn frontend test # Run Backend Nest Tests (see note) yarn backend test:ci-cov
NOTE: The Backend Nest Tests will remove (BULKDELETE) all entries in the configured PostgreSQL server for the following tables:
Backend Nest Tests
The application includes an End-to-End (E2E) frontend and Backend tests (built using the cypress.io framework). The E2E tests performed is to validate that Heimdall Server is running as intended. In order to run these tests, a running instance of the application is required.
CYPRESS_TESTING=true yarn start:dev CYPRESS_BASE_URL=http://localhost:8080 yarn test:ui:open
The first command will start an instance of Heimdall Server and exposes additional routes required to allow the tests to run. The second will open the Cypress UI which will run the tests any time code changes are made.
[!NOTE] When running the tests locally, tests that integrate with external services such as LDAP or Splunk will fail without having that external service running and configured. If these failures occur locally and local development does not impact the code relevant to those tests, you may consider permitting these failing tests locally and check that they pass in the pipeline in lieu of standing up local services only for testing purposes.
Note: This action requires appropriate privileges on the repository to perform.
The steps to create a release are now on the wiki.
This project uses the Semantic Versioning Policy
Please feel free to look through our issues, make a fork and submit PRs and improvements. We love hearing from our end-users and the community and will be happy to engage with you on suggestions, updates, fixes or new capabilities.
Please feel free to contact us by opening an issue on the issue board, or, at [email protected] should you have any suggestions, questions or issues. If you have more general questions about the use of our software or other concerns, please contact us at [email protected].