## Malware DB Python Client
[](https://github.com/malwaredb/malwaredb-rs/actions/workflows/test.yml)[](https://github.com/malwaredb/malwaredb-rs/actions/workflows/lint.yml)[](https://github.com/malwaredb/malwaredb-rs/actions/workflows/python_release.yml)[](https://github.com/malwaredb/malwaredb-rs/actions/workflows/release.yml)[](https://docs.rs/malwaredb-client-py/)[](https://crates.io/crates/malwaredb-client-py)
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](https://github.com/CybercentreCanada/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](https://pypi.org/project/cart/) as an alternative `CaRT` module which is probably more feature-rich.