nemesis-shield

Nemesis Shield - SDK

Nemesis Shield 的官方开源 SDK——统一的运行时安全平台（应用/API/LLM 防护、遥测关联、网络/DNS、响应和合规）。在应用中接入其中一个，Nemesis 就会学习应用的正常行为，然后标记任何偏离行为，并在强制执行模式下加以阻止。这是一种正向安全（允许列表）模型：它不猜测通用攻击特征，而是强制执行 “此应用只会以这些方式运行。”

正在使用 AI 助手构建应用？ 有两种方式可以让 Agent 在构建过程中添加 Nemesis Shield：

1. MCP 服务 - 为 Cursor、Claude Code/Desktop 和 Windsurf 提供 17 个可调用工具 （nemesis_protect、nemesis_scan、nemesis_explain，以及 Omniguard 欺诈评分和通过 nemesis_omniguard_verify 进行的独立身份/AML 筛查），让 Agent 无需离开编辑器即可添加安全防护、扫描网站、 筛查身份并说明覆盖范围。
2. AI 编辑器规则包（AGENTS.md、Cursor、Windsurf、Claude Code）- 可直接使用的规则， 指示 Agent 默认添加单行 SDK。

每种技术栈都只需一行，并且默认安全（观察模式）。完整的已验证参考： ai-rules/AGENTS.md。

隐私设计至上： SDK 只发送行为元数据——HTTP 方法、路径的形态（/orders/123 → /orders/{int}）、状态码，以及调用方是否通过身份验证。它们绝不会发送请求正文、响应、机密或源代码。所有 SDK 都采用故障时放行机制：如果无法连接 Nemesis，应用将完全不受影响。

正在开发新应用？使用 Nemesis Learn 几分钟内完成学习。 接入 SDK（观察模式）， 然后运行一条命令，让 Agent 在开发/暂存环境中测试应用的每条路由——端点、 表单、上传、CRUD 流程——无需等待真实流量即可完成基线学习。它与语言和框架无关（通过 HTTP 驱动应用）， 可离线运行，也可以读取代码库以查找路由，并报告覆盖情况，让控制台准确显示何时可以开始强制执行。

npx @nemesis-shield-autogon/learn --target http://localhost:3000 --app-token nsk_… --repo .

语言	软件包	集成方式
Node.js	@nemesis-shield-autogon/sentinel	单行 Express/Connect 中间件 → node/
Python	nemesis-shield	ASGI/WSGI 中间件（FastAPI/Starlette/Flask）→ python/
Go	github.com/eobi/nemesis_shield_sdks/go	net/http 中间件 → go/
Ruby	nemesis_shield.rb	Rack 中间件（Rails/Sinatra）→ ruby/
PHP	composer require nemesislabs/sentinel	Laravel 自动发现 / register_shutdown_function → php/
WordPress	可直接安装的插件	行为防火墙（前端、REST 和 admin-ajax）+ 暴力破解锁定、恶意软件/文件完整性扫描和漏洞警报 → wordpress/
Java	io.github.eobi:sentinel	Servlet 过滤器 / Spring Boot（JDK 11+）→ java/
.NET / C#	dotnet add package NemesisShield	ASP.NET Core 中间件（net8.0 + netstandard2.0）→ dotnet/
Rust	cargo add nemesis-shield	axum（tower）/ actix-web 中间件 → rust/
边缘 / Supabase（Deno TS）	@nemesis-shield-autogon/edge（npm）· @nemesis-shield/edge（JSR）	用于 Supabase Edge / Deno / CF Workers / Vercel Edge / Next.js 的 withShield() → edge/
Supabase 直接数据库 API	Cloudflare Worker	保护 supabase.from()（PostgREST）的反向代理——在请求到达数据库前阻止偏离基线的表/操作/身份验证请求 → cloudflare-supabase-proxy/

前端（浏览器）

上述后端 SDK 可保护服务器。浏览器 SDK 保护另一半——WAF 和后端都看不到的客户端攻击。专为支付 / 电商页面打造，达到结账级别：它可阻止银行卡信息窃取通过所有渠道外传数据（fetch、XHR、beacon、image beacons、WebSocket、EventSource）、Magecart / 注入脚本和表单劫持；检测内联篡改、字段注入和点击劫持；并直接映射到 PCI DSS 4.0.1 §6.4.3 & §11.6.1（脚本清单、授权、篡改告警）。可在控制台中审核并批准学习到的 CSP。

前端	包	集成方式
React · Angular · Vue · jQuery · plain JS	@nemesis-shield-autogon/browser	添加一个 <script data-token> 标签，或使用 NemesisShield.init({token}) → browser/

一个 SDK 覆盖所有框架——它们都使用相同的浏览器基础功能。

使用 TypeScript？ 没有单独的 TS SDK——TypeScript 使用的就是这些运行时。Node 后端使用 @nemesis-shield-autogon/sentinel（附带 .d.ts），Supabase Edge / Deno / Workers 使用 edge/，TS 前端使用 @nemesis-shield-autogon/browser（附带 .d.ts）。

获取令牌

1. 在 shield.nemesislabs.xyz 注册（免费，无需银行卡）。
2. 保护一个应用——你会获得一个一次性安装令牌（nsk_…）。
3. 添加下方的 SDK，设置令牌，然后部署。流量会立即开始构建每个应用的基线；在控制台中查看学习到的行为并批准或阻止它们。

快速开始

Node.js

npm install @nemesis-shield-autogon/sentinel

import { sentinel } from "@nemesis-shield-autogon/sentinel/express";
app.use(sentinel({ token: process.env.NEMESIS_TOKEN })); // one line, zero route changes

Python

pip install nemesis-shield

from nemesis_shield.asgi import SentinelMiddleware
app.add_middleware(SentinelMiddleware, token=os.environ["NEMESIS_TOKEN"])

Go

handler := nemesis.Middleware(os.Getenv("NEMESIS_TOKEN"))(mux)
http.ListenAndServe(":8080", handler)

Ruby（Rack）

use NemesisShield::Middleware, token: ENV["NEMESIS_TOKEN"]

PHP - composer require nemesislabs/sentinel（Laravel 会自动发现中间件；原生 PHP：）

NemesisShield::guard(getenv('NEMESIS_TOKEN'));                                        // block off-baseline
register_shutdown_function(fn() => NemesisShield::observe(getenv('NEMESIS_TOKEN'))); // learn

WordPress - 完整的安全插件：AI 行为防火墙，以及防暴力破解登录锁定、恶意软件 / 文件完整性扫描和漏洞告警。将 wordpress/nemesis-shield/ 插件放入 wp-content/plugins/，启用插件并设置令牌：

// wp-config.php
define('NEMESIS_SHIELD_TOKEN', 'nsk_your_site_token');

Java - Maven Central 上的 io.github.eobi:sentinel（Spring Boot 过滤器，或原生方式：）

import io.github.eobi.sentinel.NemesisShield;
var nemesis = new NemesisShield(System.getenv("NEMESIS_TOKEN"));
if (nemesis.guard(method, path, authed, exchange)) return;   // block off-baseline (403)
nemesis.observe(method, path, authed, status);               // learn

.NET / C# - dotnet add package NemesisShield（net8.0 + netstandard2.0 / .NET Framework 4.6.1+）

// Program.cs - register FIRST (before UseRouting) so it inspects every request, incl. unmatched paths
app.UseMiddleware<NemesisShield.SentinelMiddleware>();   // set NEMESIS_TOKEN in env

Rust（axum / actix - 中间件请参阅 rust/）

let shield = nemesis_shield::Client::new(std::env::var("NEMESIS_TOKEN").unwrap_or_default());
// .layer(middleware::from_fn_with_state(shield.clone(), shield_mw))

Edge（Deno / Cloudflare Workers / Vercel Edge / Supabase / Next.js 中间件）- npm i @nemesis-shield-autogon/edge 或 deno add jsr:@nemesis-shield/edge

import { withShield } from "@nemesis-shield-autogon/edge";
// wraps any Web-standard (Request) => Response; same line on every edge runtime:
Deno.serve(withShield(handler, { token: Deno.env.get("NEMESIS_TOKEN") }));   // Supabase/Deno
// Cloudflare: export default { fetch: (req, env) => withShield(handler, { token: env.NEMESIS_TOKEN })(req) };

执行机制（所有 SDK）

每个 SDK 都是原生实现：它会在本地计算保护隐私的请求形态，缓存编译后的策略，并在处理程序运行前于进程内做出阻止决策——无需代理、无需 sidecar、无需逐请求往返。

1. 观察（默认）- SDK 记录每个请求的形态，并构建每个应用的基线。
2. 批准 - 在控制台中查看学习到的行为；批准合法行为（学习窗口期间会自动批准）。
3. 执行 - 在控制台中将应用切换为执行模式。不符合已批准基线形态的请求会被阻止，并返回 403 blocked_by_nemesis_shield，同时报告为发现项。无需重新部署——后台轮询器会获取模式变更（PHP 会刷新短 TTL 策略缓存）。

已在 8 种语言 / 约 20 个框架中完成端到端验证（学习 → 执行 → 攻击，实际阻止）：Python（FastAPI/Flask/Django）、Node（Express/Fastify/Koa）、Go（net/http/Chi/Gin/Echo）、Ruby（Rails/Sinatra/Rack）、PHP（raw/Laravel/Symfony）、Java（Servlet/Spring Boot）、.NET（ASP.NET Core）、Rust（axum/actix）。合法流量正常通过；身份验证绕过、BOLA、路径遍历和扫描器探测均会被阻止。

LLM 防护

Node 和 Python SDK 还会报告 LLM 交互，以提供 OWASP-LLM-Top-10 行为防护 （提示注入、越狱、系统提示词泄露、未授权工具调用、敏感输出）。只存储检测标签和数据结构，不会存储原始提示词或响应。

import { reportLLM } from "@nemesis-shield-autogon/sentinel";
await reportLLM(token, { prompt, system, response, tools, allowedTools: ["search"] });

---

仓库指南（维护者适用）

以上内容面向使用 SDK 的开发者。本节面向转交后维护本仓库的开发者。每种语言的 SDK 都是独立的手写实现，行为保持字节级一致（相同的请求结构、策略模型和内嵌的 LLM-Guard 权重），因此各语言之间没有共享的构建步骤：请在各自目录中使用对应生态系统的原生工具开发、测试和发布。

仓库布局

node/        Node/JS SDK  -> npm  @nemesis-shield-autogon/sentinel  (Express/Fastify/Koa + /llm)
python/      Python SDK   -> PyPI nemesis-shield                    (ASGI/WSGI + provider wrappers)
go/          Go SDK       -> go   github.com/eobi/nemesis_shield_sdks/go
ruby/        Ruby SDK     -> gem  nemesis-shield
php/         PHP SDK      -> Packagist nemesislabs/sentinel         (Laravel auto-discovery)
java/        Java SDK     -> Maven Central io.github.eobi:sentinel
dotnet/      .NET SDK     -> NuGet NemesisShield
rust/        Rust SDK     -> crates.io nemesis-shield
edge/        Edge/Deno TS -> npm @nemesis-shield-autogon/edge · JSR @nemesis-shield/edge
browser/     Browser SDK  -> npm @nemesis-shield-autogon/browser   (Page Shield / anti-Magecart)
wordpress/   WordPress plugin (drop-in)
cloudflare-supabase-proxy/  Worker that guards supabase.from() / PostgREST

mcp/         MCP server (17 tools: nemesis_protect, nemesis_scan, nemesis_omniguard_verify, ...)
learn/       @nemesis-shield-autogon/learn - the baseline traffic driver
ai-rules/    Editor rule packs (AGENTS.md, Cursor, Windsurf, Claude Code)
create-nemesis-app/  scaffolder
demo/ examples/       runnable samples
e2e/         live over-the-wire tests (learn -> enforce -> attack) across every language

每种语言的目录都包含自己的 README，其中介绍了特定框架的设置方式。使用任何 SDK 前，请先查看对应的 README。

前置条件

只安装你要修改的 SDK 所需的工具链：Node 18+（node/edge/browser/mcp/learn）、Python 3.9+（python）、Go 1.21+（go）、Ruby 2.7+（ruby）、PHP 7.2+ 和 Composer（php）、JDK 11+ 和 Maven（java）、.NET 8 SDK（dotnet）、稳定版 Rust（rust）。

开发、测试和发布

在 SDK 的目录中使用其原生命令操作。常见流程如下：

SDK	安装 / 构建	测试	发布
Node · Edge · Browser	npm install	npm test	npm publish --access public
Python	python -m build	pytest	twine upload dist/*
Go	go build ./...	go test ./...	git tag（模块通过标签使用）
Ruby	gem build *.gemspec	rake test	gem push *.gem
PHP	composer install	composer test	打标签 -> Packagist 自动同步
Java	mvn package	mvn test	mvn deploy（Central）
.NET	dotnet build	dotnet test	dotnet pack + dotnet nuget push
Rust	cargo build	cargo test	cargo publish

发布需要凭据。请从团队机密存储中获取注册表令牌（npm、PyPI、Maven Central、NuGet、crates.io、RubyGems），切勿从本仓库获取。mcp/ 服务有自己的发布流程（npm + MCP 注册表 + Smithery）；请参阅 mcp/README.md。

跨语言约定（不得偏离）

任何行为变更都必须在每个 SDK 中一致实现。约束如下：

• 默认数据接收端点：POST https://shield.nemesislabs.xyz/api/v1/sketches（LLM：/api/v1/llm）， 可通过 NEMESIS_ENDPOINT / endpoint 选项覆盖。
• 身份验证：Authorization: Bearer nsk_…。
• 模式：observe（默认）-> enforce，在控制台中切换；SDK 会在后台刷新编译后的策略，无需重新部署。
• 被拦截的请求：HTTP 403，响应为 {"error":"blocked_by_nemesis_shield", ...}。
• 紧急放行列表（永不拦截）：/login /signin /sign-in /auth /oauth /session /wp-login.php /wp-admin，可通过 NEMESIS_SHIELD_BOOTSTRAP 覆盖。
• 仅请求结构：方法、规范化路径（/orders/123 -> /orders/{int}）、查询参数结构（名称 + 类型，绝不包含参数值）、身份验证标记、状态码。绝不包含请求正文或机密信息。
• LLM-Guard 权重（ml_weights.json）以字节级一致的形式嵌入，并使用 Ed25519 签名；可通过 refreshModel() 使用固定的公钥热切换。

每个 SDK 都会故障时默认放行：如果服务无法访问，应用不受影响。请保持这一特性。

修改任何 SDK 后

运行对应语言的测试，然后运行相关的 e2e/ 场景（通过网络实际执行 learn -> enforce -> attack）。未通过 e2e 测试的 SDK 不得发布。

许可证

MIT © Autogon Inc. - 可在任何项目中自由使用。

覆盖范围与安全解锁（所有 SDK）

每个后端 SDK 都挂载在最外层，因此能检测所有路由（攻击可能来自任何路径，而不只是 API）；请求结构现在还包含查询参数结构——仅记录名称和类型，绝不记录值——因此可以捕获已知路由上的参数篡改、注入参数和类型异常，而不只是未知路径。路径遍历片段会规范化为 {traversal}。

每条路由都受强制执行保护，并设有紧急绕过机制：登录／身份验证路径永远不会被拦截，因此仍在学习基线的系统不会把你锁在外面。默认值：/login /signin /sign-in /auth /oauth /session /wp-login.php /wp-admin。按应用覆盖：

export NEMESIS_SHIELD_BOOTSTRAP="/login,/admin,/healthz"

已通过实时网络传输测试验证所有 SDK：正常流量（包括同一路由的参数值变化和参数顺序互换）均可通过；未知路径、注入／篡改参数、方法和身份验证异常，以及 100 多种 CVE 模式探测（路径遍历、LFI/RFI、Log4Shell、Spring4Shell、Actuator、PHPUnit/Ignition RCE、ViewState、PostgREST 表枚举、原型污染、NoSQL、SSTI……）均会被拦截。