malshare-sdk 1.0.0

package/src/cli.js

@@ -0,0 +1,210 @@
+#!/usr/bin/env bun
+/**
+ * MalShare CLI — command-line interface for the MalShare API.
+ *
+ * Install:  npm install -g malshare-sdk  (or bun install -g)
+ * Usage:    malshare <command> [options]
+ *
+ * Auth:     MALSHARE_KEY env var, or --key flag
+ *
+ * @module malshare-sdk/cli
+ */
+
+import { MalShare } from './index.js';
+import { parseArgs } from 'node:util';
+
+const KEY = process.env.MALSHARE_KEY || '';
+
+/**
+ * Get configured MalShare client.
+ */
+function getClient(key) {
+  if (!key) {
+    console.error('⚠️  MALSHARE_KEY env var is not set.');
+    console.error('    Register at https://malshare.com/register.php');
+    console.error('    Then: export MALSHARE_KEY=your-key-here');
+    process.exit(1);
+  }
+  return new MalShare(key);
+}
+
+/**
+ * Format bytes to human-readable.
+ */
+function formatBytes(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1_048_576) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / 1_048_576).toFixed(1)} MB`;
+}
+
+// ══════════════════════════════════════════════════════════════════
+// MAIN
+// ══════════════════════════════════════════════════════════════════
+
+async function main() {
+  const args = process.argv.slice(2);
+  const cmd = args[0];
+
+  // Parse --key flag
+  let key = KEY;
+  const keyIdx = args.indexOf('--key');
+  if (keyIdx > -1 && args[keyIdx + 1]) {
+    key = args[keyIdx + 1];
+    args.splice(keyIdx, 2);
+  }
+
+  if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
+    console.log(`
+MalShare CLI — https://malshare.com
+
+  Usage: malshare <command> [options]
+
+  Commands:
+    list          List SHA256 hashes from the past 24 hours
+    raw           List SHA256 hashes (raw text, one per line)
+    sources       List sample sources from the past 24 hours
+    filenames     List file names from the past 24 hours
+    types         List file types and counts
+    info <hash>   Get sample details by hash
+    search <q>    Search by hash, source, or file name
+    type <type>   List hashes by file type (PE32, ELF, PDF...)
+    download <h>  Download a sample (raw bytes to stdout)
+    save <h> <f>  Download a sample and save to file
+    quota         Check API quota
+    url <url>     Submit URL for MalShare to download
+
+  Auth:
+    export MALSHARE_KEY=your-key-here
+    Or use --key flag: malshare list --key your-key
+
+  Examples:
+    malshare list                    # latest samples
+    malshare info 46faab8ab153...    # sample details
+    malshare save 46faab8ab153... ./malware.bin
+    malshare types                   # file type distribution
+    malshare quota                   # API calls remaining
+`);
+    process.exit(0);
+  }
+
+  const ms = getClient(key);
+
+  try {
+    switch (cmd) {
+      case 'list': {
+        const hashes = await ms.listSamples();
+        console.log(`${hashes.length} samples in the last 24 hours`);
+        hashes.slice(0, 20).forEach((h) => console.log(`  ${h}`));
+        break;
+      }
+
+      case 'raw': {
+        const text = await ms.listSamplesRaw();
+        process.stdout.write(text);
+        break;
+      }
+
+      case 'sources': {
+        const sources = await ms.listSources();
+        console.log(`${sources.length} sources`);
+        for (const s of (Array.isArray(sources) ? sources : [])) {
+          console.log(`  ${s.source || s.name || JSON.stringify(s)}`);
+        }
+        break;
+      }
+
+      case 'filenames': {
+        const names = await ms.listFileNames();
+        console.log(`${names.length} file names`);
+        for (const n of names.slice(0, 20)) console.log(`  ${n}`);
+        break;
+      }
+
+      case 'types': {
+        const types = await ms.listTypes();
+        console.log(`${types.length} file types`);
+        for (const t of (Array.isArray(types) ? types : [])) {
+          console.log(`  ${t.type || t.name || JSON.stringify(t)}`);
+        }
+        break;
+      }
+
+      case 'info': {
+        const hash = args[1];
+        if (!hash) { console.error('Usage: malshare info <hash>'); process.exit(1); }
+        const details = await ms.details(hash);
+        if (!details) { console.log('Sample not found'); process.exit(1); }
+        console.log('SHA256:  ', details.SHA256);
+        console.log('SHA1:    ', details.SHA1);
+        console.log('MD5:     ', details.MD5);
+        console.log('Type:    ', details.F_TYPE);
+        console.log('Size:    ', formatBytes(details.F_SIZE));
+        console.log('Name:    ', details.F_NAME || 'N/A');
+        console.log('Sources: ', (details.SOURCES || []).join(', '));
+        break;
+      }
+
+      case 'search': {
+        const query = args.slice(1).join(' ');
+        if (!query) { console.error('Usage: malshare search <query>'); process.exit(1); }
+        const results = await ms.search(query);
+        console.log(results);
+        break;
+      }
+
+      case 'type': {
+        const fileType = args.slice(1).join(' ');
+        if (!fileType) { console.error('Usage: malshare type <filetype>'); process.exit(1); }
+        const hashes = await ms.searchByType(fileType);
+        console.log(`${hashes.length} ${fileType} samples (24h)`);
+        hashes.slice(0, 20).forEach((h) => console.log(`  ${h}`));
+        break;
+      }
+
+      case 'download': {
+        const hash = args[1];
+        if (!hash) { console.error('Usage: malshare download <hash>'); process.exit(1); }
+        const bytes = await ms.download(hash);
+        process.stdout.write(bytes);
+        break;
+      }
+
+      case 'save': {
+        const hash = args[1];
+        const filePath = args[2];
+        if (!hash || !filePath) { console.error('Usage: malshare save <hash> <filepath>'); process.exit(1); }
+        const result = await ms.downloadTo(hash, filePath);
+        console.log(`✅ Saved ${formatBytes(result.size)} → ${result.path}`);
+        break;
+      }
+
+      case 'quota': {
+        const quota = await ms.getQuota();
+        console.log(`Daily limit:   ${quota.limit}`);
+        console.log(`Remaining:     ${quota.remaining}`);
+        console.log(`Used:          ${(quota.limit - quota.remaining)}`);
+        console.log(`Usage:         ${((1 - quota.remaining / quota.limit) * 100).toFixed(1)}%`);
+        break;
+      }
+
+      case 'url': {
+        const url = args[1];
+        if (!url) { console.error('Usage: malshare url <url> [--recursive]'); process.exit(1); }
+        const recursive = args.includes('--recursive');
+        const result = await ms.downloadUrl(url, recursive);
+        console.log(JSON.stringify(result, null, 2));
+        break;
+      }
+
+      default:
+        console.error(`Unknown command: ${cmd}`);
+        console.error('Run: malshare help');
+        process.exit(1);
+    }
+  } catch (err) {
+    console.error(`❌ Error: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+main();

package/src/index.d.ts

@@ -0,0 +1,309 @@
+/**
+ * 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...');
+ */
+/**
+ * @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
+ */
+export class MalShare {
+    /**
+     * @param {string} apiKey — MalShare API key (free at https://malshare.com/register.php)
+     * @param {Partial<MalShareConfig>} [config]
+     */
+    constructor(apiKey: string, config?: Partial<MalShareConfig>);
+    /** @type {MalShareConfig} */
+    config: MalShareConfig;
+    /**
+     * Make an API request.
+     * @param {string} action — API action
+     * @param {Object} [params={}] — query parameters
+     * @param {Object} [opts={}] — request options
+     * @returns {Promise<any>}
+     */
+    _request(action: string, params?: Object, opts?: Object): Promise<any>;
+    /**
+     * List SHA256 hashes from the past 24 hours.
+     * @returns {Promise<string[]>}
+     */
+    listSamples(): Promise<string[]>;
+    /**
+     * List SHA256 hashes from the past 24 hours (raw text, one per line).
+     * @returns {Promise<string>}
+     */
+    listSamplesRaw(): Promise<string>;
+    /**
+     * List sample sources from the past 24 hours.
+     * @returns {Promise<{source: string, count: number}[]>}
+     */
+    listSources(): Promise<{
+        source: string;
+        count: number;
+    }[]>;
+    /**
+     * List sample sources from the past 24 hours (raw text).
+     * @returns {Promise<string>}
+     */
+    listSourcesRaw(): Promise<string>;
+    /**
+     * List file names from uploads in the past 24 hours.
+     * @returns {Promise<string[]>}
+     */
+    listFileNames(): Promise<string[]>;
+    /**
+     * Get file types and counts from the past 24 hours.
+     * @returns {Promise<{type: string, count: number}[]>}
+     */
+    listTypes(): Promise<{
+        type: string;
+        count: number;
+    }[]>;
+    /**
+     * 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);
+     */
+    details(hash: string): Promise<FileDetails | null>;
+    /**
+     * 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...']);
+     */
+    hashLookup(hashes: string[]): Promise<FileDetails[]>;
+    /**
+     * 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');
+     */
+    searchByType(fileType: string): Promise<string[]>;
+    /**
+     * Search samples by query (hash, source, or file name).
+     * Returns raw text results.
+     *
+     * @param {string} query — search term
+     * @returns {Promise<string>} — raw search results
+     */
+    search(query: string): Promise<string>;
+    /**
+     * 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);
+     */
+    download(hash: string): Promise<Uint8Array>;
+    /**
+     * 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}>}
+     */
+    downloadTo(hash: string, filePath: string): Promise<{
+        path: string;
+        size: number;
+    }>;
+    /**
+     * 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>}
+     */
+    upload(file: Uint8Array | Buffer | Blob, fileName?: string): Promise<UploadResult>;
+    /**
+     * 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>}
+     */
+    downloadUrl(url: string, recursive?: boolean): Promise<DownloadUrlResult>;
+    /**
+     * Check the status of a URL download task.
+     *
+     * @param {string} guid — task GUID from downloadUrl()
+     * @returns {Promise<DownloadUrlStatus>}
+     */
+    downloadUrlStatus(guid: string): Promise<DownloadUrlStatus>;
+    /**
+     * Get API quota information.
+     * @returns {Promise<QuotaInfo>}
+     */
+    getQuota(): Promise<QuotaInfo>;
+}
+export default MalShare;
+export type MalShareConfig = {
+    /**
+     * — MalShare API key
+     */
+    apiKey: string;
+    /**
+     * — API base URL
+     */
+    baseUrl?: string | undefined;
+    /**
+     * — request timeout in ms
+     */
+    timeoutMs?: number | undefined;
+    /**
+     * — custom fetch implementation (for CF Workers etc.)
+     */
+    fetch?: Function | undefined;
+};
+export type FileDetails = {
+    /**
+     * — MD5 hash
+     */
+    MD5: string;
+    /**
+     * — SHA1 hash
+     */
+    SHA1: string;
+    /**
+     * — SHA256 hash
+     */
+    SHA256: string;
+    /**
+     * — file type (e.g. 'PE32 executable')
+     */
+    F_TYPE: string;
+    /**
+     * — file size in bytes
+     */
+    F_SIZE: number;
+    /**
+     * — original file name
+     */
+    F_NAME?: string | undefined;
+    /**
+     * — sample sources
+     */
+    SOURCES?: string[] | undefined;
+    /**
+     * — first seen timestamp
+     */
+    FIRST_SEEN?: string | undefined;
+    /**
+     * — last seen timestamp
+     */
+    LAST_SEEN?: string | undefined;
+};
+export type UploadResult = {
+    /**
+     * — 'OK' or 'ERROR'
+     */
+    status: string;
+    /**
+     * — upload GUID for status tracking
+     */
+    guid?: string | undefined;
+    /**
+     * — error message if status is ERROR
+     */
+    error?: string | undefined;
+};
+export type DownloadUrlResult = {
+    /**
+     * — 'OK' or 'ERROR'
+     */
+    status: string;
+    /**
+     * — task GUID for checking status
+     */
+    guid?: string | undefined;
+    /**
+     * — error message
+     */
+    error?: string | undefined;
+};
+export type DownloadUrlStatus = {
+    /**
+     * — 'missing' | 'pending' | 'processing' | 'finished'
+     */
+    status: string;
+    /**
+     * — task GUID
+     */
+    guid?: string | undefined;
+};
+export type QuotaInfo = {
+    /**
+     * — allocated API calls per day
+     */
+    limit: number;
+    /**
+     * — remaining API calls
+     */
+    remaining: number;
+};