niceappspl/silker-ai-sdk
GitHub: niceappspl/silker-ai-sdk
面向 AI Web 应用的运行时安全 SDK，通过一行代码集成即可实时检测并拦截 SQLi、XSS、Prompt Injection、SSRF 等多种攻击。
Stars: 0 | Forks: 0
# @silker-ai/agent
**专为 AI 驱动的 Web 应用提供的运行时安全防护。**
实时检测并拦截攻击 - 包括 SQLi、XSS、prompt injection、SSRF、IDOR 等。
无需修改任何业务逻辑。遥测数据将流向您的 [Silker AI 仪表盘](https://platform.silkerai.com)。
[](https://www.npmjs.com/package/@silker-ai/agent)
## 2 分钟快速入门
### 步骤 1 - 注册账号并获取您的 API key
1. 访问 [platform.silkerai.com](https://platform.silkerai.com) 并注册（免费）
2. 点击 **New Application** → 为其命名（例如 "my-saas-app"）
3. 打开 **Configuration** → 复制您的 API key：`sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`
### 步骤 2 - 安装
```
npm install @silker-ai/agent
```
### 步骤 3 - 将您的 API key 添加到环境变量中
创建或编辑 `.env.local` (Next.js) 或 `.env` (Express/Node)：
```
# .env.local
SILKER_API_KEY=sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```
### 步骤 4 - 初始化 Silker
#### Express (零配置)
```
import express from 'express';
import { initSilker, middleware } from '@silker-ai/agent';
const app = express();
app.use(express.json());
app.use(middleware()); // protects INCOMING traffic (reads SILKER_API_KEY from process.env)
await initSilker(); // additionally hooks OUTGOING fetch() (SSRF protection)
```
大功告成。设置 `SILKER_API_KEY` 后，遥测数据将流向您的仪表盘。
如果未提供 key，SDK 会记录一条警告并以仅检测模式运行
（仍然会拦截攻击，但没有遥测数据） - 它绝不会使您的应用崩溃。
您也可以进行显式配置：
```
app.use(middleware({ apiKey: process.env.SILKER_API_KEY }));
```
#### 通用 Node.js / Serverless
```
import { initSilker } from '@silker-ai/agent';
await initSilker(); // reads SILKER_API_KEY from process.env
// All outgoing fetch() calls are now monitored
```
#### Next.js（Edge `middleware.ts`）
从 v1.3.0 版本开始，Silker 通过 `@silker-ai/agent/next` 子路径提供了原生的 Next.js App Router / Edge runtime adapter：
```
// middleware.ts (project root)
import { nextMiddleware } from '@silker-ai/agent/next';
export const middleware = nextMiddleware(); // reads SILKER_API_KEY from process.env
export const config = { matcher: '/api/:path*' };
```
该 adapter 采用 fail-open 机制（绝不会破坏您的应用），以“即发即忘”的方式发送遥测数据，并应用由仪表盘管理的 feature config 以及从 ingest response 中获取的 banned IPs（使用 `remoteConfig: false` 可禁用此功能）。
或者，您仍然可以在[自定义 Express 服务器](https://nextjs.org/docs/pages/guides/custom-server)后台运行 Express 风格的 `middleware()`：
```
// server.ts
import express from 'express';
import next from 'next';
import { middleware } from '@silker-ai/agent';
const app = next({ dev: process.env.NODE_ENV !== 'production' });
const handle = app.getRequestHandler();
app.prepare().then(() => {
const server = express();
server.use(express.json());
server.use(middleware()); // reads SILKER_API_KEY from process.env
server.all('*', (req, res) => handle(req, res));
server.listen(3000);
});
```
### 步骤 5 - 验证是否生效
1. 部署您的应用（或在本地运行）
2. 向您的 API 发起请求（例如 `curl http://localhost:3000/api/test`）
3. 打开您的 [Silker AI 仪表盘](https://platform.silkerai.com/apps) → 您的应用 → **Dashboard**
4. 您应该会在几秒钟内看到请求出现
如果状态徽章显示为 **Live**（绿色） - 您已受到保护。✓
## CLI 设置向导（可选）
如果您偏好引导式设置：
```
npx @silker-ai/agent init
```
该向导将：
- 检测您的框架（Next.js、Express、Node.js）
- 询问您的 API key 并将其保存至 `.env.local`
- 展示需要添加的准确代码片段
- 如果尚未安装，则自动安装该 package
## 保护范围
**默认开启**（误报率低，对生产环境 API 安全）：
| 攻击类型 | 检测 | 拦截 |
|---|---|---|
| SQL Injection | ✓ | ✓ |
| XSS (跨站脚本攻击) | ✓ | ✓ |
| Path Traversal | ✓ | ✓ |
| Prompt Injection (LLM) | ✓ | ✓ |
| Rate Limiting / 暴力破解 | ✓ | ✓ |
| 数据泄露 (PII, API keys) | ✓ | 脱敏/拦截 |
| 恶意文件上传 | ✓ | ✓ |
| SSRF (传出 `fetch` 调用) | ✓ | 可选启用 (`blockOutgoing`) |
**可选启用**（这些选项往往会在生产环境 API 上标记正常流量，因此除非您在 `features` 中显式开启，否则它们将处于禁用状态）：
`csrfDetection`、`ssrfDetection` (传入)、`idorDetection`、`hostHeaderInjectionDetection`、`accessControlDetection`、`authenticationValidation`、`cryptographicValidation`、`vulnerableComponentsDetection`、`softwareIntegrityValidation`、`sessionAnomaliesDetection`、`thirdPartyDetection`、`complianceDetection`、`threatIntelligence`、`zeroTrustDetection`
## 高级配置（可选）
```
import { middleware } from '@silker-ai/agent';
app.use(middleware({
// apiKey defaults to process.env.SILKER_API_KEY
debug: true, // logs blocked requests to console
// Opt into advanced detectors (disabled by default):
features: {
csrfDetection: true,
idorDetection: true,
zeroTrustDetection: true,
// ... see CONFIGURATION.md for the full list and defaults
}
}));
```
### 传出请求监控（`fetch` hook）
通过 `initSilker()` 初始化时，Silker 还会监控传出的 `fetch()` 调用（包括针对内部地址 / 云元数据端点的 SSRF）。
默认情况下，这是**仅监控模式**：异常情况会报告给您的仪表盘，但绝不会拦截请求。若要主动拦截恶意的传出请求，请选择启用：
```
await initSilker({ blockOutgoing: true });
```
出站 SSRF 检查由 `outboundSsrfProtection` 功能（默认**开启**）控制。设置 `ssrfDetection: false` 也会显式禁用它。
### 客户端 IP 与代理（`trustProxy`）
默认情况下，Silker 会信任 proxy headers（`x-forwarded-for`、`x-real-ip`）来解析客户端 IP - 这在 Vercel、Cloudflare 或负载均衡器后方是必需的。
**如果您的应用不在受信任的代理之后，请设置 `trustProxy: false`** - 否则客户端可以伪造 `x-forwarded-for`，导致基于 IP 的封禁 / 速率限制变得不可靠：
```
app.use(middleware({ trustProxy: false })); // use the socket remote address
```
### 分布式速率限制（`store`）
默认情况下，Rate-limit 计数器和 IP 封禁存储在进程内存中。对于多实例部署，您可以通过实现 `SilkerStateStore` 接口的 `store` 选项接入共享存储（例如 Redis） - 接口定义和 Redis 示例请参见 [CONFIGURATION.md](./CONFIGURATION.md)。
本地内存对于同步的拦截/允许决定保持权威地位；外部存储尽力进行同步（最终一致性）。
完整选项列表：[CONFIGURATION.md](./CONFIGURATION.md)
## 工作原理
```
Your app receives a request
↓
Silker inspects it in ~0ms (heuristic, no network call)
↓
Clean request → passes through to your handler
Malicious request → blocked (403), event logged
↓
Telemetry sent async to platform.silkerai.com/api/ingest
↓
Visible in your dashboard: threats, requests, map, AI analysis
```
**故障保护：** 如果 Silker 平台不可达，您的应用将继续正常运行。被丢弃的将是安全事件（而不是您的流量）。
## 兼容性
| Runtime | 状态 |
|---|---|
| Node.js ≥ 14 | ✅ |
| Express / NestJS | ✅ |
| Next.js (自定义 Express 服务器) | ✅ |
| Next.js Edge `middleware.ts` | ✅ 通过 `@silker-ai/agent/next` (v1.3.0+) |
| Vercel / AWS Lambda | ✅ (已优化刷新) |
| Bun / Deno | ⚠️ 实验性 |
## 常见问题
**我需要修改业务逻辑吗？**
不需要。Silker 会包装您现有的请求处理器。对您的路由零修改。
**它会使我的应用变慢吗？**
检测过程在 ~0ms 内完成（基于进程内的启发式算法）。遥测数据是在响应之后异步发送的 - 绝不会阻塞您的用户。
**如果我的 API key 泄露了怎么办？**
请立即在仪表盘中重新生成（Configuration → Regenerate）。旧 key 会立即失效。
**我可以为多个应用使用多个 API key 吗？**
可以。在仪表盘中为每个项目创建单独的应用程序。每个应用程序都有各自的 key 和专属仪表盘。
**有免费层级吗？**
有。请在 [platform.silkerai.com](https://platform.silkerai.com) 创建账号。
## 支持
- 文档：[silkerai.com/docs](https://silkerai.com/docs)
- 邮箱：[support@silkerai.com](mailto:support@silkerai.com)
- 仪表盘：[platform.silkerai.com](https://platform.silkerai.com)
专有软件。© 2026 Silker AI。保留所有权利。
标签：AI应用防火墙, AppImage, CISA项目, GNU通用公共许可证, MITM代理, Node.js, Web安全, Web应用防火墙, 大模型安全, 暗色界面, 自动化攻击, 蓝队分析