malshare-sdk 1.0.0

package/src/index.js

@@ -0,0 +1,404 @@
+/**
+ * MalShare SDK — JavaScript client for the MalShare API.
+ *
+ * MalShare is a free malware sample repository with 1M+ samples.
+ * API: https://malshare.com/doc.php
+ * Registration: https://malshare.com/register.php
+ *
+ * Works on: Bun, Node.js, Deno, Cloudflare Workers.
+ * Zero dependencies. Uses native fetch() or Bun/node:http.
+ *
+ * @module malshare-sdk
+ * @license MIT
+ *
+ * @example
+ *   import { MalShare } from 'malshare-sdk';
+ *   const ms = new MalShare('your-api-key');
+ *   const hashes = await ms.listSamples();
+ *   const sample = await ms.download('abc123...');
+ */
+
+// ══════════════════════════════════════════════════════════════════
+// TYPES
+// ══════════════════════════════════════════════════════════════════
+
+/**
+ * @typedef {Object} MalShareConfig
+ * @property {string} apiKey — MalShare API key
+ * @property {string} [baseUrl='https://malshare.com/api.php'] — API base URL
+ * @property {number} [timeoutMs=60000] — request timeout in ms
+ * @property {Function} [fetch] — custom fetch implementation (for CF Workers etc.)
+ */
+
+/**
+ * @typedef {Object} FileDetails
+ * @property {string} MD5 — MD5 hash
+ * @property {string} SHA1 — SHA1 hash
+ * @property {string} SHA256 — SHA256 hash
+ * @property {string} F_TYPE — file type (e.g. 'PE32 executable')
+ * @property {number} F_SIZE — file size in bytes
+ * @property {string} [F_NAME] — original file name
+ * @property {string[]} [SOURCES] — sample sources
+ * @property {string} [FIRST_SEEN] — first seen timestamp
+ * @property {string} [LAST_SEEN] — last seen timestamp
+ */
+
+/**
+ * @typedef {Object} UploadResult
+ * @property {string} status — 'OK' or 'ERROR'
+ * @property {string} [guid] — upload GUID for status tracking
+ * @property {string} [error] — error message if status is ERROR
+ */
+
+/**
+ * @typedef {Object} DownloadUrlResult
+ * @property {string} status — 'OK' or 'ERROR'
+ * @property {string} [guid] — task GUID for checking status
+ * @property {string} [error] — error message
+ */
+
+/**
+ * @typedef {Object} DownloadUrlStatus
+ * @property {string} status — 'missing' | 'pending' | 'processing' | 'finished'
+ * @property {string} [guid] — task GUID
+ */
+
+/**
+ * @typedef {Object} QuotaInfo
+ * @property {number} limit — allocated API calls per day
+ * @property {number} remaining — remaining API calls
+ */
+
+// ══════════════════════════════════════════════════════════════════
+// MAIN CLASS
+// ══════════════════════════════════════════════════════════════════
+
+export class MalShare {
+  /**
+   * @param {string} apiKey — MalShare API key (free at https://malshare.com/register.php)
+   * @param {Partial<MalShareConfig>} [config]
+   */
+  constructor(apiKey, config = {}) {
+    if (!apiKey) throw new Error('MalShare requires an API key. Register at https://malshare.com/register.php');
+
+    /** @type {MalShareConfig} */
+    this.config = {
+      apiKey,
+      baseUrl: config.baseUrl || 'https://malshare.com/api.php',
+      timeoutMs: config.timeoutMs || 60000,
+      fetch: config.fetch || globalThis.fetch,
+    };
+  }
+
+  // ═══════════════ INTERNAL ═══════════════
+
+  /**
+   * Make an API request.
+   * @param {string} action — API action
+   * @param {Object} [params={}] — query parameters
+   * @param {Object} [opts={}] — request options
+   * @returns {Promise<any>}
+   */
+  async _request(action, params = {}, opts = {}) {
+    const { raw = false, method = 'GET' } = opts;
+    const qs = new URLSearchParams({ api_key: this.config.apiKey, action, ...params });
+    const url = `${this.config.baseUrl}?${qs}`;
+
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.config.timeoutMs);
+
+    try {
+      const res = await this.config.fetch(url, {
+        method,
+        signal: controller.signal,
+        headers: { 'Accept': 'application/json, text/plain, */*' },
+      });
+
+      if (!res.ok) {
+        throw new Error(`MalShare API error: ${res.status} ${res.statusText}`);
+      }
+
+      if (raw) {
+        const buf = await res.arrayBuffer();
+        return new Uint8Array(buf);
+      }
+
+      const text = await res.text();
+      try {
+        return JSON.parse(text);
+      } catch {
+        // Some endpoints return raw text (e.g. search)
+        return text;
+      }
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  // ═══════════════ SAMPLE LISTING ═══════════════
+
+  /**
+   * List SHA256 hashes from the past 24 hours.
+   * @returns {Promise<string[]>}
+   */
+  async listSamples() {
+    const data = await this._request('getlist');
+    return Array.isArray(data) ? data : [];
+  }
+
+  /**
+   * List SHA256 hashes from the past 24 hours (raw text, one per line).
+   * @returns {Promise<string>}
+   */
+  async listSamplesRaw() {
+    return this._request('getlistraw');
+  }
+
+  /**
+   * List sample sources from the past 24 hours.
+   * @returns {Promise<{source: string, count: number}[]>}
+   */
+  async listSources() {
+    return this._request('getsources');
+  }
+
+  /**
+   * List sample sources from the past 24 hours (raw text).
+   * @returns {Promise<string>}
+   */
+  async listSourcesRaw() {
+    return this._request('getsourcesraw');
+  }
+
+  /**
+   * List file names from uploads in the past 24 hours.
+   * @returns {Promise<string[]>}
+   */
+  async listFileNames() {
+    return this._request('getfilenames');
+  }
+
+  /**
+   * Get file types and counts from the past 24 hours.
+   * @returns {Promise<{type: string, count: number}[]>}
+   */
+  async listTypes() {
+    return this._request('gettypes');
+  }
+
+  // ═══════════════ SAMPLE INFO ═══════════════
+
+  /**
+   * Get detailed information about a sample.
+   *
+   * @param {string} hash — MD5, SHA1, or SHA256 hash
+   * @returns {Promise<FileDetails|null>}
+   *
+   * @example
+   *   const details = await ms.details('46faab8ab153fae...');
+   *   console.log(details.F_TYPE, details.MD5);
+   */
+  async details(hash) {
+    const data = await this._request('details', { hash });
+    if (!data || data.status === 'ERROR' || !data.SHA256) return null;
+
+    return {
+      MD5: data.MD5 || '',
+      SHA1: data.SHA1 || '',
+      SHA256: data.SHA256 || '',
+      F_TYPE: data.F_TYPE || '',
+      F_SIZE: data.F_SIZE || 0,
+      F_NAME: data.F_NAME || '',
+      SOURCES: data.SOURCES || [],
+      FIRST_SEEN: data.FIRST_SEEN || '',
+      LAST_SEEN: data.LAST_SEEN || '',
+      ...data,
+    };
+  }
+
+  /**
+   * Bulk hash lookup — supply an array of hashes.
+   *
+   * @param {string[]} hashes — array of hex-encoded hashes
+   * @returns {Promise<FileDetails[]>}
+   *
+   * @example
+   *   const results = await ms.hashLookup(['abc123...', 'def456...']);
+   */
+  async hashLookup(hashes) {
+    if (!Array.isArray(hashes) || hashes.length === 0) return [];
+
+    const formData = new URLSearchParams();
+    formData.append('hashes', JSON.stringify(hashes));
+
+    const qs = new URLSearchParams({ api_key: this.config.apiKey, action: 'hashlookup' });
+    const url = `${this.config.baseUrl}?${qs}`;
+
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.config.timeoutMs);
+
+    try {
+      const res = await this.config.fetch(url, {
+        method: 'POST',
+        body: formData,
+        signal: controller.signal,
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      });
+      if (!res.ok) throw new Error(`MalShare API error: ${res.status}`);
+      return res.json();
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  /**
+   * Search by file type (samples from past 24h).
+   *
+   * @param {string} fileType — e.g. 'PE32', 'ELF', 'PDF', 'Zip', 'JavaScript'
+   * @returns {Promise<string[]>} — array of MD5/SHA1/SHA256 hashes
+   *
+   * @example
+   *   const hashes = await ms.searchByType('PE32 executable');
+   */
+  async searchByType(fileType) {
+    const data = await this._request('type', { type: fileType });
+    return Array.isArray(data) ? data : [];
+  }
+
+  /**
+   * Search samples by query (hash, source, or file name).
+   * Returns raw text results.
+   *
+   * @param {string} query — search term
+   * @returns {Promise<string>} — raw search results
+   */
+  async search(query) {
+    return this._request('search', { query });
+  }
+
+  // ═══════════════ SAMPLE DOWNLOAD ═══════════════
+
+  /**
+   * Download a malware sample by hash.
+   * Returns raw bytes. **Handle with care — this is live malware.**
+   *
+   * @param {string} hash — MD5, SHA1, or SHA256 hash
+   * @returns {Promise<Uint8Array>} — raw file bytes
+   *
+   * @example
+   *   const bytes = await ms.download('46faab8ab153fae...');
+   *   await Bun.write('/tmp/malware.bin', bytes);
+   */
+  async download(hash) {
+    return this._request('getfile', { hash }, { raw: true });
+  }
+
+  /**
+   * Download a sample and save to disk (Bun/Node only).
+   *
+   * @param {string} hash — file hash
+   * @param {string} filePath — where to save
+   * @returns {Promise<{path: string, size: number}>}
+   */
+  async downloadTo(hash, filePath) {
+    const bytes = await this.download(hash);
+    if (typeof Bun !== 'undefined') {
+      await Bun.write(filePath, bytes);
+    } else {
+      const { writeFileSync } = await import('node:fs');
+      writeFileSync(filePath, bytes);
+    }
+    return { path: filePath, size: bytes.length };
+  }
+
+  // ═══════════════ UPLOAD ═══════════════
+
+  /**
+   * Upload a malware sample.
+   * Uploading files temporarily increases your API quota.
+   *
+   * @param {Uint8Array|Buffer|Blob} file — the sample to upload
+   * @param {string} [fileName='sample.bin'] — file name
+   * @returns {Promise<UploadResult>}
+   */
+  async upload(file, fileName = 'sample.bin') {
+    const formData = new FormData();
+    formData.append('upload', new Blob([file]), fileName);
+
+    const qs = new URLSearchParams({ api_key: this.config.apiKey, action: 'upload' });
+    const url = `${this.config.baseUrl}?${qs}`;
+
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.config.timeoutMs * 2); // uploads can be slow
+
+    try {
+      const res = await this.config.fetch(url, {
+        method: 'POST',
+        body: formData,
+        signal: controller.signal,
+      });
+      return res.json();
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  // ═══════════════ URL DOWNLOAD ═══════════════
+
+  /**
+   * Submit a URL for MalShare to download and add to its collection.
+   *
+   * @param {string} url — URL to download
+   * @param {boolean} [recursive=false] — enable crawling
+   * @returns {Promise<DownloadUrlResult>}
+   */
+  async downloadUrl(url, recursive = false) {
+    const formData = new URLSearchParams();
+    formData.append('url', url);
+    if (recursive) formData.append('recursive', '1');
+
+    const qs = new URLSearchParams({ api_key: this.config.apiKey, action: 'download_url' });
+    const reqUrl = `${this.config.baseUrl}?${qs}`;
+
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.config.timeoutMs);
+
+    try {
+      const res = await this.config.fetch(reqUrl, {
+        method: 'POST',
+        body: formData,
+        signal: controller.signal,
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      });
+      return res.json();
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  /**
+   * Check the status of a URL download task.
+   *
+   * @param {string} guid — task GUID from downloadUrl()
+   * @returns {Promise<DownloadUrlStatus>}
+   */
+  async downloadUrlStatus(guid) {
+    return this._request('download_url_check', { guid });
+  }
+
+  // ═══════════════ QUOTA ═══════════════
+
+  /**
+   * Get API quota information.
+   * @returns {Promise<QuotaInfo>}
+   */
+  async getQuota() {
+    const text = await this._request('getlimit');
+    // Response format: "LIMIT: 2000\nREMAINING: 1523"
+    const limit = parseInt(text.match(/LIMIT:\s*(\d+)/i)?.[1] || '0');
+    const remaining = parseInt(text.match(/REMAINING:\s*(\d+)/i)?.[1] || '0');
+    return { limit, remaining };
+  }
+}
+
+export default MalShare;