abuse.ch/readme.hints.md

Project Hints

Overview

This is an unofficial TypeScript client for accessing abuse.ch threat intelligence APIs, including URLhaus, ThreatFox, and FeodoTracker.

Recent Changes (2025-11-22)

Dependency Upgrades

• Migrated from @gitzone to @git.zone scope packages

  • All dev dependencies now use @git.zone/* scope (the correct new scope)
  • @git.zone/tsbuild: 3.1.0
  • @git.zone/tsbundle: 2.5.2
  • @git.zone/tsdoc: 1.9.2
  • @git.zone/tsrun: 2.0.0
  • @git.zone/tstest: 3.1.3

• Removed @push.rocks/tapbundle

  • Now using import { tap, expect } from '@git.zone/tstest/tapbundle'
  • Tests updated to use export default tap.start() pattern

• Updated production dependencies

  • @push.rocks/smartfile: 11.2.7 (stayed on v11 to avoid v13 breaking changes)
  • @push.rocks/smartpath: 6.0.0
  • csv-parser: 3.2.0
  • https-proxy-agent: 7.0.6
  • unzipper: 0.12.3

TypeScript Configuration

• Fixed tsconfig.json to use module: "nodenext" to match moduleResolution: "nodenext"
• Build command works with tsbuild --allowimplicitany (without --web flag to avoid type errors in node_modules)

File Naming

• Note: There was a typo in the file naming - originally had urlhouse.ts, now correctly named urlhaus.ts

Architecture

Main Classes

• UrlHaus - Fetches malicious URL data from URLhaus CSV export
• ThreatFox - Fetches IOC data from ThreatFox CSV export
• FeodoTracker - Fetches botnet C&C server data from FeodoTracker JSON API

Data Flow

1. Classes fetch data from abuse.ch APIs
2. For CSV data (URLhaus, ThreatFox): Downloads, extracts from ZIP, parses CSV
3. For JSON data (FeodoTracker): Direct JSON fetch and parse
4. Returns typed TypeScript interfaces

Dependencies

• smartfile v11.2.7 - Used for:
  • plugins.smartfile.fs.ensureDirSync() - Create temporary directories
  • plugins.smartfile.fs.removeSync() - Clean up temporary files
• smartpath v6.0.0 - Used for:
  • plugins.smartpath.get.dirnameFromImportMetaUrl() - Get package directory from import.meta.url
• node-fetch - HTTP requests to abuse.ch APIs
• csv-parser - Parse CSV data from URLhaus and ThreatFox
• unzipper - Extract downloaded ZIP files
• https-proxy-agent - Proxy support for HTTP requests

Testing

• Tests use @git.zone/tstest framework
• Run with: pnpm test
• Tests verify data retrieval from all three abuse.ch services
• All tests currently passing ✅

Build

• Build with: pnpm build
• Uses @git.zone/tsbuild
• Outputs to: dist_ts/
• Note: Use without --web flag to avoid type errors in node_modules

Known Issues

• None currently

Important Notes

• This module accesses free community threat intelligence data
• Be respectful of abuse.ch resources - avoid excessive polling
• The module automatically detects and uses HTTP_PROXY/HTTPS_PROXY environment variables
• All classes return Promises - use async/await