malwaredb 0.3.3

Python client for MalwareDB

Malware DB Python Client

This is a Python module for interacting with an instance of Malware DB.

Installation

Assuming you already have Malware DB checked out:

1. python3 -m venv mdb-venv
2. source mdb-venv/bin/activate
3. pip install maturin
4. cd client-py
5. maturin develop (or maturin build to create a distributable wheel)

Features

If using this crate with another library, be sure to use the rust_lib feature flag to avoid creating the Malware DB client module type. This could be useful for reusing the functions defined in this crate with another Python module.

Use

1. Import the module: from malwaredb import MalwareDBClient
2. Create a client object from one of three ways:
   • MalwareDBClient.from_file() to use a configuration file
   • MalwareDBClient() to have the client library find a configuration file
   • MalwareDBClient.connect(url, api_key, [cert_path]) to provide the URL, API key, and optional path for a certificate for encrypted communication
   • MalwareDBClient.login(url, username, password, save, [cert_path]) to provide the URL, username, password, whether to save the configuration, and optional path for a certificate for encrypted communication
   • MalwareDBCLient.discover() to find local servers via multicast DNS
3. Client functionality:
   • .get_file_bytes() get a file from Malware DB
   • .server_info() get server information
   • .submit_file() submit a file to Malware DB
   • .get_supported_file_types() get a list of file types supported by the Malware DB server
   • .search() search for files based on some criteria. Some optional keyword arguments, a minimum of one criterion is required:
     • hash=: specify a partial hash
     • hash_type=: specify the type of the partial hash, options are md5, sha1, sha256, or sha512, default is sha256
     • file_name=: specify all or part of a file name
     • labels=: specify a list of labels
     • file_type=: specify a file type, which must match a file type from .get_supported_file_types()
     • magic=: specify all or part of the file command (libmagic) output for a given file
     • response_hash=: specify the hash type to be returned, options are md5, sha1, sha256, or sha512, default is sha256
     • limit=: integer specifying the maximum results to be returned, must be greater than zero
   • .labels() get available labels for samples
   • .whoami() get information about the user's account
   • .yara_search() search for files using Yara, if the server supports it
   • .yara_result() get results of Yara search using UUID
4. CaRT functionality:
   • malwaredb.cart.create_cart() encodes bytes into a CaRT bytes
   • malwaredb.cart.decode_cart() decodes CaRT bytes back into the original binary long with header and footer data. See client-py/py_test/cart.py.
   • Current limitations:
     • create_cart() doesn't allow setting custom fields.
     • decode_cart() will not be able to return fields which aren't plain float, integer, or string types.
   • See cart as an alternative CaRT module which is probably more feature-rich.