MetaDefender TypeScript SDK

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

Versions

• API version: 4.0
• SDK version: 1.0.1

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
• Setup & Configuration
  • Supported Node.js 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 Node.js Versions

This SDK is compatible with the following versions:

• Node.js 16.x or higher
• npm or yarn package manager

Installation

Install the SDK using npm:

npm install @opswat/mcl-platform-sdk-javascript

Requirements: Node.js 16.x or higher

yarn add @opswat/mcl-platform-sdk-javascript

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:

import { Configuration } from "@opswat/mcl-platform-sdk-javascript";

const config = new Configuration({ apiKey: "YOUR_API_KEY" });

Basic Usage

import { Configuration, FileScanningApi } from "@opswat/mcl-platform-sdk-javascript";
import * as fs from "fs";

const config = new Configuration(); // Reads METADEFENDER_APIKEY
const fsApi = new FileScanningApi(config);

// Upload and scan file
const fileBuffer = fs.readFileSync("test.pdf");
const file = new File([fileBuffer], "test.pdf");
const upload = await fsApi.analyzeFile(file, {
  filename: "test.pdf",
  rule: "sanitize",
});

// Poll for results with timeout
const result = await fsApi.fileLookupWithPolling(upload.data.data_id, {
  timeout: 60,
  pollInterval: 2000,
});

console.log("Scan result:", result.data.scan_results?.scan_all_result_a);

API Services

File Scanning

import { FileScanningApi } from "@opswat/mcl-platform-sdk-javascript";

const fsApi = new FileScanningApi(config);

// Upload file
const upload = await fsApi.analyzeFile(file, {
  filename: "filename.pdf",
  rule: "sanitize", // multiscan, sanitize, cdr, unarchive, dlp
});

// Poll for scan completion (recommended)
const result = await fsApi.fileLookupWithPolling(dataId, {
  timeout: 60,
  pollInterval: 2000,
});

Data Sanitization (CDR)

import { DataSanitizationCDRApi } from "@opswat/mcl-platform-sdk-javascript";

const cdrApi = new DataSanitizationCDRApi(config);

// Get sanitized file URL
const sanitized = await cdrApi.downloadSanitizedFile(dataId);
console.log("Download URL:", sanitized.data.sanitizedFilePath);

// Cleanup
await cdrApi.deleteSanitizedFile(dataId);

Hash Lookups

import { HashLookupsApi } from "@opswat/mcl-platform-sdk-javascript";

const hashApi = new HashLookupsApi(config);
const result = await hashApi.lookupHash("640CCA22FBF439406BA200EEFB9C52BE87BC97D6");

Reputation Service

import { ReputationServiceApi } from "@opswat/mcl-platform-sdk-javascript";

const repApi = new ReputationServiceApi(config);

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

Dynamic Analysis (Sandbox)

import { DynamicAnalysisApi } from "@opswat/mcl-platform-sdk-javascript";

const sandboxApi = new DynamicAnalysisApi(config);
const sandboxRes = await sandboxApi.getSandbox(sandboxId);
console.log("Verdict:", sandboxRes.data.final_verdict);

API Key Management

import { ApikeyApi } from "@opswat/mcl-platform-sdk-javascript";

const apikeyApi = new ApikeyApi(config);

// Get API key info
const info = await apikeyApi.getAPIKey();
console.log("Nickname:", info.data.nickname);

// Check limits
const limits = await apikeyApi.getAPIKeyLimits();
const remaining = await apikeyApi.getAPIKeyRemainingLimits();
const history = await apikeyApi.listAPIKeyScanHistory();

Error Handling

import { AxiosError } from "axios";

try {
  const result = await fsApi.getFileAnalysis(dataId);
} catch (error) {
  if (error instanceof AxiosError) {
    console.error("Status:", error.response?.status);
    console.error("Details:", error.response?.data);
  } else {
    console.error("Error:", error);
  }
}

Example Workflow

See the complete example in tests/exemple_all_workflows.ts:

export METADEFENDER_APIKEY="YOUR_API_KEY"
# Use this only if you have a staging API key
export METADEFENDER_BASE_PATH="https://api-staging.metadefender.com/v4"
npm test

The example demonstrates:

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

License

MIT License - see LICENSE.md for details.