MetaDefender Java SDK

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

Versions

• API version: 4.0
• SDK version: 4.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

Table of Contents

• Versions
• About the API
• Documentation (API reference)
• Setup & Configuration
  • Requirements
• 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

Documentation (API reference)

• docs/README.md — service API markdown pages under docs/ (same names as in docs_JavaScript, without the Api file suffix), grouped by MetaDefender Cloud (mdcloud) vs Core (mdcore).
• docs/Overview.md — availability tags and product context.

Setup & Configuration

Requirements

• Java 8 or higher
• Maven 3.x

Installation

Add the dependency to your pom.xml:

<dependency>
    <groupId>io.github.opswat</groupId>
    <artifactId>mcl-platform-sdk-java</artifactId>
  <version>4.0</version>
</dependency>

Or with Gradle:

implementation 'io.github.opswat:mcl-platform-sdk-java:4.0'

Authentication

Set your API key as an environment variable:

export METADEFENDER_APIKEY="YOUR_API_KEY_HERE"

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

import core.ApiClient;
import core.Configuration;

ApiClient apiClient = Configuration.getDefaultApiClient();
apiClient.setApiKey("YOUR_API_KEY");

Basic Usage

import core.ApiClient;
import core.Configuration;
import core.ApiException;
import api.FileScanningApi;
import model.FileUploadResults;
import model.FileScanResults;
import headers.FileUploadHeaders;
import headers.FileLookupHeaders;
import java.io.File;

ApiClient apiClient = Configuration.getDefaultApiClient(); // Reads METADEFENDER_APIKEY
FileScanningApi fsApi = new FileScanningApi(apiClient);

// Upload and scan file
FileUploadResults upload = fsApi.analyzeFile(new File("test.pdf"),
    new FileUploadHeaders()
        .filename("test.pdf")
        .rule("sanitize")
);

// Poll for results (blocks until complete or timeout)
try {
    FileScanResults result = fsApi.fileLookupWithPolling(upload.getDataId(),
        new FileLookupHeaders().timeout(60));
    System.out.println("Scan result: " + result.getScanResults().getScanAllResultA());
} catch (ApiException e) {
    System.out.println("Scan failed to complete in 60 seconds");
}

API Services

File Scanning

import api.FileScanningApi;
import headers.FileUploadHeaders;
import headers.FileLookupHeaders;

FileScanningApi fsApi = new FileScanningApi(apiClient);

// Upload file with options
FileUploadResults upload = fsApi.analyzeFile(new File("document.pdf"),
    new FileUploadHeaders()
        .filename("document.pdf")
        .rule("sanitize")       // multiscan, sanitize, cdr, unarchive, dlp
        .sandbox("windows10")   // windows7, windows10
);

// Poll for scan completion (blocks until done or timeout)
FileScanResults result = fsApi.fileLookupWithPolling(dataId,
    new FileLookupHeaders().timeout(60));

// With custom poll interval (5 seconds instead of default 2)
FileScanResults result = fsApi.fileLookupWithPolling(dataId,
    new FileLookupHeaders().timeout(60).pollInterval(5));

// Single lookup without polling
FileScanResults result = fsApi.getFileAnalysis(dataId);

Data Sanitization (CDR)

import api.DataSanitizationCDRApi;

DataSanitizationCDRApi cdrApi = new DataSanitizationCDRApi(apiClient);

// Get sanitized file download link
SanitizedFileDownloadLink sanitized = cdrApi.downloadSanitizedFile(dataId);
System.out.println("Download URL: " + sanitized);

// Cleanup
cdrApi.deleteSanitizedFile(dataId);

Hash Lookups

import api.HashLookupsApi;

HashLookupsApi hashApi = new HashLookupsApi(apiClient);
HashLookupResults result = hashApi.lookupHash("640CCA22FBF439406BA200EEFB9C52BE87BC97D6");

Reputation Service

import api.ReputationServiceApi;

ReputationServiceApi repApi = new ReputationServiceApi(apiClient);

// Check IP, domain, or URL reputation
IPReputation ipRep = repApi.lookupIP("198.15.127.171");
DomainReputation domainRep = repApi.lookupDomain("example.com");
URLReputation urlRep = repApi.lookupURL("http://suspicious-url.com");

Dynamic Analysis (Sandbox)

import api.DynamicAnalysisApi;

DynamicAnalysisApi sandboxApi = new DynamicAnalysisApi(apiClient);
SandboxResponseForAFile1 sandboxRes = sandboxApi.getSandboxByHash(sha256Hash);
System.out.println("Verdict: " + sandboxRes.getFinalVerdict());

API Key Management

import api.ApikeyApi;

ApikeyApi apikeyApi = new ApikeyApi(apiClient);

// Get API key info
AccountInformation info = apikeyApi.getAPIKey();

// Check limits
ApikeyUsage limits = apikeyApi.getAPIKeyLimits();
ApikeyUsage1 remaining = apikeyApi.getAPIKeyRemainingLimits();

// Scan history (optional pagination via headers.ScanHistoryHeaders)
ScanHistory history = apikeyApi.listAPIKeyScanHistory();

Error Handling

import core.ApiException;

try {
    FileScanResults result = fsApi.getFileAnalysis(dataId);
    } catch (ApiException e) {
    System.err.println("Status: " + e.getCode());
    System.err.println("Details: " + e.getResponseBody());
    System.err.println("Headers: " + e.getResponseHeaders());
}

Example Workflow

See the complete example in tests/ExempleAllWorkflows.java:

export METADEFENDER_APIKEY="YOUR_API_KEY"
# Optional: staging or custom host — set on the client (not via env):
#   Configuration.getDefaultApiClient().setBasePath("https://api-staging.metadefender.com/v4");
# Optional: test file (defaults to tests/Test.pdf under the project root)
# export METADEFENDER_TEST_FILE_PATH="/path/to/sample.pdf"
# Build once so target/lib contains dependencies (or: mvn -q compile dependency:copy-dependencies)
mvn -q package -DskipTests
java -cp "target/classes:target/lib/*" tests.ExempleAllWorkflows

The example demonstrates:

• API key validation
• File upload and scanning
• Polling for results
• Sanitized file retrieval
• Sandbox analysis
• Hash lookups
• IP/Domain/URL reputation checks

License

MIT License - see LICENSE.md for details.