Metadata-Version: 2.4
Name: dll-downloader
Version: 1.1.0
Summary: A Python script to automatically search and download DLL files
Author-email: Marc Rivero Lopez <mriverolopez@gmail.com>
License-Expression: LicenseRef-MIT-Attribution
Project-URL: Homepage, https://github.com/seifreed/DLL-Downloader
Project-URL: Repository, https://github.com/seifreed/DLL-Downloader
Project-URL: Issues, https://github.com/seifreed/DLL-Downloader/issues
Keywords: dll,windows,download,security,virustotal
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Requires-Python: <3.15,>=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Provides-Extra: dev
Requires-Dist: black; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: types-requests; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Dynamic: license-file

<p align="center">
  <img src="https://img.shields.io/badge/DLL--Downloader-Windows%20DLLs-blue?style=for-the-badge" alt="DLL-Downloader">
</p>

<h1 align="center">DLL-Downloader</h1>

<p align="center">
  <strong>Search, download, and optionally scan DLL files with VirusTotal</strong>
</p>

<p align="center">
  <a href="https://pypi.org/project/dll-downloader/"><img src="https://img.shields.io/pypi/v/dll-downloader?style=flat-square&logo=pypi&logoColor=white" alt="PyPI Version"></a>
  <a href="https://pypi.org/project/dll-downloader/"><img src="https://img.shields.io/pypi/pyversions/dll-downloader?style=flat-square&logo=python&logoColor=white" alt="Python Versions"></a>
  <a href="https://github.com/seifreed/DLL-Downloader/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT%20%2B%20Attribution-green?style=flat-square" alt="License"></a>
  <a href="https://github.com/seifreed/DLL-Downloader/actions"><img src="https://img.shields.io/github/actions/workflow/status/seifreed/DLL-Downloader/ci.yml?style=flat-square&logo=github&label=CI" alt="CI Status"></a>
</p>

<p align="center">
  <a href="https://github.com/seifreed/DLL-Downloader/stargazers"><img src="https://img.shields.io/github/stars/seifreed/DLL-Downloader?style=flat-square" alt="GitHub Stars"></a>
  <a href="https://github.com/seifreed/DLL-Downloader/issues"><img src="https://img.shields.io/github/issues/seifreed/DLL-Downloader?style=flat-square" alt="GitHub Issues"></a>
  <a href="https://buymeacoffee.com/seifreed"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-support-yellow?style=flat-square&logo=buy-me-a-coffee&logoColor=white" alt="Buy Me a Coffee"></a>
</p>

---

## Overview

**DLL-Downloader** is a Python tool that searches and downloads DLL files from trusted sources and can optionally scan them using VirusTotal. It works as both a CLI tool and a Python library.

### Key Features

| Feature | Description |
|---------|-------------|
| **Search & Download** | Resolve DLL names and download the correct file |
| **ZIP Extraction** | Optionally extract the DLL when the source returns a ZIP |
| **Architecture Support** | x86 and x64 downloads with PE architecture validation |
| **VirusTotal Scan** | Optional security scan before saving |
| **Batch Mode** | Download many DLLs from a file |
| **Library Mode** | Use the downloader directly from Python |
| **Clean Architecture** | Domain/use-case/infrastructure separation |

---

## Installation

### From PyPI (Recommended)

```bash
pip install dll-downloader
```

### From Source

```bash
git clone https://github.com/seifreed/DLL-Downloader.git
cd DLL-Downloader
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -e .
```

---

## Configuration

You can configure settings using `.config.json`, environment variables, or `~/.vt.toml`.

### JSON config (`.config.json`)

```json
{
  "virustotal_api_key": "your_virustotal_api_key_here",
  "download_directory": "./downloads",
  "download_base_url": "https://es.dll-files.com",
  "http_timeout": 60,
  "virustotal_timeout": 60.0,
  "verify_ssl": true,
  "scan_before_save": true,
  "malicious_threshold": 5,
  "suspicious_threshold": 1,
  "log_level": "INFO",
  "user_agent": null
}
```

### VirusTotal key via `~/.vt.toml`

```toml
apikey="your_virustotal_api_key_here"
```

### Environment variables

```bash
export DLL_VIRUSTOTAL_API_KEY="your_virustotal_api_key_here"
export DLL_DOWNLOAD_DIRECTORY="./downloads"
export DLL_VIRUSTOTAL_TIMEOUT="60"
```

---

## Quick Start

```bash
# Download a single DLL
python3 dll-downloader.py msvcp140.dll

# Download x86 and fail if the source does not provide a matching PE DLL
python3 dll-downloader.py msvcp140.dll --arch x86

# Download and extract when the source returns a ZIP
python3 dll-downloader.py msvcp140.dll --extract

# Download from a list
python3 dll-downloader.py --file dll_list.txt

# Emit machine-readable JSON
python3 dll-downloader.py msvcp140.dll --json

# Emit SARIF for CI/security pipelines
python3 dll-downloader.py msvcp140.dll --sarif
```

---

## Usage

### Command Line Interface

```bash
python3 dll-downloader.py <dll_name> [options]
```

### Available Options

| Option | Description |
|--------|-------------|
| `--file` | File with one DLL name per line |
| `--arch` | Target architecture (`x86` or `x64`; default: `x64`) |
| `--debug` | Enable debug output |
| `--no-scan` | Skip VirusTotal scan |
| `--force` | Force download even if cached |
| `--output-dir` | Custom output directory |
| `--extract` | Extract the DLL when the download is a ZIP archive |
| `--json` | Emit machine-readable JSON output |
| `--sarif` | Emit SARIF v2.1.0 output |

Some providers return the DLL inside a ZIP archive. By default, `dll-downloader`
expects the payload to be a real ZIP and validates that it contains a valid PE
DLL. Without `--extract`, the validated ZIP is saved as-is. With `--extract`,
the tool saves the unpacked `.dll`, which is useful in CI/CD workflows. If the
payload is not a valid ZIP or the embedded DLL is not a valid PE file, the
download fails with an explicit error.

The selected architecture is also validated against the embedded PE header.
If `--arch x86` is requested and the source returns an x64 DLL, the download
fails instead of saving a mislabeled file.

The HTTP transport retries transient failures up to 5 times by default and
rotates across a pool of 5 legitimate `User-Agent` strings unless you provide
an explicit `user_agent` in configuration.

Retry policy settings:

- `http_max_retries`
- `http_retry_backoff_seconds`
- `http_retry_jitter_seconds`
- `user_agent`
- `user_agent_pool`

For pipeline integration, `--json` emits one structured JSON document and
`--sarif` emits one SARIF v2.1.0 log. Both formats also serialize boundary
errors such as invalid CLI input or unreadable DLL list files.

---

## Python Library

### Basic Usage

```python
from dll_downloader.api import (
    Architecture,
    DownloadDLLRequest,
)
from dll_downloader.runtime import (
    load_settings,
    create_dependencies,
)

settings = load_settings()
use_case, http_client, scanner = create_dependencies(settings)

try:
    response = use_case.execute(DownloadDLLRequest(
        dll_name="msvcp140.dll",
        architecture=Architecture.X64,
        scan_before_save=True,
        force_download=False,
        extract_archive=True,
    ))
    print(response)
finally:
    http_client.close()
    if scanner:
        scanner.close()
```

---

## Requirements

- Python 3.13 or 3.14
- See `pyproject.toml` for dependencies

---

## Contributing

Contributions are welcome. Please open a PR with clear changes and tests if needed.

---

## Support the Project

If you find DLL-Downloader useful, consider supporting its development:

<a href="https://buymeacoffee.com/seifreed" target="_blank">
  <img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" height="50">
</a>

---

## License

See the [LICENSE](LICENSE) file for details.

**Attribution Required:**
- Author: **Marc Rivero Lopez**
- Repository: [github.com/seifreed/DLL-Downloader](https://github.com/seifreed/DLL-Downloader)

---

<p align="center">
  <sub>Built for secure, reliable DLL acquisition</sub>
</p>
