Argos Security SDK

A production-grade TypeScript/JavaScript SDK for real-time threat detection and fraud prevention. Argos monitors every request, scores risk using ML models, and blocks malicious traffic automatically.

Features

• AI-Powered Detection: ML models analyze requests in real-time and return risk scores
• Sync & Async Modes: Block malicious requests instantly or queue events for peak traffic
• Auto-Block: Automatically add malicious IPs to blocklist when ML returns BLOCK verdict
• Framework Middleware: Drop-in middleware for Express, Fastify, Koa, and Next.js
• Auto-Detection: Environment ID auto-detected from API key (no manual config needed)
• Circuit Breaker: Built-in resilience with automatic recovery
• Blocklist Check: Check blocklist before processing (fail-fast)

Installation

# Install the SDK
npm install argos-sdk

# With framework (optional)
npm install argos-sdk express   # For Express middleware
npm install argos-sdk fastify  # For Fastify middleware
npm install argos-sdk koa     # For Koa middleware

Quick Start

1. Create a Client

import { ArgosClient } from 'argos-sdk';

const client = new ArgosClient({
  apiKey: process.env.ARGOS_API_KEY!,
  baseURL: 'https://api.argos.io', // or your self-hosted URL
});

The SDK will auto-detect your environmentId from the API key. No manual configuration needed!

2. Add Middleware (Express Example)

import express from 'express';
import { ArgosClient, createExpressMiddleware } from 'argos-sdk';

const app = express();

// Create client with auto-block enabled
const client = new ArgosClient({
  apiKey: process.env.ARGUS_API_KEY!,
});

// Create middleware (sync mode blocks malicious requests)
app.use(createExpressMiddleware(client, {
  mode: 'sync',          // 'sync' blocks requests, 'async' queues
  checkBlocklist: true,  // Check blocklist BEFORE processing (recommended)
  includeHeaders: true,
  includeBody: true,
}));

app.get('/api/protected', (req, res) => {
  res.json({ message: 'Protected by Argos!' });
});

app.listen(3000);

3. That's It!

All requests will now be:

1. Checked against blocklist → 403 if blocked
2. Analyzed by ML → BLOCK verdict triggers auto-block
3. Auto-blocked IPs are added to blocklist automatically

Auto-Block Configuration

Enable automatic IP blocking when ML returns a BLOCK verdict:

const client = new ArgosClient({
  apiKey: process.env.ARGUS_API_KEY!,
  autoBlockOnBlock: true,    // Auto-block when ML returns BLOCK
  autoBlockTTL: 3600000,    // Block duration in ms (default: 1 hour)
});

When autoBlockOnBlock is enabled:

• Any request with BLOCK verdict will auto-add the client's IP to the blocklist
• Subsequent requests from that IP get 403 before processing

Configuration Options

const client = new ArgosClient({
  apiKey: 'required-your-api-key',
  baseURL: 'https://api.argos.io',        // Default: https://argos-api.tachyonix.net
  timeout: 30000,                    // Request timeout (ms)
  maxRetries: 3,                   // Retry attempts
  retryStrategy: 'exponential',      // 'exponential', 'linear', 'none'
  autoBlockOnBlock: false,            // Auto-block IPs on BLOCK verdict
  autoBlockTTL: 3600000,             // Auto-block duration (ms)
  environmentId: 'optional',         // Auto-detected if not provided
  trustedProxies: [],               // Trusted proxy CIDRs
});

All Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | Required | Your Argos API key | | baseURL | string | https://argos-api.tachyonix.net | API endpoint | | timeout | number | 30000 | Request timeout in ms | | maxRetries | number | 3 | Maximum retry attempts | | autoBlockOnBlock | boolean | false | Auto-block IP when ML returns BLOCK | | autoBlockTTL | number | 3600000 | Auto-block duration (ms) | | environmentId | string | Auto-detected | Your environment ID | | trustedProxies | string[] | [] | Trusted proxy CIDRs |

Middleware Options

const middleware = createExpressMiddleware(client, {
  mode: 'sync',              // 'sync' = block bad requests, 'async' = queue
  checkBlocklist: true,       // Check blocklist BEFORE ingest (recommended!)
  includeHeaders: true,      // Include request headers in event
  includeBody: false,      // Include request body in event
  excludePaths: ['/health', '/metrics', '/_health'], // Skip these paths
  identityHeader: 'X-User-ID', // Header to extract user ID from
});

Mode Explanation

| Mode | Behavior | |------|---------| | sync | Waits for ML decision, blocks if BLOCK verdict | | async | Queues event, returns immediately (verdict available later via WebSocket) |

checkBlocklist Option

When checkBlocklist: true (recommended):

1. Check if client IP is already blocked → 403 immediately
2. If not blocked, send to ML for analysis
3. If BLOCK verdict and autoBlockOnBlock: true, auto-block the IP
4. Next request from that IP gets blocked before ML analysis

This provides two layers of protection:

• Layer 1: Already blocked IPs get rejected fast (no ML call)
• Layer 2: New threats get ML analysis AND auto-blocked for next time

Framework Examples

Express

import express from 'express';
import { ArgosClient, createExpressMiddleware } from 'argos-sdk';

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

app.use(createExpressMiddleware(client, {
  mode: 'sync',
  checkBlocklist: true,
}));

app.get('/', (req, res) => res.send('Protected!'));

Fastify

import Fastify from 'fastify';
import { ArgosClient, createFastifyMiddleware } from 'argos-sdk';

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

await app.register(createFastifyMiddleware, {
  client,
  mode: 'sync',
  checkBlocklist: true,
});

Koa

import Koa from 'koa';
import { ArgosClient, createKoaMiddleware } from 'argos-sdk';

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

app.use(createKoaMiddleware({ client, mode: 'sync', checkBlocklist: true }));

Next.js

// middleware.ts
import { ArgosClient, createNextMiddleware } from 'argos-sdk';

const client = new ArgosClient({ apiKey: process.env.ARGUS_API_KEY! });

export default createNextMiddleware({ client, mode: 'sync' });

Programmatic Usage

Ingest an Event

const event = await client.ingest({
  event_type: 'login',
  user_id: 'user123',
  ip_address: '192.168.1.1',
  status: 'success',
});

if (event.signal === 'BLOCK') {
  console.log('Threat detected:', event.reason);
}

Check Blocklist

const result = await client.isBlocked('192.168.1.1');
if (result.blocked) {
  console.log('IP blocked:', result.reason);
}

Manual Block

const entry = await client.blockIP('192.168.1.1', environmentId, 'Manual block reason');
await client.unblock(entry.id);

Get Environment ID

const envId = client.getEnvironmentId();
console.log('Environment:', envId);

Auto-Detection

The SDK automatically detects your environmentId by calling /api/v1/me with your API key. This happens asynchronously on first request.

If you need it synchronously, you can:

// Option 1: Pass it manually
const client = new ArgosClient({
  apiKey: 'your-key',
  environmentId: 'env_123',  // From dashboard
});

// Option 2: Get it after detection
await client.detectEnvironmentId();  // Returns Promise
const envId = client.getEnvironmentId();

Response Headers

When using middleware, responses include Argos headers:

X-Argos-Verdict: block
X-Argos-Reason: sqli

• X-Argos-Verdict: allow or block
• X-Argos-Reason: Block reason (e.g., anomaly_score=0.85, sqli)

Error Handling

import {
  ArgosError,
  ArgosAPIError,
  ArgosAuthenticationError,
  ArgosRateLimitError,
  ArgosCircuitOpenError,
} from 'argos-sdk';

try {
  const event = await client.ingest({...});
} catch (e) {
  if (e instanceof ArgosAuthenticationError) {
    console.log('Invalid API key');
  } else if (e instanceof ArgosRateLimitError) {
    console.log('Rate limited. Retry after:', e.retryAfter);
  } else if (e instanceof ArgosCircuitOpenError) {
    console.log('Argos unavailable (circuit open)');
  }
}

TypeScript

This SDK is written in TypeScript with full type definitions included.

License

MIT License - see LICENSE for details.