EDMTool

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.

Table of Contents

• Features
• Development
• Installation
• Usage
  • Hash EDM DB file
  • Create a New Database Entry and Upload the EDM DB File
  • Create a New Database Entry
  • Upload the EDM DB File
  • Update an existing Database Entry and Upload the EDM DB File

Features

• 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.

Development

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 venv

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

To install all dependencies

make install-dev

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

python3 -m edmtool <commands>

Installation

Build the package:

make build

To install after building (from the dist folder), you can use pip:

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

or you can run the following to install locally:

make install-local

Usage

Hash EDM DB file

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 a new Database Entry and upload

Create an new EDM DB entry and upload the associated file.

edmtool create_and_upload --name "Your DB Name" --description "Your Description" --metadata_file_path /path/to/your/file_encoded_metadata.json --base_url http://example.cyberhaven.com --token YOUR_AUTH_TOKEN

Update an existing Database Entry and upload

Update an existing EDM DB entry and upload the associated file.

edmtool update_and_upload --id DATABASE_ID --description "Your Description" --metadata_file_path /path/to/your/updated_file_encoded_metadata.json --base_url http://example.cyberhaven.com --token YOUR_AUTH_TOKEN

Create a new Database entry

Create the database entry based on a generated EDM DB encoded file.

edmtool create --name "Your DB Name" --description "Your Description" --metadata_file_path /path/to/your/file_encoded_metadata.json --base_url http://example.cyberhaven.com --token YOUR_AUTH_TOKEN

Update an existing Database entry

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 http://example.cyberhaven.com --token YOUR_AUTH_TOKEN

Upload an encoded file

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 http://api.example.com --token YOUR_AUTH_TOKEN