contrastapi 1.0.0

package/README.md

@@ -0,0 +1,126 @@
+# ContrastAPI Node.js SDK
+
+Official Node.js SDK for [ContrastAPI](https://api.contrastcyber.com) — security intelligence for developers and AI agents.
+
+Zero dependencies. Works with Node.js 14+.
+
+## Install
+
+```bash
+npm install contrastapi
+```
+
+## Quick Start
+
+```javascript
+const ContrastAPI = require("contrastapi");
+const api = ContrastAPI();
+
+async function main() {
+  // Domain intelligence
+  const report = await api.domain.report("example.com");
+
+  // CVE lookup
+  const cve = await api.cve.lookup("CVE-2024-3094");
+
+  // SSL certificate check
+  const ssl = await api.domain.ssl("example.com");
+
+  // Scan HTTP security headers (live)
+  const headers = await api.scan.headers("example.com");
+
+  // Check code for secrets
+  const secrets = await api.check.secrets("const key = 'AKIA...'", "javascript");
+}
+
+main();
+```
+
+## With API Key (Pro)
+
+```javascript
+const api = ContrastAPI({ apiKey: "your-api-key" });
+```
+
+## All Methods
+
+### Domain Intelligence
+```javascript
+api.domain.report("example.com")           // Full domain report
+api.domain.report("example.com", {lite: true}) // Fast lite report
+api.domain.dns("example.com")              // DNS records
+api.domain.whois("example.com")            // WHOIS data
+api.domain.subdomains("example.com")       // Subdomain enumeration
+api.domain.certs("example.com")            // Certificate transparency
+api.domain.ssl("example.com")              // SSL/TLS analysis
+api.domain.tech("example.com")             // Technology fingerprint
+api.domain.threat("example.com")           // Threat intelligence
+api.domain.monitor("example.com")          // Domain monitoring
+api.domain.vulns("example.com")            // Known vulnerabilities
+api.domain.bulk(["a.com", "b.com"])        // Bulk domain reports
+```
+
+### IP & ASN
+```javascript
+api.ip.lookup("8.8.8.8")                   // IP intelligence
+api.asn.lookup("google.com")               // ASN lookup
+```
+
+### CVE Intelligence
+```javascript
+api.cve.lookup("CVE-2024-3094")            // Single CVE
+api.cve.search({product: "apache", severity: "critical"})
+api.cve.recent()                           // Recently published
+api.cve.kev()                              // Known exploited (CISA KEV)
+api.cve.epss("CVE-2024-3094")              // EPSS score
+api.cve.exploit("CVE-2024-3094")           // Public exploits
+```
+
+### Threat Intelligence
+```javascript
+api.ioc.lookup("evil.com")                 // IOC enrichment (auto-detect type)
+api.ioc.hash("abc123...")                  // Malware hash lookup
+api.ioc.phishing("https://evil.com/login") // Phishing check
+```
+
+### Email & Phone
+```javascript
+api.email.mx("example.com")               // MX + SPF/DMARC/DKIM
+api.email.disposable("user@tempmail.com")  // Disposable email check
+api.phone.lookup("+1234567890")            // Phone validation
+```
+
+### Password
+```javascript
+api.password.check("5baa61e4...")           // HIBP breach check (SHA1)
+```
+
+### Code Security
+```javascript
+api.check.secrets(code, "python")          // Detect hardcoded secrets
+api.check.injection(code, "javascript")    // SQL/command injection
+api.check.headers({"Content-Security-Policy": "..."})  // Header validation
+api.check.dependencies([{name: "lodash", version: "4.17.0"}])  // CVE check
+api.scan.headers("example.com")            // Live header scan
+```
+
+### Meta
+```javascript
+api.status()                               // API health
+api.usage()                                // Usage stats (Pro)
+```
+
+## Error Handling
+
+```javascript
+try {
+  const result = await api.cve.lookup("CVE-9999-0000");
+} catch (err) {
+  console.log(err.status);    // 404
+  console.log(err.message);   // "CVE not found"
+}
+```
+
+## License
+
+MIT

package/index.d.ts

@@ -0,0 +1,62 @@
+declare function ContrastAPI(options?: {
+  baseUrl?: string;
+  apiKey?: string;
+  timeout?: number;
+  allowInsecure?: boolean;
+}): {
+  domain: {
+    report(domain: string, opts?: { lite?: boolean }): Promise<any>;
+    dns(domain: string): Promise<any>;
+    whois(domain: string): Promise<any>;
+    subdomains(domain: string): Promise<any>;
+    certs(domain: string): Promise<any>;
+    ssl(domain: string): Promise<any>;
+    tech(domain: string): Promise<any>;
+    threat(domain: string): Promise<any>;
+    monitor(domain: string): Promise<any>;
+    vulns(domain: string): Promise<any>;
+    bulk(domains: string[]): Promise<any>;
+  };
+  ip: {
+    lookup(ip: string): Promise<any>;
+  };
+  asn: {
+    lookup(target: string): Promise<any>;
+  };
+  cve: {
+    lookup(cveId: string): Promise<any>;
+    search(params?: { product?: string; severity?: string; days?: number; limit?: number }): Promise<any>;
+    recent(params?: { hours?: number; limit?: number }): Promise<any>;
+    kev(params?: { limit?: number }): Promise<any>;
+    epss(cveId: string): Promise<any>;
+    exploit(cveId: string): Promise<any>;
+  };
+  ioc: {
+    lookup(indicator: string): Promise<any>;
+    hash(fileHash: string): Promise<any>;
+    phishing(url: string): Promise<any>;
+  };
+  email: {
+    mx(domain: string): Promise<any>;
+    disposable(email: string): Promise<any>;
+  };
+  phone: {
+    lookup(number: string): Promise<any>;
+  };
+  password: {
+    check(sha1Hash: string): Promise<any>;
+  };
+  check: {
+    secrets(code: string, language: string): Promise<any>;
+    injection(code: string, language: string): Promise<any>;
+    headers(headers: Record<string, string>): Promise<any>;
+    dependencies(packages: Array<{ name: string; version?: string }>): Promise<any>;
+  };
+  scan: {
+    headers(domain: string): Promise<any>;
+  };
+  status(): Promise<any>;
+  usage(): Promise<any>;
+};
+
+export = ContrastAPI;

package/index.js

@@ -0,0 +1,196 @@
+/**
+ * ContrastAPI — Security Intelligence SDK
+ * https://api.contrastcyber.com
+ */
+
+const https = require("https");
+const http = require("http");
+
+const DEFAULT_BASE = "https://api.contrastcyber.com";
+const MAX_BODY = 10 * 1024 * 1024; // 10 MB
+const VERSION = require("./package.json").version;
+
+function enc(v) {
+  if (!v && v !== 0) throw new Error("Missing required parameter");
+  return encodeURIComponent(String(v));
+}
+
+function encPath(v) {
+  if (!v) throw new Error("Missing required parameter");
+  return String(v).split("/").map(encodeURIComponent).join("/");
+}
+
+function ContrastAPI(options = {}) {
+  const baseUrl = (options.baseUrl || DEFAULT_BASE).replace(/\/$/, "");
+  const apiKey = options.apiKey || null;
+  const timeout = Math.max(1000, Math.min(options.timeout || 30000, 120000));
+
+  if (!baseUrl.startsWith("https://") && !options.allowInsecure) {
+    throw new Error("Only HTTPS is allowed. Pass { allowInsecure: true } to override.");
+  }
+
+  function request(method, path, body) {
+    return new Promise((resolve, reject) => {
+      const url = new URL(path, baseUrl);
+      if (url.origin !== new URL(baseUrl).origin) {
+        return reject(new Error("URL origin mismatch"));
+      }
+
+      const headers = {
+        "Accept": "application/json",
+        "User-Agent": `contrastapi-node/${VERSION}`,
+      };
+      if (apiKey) {
+        if (url.protocol !== "https:") {
+          return reject(new Error("Refusing to send API key over insecure connection"));
+        }
+        headers["X-API-Key"] = apiKey;
+      }
+
+      let payload;
+      if (body) {
+        payload = JSON.stringify(body);
+        headers["Content-Type"] = "application/json";
+        headers["Content-Length"] = Buffer.byteLength(payload);
+      }
+
+      const mod = url.protocol === "https:" ? https : http;
+      const req = mod.request(url, { method, headers, timeout }, (res) => {
+        let data = "";
+        let size = 0;
+        res.on("data", (chunk) => {
+          size += chunk.length;
+          if (size > MAX_BODY) {
+            req.destroy();
+            return reject(new Error("Response too large"));
+          }
+          data += chunk;
+        });
+        res.on("end", () => {
+          try {
+            const json = JSON.parse(data);
+            if (res.statusCode >= 400) {
+              const err = new Error(json.detail || json.message || `HTTP ${res.statusCode}`);
+              err.status = res.statusCode;
+              reject(err);
+            } else {
+              resolve(json);
+            }
+          } catch {
+            reject(new Error(`Invalid JSON response (HTTP ${res.statusCode})`));
+          }
+        });
+      });
+
+      req.on("error", reject);
+      req.on("timeout", () => { req.destroy(); reject(new Error("Request timed out")); });
+      if (payload) req.write(payload);
+      req.end();
+    });
+  }
+
+  function get(path) { return request("GET", path); }
+  function post(path, body) { return request("POST", path, body); }
+
+  return {
+    // --- Domain Intelligence ---
+    domain: {
+      report: (domain, opts = {}) => get(`/v1/domain/${enc(domain)}${opts.lite ? "?lite=true" : ""}`),
+      dns: (domain) => get(`/v1/dns/${enc(domain)}`),
+      whois: (domain) => get(`/v1/whois/${enc(domain)}`),
+      subdomains: (domain) => get(`/v1/subdomains/${enc(domain)}`),
+      certs: (domain) => get(`/v1/certs/${enc(domain)}`),
+      ssl: (domain) => get(`/v1/ssl/${enc(domain)}`),
+      tech: (domain) => get(`/v1/tech/${enc(domain)}`),
+      threat: (domain) => get(`/v1/threat/${enc(domain)}`),
+      monitor: (domain) => get(`/v1/monitor/${enc(domain)}`),
+      vulns: (domain) => get(`/v1/domain/${enc(domain)}/vulns`),
+      bulk: (domains) => {
+        if (!Array.isArray(domains) || !domains.every(d => typeof d === "string")) {
+          throw new Error("domains must be an array of strings");
+        }
+        return post("/v1/domains/bulk", { domains });
+      },
+    },
+
+    // --- IP Intelligence ---
+    ip: {
+      lookup: (ip) => get(`/v1/ip/${enc(ip)}`),
+    },
+
+    // --- ASN ---
+    asn: {
+      lookup: (target) => get(`/v1/asn/${enc(target)}`),
+    },
+
+    // --- CVE Intelligence ---
+    cve: {
+      lookup: (cveId) => get(`/v1/cve/${enc(cveId)}`),
+      search: (params = {}) => {
+        const q = new URLSearchParams();
+        if (params.product) q.set("product", params.product);
+        if (params.severity) q.set("severity", params.severity);
+        if (params.days) q.set("days", params.days);
+        if (params.limit) q.set("limit", params.limit);
+        return get(`/v1/cves?${q}`);
+      },
+      recent: (params = {}) => {
+        const q = new URLSearchParams();
+        if (params.hours) q.set("hours", params.hours);
+        if (params.limit) q.set("limit", params.limit);
+        const qs = q.toString();
+        return get(`/v1/cves/recent${qs ? "?" + qs : ""}`);
+      },
+      kev: (params = {}) => {
+        const q = new URLSearchParams();
+        if (params.limit) q.set("limit", params.limit);
+        const qs = q.toString();
+        return get(`/v1/cves/kev${qs ? "?" + qs : ""}`);
+      },
+      epss: (cveId) => get(`/v1/epss/${enc(cveId)}`),
+      exploit: (cveId) => get(`/v1/exploit/${enc(cveId)}`),
+    },
+
+    // --- Threat Intelligence / IOC ---
+    ioc: {
+      lookup: (indicator) => get(`/v1/ioc/${encPath(indicator)}`),
+      hash: (fileHash) => get(`/v1/hash/${enc(fileHash)}`),
+      phishing: (url) => get(`/v1/phishing/${encPath(url)}`),
+    },
+
+    // --- Email ---
+    email: {
+      mx: (domain) => get(`/v1/email/mx/${enc(domain)}`),
+      disposable: (email) => get(`/v1/email/disposable/${enc(email)}`),
+    },
+
+    // --- Phone ---
+    phone: {
+      lookup: (number) => get(`/v1/phone/${enc(number)}`),
+    },
+
+    // --- Password ---
+    password: {
+      check: (sha1Hash) => get(`/v1/password/${enc(sha1Hash)}`),
+    },
+
+    // --- Code Security ---
+    check: {
+      secrets: (code, language) => post("/v1/check/secrets", { code, language }),
+      injection: (code, language) => post("/v1/check/injection", { code, language }),
+      headers: (headers) => post("/v1/check/headers", { headers }),
+      dependencies: (packages) => post("/v1/check/dependencies", { packages }),
+    },
+
+    // --- Headers (live scan) ---
+    scan: {
+      headers: (domain) => get(`/v1/scan/headers/${enc(domain)}`),
+    },
+
+    // --- Meta ---
+    status: () => get("/v1/status"),
+    usage: () => get("/v1/usage"),
+  };
+}
+
+module.exports = ContrastAPI;

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "contrastapi",
+  "version": "1.0.0",
+  "description": "Official Node.js SDK for ContrastAPI — security intelligence for developers and AI agents",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "license": "MIT",
+  "author": "ContrastCyber <hello@contrastcyber.com>",
+  "homepage": "https://contrastcyber.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/UPinar/contrastapi"
+  },
+  "keywords": [
+    "security",
+    "cve",
+    "vulnerability",
+    "domain",
+    "dns",
+    "whois",
+    "ssl",
+    "threat-intelligence",
+    "mcp",
+    "osint",
+    "api"
+  ],
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=14"
+  }
+}