malwaredb 0.3.0
Python client for MalwareDB
Requires Python: >=3.7
Keywords: cybersecurity, database, forensics, malware, research

## Malware DB Python Client
[![Test](https://github.com/malwaredb/malwaredb-rs/actions/workflows/test.yml/badge.svg)](https://github.com/malwaredb/malwaredb-rs/actions/workflows/test.yml)[![Lint](https://github.com/malwaredb/malwaredb-rs/actions/workflows/lint.yml/badge.svg)](https://github.com/malwaredb/malwaredb-rs/actions/workflows/lint.yml)[![Python](https://github.com/malwaredb/malwaredb-rs/actions/workflows/python_release.yml/badge.svg)](https://github.com/malwaredb/malwaredb-rs/actions/workflows/python_release.yml)[![Release](https://github.com/malwaredb/malwaredb-rs/actions/workflows/release.yml/badge.svg)](https://github.com/malwaredb/malwaredb-rs/actions/workflows/release.yml)[![Documentation](https://docs.rs/malwaredb-client-py/badge.svg)](https://docs.rs/malwaredb-client-py/)[![Crates.io Version](https://img.shields.io/crates/v/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.