Metadata-Version: 2.4
Name: mw-collector
Version: 0.1.0
Summary: A CLI tool for collecting malware samples and metadata from a list of public malware repositories.
Author: Batu Durmazel
License-Expression: MIT
License-File: LICENSE
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Dist: requests
Requires-Dist: python-dotenv
Requires-Dist: pydantic
Requires-Dist: platformdirs
Requires-Python: >=3.13
Project-URL: Homepage, https://github.com/silveera/malware-collector
Project-URL: Issues, https://github.com/silveera/malware-collector/issues
Description-Content-Type: text/markdown

# malware-collector

A CLI tool for collecting malware samples and metadata from a list of public malware repositories.

> **Warning:** This project downloads real malware samples. Handle downloaded samples with care and only use the tool in an appropriate environment.

## Features

* Collect malware samples from multiple sources.
* Store sample metadata in a local SQLite database.
* Detect previously collected samples using SHA-256 hashes.
* Store downloaded samples in a configurable quarantine directory.
* Configure API keys through the CLI.
* Configure database and quarantine locations.

## Supported Sources

| Source | API Key | Password | Discovery | API Limit |
| --- | --- | --- | --- | --- |
| MalwareBazaar | Required | `infected` | last 100 | 2000/day |
| MalShare      | Required | None       | last 24h | 2000/day |

The "Password" column is for sources which download locked files. For example, MalwareBazaar only downloads `.zip` archives locked with the password "infected".

The "Discovery" column shows which recent samples each source exposes and is the default download window for sources in the application. MalwareBazaar currently exposes the last 100 samples while MalShare exposes samples from the last 24 hours. Ways to limit/modify download amounts will be introduced in a future version.

The "API Limit" column shows the default documented limit for API requests per source. This does not necessarily represent the number of samples that can be downloaded, as sources differ on API request usage.

Support for additional sources is pending.

## Requirements

* Python 3.13 or later
* An API key for each source you intend to use

## Installation

Install using pip:

```bash
pip install mw-collector
```

Alternatively, install using uv:

```bash
uv tool install mw-collector
```

After installation, the application can be accessed through the `mw-collector` command:

```bash
mw-collector --help
```

## Configuration

### API Keys

API keys can be configured using:

```bash
mw-collector config api-key <source>
```

For example:

```bash
mw-collector config api-key malwarebazaar
```

The API key will be requested interactively without displaying the entered value.

Available sources are:

```text
malwarebazaar
malshare
```

### Application Paths

The application stores its configuration and data in user-specific application directories rather than in the installation directory.

To print the configuration file path:

```bash
mw-collector config path
```

A specific path can also be selected using `--target` or `-t`:

```bash
mw-collector config path --target config
mw-collector config path --target api-keys
mw-collector config path -t db
mw-collector config path -t quarantine
```

On Linux, the default locations are:

```text
~/.config/mw-collector/config.toml
~/.config/mw-collector/api_keys.env
~/.local/share/mw-collector/malware.db
~/.local/share/mw-collector/quarantine/
```

### Changing Storage Paths

The configuration file contains the database and quarantine locations:

```toml
[storage]
database = "/path/to/malware.db"
quarantine = "/path/to/quarantine"
```

These values can be changed manually to use different storage locations.

## Usage

### Collecting Samples

To collect from all supported sources:

```bash
mw-collector collect
```

Or:

```bash
mw-collector collect --sources all
```

To collect from a specific source:

```bash
mw-collector collect --sources malwarebazaar
```

The short form of the option is also available:

```bash
mw-collector collect -s malwarebazaar
```

Multiple sources can be specified:

```bash
mw-collector collect -s malwarebazaar malshare
```

### Duplicate Samples

Samples are identified using their SHA-256 hashes.

Before retrieving a sample, the application checks whether its SHA-256 hash already exists in the local database. Previously collected samples are skipped. An option to download duplicates will be added in future versions.

## Storage

### Database

Metadata for collected samples is stored in a local SQLite database.

The following information is currently stored for each sample:

* SHA-256 hash
* File type
* Malware family, when available
* Source
* Collection timestamp in UTC

### Quarantine

Downloaded samples are stored in the configured quarantine directory.

Files are identified by their SHA-256 hashes. The exact format of downloaded content may depend on the source.

Files in the quarantine directory should always be treated as potentially malicious.

## Development

Clone the repository:

```bash
git clone https://github.com/silveera/malware-collector.git
cd malware-collector
```

Install the project and its dependencies using uv:

```bash
uv sync
```

Run the CLI from the development environment:

```bash
uv run mw-collector --help
```

## Disclaimer

This project is intended for legitimate cybersecurity research and testing.

The application retrieves malware from third-party services. Users are responsible for handling downloaded samples safely and for complying with applicable laws and the terms of the respective services.

## License

This project is licensed under the MIT License. See `LICENSE` for details.
