LogoDocsHub
Shield Base

TypeScript Types

All exported TypeScript type definitions for built-in data sources, the compiler inputs, and how to auto-generate types from any JSON data.

@riavzon/shield-base ships fully typed interfaces for every built-in data source and the compiler system. All types are exported from the main package entry point.

Generating Types from JSON

Shield Base can generate TypeScript type definitions from any JSON input. The output is a .ts file with interfaces that reflect the full structure of the data, including nested objects, arrays, and mixed types.

CLI

# Generate from a JSON file
pnpm dlx @riavzon/shield-base types --name myData --outputDir ./src/types data.json

# Generate from a raw JSON string
pnpm dlx @riavzon/shield-base types --name myData --outputDir ./src/types '{"key": "value", "count": 1}'

# Batch: multiple files generate indexed type files
pnpm dlx @riavzon/shield-base types --name batchTypes --outputDir ./src/types file1.json file2.json

Batch processing produces: batchTypesTypes.ts, batchTypes-1Types.ts, batchTypes-2Types.ts, and so on.

The generateTypeFile utility accepts three input formats:

  • File path: A string path to a .json file.
  • JSON string: A raw stringified JSON.
  • Object: A standard JavaScript object or array already in memory.

Example

Given the input data:

example.json
[
  {
    "range": "1.1.1.0/24",
    "metadata": {
      "version": "1.0.0",
      "tags": ["dns", "secure"]
    },
    "organization": {
      "name": "Cloudflare, Inc.",
      "details": { "employees": 3000, "is_public": true }
    }
  }
]

The generated exampleTypes.ts file:

exampleTypes.ts
interface Example {
  range: string;
  metadata: Metadata;
  organization: Organization;
}

interface Organization {
  name: string;
  details: Details;
}

interface Details {
  employees: number;
  is_public: boolean;
}

interface Metadata {
  version: string;
  tags: string[];
}

Built-in Source Types

BGP / ASN

import type { BgpRecord, BGPRouteRaw, AsnDictionaryEntry } from '@riavzon/shield-base';

interface BgpRecord {
  range: string;
  asn_id: string;         // e.g. "15169"
  asn_name: string;       // e.g. "Google LLC"
  classification: string; // "Content" | "Eyeballs" | "Unknown"
  hits: string;
}

interface BGPRouteRaw {
  CIDR: string;
  ASN: number;
  Hits: number;
}

interface AsnDictionaryEntry {
  name: string;
  type: string;
}

City Geolocation

import type { CityGeoRecord } from '@riavzon/shield-base';

interface CityGeoRecord {
  range: string;
  country_code: string;
  region: string;
  city: string;
  zip_code: string;
  numericCode: string;
  latitude: string;
  longitude: string;
  state: string;
  name: string;
  native: string;
  phone: string;
  continent: string;
  capital: string;
  currency: string;
  currency_name: string;
  iso639: string;
  languages: string;
  emoji: string;
  timezone: string;
  utc_offset: string;
  tld: string;
  nationality: string;
  subregion: string;
  timeZoneName: string;
}

Country Geolocation

import type { GeoRecord } from '@riavzon/shield-base';

interface GeoRecord {
  range: string;
  country_code: string;
  region: string;
  numericCode: string;
  name: string;
  native: string;
  phone: string;
  capital: string;
  currency: string;
  currency_name: string;
  currency_symbol: string;
  iso639: string;
  languages: string;
  emoji: string;
  tld: string;
  nationality: string;
  subregion: string;
  timezone: string;
  timeZoneName: string;
  utc_offset: string;
}

Proxy Detection

import type { ProxyRecord } from '@riavzon/shield-base';

interface ProxyRecord {
  range: string;
  port: string;
  comment: string; // Comma-separated source feed names
}

Tor Nodes

import type { TorRecord } from '@riavzon/shield-base';

interface TorRecord {
  range: string;
  or_addresses: string;
  exit_addresses: string;
  last_seen: string;
  last_changed_address_or_port: string;
  first_seen: string;
  running: boolean;
  flags: string;                // e.g. "Exit,Fast,Guard,Running,Valid"
  country: string;
  country_name: string;
  as: string;                   // ASN identifier
  as_name: string;
  last_restarted: string;
  exit_policy: string;
  exit_policy_summary: string;
  exit_policy_v6_summary?: string;
  contact: string;
  version_status: string;
  guard_probability: number;
  middle_probability: number;
  exit_probability: number;
  recommended_version: boolean;
  measured: boolean;
}

FireHOL Threat Intelligence

import type { ThreatRecord } from '@riavzon/shield-base';

interface ThreatRecord {
  range: string;
  comment: string;
}

Verified Crawlers

import type { CrawlersRecord, ProvidersLists, BotIpData } from '@riavzon/shield-base';

interface CrawlersRecord {
  range: string;
  provider: string;     // e.g. "google", "bing", "apple"
  syncToken: string;
  creationTime: string;
}

interface ProvidersLists {
  name: string;
  type: 'HTML' | 'JSON' | 'CSV';
  urls: string[];
}

User-Agent Patterns

import type { UserAgentRecord, Severity } from '@riavzon/shield-base';

type Severity = 'none' | 'low' | 'medium' | 'high' | 'critical';
type Usage = 'Hunting' | 'Detection rule';

interface UserAgentRecord {
  useragent_rx: string;                // Regex pattern
  metadata_description: string;
  metadata_tool: string;
  metadata_category: string;
  metadata_link: string;
  metadata_priority: Severity;
  metadata_fp_risk: Severity;
  metadata_severity: Severity;
  metadata_usage: Usage;
  metadata_flow_from_external: boolean | null;
  metadata_flow_from_internal: boolean | null;
  metadata_flow_to_internal: boolean | null;
  metadata_flow_to_external: boolean | null;
  metadata_for_successful_external_login_events: boolean | null;
  metadata_comment: string;
  date: string;
  comment: string;
}

Disposable Email Domains

import type { EmailListRecord } from '@riavzon/shield-base';

interface EmailListRecord {
  domain: string;
  date: string;
  comment: string;
}

Compiler Input Types

import type { Input, LmdbInput, LmdbSources, StringOfSources } from '@riavzon/shield-base';

type CompilerOptions<T> = 
    | { type: 'lmdb'; input: LmdbInput<T> }
    | { type: 'mmdb'; input: Input<T> };


type LmdbInput<T> = Omit<Input<T>, 'mmdbPath'> & {
    data: LmdbSources<T>;   
};

interface Input<T> {
    outputPath: string;
    dataBaseName: string;
    data: T[] | StringOfSources[] | string;
    mmdbPath: string;
    generateTypes: boolean;
}

interface DatabaseRecord<T> {
    key: string,
    data: T
}

interface StringOfSources {
    pathToJson: string,
    dataBaseName: string;
    outputPath: string;
}

type LmdbSources<T> = DatabaseRecord<T>[] | StringOfSources[] | string | (T & {key: string})[];

Cache Type

import type { InputCache } from '@riavzon/shield-base';

interface InputCache {
  selectedDataTypes: string[];   // Previously selected source IDs
  useragent: string;             // BGP.tools contact string
  license: boolean;              // FireHOL license acknowledged
  mmdbctlPath: string;           // Absolute path to the mmdbctl binary
  outPutPath: string;            // Output directory from last run
}

This structure is stored at ~/.shield-base/.cache.json between runs.

Custom Data Sources

API Reference

Logo