shieldcortex-sdk

Official TypeScript SDK for the ShieldCortex API. Scan AI agent memory and inputs for prompt injection, credential leaks, and other threats.

Install

npm install shieldcortex-sdk

Quick Start

import { ShieldCortex } from 'shieldcortex-sdk';

const sc = new ShieldCortex({ apiKey: 'sc_live_...' });

const result = await sc.scan({ content: 'user input here' });

if (!result.allowed) {
  console.log('Blocked:', result.firewall.reason);
}

Getting an API Key

1. Sign up at shieldcortex.ai
2. Go to Dashboard > Keys
3. Click Create Key with the scan scope
4. Copy the key (it's only shown once)

API

new ShieldCortex(options)

Option	Type	Default	Description
apiKey	string	required	Your API key (sc_live_... or sc_test_...)
baseUrl	string	https://api.shieldcortex.ai	API base URL

Scanning

scan(input): Promise<ScanResult>

Scan a single piece of content through the 6-layer defence pipeline.

const result = await sc.scan({
  content: 'Text to scan',
  title: 'Optional title',
  source: { type: 'user', identifier: 'user-123' },
  config: { mode: 'strict' },
});

console.log(result.allowed);            // true or false
console.log(result.firewall.result);    // 'ALLOW' | 'BLOCK' | 'QUARANTINE'
console.log(result.trust.score);        // 0.0 - 1.0
console.log(result.sensitivity.level);  // 'PUBLIC' | 'INTERNAL' | 'CONFIDENTIAL' | 'RESTRICTED'
console.log(result.auditId);            // Unique audit trail ID

scanBatch(items, options?): Promise<BatchResult>

Scan up to 100 items in a single request.

const result = await sc.scanBatch([
  { content: 'First input' },
  { content: 'Second input' },
], {
  source: { type: 'agent', identifier: 'my-bot' },
  config: { mode: 'balanced' },
});

console.log(result.totalScanned);  // 2
console.log(result.threats);       // Number of blocked/quarantined items
console.log(result.results);       // Individual ScanResult per item

Audit Logs

getAuditLogs(query?): Promise<AuditResponse>

Query your team's audit trail with optional filters and pagination.

const logs = await sc.getAuditLogs({
  level: 'BLOCK',       // Filter: 'ALLOW' | 'BLOCK' | 'QUARANTINE'
  from: '2026-01-01',   // ISO datetime
  limit: 50,
  offset: 0,
});

for (const log of logs.logs) {
  console.log(log.firewall_result, log.trust_score, log.reason);
}

getAuditStats(timeRange?): Promise<AuditStats>

Get summary statistics for your team.

const stats = await sc.getAuditStats('7d');  // '24h' | '7d' | '30d'

console.log(stats.totalOperations);
console.log(stats.blockedCount);
console.log(stats.topSources);       // [{ source, count }]
console.log(stats.threatBreakdown);  // { indicator: count }

Quarantine

getQuarantine(query?): Promise<QuarantineResponse>

List quarantined items pending review.

const queue = await sc.getQuarantine({ status: 'pending', limit: 10 });

for (const item of queue.items) {
  console.log(item.reason, item.anomalyScore);
}

reviewQuarantine(id, action): Promise<void>

Approve or reject a quarantined item.

await sc.reviewQuarantine(42, 'approve');
await sc.reviewQuarantine(43, 'reject');

Error Handling

The SDK throws typed errors you can catch:

import { ShieldCortex, AuthError, RateLimitError, ValidationError } from 'shieldcortex-sdk';

try {
  await sc.scan({ content: 'test' });
} catch (err) {
  if (err instanceof AuthError) {
    // 401 - Invalid or expired API key
    console.error('Bad API key');
  } else if (err instanceof RateLimitError) {
    // 429 - Too many requests
    console.log('Retry after:', err.retryAfter, 'seconds');
  } else if (err instanceof ValidationError) {
    // 400 - Invalid request body
    console.error('Bad input:', err.body);
  }
}

Defence Modes

Mode	Description
strict	Maximum security. Blocks on low-confidence threats.
balanced	Default. Good balance of security and usability.
permissive	Minimal blocking. Logs threats but rarely blocks.

Requirements

• Node.js 18+ (uses native fetch)
• TypeScript 5+ (for type definitions)

Links

• Website
• Documentation
• npm package (core)
• GitHub

Licence

MIT