norviq-dev/norviq

Norviq 是一个位于 AI agent 推理循环与其可调用工具之间的策略执行点 (PEP)。每个工具调用都会被拦截，并根据限定于该工作负载 Kubernetes/SPIFFE 身份的 OPA/Rego 策略进行评估，然后在工具运行之前决定是**允许、拦截、上报还是审计**。它将“模型决定调用 `execute_sql` / `send_email` / `shell`”从一种隐式信任转变为一种强制的、基于特定身份的、可审计的决策。 ## 为什么需要 LLM agent 被赋予了真实的工具——数据库、shell、邮件、云 API 以及内部服务。模型会在运行时选择调用哪一个，而仅仅一次 prompt 注入或推理错误，就可能将一个无害的 agent 变成数据泄露或破坏的路径。Norviq 在这个攻击面上设置了一个确定性的、基于策略的关卡，因此只有当该 agent 身份的明确策略允许时，工具调用才会执行。 ## 工作原理 每个工具调用在执行之前都会在引擎中进行一次往返： ``` sequenceDiagram autonumber participant Agent as Agent (LangGraph / SDK) participant PEP as Norviq sidecar / SDK participant Engine as Norviq API / engine participant OPA as OPA / Rego Agent->>PEP: tool call — {tool, params, identity} PEP->>Engine: POST /evaluate Note over Engine: resolve SPIFFE identity
collect policy tiers + overlays Engine->>OPA: evaluate OPA-->>Engine: decision Engine-->>PEP: allow / block / escalate / audit
+ rule_id + reason PEP-->>Agent: enforced decision Engine->>Engine: audit log · trust score · asset/attack graph ``` - **拦截** — 注入的 sidecar（或 SDK）将每个工具调用转发到引擎的 `/evaluate`。 - **身份** — 决策被限定为调用工作负载的 SPIFFE 身份（SPIRE SVID），而不是共享密钥，因此策略是基于 agent 类别和 namespace 的。 - **策略** — Rego 策略按层级划分（agent 类别 → namespace 基准 → cluster 基准），并带有“仅允许收紧”的覆盖规则；最严格且匹配的规则将最终生效。 - **模式** — `block`（拒绝并给出原因）、`escalate`（上报）、`audit`（仅记录 / 监控模式），因此你可以在正式启用前，以可观测的方式推行执行策略。 ### 部署组件 ``` flowchart LR subgraph tenant["Agent namespace"] pod["Agent pod
+ Norviq sidecar (PEP)"] end subgraph norviq["norviq namespace"] api["API
+ OPA sidecar"] engine["Engine
+ OPA sidecar"] pg[("PostgreSQL")] redis[("Redis")] ui["Console UI"] webhook["Admission
webhook"] end pod -->|POST /api/v1/evaluate| api api --> pg api --> redis engine --> pg engine --> redis webhook -. injects sidecar .-> pod webhook -. syncs NrvqPolicy/NrvqClass .-> api ui --> api ``` API 和 Engine 都会针对它们各自的 OPA sidecar（每个副本一个 OPA，绑定到 `127.0.0.1`）进行**进程内**评估——两者互不代理。在默认的注入模式（`webhook.injection.sidecarMode: proxy`）下，被注入的 sidecar 会将每个工具调用 POST 到中央 API，因此 Postgres、Redis 和策略加载都保持集中化，不会在单个 pod 中进行评估。Engine Deployment 将同样的评估器作为独立的 cluster 工作负载运行（`NRVQ_SIDECAR_MODE=embedded`，通过 `norviq-engine:8282` 暴露），供希望在不经过 API 的情况下直接进行评估的调用方使用。 ## 兼容你的 agent 框架 上文的 sidecar 是零代码修改的。如果你需要进程内拦截——即不使用 sidecar，而是用你自己的事件循环——SDK（`norviq/sdk/`）会包装这些框架的工具调用点，使得 block/escalate 决策能在工具运行前抛出。请参阅 **[docs/guides/integrating-agents.md](docs/guides/integrating-agents.md)** 了解配置和代码片段。 - **LangChain** — `norviq.sdk.langchain.adapter.protect(tools, interceptor)` - **LangGraph** — `norviq.sdk.langgraph.adapter.GuardedToolNode(tools, interceptor)` - **CrewAI** — `norviq.sdk.crewai.adapter.protect(tools, interceptor)` - **AutoGen** — `norviq.sdk.autogen.adapter.protect(tools, interceptor)` - **Azure / Semantic Kernel** — `norviq.sdk.semantic_kernel.adapter.policy_filter(interceptor)` **[`examples/chatbot/`](examples/chatbot/)** 是一个可运行的 LangChain/LangGraph chatbot（Groq），在其中由真实的模型决定工具调用，而 Norviq 会在危险操作运行前将其拦截——内附 `Dockerfile` 和 `k8s/` 清单文件，用于在 cluster 内通过注入的 sidecar 运行。 ## 功能特性 - **策略执行** — 针对每次工具调用评估 OPA/Rego，亚秒级响应，默认失败即拒绝。 -**Kubernetes 原生** — 包含 `NrvqPolicy` / `NrvqClass` / `NrvqConfig` CRD，用于注入执行 sidecar 的 mutating webhook，以及一个 Helm chart。 - **工作负载身份** — 支持 SPIFFE/SPIRE SVID（并为非 SPIRE cluster 提供了 mock 模式）。 - **控制台 UI** — 提供策略目录与编辑器、攻击图、资产图、agent 信任度以及审计流。 - **红队测试套件** — 内置对抗性测试（如 prompt 注入、编码/嵌套绕过、SQLi、PII/PCI 数据窃取），用于证明策略确实起到了拦截作用。 - **合规性映射** — 覆盖 MITRE ATLAS 和 OWASP LLM Top-10，并提供“生成执行策略”的修复方案。 - **高可用性** — 支持多副本，具备跨副本策略传播和 DB 权威删除；为多节点 cluster 提供 HPA/PDB/反亲和性。 - **多集群管理** — 支持在中心集群与边缘集群间分发已签名的策略包。 ## 快速开始 **前置条件：** 一个 Kubernetes 集群 (1.30+)、`kubectl` 以及 Helm 3。 ``` git clone https://github.com/norviq-dev/norviq.git cd norviq # 1. 安装 CRDs kubectl apply -f helm/norviq/crds/ # 2. 安装 Norviq（默认从 ghcr.io/norviq-dev 拉取 public images） kubectl create namespace norviq helm install norviq ./helm/norviq -n norviq \ --set 'policyQuotaNamespaces={default}' \ --set config.dbSslMode=disable # the bundled Postgres has no TLS; omit if you point at an external TLS DB ``` `policyQuotaNamespaces` 是将要运行 agent 的租户 namespace 列表——它是**必填的**，而非可选项。该 chart 会为每个条目安装一个失败即拒绝的 `strict` namespace 基准，因此如果列表为空，出于安全设计会导致安装失败，而不是在集群中留下没有基准防护的状态。请添加你计划使用的每一个 agent namespace。 该 chart 会部署 API、Engine、控制台 UI、mutating webhook 以及内置的 PostgreSQL + Redis + OPA。 使用端口转发访问控制台： ``` kubectl -n norviq port-forward svc/norviq-ui 8080:80 # 打开 http://localhost:8080 ``` 以 `admin` 身份登录。Chart 在安装时会生成一个随机的初始密码（只有当你自己设置了 `auth.adminPassword` 时，它才会使用字面量密码）——请读取出该密码，并在控制台提示时进行修改： ``` kubectl get secret norviq-secrets -n norviq -o jsonpath='{.data.NRVQ_AUTH_ADMIN_PASSWORD}' | base64 -d ``` Sidecar 注入默认是**关闭**的（`webhook.injection.enabled: false`）。请将其开启，然后为你刚才在 `policyQuotaNamespaces` 中列出的 namespace 添加标签——在 webhook 启用之前，单靠标签是没有任何作用的： ``` helm upgrade norviq ./helm/norviq -n norviq --reuse-values --set webhook.injection.enabled=true kubectl label namespace norviq-injection=enabled ``` 随后，带有该标签的 namespace 中每一个新建的 pod 都会被注入执行 sidecar。 ## 文档 完整文档请访问 **[docs.norviq.dev](https://docs.norviq.dev)**： - **[快速开始](https://docs.norviq.dev/getting-started/)** — 安装、首次登录、sidecar 注入、首条策略 - **[核心概念](https://docs.norviq.dev/concepts/)** — agent 类别、策略层级、执行模式、信任评分、SPIFFE 身份 - **[编写策略](https://docs.norviq.dev/guides/writing-policies/)** — Rego 契约、包、仅允许收紧的覆盖规则、校验 - **[策略手册](https://docs.norviq.dev/guides/policy-cookbook/)** — 可复制粘贴的 `NrvqPolicy` 方案 + 经过验证的 Rego 构建块 - **[资产与攻击图](https://docs.norviq.dev/guides/graphs/)** — 真实可达性、攻击链、模拟、防御、工具分类 - **[合规性与覆盖率](https://docs.norviq.dev/guides/compliance/)** — MITRE ATLAS / OWASP LLM 覆盖率、缺口、修复方案、证据包 - **[集成 Agent](https://docs.norviq.dev/guides/integrating-agents/)** — SDK 支持：LangChain, LangGraph, CrewAI, AutoGen, Semantic Kernel - **[CLI 参考](https://docs.norviq.dev/cli/)** — `norviq login`、策略、审计、agent、红队、集群舰队 - **[配置指南](https://docs.norviq.dev/configuration/)** — Helm `values.yaml` 参考 - **[部署说明](https://docs.norviq.dev/deployment/)** — 生产级高可用、云平台 (AKS / EKS / GKE) 及多集群管理 - **[安全模型](https://docs.norviq.dev/security-model/)** — 信任边界与威胁模型 可运行的示例位于 [`examples/`](examples/) 目录下；工程参考文档位于 [`docs/engineering/`](docs/engineering/) 目录下。 ## 开发指南 ``` pip install -e ".[dev]" # backend + test tooling make test # pytest tests/ make lint # ruff check norviq/ tests/ ``` 控制台测试套件位于 `ui/` 目录下，可通过 `npm test` (vitest) 运行。随附的 Rego 使用的是 v0 语法，因此其测试套件需要加上兼容性标志： ``` opa test --v0-compatible webhook/presets/ comprehensive.rego ``` 技术栈方面，引擎使用 Python (FastAPI) + OPA/Rego，控制台使用 React + Vite (TypeScript)，准入 webhook 使用 Go。详情请参阅 **[CONTRIBUTING.md](CONTRIBUTING.md)**。 ## 安全准则 发现了安全漏洞？请遵循 **[SECURITY.md](SECURITY.md)** 中的协调披露流程——切勿针对安全报告公开提交 issue。 ## 开源协议 [Apache 2.0](LICENSE)。

标签：DLL 劫持, Lerna, OPA/Rego, Streamlit, 人工智能安全, 合规性, 大语言模型, 子域名突变, 搜索引擎查询, 日志审计, 测试用例, 策略执行, 访问控制, 逆向工具