noviqtechnologies/agentwall

# Vexa AgentWall Vexa AgentWall 是一个企业级默认拒绝安全网关和 LLM agent 出口代理，通过 MCP (Model Context Protocol)、HTTP、HTTPS 和 WebSocket 连接运行。它能拦截、沙箱化、审计并主动执行严格的安全策略，涵盖 AI agent 工具调用和出站 LLM API 流量，适用于开发者工作站、团队 staging 环境和生产环境集群——具备内联 DLP 扫描、OIDC 身份绑定、集中式 API Key 托管以及 HMAC 链式防篡改审计日志等功能。

官网 · 用户指南 · 文档 · 问题 · 安全

## 安装说明 AgentWall 提供灵活的安装方法，专为您的部署层级量身定制： ### 1. 开发者 / 二进制安装（独立 CLI） 将静态链接的 `agentwall` 二进制文件安装到 `~/.local/bin/agentwall`： ``` curl -fsSL https://vexasec.io/install.sh | sh ``` 或从源码构建（需要 Rust 1.89+）： ``` git clone https://github.com/noviqtechnologies/agentwall.git cd agentwall cargo build --release # Binary path: ./target/release/agentwall ``` ### 2. 团队 / Staging 安装（Docker Compose） 运行完整的自托管 Control Hub 技术栈（Go API、React UI、PostgreSQL DB）： ``` cd control-plane docker compose up -d --build ``` - **Control Hub UI:** `http://localhost:8081` - **Control Hub API:** `http://localhost:8400` ### 3. 企业级生产安装（Kubernetes & Helm） 使用官方 Helm chart 部署集中式执行集群和 Control Hub： ``` helm install agentwall ./chart \ --namespace agentwall-system \ --create-namespace \ --set gateway.tls.enabled=true \ --set dashboardApi.enabled=true \ --set dashboardDb.enabled=true \ --set dashboardFrontend.enabled=true ``` ## 架构  ### 部署层级 | 层级 | 组件 | 部署目标 | 指南与安装链接 | |------|-----------|------------------|---------------------------| | **本地 Sidecar** | Gateway + SQLite | 独立开发者工作站 (`agentwall dev`) | [二进制安装](#1-developer--binary-install-standalone-cli) · [层级 1 指南](docs/user_guide.md#tier-1-developer--workstation) | | **团队 Hub** | Gateway + Hub API + Hub UI + PostgreSQL | 团队 Staging / 共享服务器 (Docker Compose) | [Docker Compose 安装](#2-team--staging-install-docker-compose) · [层级 2 指南](docs/user_guide.md#tier-2-team--staging) | | **企业级** | Gateway 集群 + Hub API 集群 + PostgreSQL | 企业级多租户 (Kubernetes & Helm) | [Helm 生产环境安装](#3-enterprise-production-install-kubernetes--helm) · [层级 3 指南](docs/user_guide.md#tier-3-enterprise-cloud--production) | ## 快速开始 ### 1. 本地 Shadow 代理与内置仪表盘 (`agentwall dev`) **前置条件：** - **已安装 AgentWall CLI**：已在本地安装 `agentwall` 二进制文件（参见 [安装说明](#installation) 步骤 1）。 - **目标上游 MCP Server / HTTP 服务**：一个活动的本地或远程 MCP server / AI agent 服务用于代理（或使用 `--stdio` 直接包装 stdio 命令）。 - **可用的 Socket 地址**：本地端口 `127.0.0.1:8080`（或通过 `--listen` 指定自定义地址）须保持空闲，供代理和内置 Web UI 使用。 以观察模式启动 shadow 代理。这会自动在 `http://127.0.0.1:8080` 启动本地 Web UI 并打开您的浏览器： ``` agentwall dev ``` * 使用 `--no-browser` 阻止自动启动浏览器。 * 使用 `--enforce` 在无需运行完整 gateway 部署的情况下，在本地测试活动的 DLP 和策略拦截。 * 包装基于 stdio 的 MCP server： agentwall dev --stdio -- npx -y @modelcontextprotocol/server-filesystem /workspace ### 2. 路由本地 Agent 流量 在您的终端中设置标准的代理环境变量： ``` export HTTP_PROXY=http://127.0.0.1:8080 export HTTPS_PROXY=http://127.0.0.1:8080 export AGENTWALL_PROXY_URL=http://127.0.0.1:8080 python my_agent.py ``` ### 3. 包装本地 IDE (`agentwall wrap`) 自动修补 IDE 配置文件，将所有 MCP server 工具调用路由至 AgentWall： ``` # 包装 Claude Desktop agentwall wrap claude # 检查所有受支持编辑器的 IDE 状态 agentwall status ``` ### 4. 自动生成与 Lint 策略 根据观察到的 shadow 模式流量起草 YAML 安全策略并进行 lint： ``` agentwall generate-policy --decay-window 30 agentwall lint agentwall-policy.yaml ``` ## 配置 ### 策略 YAML 示例（v2 Schema） AgentWall 策略基于**默认拒绝**原则运行 (`agentwall-policy.yaml`)： ``` version: 2 default_action: deny identity_binding: oidc_discovery_url: "https://auth.corp.com/.well-known/openid-configuration" allowed_audiences: ["agentwall-gateway-prod"] group_claim: "groups" tools: - name: "read_file" action: allow credential_scope: ["file:read"] parameters: - name: "path" type: string required: true max_length: 512 validators: - path_traversal - no_sensitive_paths regex: "^/home/[a-z]+/projects/.*" deny_patterns: ["\\.ssh", "\\.env", "\\.aws"] dlp: scannable_tools: ["read_file", "execute_command"] safe_tools: ["list_directory"] patterns: - name: "aws_access_key" regex: "AKIA[0-9A-Z]{16}" action: block - name: "credit_card" regex: "\\b\\d{4}[- ]?\\d{4}[- ]?\\d{4}[- ]?\\d{4}\\b" action: redact spend: max_tokens_per_session: 100000 max_concurrent_sessions: 10 loop_detection: threshold: 3 action: PivotError audit: log_file: "/var/log/agentwall/audit.jsonl" siem_export: type: "splunk_hec" endpoint: "https://splunk.corp.com:8088/services/collector/event" token: "${SPLUNK_HEC_TOKEN}" ``` ### 环境变量 | 变量 | CLI 命令 | 描述 | 默认值 | |---|---|---|---| | `HTTP_PROXY` / `HTTPS_PROXY` | `dev`, client | 标准 HTTP 代理路由 URL | - | | `AGENTWALL_LISTEN` | `start`, `dev` | Gateway 监听 socket 地址 | `127.0.0.1:8080` | | `AGENTWALL_POLICY_PATH` | `start` | YAML 策略文件的路径 | - | | `DASHBOARD_API_URL` | `start`, proxy | Control Hub API endpoint URL | - | | `POLICY_READ_SECRET` | `start` | 用于策略热重载 SSE 的共享密钥 | - | | `GATEWAY_SECRET` | `start` | 用于遥测数据发布的共享密钥 | - | | `AGENTWALL_LOG_PATH` | `start` | 持久化审计日志文件的路径 | `audit.log` | | `AGENTWALL_OIDC_ISSUER` | `start` | 用于身份绑定的 OIDC issuer URL | - | | `AGENTWALL_SIEM_BACKEND` | `start` | SIEM 后端 (`splunk`, `datadog`, `opensearch`, `local`) | `local` | | `AGENTWALL_SIEM_ENDPOINT` | `start` | SIEM 摄取 URL | - | | `AGENTWALL_SIEM_TOKEN` | `start` | SIEM 身份验证 token | - | | `AGENTWALL_SHADOW_MODE` | `start` | 观察模式（仅记录不拦截） | `false` | | `AGENTWALL_DRY_RUN` | `start` | 仅记录策略违规，不拒绝调用 | `false` | | `AGENTWALL_STRICT_CREDENTIAL_SCOPE` | `start` | 凭据范围不匹配时返回 403 拒绝 | `false` | | `AGENTWALL_TLS_CERT` | `start` | TLS 证书 PEM 文件的路径 (`rustls`) | - | | `AGENTWALL_TLS_KEY` | `start` | TLS 私钥 PEM 文件的路径 (`rustls`) | - | ## 用户指南与文档链接 有关详细的分步文档、架构规范和高级部署指南，请查阅我们的文档库： - 📖 **[Vexa AgentWall 详细用户指南](docs/user_guide.md)** — 涵盖部署层级、v2 策略创建、DLP 调优、OIDC 身份绑定、Control Hub 设置、审计验证和故障排除的综合指南。 - 📚 **[文档中心](docs/index.md)** — 核心文档索引与功能概述。 - 🛠️ **[全面功能操作演示](docs/comprehensive_guide.md)** — 面向开发者的基于场景的命令操作演示。 ## 许可证 版权所有 © [NoviqTech](https://vexasec.io)。基于 [Apache License 2.0](LICENSE) 获得许可。

标签：AI代理网关, Rust, 出向代理, 可视化界面, 子域名突变, 安全防护, 日志审计, 测试用例, 网络流量审计, 请求拦截, 通知系统