Metadata-Version: 2.4
Name: mcl_platform_sdk
Version: 1.0.0
Summary: OPSWAT MetaDefender Cloud Python SDK
Home-page: https://github.com/opswat/mcl-platform-sdk
Author: Florentina Gheorma
Author-email: Florentina Gheorma <gheorma.florentina@opswat.com>
License: MIT
Project-URL: Repository, https://github.com/opswat/mcl-platform-sdk
Project-URL: Homepage, https://www.opswat.com/
Project-URL: Documentation, https://docs.opswat.com/
Keywords: OPSWAT,MetaDefender,MetaDefender Cloud,Security,Malware Scanning
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: urllib3<3.0.0,>=2.1.0
Requires-Dist: python-dateutil>=2.8.2
Requires-Dist: pydantic>=2
Requires-Dist: typing-extensions>=4.7.1
Dynamic: author
Dynamic: home-page
Dynamic: license-file

# MetaDefender Python SDK

[![PyPI version](https://img.shields.io/pypi/v/mcl-platform-sdk.svg)](https://pypi.org/project/mcl-platform-sdk/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE.md)

Python SDK for MetaDefender Cloud - file scanning, threat detection, and CDR with 20+ anti-malware engines.

## Versions

- API version: `4.0`
- SDK version: `1.0.0`

## About the API

MetaDefender SDK provides an interface for interacting with MetaDefender Cloud and Core services. It enables file analysis with 20+ anti-malware engines, Deep Content Disarm and Reconstruction (CDR), sandbox analysis, and more.

### Key Features of MetaDefender Cloud

- **File Analysis** – Scan files using 20+ anti-malware engines
- **Deep CDR** – Supports sanitization of 100+ file types
- **Sandbox Analysis** – Detects unknown and targeted attacks through dynamic analysis

## Maintainer: publish to Test PyPI

Build and upload with a Test PyPI API token (non-interactive):

```bash
python -m pip install build twine && python -m build
export TWINE_USERNAME=__token__
export TWINE_PASSWORD=pypi-your-testpypi-token
twine upload --repository-url https://test.pypi.org/legacy/ dist/*
```

See **[docs/PUBLISHING.md](docs/PUBLISHING.md)** for details and production PyPI.

## Table of Contents

- [Versions](#versions)
- [About the API](#about-the-api)
- [Setup & Configuration](#setup--configuration)
  - [Supported Python Versions](#supported-python-versions)
- [Installation](#installation)
- [Authentication](#authentication)
  - [Basic Usage](#basic-usage)
- [API Services](#api-services)
  - [File Scanning](#file-scanning)
  - [Data Sanitization (CDR)](#data-sanitization-cdr)
  - [Hash Lookups](#hash-lookups)
  - [Reputation Service](#reputation-service)
  - [Dynamic Analysis (Sandbox)](#dynamic-analysis-sandbox)
  - [API Key Management](#api-key-management)
- [Error Handling](#error-handling)
- [Example Workflow](#example-workflow)
- [License](#license)

## Setup & Configuration

### Supported Python Versions

This SDK is compatible with the following versions:
- Python 3.9 or higher
- pip package manager

## Installation

Install the SDK using pip:

```bash
pip install mcl-platform-sdk
```

**Requirements:** Python 3.9 or higher

**Import name:** After install, import the SDK as **`mcl_platform_sdk`**:

```python
from mcl_platform_sdk import ApiClient
from mcl_platform_sdk.api.file_scanning_api import FileScanningApi
```

## Authentication

Set your API key as an environment variable:

```bash
export METADEFENDER_APIKEY="YOUR_API_KEY_HERE"
```

The SDK automatically reads from `METADEFENDER_APIKEY`. Alternatively, pass it directly:

```python
from mcl_platform_sdk import ApiClient

config = ApiClient(api_key="YOUR_API_KEY")
```

The ApiClient automatically reads the API key from the METADEFENDER_APIKEY environment variable.

### Optional parameters (`headers` options bag)

All SDK methods keep only **required** path/body parameters in the function signature.
All **optional request parameters** (both HTTP headers *and* query parameters) are passed via:

- `headers: Optional[Dict[str, Any]] = None`

Example:

```python
fs_api.analyze_file(file=data, headers={"filename": "test.pdf", "rule": "sanitize"})
```

### Basic Usage

```python
from mcl_platform_sdk import ApiClient
from mcl_platform_sdk.api.file_scanning_api import FileScanningApi

# Initialize client - reads METADEFENDER_APIKEY automatically
client = ApiClient()
fs_api = FileScanningApi(client)

# Upload and scan file
with open('test.pdf', 'rb') as f:
    upload = fs_api.analyze_file(
        file=f.read(),
        headers={
            "filename": "test.pdf",
            "rule": "sanitize",
        }
    )

# Poll for results with automatic timeout (configured via headers)
try:
    result = fs_api.get_file_analysis(
        upload.data_id,
        headers={
            "timeout": 60,
            "poll_interval": 2,  # seconds (optional)
        },
    )
    print('Scan result:', result.scan_results.scan_all_result_a)
except TimeoutError:
    print('Scan failed to complete in 60 seconds')
```

## API Services

### File Scanning

```python
from mcl_platform_sdk.api.file_scanning_api import FileScanningApi

fs_api = FileScanningApi(client)

# Upload file
with open('file.pdf', 'rb') as f:
    upload = fs_api.analyze_file(
        file=f.read(),
        headers={
            "filename": "file.pdf",
            "rule": "sanitize",  # Options: multiscan, sanitize, cdr, unarchive, dlp
        }
    )

# Poll for scan completion (recommended)
try:
    result = fs_api.get_file_analysis(upload.data_id, headers={"timeout": 60})
    print('Scan completed:', result.scan_results.scan_all_result_a)
except TimeoutError:
    print('Scan failed to complete in 60 seconds')
```

### Data Sanitization (CDR)

```python
from mcl_platform_sdk.api.data_sanitization_cdr_api import DataSanitizationCDRApi

cdr_api = DataSanitizationCDRApi(client)

# Get sanitized file URL
sanitized = cdr_api.file_sanitized(data_id)
print('Download URL:', sanitized.sanitized_file_path)

# Cleanup
cdr_api.file_converted_data_id_delete(data_id)
```

### Hash Lookups

```python
from mcl_platform_sdk.api.hash_lookups_api import HashLookupsApi

hash_api = HashLookupsApi(client)
result = hash_api.hash_lookup('640CCA22FBF439406BA200EEFB9C52BE87BC97D6')
print('Hash lookup result:', result)
```

### Reputation Service

```python
from mcl_platform_sdk.api.reputation_service_api import ReputationServiceApi

rep_api = ReputationServiceApi(client)

# Check IP, domain, or URL reputation
ip_rep = rep_api.i_p_lookup(observable_ip='198.15.127.171')
domain_rep = rep_api.domain_lookup(observable_domain='example.com')
url_rep = rep_api.url_lookup(observable_url='http://suspicious-url.com')
```

### Dynamic Analysis (Sandbox)

```python
from mcl_platform_sdk.api.dynamic_analysis_api import DynamicAnalysisApi

sandbox_api = DynamicAnalysisApi(client)
sandbox_res = sandbox_api.sandbox_lookup(sandbox_id)
print('Verdict:', sandbox_res.final_verdict)
```

### API Key Management

```python
from mcl_platform_sdk.api.apikey_api import ApikeyApi

apikey_api = ApikeyApi(client)

# Get API key info
info = apikey_api.get_api_key()
print('Nickname:', info.nickname)

# Check limits
limits = apikey_api.apikey_limits()
remaining = apikey_api.apikey_limits_status_get()
history = apikey_api.apikey_scan_history_get()
```

## Error Handling

```python
from mcl_platform_sdk.rest import ApiException

try:
    result = fs_api.get_file_analysis(data_id)
except ApiException as e:
    print('Status:', e.status)
    print('Details:', e.body)
except TimeoutError as e:
    print('Timeout:', e)
except Exception as e:
    print('Error:', e)
```

## Example Workflow

The SDK includes a comprehensive example script. After installation:

```bash
# Set your API key
export METADEFENDER_APIKEY="YOUR_API_KEY"

# Run the example workflow
python -m exemples.exemple_all_workflows
```

The example demonstrates:
- API key validation
- File upload and scanning
- Polling for results
- Sanitized file retrieval
- Hash lookups
- IP/Domain/URL reputation checks

## For maintainers: build and publish

To build the package and publish to PyPI, see **[docs/PUBLISHING.md](docs/PUBLISHING.md)** for the full build and deploy process.

To regenerate the client from OpenAPI Generator, use **`packageName=mcl_platform_sdk`** . See **[docs/REGENERATING_CLIENT.md](docs/REGENERATING_CLIENT.md)**.

## License

MIT License - see [LICENSE.md](LICENSE.md) for details.
