Using an unreleased version of a package from the Heimdall monorepo in the SAF CLI

If you want to test an unreleased version of a package contained in the Heimdall2 monorepo on the SAF CLI, follow these steps:

Run git clone for the mitre/heimdall2 and mitre/saf repos

If you already have a copy of mitre/heimdall2 and mitre/saf, please keep track of the file paths for a future step.

Otherwise, clone local copies of both the mitre/heimdall2 repository (which is a monorepo containing the hdf-converters, inspecjs, and heimdall-lite packages) and the mitre/saf repository. This can be done by using the git clone command like so:

git clone --branch <tag> <repo>

where <tag> is the name of the branch and <repo> is the link to the repository (either SSH or HTTPS). For example, to clone the master branch of heimdall2:

git clone --branch master https://github.com/mitre/heimdall2.git

Install the local Heimdall package into the local SAF CLI

To configure the local saf repository to use a local version of a Heimdall package, navigate to the saf repository in the terminal and run the following commands to install a Heimdall package for use in the SAF CLI. The commands for each Heimdall package all follow the same format as shown below. Choose the npm run command(s) that correspond to the local Heimdall package(s) that you want to use.

git switch <saf-branch-name>
npm install

# hdf-converters
npm run pack-hdf-converters --branch=<heimdall-branch-name> --heimdall=<path-to-heimdall>

# inspecjs
npm run pack-inspecjs --branch=<heimdall-branch-name> --heimdall=<path-to-heimdall>

# heimdall-lite
npm run pack-heimdall-lite --branch=<heimdall-branch-name> --heimdall=<path-to-heimdall>

where <saf-branch-name> is the desired branch of saf you wish to use, <heimdall-branch-name> is the desired branch of heimdall2 you wish to use, and <path-to-heimdall> is either the absolute or relative path to your local heimdall2 repository.

Note

• A copy of your local heimdall2 branch must also be stored on a remote branch.
• If your changes to a converter involved changes to inspecjs, you will have to run the installation commands for both hdf-converters and inspecjs.
• Do not forget any equal signs in the packing command!

Defaults:

1. If the git switch command is not run, the current branch of the SAF CLI is used.
2. If the heimdall2 branch name is not given (--branch=<heimdall-branch-name>), the master branch is used.
3. If the path for heimdall2 (--heimdall=<path-to-heimdall>) is not provided, the command will look for a directory called heimdall2 at the same level as the saf repository by default. See the example file tree below.

Repositories
├── heimdall2
│   └── ...
└── saf
    └── ...

Testing your installation of local Heimdall packages

To run/test your commands and converters use:

npm run dev -- <saf-cli-command>

If any commands do not work, build the SAF CLI locally by running npm run prepack. This will build and create the bin directory at root. Then run your command with the following:

./bin/run <saf-cli-command>

Testing hdf-converters with the SAF CLI

npm run dev -- convert <converter> -i <path-to-input> -o <path-to-output>

# Example:
npm run dev -- convert burpsuite2hdf -i dummy/file.xml -o dummy/output.json

Testing inspecjs with the SAF CLI

To tests your changes to inspecjs with the SAF CLI, determine which commands make use of the features/code that was modified and then run:

npm run dev -- <relevant-saf-command>

Testing heimdall-lite with the SAF CLI

To open heimdall-lite with the SAF CLI, run the following command:

npm run dev heimdall