Helper Library for CTX Cyber Threat Intelligence API

Node.js TypeScript unofficial helper library for CTX Cyber Threat Intelligence API

Disclaimer

• Unofficial helper library: This project is community-maintained and not affiliated with ctx.io.
• Use of this library requires a valid ctx.io account and acceptance of ctx.io’s API Terms of Service. This library does not grant rights to ctx.io’s API or data.
• Trademarks and brand names belong to their respective owners.

Installation

npm install libctx

Quick Start

import { CTXClient } from 'libctx';

const client = new CTXClient({ apiKey: 'your-api-key' });

// Get file report by hash
const report = await client.ioc.getFileReport('sha256-hash');
console.log(report.detect, report.threatTypes);

// Get IP report
const ipReport = await client.ioc.getIPReport('156.236.72.121');
console.log(ipReport.aptThreatActors);

// Get domain report
const domainReport = await client.ioc.getDomainReport('malicious.com');
console.log(domainReport.aptCampaigns);

Configuration

const client = new CTXClient({
  apiKey: 'your-api-key',      // Required
  baseUrl: 'https://api.ctx.io/v1',  // Optional (default)
  timeout: 30000,              // Optional (default: 30s)
});

Modules

IoC Intelligence (client.ioc)

File, IP, and Domain analysis with IoC relationships.

// File operations
await client.ioc.uploadFile('./malware.exe');
await client.ioc.uploadFile(buffer, { fileName: 'sample.exe' });
await client.ioc.downloadFile('sha256-hash');
await client.ioc.getFileReport('sha256-hash');

// IP/Domain reports
await client.ioc.getIPReport('1.2.3.4');
await client.ioc.getDomainReport('example.com');

// Similar files & IoC relationships
await client.ioc.getSimilarFiles('sha256-hash');
await client.ioc.getAssociatedIoCs('sha256-hash');
await client.ioc.getIPAssociatedIoCs('1.2.3.4');
await client.ioc.getDomainAssociatedIoCs('example.com');

// Search by tag
await client.ioc.searchByTag('ransomware', { limit: 100 });
await client.ioc.searchByTag(['trojan', 'downloader']);

APT Intelligence (client.apt)

Campaign reports and threat actor information.

// Campaign report
await client.apt.getCampaignReport('threat--uuid');

// Campaigns by IoC
await client.apt.getFileCampaigns('sha256-hash');
await client.apt.getDomainCampaigns('malicious.com');

// Campaigns by threat actor (name or MITRE ATT&CK G-ID)
await client.apt.getThreatActorCampaigns('Lazarus Group');
await client.apt.getThreatActorCampaigns('G0032');

// Campaigns by country
await client.apt.getAttackerCountryCampaigns('KP');  // North Korea
await client.apt.getVictimCountryCampaigns('KR');    // South Korea

// Search campaigns by tag
await client.apt.searchCampaignsByTags('ransomware');
await client.apt.searchCampaignsByTags(['apt', 'backdoor']);

Total Intelligence (client.total)

Combined IoC + APT intelligence in a single request.

// Get complete intelligence report
const fileReport = await client.total.getFileReport('sha256-hash');
console.log(fileReport.ioc);  // IoC intelligence
console.log(fileReport.apt);  // APT intelligence

const ipReport = await client.total.getIPReport('1.2.3.4');
const domainReport = await client.total.getDomainReport('example.com');

Search (client.search)

Advanced search capabilities.

// Submit search request
const result = await client.search.advancedSearch({
  iocType: 'file',  // 'file' | 'ip' | 'domain'
  query: 'tags:Ransomware AND threat_types:Trojan',
  cursor: 'optional-cursor-for-pagination',
});

console.log(result.reqId);      // Request ID for retrieving results
console.log(result.totalCount); // Total matching results
console.log(result.files);      // File results (when iocType is 'file')

// Get search results by request ID
const results = await client.search.getSearchResults(result.reqId);

Feed (client.feed)

Threat intelligence feeds by date. Feed data is returned in NDJSON format.

Date Formats: YYYY-MM-DD HH, YYYYMMDDHH, YYYY-MM-DD HH:mm, YYYYMMDDHHmm

// IoC Feeds
const files = await client.feed.getFileFeed('2024-04-09 11');
const domains = await client.feed.getDomainFeed('2024040911');
const urls = await client.feed.getURLFeed('2024-04-09 11:30');

// File feed contains rich data
files.items.forEach((file) => {
  console.log(file.hash.sha256);
  console.log(file.detect);
  console.log(file.attackTechniques);      // MITRE ATT&CK
  console.log(file.iocRelation);           // Related IPs, domains, files
  console.log(file.aptThreatActors);       // Associated threat actors
  console.log(file.aptCampaigns);          // Associated campaigns
});

// Campaign Feeds
await client.feed.getThreatActorFeed('G0032', '2024-04-09 11');
await client.feed.getAttackerCountryFeed('KP', '2024-04-09 11');
await client.feed.getVictimCountryFeed('KR', '2024-04-09 11');
await client.feed.getCampaignTagFeed('ransomware', '2024-04-09 11');

API Reference

IoC Intelligence

| Method | Description | |--------|-------------| | uploadFile(path \| buffer, options?) | Upload file for analysis | | downloadFile(hash) | Download file by hash | | getFileReport(hash) | Get file analysis report | | getIPReport(ip) | Get IP analysis report | | getDomainReport(domain) | Get domain analysis report | | getSimilarFiles(hash) | Get similar files by hash | | getAssociatedIoCs(hash) | Get IoCs associated with file | | getIPAssociatedIoCs(ip) | Get IoCs associated with IP | | getDomainAssociatedIoCs(domain) | Get IoCs associated with domain | | searchByTag(tags, options?) | Search files by tag(s) |

APT Intelligence

| Method | Description | |--------|-------------| | getCampaignReport(ctxId) | Get campaign report by ID | | getFileCampaigns(hash) | Get campaigns associated with file | | getDomainCampaigns(domain) | Get campaigns associated with domain | | getThreatActorCampaigns(actor) | Get campaigns by threat actor | | getAttackerCountryCampaigns(country) | Get campaigns by attacker country | | getVictimCountryCampaigns(country) | Get campaigns targeting country | | searchCampaignsByTags(tags) | Search campaigns by tag(s) |

Total Intelligence

| Method | Description | |--------|-------------| | getFileReport(hash) | Get combined IoC + APT report for file | | getIPReport(ip) | Get combined IoC + APT report for IP | | getDomainReport(domain) | Get combined IoC + APT report for domain |

Search

| Method | Description | |--------|-------------| | advancedSearch(options) | Submit advanced search query | | getSearchResults(reqId) | Get search results by request ID |

Feed

| Method | Description | |--------|-------------| | getFileFeed(date) | Get malicious file feed | | getDomainFeed(date) | Get malicious domain feed | | getURLFeed(date) | Get malicious URL feed | | getThreatActorFeed(actor, date) | Get campaigns by threat actor | | getAttackerCountryFeed(country, date) | Get campaigns by attacker country | | getVictimCountryFeed(country, date) | Get campaigns targeting country | | getCampaignTagFeed(tag, date) | Get campaigns by tag |

Error Handling

import { CTXClient, ApiError, ValidationError, TimeoutError } from 'libctx';

try {
  const report = await client.ioc.getFileReport('invalid-hash');
} catch (error) {
  if (error instanceof ValidationError) {
    console.log('Invalid input:', error.message);
  } else if (error instanceof ApiError) {
    console.log('API error:', error.message, error.statusCode);
  } else if (error instanceof TimeoutError) {
    console.log('Request timed out');
  }
}

Types

All types are exported from the package:

import {
  // Client & Config
  CTXClient,
  CTXConfig,

  // Errors
  CTXError,
  ApiError,
  ValidationError,
  TimeoutError,

  // IoC Types
  FileReportResult,
  IPReportResult,
  DomainReportResult,
  AttackTechnique,
  SimilarFile,
  AssociatedFile,
  AssociatedIP,
  AssociatedDomain,

  // APT Types
  CampaignReportResult,
  CampaignThreatActor,
  CampaignVictims,
  FileCampaignsResult,
  ThreatActorCampaignsResult,

  // Total Types
  TotalFileReportResult,
  TotalIPReportResult,
  TotalDomainReportResult,

  // Search Types
  AdvancedSearchRequestOptions,
  AdvancedSearchRequestResult,
  AdvancedSearchResponseResult,

  // Feed Types
  FileFeedResult,
  DomainFeedResult,
  URLFeedResult,
  ThreatActorFeedResult,
  AttackerCountryFeedResult,
  VictimCountryFeedResult,
  CampaignTagFeedResult,
} from 'libctx';

Licensing & Compliance

• Project license: MIT (see LICENSE).
• Dependencies: form-data (MIT), typescript (Apache-2.0), @types/node (MIT) — all compatible with MIT.
• API Terms: Use of this SDK and any data retrieved is subject to ctx.io’s API Terms of Service.

License

MIT — see LICENSE