Truss API SDK

TypeScript SDK for pulling Truss API data into applications, ingestion jobs, and agents.

Installation

npm install @truss-security/truss-sdk

Node 18 or newer is required because the SDK uses the built-in fetch API.

Run Examples Quickly

Set your API credentials once:

cp env.example .env

Then run an example from this repo:

npm install
npm run example
npm run example:basic
npm run example:typed-filter
npm run example:iterate
npm run example:stix

npm run example opens an interactive picker in a terminal. In CI or non-interactive output, it prints the available examples instead.

You can also run examples directly by name:

npm run example -- basic
npm run example -- typed-filter
npm run example -- iterate
npm run example -- stix

To print the list without opening the picker, use --list:

npm run example -- --list

Each example prints a concise human-readable summary. Add --json when you want the raw response:

npm run example -- basic --json

If TRUSS_API_KEY is not set, the CLI and local examples prompt for it in interactive terminals.

To run examples without cloning the repo:

npx -p @truss-security/truss-sdk@latest truss examples
npx -p @truss-security/truss-sdk@latest truss examples --list
npx -p @truss-security/truss-sdk@latest truss examples basic
# You will be prompted to install truss-sdk to a temporary local npm cache.
# Ok to proceed? (y) 

Quick Start

import { TrussClient, filter } from '@truss-security/truss-sdk';

const truss = new TrussClient({
  baseUrl: 'https://api.truss-security.com',
  apiKey: process.env.TRUSS_API_KEY,
});

const results = await truss.search.products({
  filter: filter.and(
    filter.eq('category', 'Malware'),
    filter.anyOf('region', ['North America', 'Europe'])
  ),
  days: 7,
  limit: 25,
});

console.log(results.products);

Get one product

const product = await truss.search.product('01ARZ3NDEKTSV4RRFFQ69G5FAV');
// or await truss.search.product(12345);

Search Products

Use search.products when you want structured product data for your app.

const page = await truss.search.products({
  filterExpression: "category = 'Phishing' AND source = 'OpenPhish'",
  startDate: '2025-01-01',
  endDate: '2025-01-31',
  page: 1,
  limit: 50,
});

For ingestion jobs and agents, use the pagination helpers instead of writing page loops.

for await (const product of truss.search.iterProducts({ days: 7, limit: 100 })) {
  await indexProduct(product);
}

const products = await truss.search.productsAll(
  { days: 7, limit: 100 },
  { maxPages: 10 }
);

Internal / admin-only search (vector, global, smart, similar)

Endpoints such as POST /search/vector, POST /search/global, POST /search/smart, and GET /search/similar/{id} require internal API access. Use **@truss-security/truss-sdk-internal**, which re-exports this package and adds TrussInternalClient with search.vector, search.global, search.smart, and search.similar. See that package’s README.

STIX

The SDK exposes STIX endpoints for security tooling interoperability.

const bundle = await truss.search.productStix(123);

const stixResults = await truss.search.productsStix({
  filterExpression: "category = 'Malware'",
  days: 14,
  limit: 50,
});

Filters

You can pass raw FilterQL with filterExpression, or use the typed filter helper.

const productFilter = filter.and(
  filter.eq('category', 'Malware'),
  filter.notEq('source', 'Example Source'),
  filter.like('title', 'ransomware')
);

const filterExpression = filter.expression(productFilter);

Supported filter attributes are exported as TypeScript types and include category, source, type, title, author, industry, region, reference, tags, validators, and indicators.

Configuration

const truss = new TrussClient({
  baseUrl: 'https://api.truss-security.com',
  apiKey: process.env.TRUSS_API_KEY,
  timeout: 30_000,
  retries: 3,
  retryDelayMs: 250,
  userAgent: 'my-app/1.0',
});

truss.setApiKey('new-api-key');

Requests retry network failures, timeouts, and common transient HTTP statuses: 408, 429, 500, 502, 503, and 504.

Error Handling

import { TrussApiError, TrussTimeoutError } from '@truss-security/truss-sdk';

try {
  await truss.search.products({ days: 7 });
} catch (error) {
  if (error instanceof TrussApiError) {
    console.error(error.status, error.response.data);
  } else if (error instanceof TrussTimeoutError) {
    console.error('Request timed out');
  } else {
    throw error;
  }
}

Development

npm install
npm run build
npm run example

# Publish
npm login
npm publish