mcl-platform-sdk 1.0.0

OPSWAT MetaDefender Cloud Python SDK

MetaDefender Python SDK

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):

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 for details and production PyPI.

Table of Contents

• Versions
• About the API
• Setup & Configuration
  • Supported Python Versions
• Installation
• Authentication
  • Basic Usage
• API Services
  • File Scanning
  • Data Sanitization (CDR)
  • Hash Lookups
  • Reputation Service
  • Dynamic Analysis (Sandbox)
  • API Key Management
• Error Handling
• Example Workflow
• 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:

pip install mcl-platform-sdk

Requirements: Python 3.9 or higher

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

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:

export METADEFENDER_APIKEY="YOUR_API_KEY_HERE"

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

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:

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

Basic Usage

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

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)

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

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

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)

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

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

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:

# 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 for the full build and deploy process.

To regenerate the client from OpenAPI Generator, use packageName=mcl_platform_sdk . See docs/REGENERATING_CLIENT.md.

License

MIT License - see LICENSE.md for details.