Using an unreleased version of select packages from the SAF ecosystem in the SAF CLI

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

Run git clone for the mitre/heimdall2 (or mitre/ts-inspec-objects) and mitre/saf repos

If you already have a copy of mitre/heimdall2 (or mitre/ts-inspec-objects) 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) (or the mitre/ts-inspec-objects repository which contains the inspec-objects package) 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 package into the local SAF CLI

To configure the local saf repository to use a local version of a package, navigate to the saf repository in the terminal and run the following commands to install a package for use in the SAF CLI. The commands for each Heimdall package and InSpec Objects all follow the same format as shown below. Choose the npm run command(s) that correspond to the local 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>

# inspec-objects
npm run pack-inspec-objects --branch=<ts-inspec-objects-branch-name> --inspec-objects=<path-to-ts-inspec-objects>

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 (<ts-inspec-objects-branch-name> for ts-inspec-objects), and <path-to-heimdall> is either the absolute or relative path to your local heimdall2 repository (likewise for <path-to-ts-inspec-objects> and your local ts-inspec-objects repository).

Note

• A copy of your local 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. a. main for ts-inspec-objects
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. a. inspec-objects will look for ts-inspec-objects

Repositories
├── heimdall2
│   └── ...
├── ts-inspec-objects
│   └── ...
└── saf
    └── ...

Testing your installation of local 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

Testing inspec-objects 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>