@centure/node-sdk (英语)

一个完全型式安全的TypeScript SDK,用于与Centure的API交互,用于即时注射检测.

安装

npm install @centure/node-sdk

使用量

初始化客户端

import { CentureClient } from "@centure/node-sdk";

// Using environment variable CENTURE_API_KEY
const client = new CentureClient();

// Or provide API key directly
const client = new CentureClient({
  apiKey: "your-api-key",
  baseUrl: "https://api.centure.ai", // Optional, defaults to production
});

扫描快速注射的文本

const result = await client.scanText("Your text content here");

console.log("Is safe:", result.is_safe);
console.log("Detected categories:", result.categories);
console.log("Reason:", result.reason); // Explanation when flagged
console.log("Request ID:", result.request_id);

扫描选项

两者 scanText 财务报告和审定财务报表 scanImage 接受选项 ScanOptions 参数 :

// Only scan for specific categories
const result = await client.scanText("content", {
  only: ["data_exfiltration", "unauthorized_actions"],
});

// Exclude certain categories
const result = await client.scanText("content", {
  exclude: ["output_manipulation"],
});

// Set minimum confidence threshold
const result = await client.scanText("content", {
  minimum_confidence: "high",
});

扫描选项

所有选项都是可选的.

扫描图像( Base64 或缓冲)

// Using base64 string
const base64Image = "iVBORw0KGgoAAAANSUhEUgAA...";
const result = await client.scanImage(base64Image);

console.log("Is safe:", result.is_safe);
console.log("Detected threats:", result.categories);

// Using Buffer (Node.js) - automatically converted to base64
import fs from "fs";

const imageBuffer = fs.readFileSync("./image.png");
const result = await client.scanImage(imageBuffer);

API 反应

所有扫描方法返回 a ScanResponse 对象 :

interface ScanResponse {
  is_safe: boolean;
  categories: DetectedCategory[];
  reason?: string;
  request_id: string;
  api_key_id: string;
  request_units: number;
  billed_request_units: number;
  service_tier: ServiceTier;
}

interface DetectedCategory {
  code: ThreatCategory;
  confidence: ConfidenceLevel;
}

MCP 一体化

SDK提供运输包装 示范背景协议(MCP) 自动扫描消息进行快速注射攻击.

CentureMCPCnition Transport 百分数运输

这个 CentureMCPClientTransport 包入任何 MCP 传输并截取信件, 在信件到达您的 MCP 服务器前扫描它们的安全威胁 .

基本用途

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
import { CentureClient } from "@centure/node-sdk";
import { CentureMCPClientTransport } from "@centure/node-sdk/mcp";

// Create your underlying MCP transport
const stdioTransport = new StdioClientTransport({
  command: "your-mcp-server",
  args: ["--arg1", "--arg2"],
});

// Wrap it with Centure security scanning
const secureTransport = new CentureMCPClientTransport({
  client: new CentureClient({
    apiKey: "your-api-key",
  }),
  transport: stdioTransport,
});

// Use with MCP client
const client = new Client({
  name: "your-client",
  version: "1.0.0",
});

await client.connect(secureTransport);

配置参数

所需参数

• transport (单位:千美元)Transport:基本MCP包装运输(如:StioClient Transport、SSEClient Transport)
• client (单位:千美元)CentureClient: 扫描信件的Centure API客户端实例

可选钩

• shouldScanMessage (单位:千美元)(context: ShouldScanMessageContext) => boolean | ShouldScanMessageResult:

  确定是否应该扫描特定信件。 返回时 false 或者说 { scan: false } 以跳过扫描.

  shouldScanMessage: ({ message, extra }) => {
    // Skip scanning for tool list requests
    if (message.method === "tool/list") {
      return false;
    }
    return true;
  };
  

• onAfterScan (单位:千美元)(context: OnAfterScanContext) => void | OnAfterScanResult:

  消息扫描后呼叫, 不管结果如何. 可以回来 { passthrough: true } 即使不安全,也允许信件.

  onAfterScan: ({ message, scanResult }) => {
    console.log(`Scanned ${message.method}: ${scanResult.is_safe}`);
  };
  

• onUnsafeMessage (单位:千美元)(context: OnUnsafeMessageContext) => OnUnsafeMessageResult:

  检测到不安全消息时调用 。 必须返回指定是允许还是屏蔽消息的对象 .

  onUnsafeMessage: ({ message, scanResult }) => {
    // Allow medium-confidence threats
    const isMedium = scanResult.categories.every(
      (c) => c.confidence === "medium",
    );
  
    if (isMedium) {
      return { passthrough: true };
    }
  
    // Block high-confidence threats with custom error
    return {
      passthrough: false,
      replace: {
        jsonrpc: "2.0",
        id: message.id,
        error: {
          code: -32001,
          message: "Security violation detected",
        },
      },
    };
  };
  

• onBeforeSend (单位:千美元)(context: { message: JSONRPCMessage, extra?: MessageExtraInfo }) => void:

  在通过运输发送任何信息之前已打电话.

  onBeforeSend: ({ message, extra }) => {
    console.log(`Sending ${message.method}`);
  };
  

完整示例

const secureTransport = new CentureMCPClientTransport({
  client: new CentureClient({
    baseUrl: "http://localhost:3001",
    apiKey: "your-api-key",
  }),
  transport: stdioTransport,

  shouldScanMessage: ({ message }) => {
    // Skip scanning for certain safe methods
    if (message.method === "tool/list") {
      return false;
    }
    return true;
  },

  onUnsafeMessage: ({ message, scanResult }) => {
    // Allow medium-confidence detections
    const isMedium = scanResult.categories.every(
      (c) => c.confidence === "medium",
    );

    if (isMedium) {
      return { passthrough: true };
    }

    // Block high-confidence threats
    return {
      passthrough: false,
      replace: {
        jsonrpc: "2.0",
        id: message.id,
        error: {
          code: -32001,
          message: "Unsafe Message!",
        },
      },
    };
  },
});

钩子类型

type ShouldScanMessageContext = {
  message: JSONRPCMessage;
  extra?: MessageExtraInfo;
};

type OnAfterScanContext = {
  message: JSONRPCMessage;
  extra?: MessageExtraInfo;
  scanResult: ScanResponse;
};

type OnUnsafeMessageContext = {
  message: JSONRPCMessage;
  extra?: MessageExtraInfo;
  scanResult: ScanResponse;
};

type OnUnsafeMessageResult = {
  passthrough: boolean;
  replace?: JSONRPCMessage;
};

处理错误

SDK为不同的情景提供了特定的出错分类:

import {
  CentureClient,
  BadRequestError,
  UnauthorizedError,
  PayloadTooLargeError,
  MissingApiKeyError,
} from "@centure/node-sdk";

try {
  const result = await client.scanText("content");
} catch (error) {
  if (error instanceof UnauthorizedError) {
    console.error("Invalid API key");
  } else if (error instanceof BadRequestError) {
    console.error("Invalid request:", error.message);
  } else if (error instanceof PayloadTooLargeError) {
    console.error("Image too large");
  }
}

配置

自定义获取选项

const client = new CentureClient({
  apiKey: "your-api-key",
  fetchOptions: {
    timeout: 30000,
    headers: {
      "X-Custom-Header": "value",
    },
  },
});

自定义获取执行

import fetch from "node-fetch";

const client = new CentureClient({
  apiKey: "your-api-key",
  fetch: fetch as any,
});

威胁类别

API检测到以下威胁类别:

许可证

麻省理工学院