mcl-platform-sdk 1.0.0__tar.gz

mcl_platform_sdk-1.0.0/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OPSWAT
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcl_platform_sdk-1.0.0/MANIFEST.in

@@ -0,0 +1,21 @@
+# Include important files
+include README.md
+include LICENSE.md
+include requirements.txt
+include setup.py
+include pyproject.toml
+
+# Include the package
+recursive-include mcl_platform_sdk *.py
+
+# Include exemples folder
+recursive-include exemples *.py
+include exemples/*.pdf
+
+# Exclude unnecessary files
+exclude .gitignore
+exclude git_push.sh
+recursive-exclude venv *
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]
+recursive-exclude * .DS_Store

mcl_platform_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,305 @@
+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.

mcl_platform_sdk-1.0.0/README.md

@@ -0,0 +1,282 @@
+# 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.