edmtool is a command-line interface tool, written in Python, designed to interact with the Cyberhaven EDM DB API. It allows users to manage and upload hashed EDM database files to the Cyberhaven console. Once the data is ingested into the Cyberhaven backend, it can be operated on them further from within the Cyberhaven dashboard (e.g., for building EDM Rules and managing the database definitions).

Our tool supports both Spooky Hash V2 and SHA256.

• Features

• Development

• Installation

• Usage

  • Hash EDM DB file
  • Create a New Database Entry and Upload the EDM DB File
  • Update a Existing Database Entry and Upload the EDM DB File
  • Create a New Database Entry (without uploading)
  • Update an Existing Database Entry (without uploading)
  • Upload the EDM DB File manually

• Hash EDM DB file into a compatible format in order to upload.
• Create a new EDM database entry and upload the EDM DB file directly.
• Upload EDM DB file with progress tracking.

If the original EDM DB file is malformed, the hashing process will not fail, but the malformed rows will be skipped. The tool will log the number of skipped rows and their positions.

For development, we recommend Python>=3.7 and pip. Please also use virtualenv (or an alternative) in order to develop in isolation from the system-wide Python packages.

Once you install virtualenv, run:

make create_venv

# IMPORTANT!
# activate the venv
source .venv/bin/activate

To install all dependencies

make install-dev-deps

Also it is possible to run the CLI for testing purposes without building and installing it locally:

python3 -m edmtool <commands>

After installing all dependencies, build the package:

make build

To install after building, you can use pip:

pip install ./dist/edmtool-<version>.tar.gz

or you can run the following to install the package from local code:

make install-local

To use edmtool, you need to create an API token in the Cyberhaven console. The token is used to authenticate the tool with the Cyberhaven backend.

Open "Settings" > "API token management (legacy)" and create a new token. Copy the token and use it as YOUR_AUTH_TOKEN in the following commands.

It takes an input file provided by you and generates 2 new output files. A <filename>_encoded.csv and <filename>_encoded_metadata.json, please do not modify in any way or remove those once generated.

edmtool encode --algorithm "spooky" --db_file_path ./path/to/your/file.csv

You can also use optional argument to indicate that your EDM DB CSV file delimiter is distinct from ','

--db_file_delimiter ';'

The supported hashing algorithms are spooky and sha256.

Create an new EDM DB entry and upload the associated file. The file has to be hashed prior to creating the database entry.

edmtool create_and_upload --name "Your DB Name" --description "Your Description" --metadata_file_path /path/to/your/file_encoded_metadata.json --base_url https://your-tenant.cyberhaven.io --token YOUR_AUTH_TOKEN

Update an existing EDM DB entry and upload updated associated file. The file has to be hashed prior to updating the database entry.

edmtool update_and_upload --id DATABASE_ID --description "Your Description" --metadata_file_path /path/to/your/updated_file_encoded_metadata.json --base_url https://your-tenant.cyberhaven.io --token YOUR_AUTH_TOKEN

Create the database entry based on a generated EDM DB encoded file. The file has to be hashed prior to creating the database entry.

edmtool create --name "Your DB Name" --description "Your Description" --metadata_file_path /path/to/your/file_encoded_metadata.json --base_url https://your-tenant.cyberhaven.io --token YOUR_AUTH_TOKEN

Update an existing database with a new EDM DB encoded file.

edmtool update --name "Your DB Name" --description "Your Description" --metadata_file_path /path/to/your/file_encoded_metadata.json --base_url https://your-tenant.cyberhaven.io --token YOUR_AUTH_TOKEN

Upload the EDM DB encoded file. This applies to both new and existing database entries.

edmtool upload --id DATABASE_ID --metadata_file_path ./path/to/your/file_encoded_metadata.json --base_url https://your-tenant.cyberhaven.io --token YOUR_AUTH_TOKEN