# AegisGate

> A Claude skill from ax128/AegisGate.

- **Type:** Skill
- **Install:** `agentstack add skill-ax128-aegisgate-aegisgate`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ax128](https://agentstack.voostack.com/s/ax128)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ax128](https://github.com/ax128)
- **Source:** https://github.com/ax128/AegisGate
- **Website:** https://github.com/ax128/AegisGate

## Install

```sh
agentstack add skill-ax128-aegisgate-aegisgate
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# AegisGate Agent Skill

> **What is this document?** This is an agent-executable skill document for AegisGate — an open-source LLM security gateway. It walks through installation, startup, token registration, upstream configuration, and client integration on a fresh machine.

本技能文档给 Agent 直接使用，目标是：在一台新机器上完成 AegisGate 的安装、启动、注册 token 或配置直连上游、以及客户端接入配置。

## 0) What does AegisGate do? 先读项目要点（必须）

- AegisGate 是 LLM 安全网关：请求侧脱敏/清洗，响应侧检测/自动净化（auto-sanitize）；`responses` 结构化 `input`（含 function/tool 输出）也会在转发上游前做脱敏。
- **两种路由模式**（可同时启用）：
  - **Token 路由**（推荐多租户场景）：每个 token 绑定独立的上游地址；注册/管理 token 时需提供网关密钥。
    - v1（LLM）：`http://:18080/v1/__gw__/t//...`
    - v2（通用 HTTP 代理）：`http://:18080/v2/__gw__/t/`，须携带 `x-target-url: ` 请求头；且目标主机须在 `AEGIS_V2_TARGET_ALLOWLIST` 白名单内（默认空＝拒绝全部目标，fail-closed）
  - **直连上游**（单用户/Agent 快速接入）：设置 `AEGIS_UPSTREAM_BASE_URL=` 后，可直接请求 `/v1/...`，无需注册 token。`v2` 仍必须使用 token 路径。
- **脱敏豁免字段（whitelist_key）**：注册 token 时可指定逗号分隔的字段名列表（如 `api_key,secret,token`）。请求体中这些字段的值**不做 PII 脱敏**，直接透传到上游。适用于需要原始凭证通过的场景。支持以下匹配模式：
  - JSON：`"field":"value"` 或 `"field": "value"`
  - 等号赋值：`field=value`
  - 冒号赋值：`field:value`
  - URL 查询参数：`?field=value`
- 管理接口（`/__gw__/register|lookup|unregister|add|remove`）应只允许内网/管理机访问。

## 1) What are the prerequisites? 环境检查

```bash
uname -a
cat /etc/os-release
which docker || true
which docker-compose || true
git --version || true
python3 --version || true
```

## 2) How to install Docker? 如果没有 Docker：先安装（Ubuntu/Debian）

```bash
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo $VERSION_CODENAME) stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker
docker --version
docker compose version
```

可选（免 sudo）：

```bash
sudo usermod -aG docker "$USER"
newgrp docker
```

## 3) How to get the source code? 获取源码

### 3.1 Git 方式

```bash
git clone https://github.com/ax128/AegisGate.git
cd AegisGate
```

### 3.2 已有源码目录

```bash
cd /path/to/AegisGate
```

## 4) How to start AegisGate with Docker? 推荐安装方式

```bash
docker network create cliproxyapi_default || true
docker network create sub2api-deploy_sub2api-network || true
docker compose up -d --build
docker compose ps
docker compose logs -f aegisgate
```

说明：仓库自带 `docker-compose.yml` 默认引用上述 external networks；如果你的环境不需要这些上游网络，需先覆盖或移除对应 network 挂载，再启动。

健康检查：

```bash
curl -sS http://127.0.0.1:18080/health
```

就绪检查（readiness，可选）：

```bash
curl -sS http://127.0.0.1:18080/ready
```

## 5) How to run without Docker? 源码本地运行

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
python -m pip install -e .
uvicorn aegisgate.core.gateway:app --host 127.0.0.1 --port 18080
```

## 6) How to connect upstream LLM providers? 接入方式选择

### 6.1 What is token routing? Token 路由（多租户，推荐）

注册上游并生成 token：

```bash
# gateway_key 从 cat config/aegis_gateway.key 获取
curl -X POST http://127.0.0.1:18080/__gw__/register \
  -H "Content-Type: application/json" \
  -d '{"upstream_base":"https://your-upstream.example.com/v1","gateway_key":""}'
```

期望返回：

```json
{
  "token": "Ab3k9Qx7Yp",
  "baseUrl": "http://127.0.0.1:18080/v1/__gw__/t/Ab3k9Qx7Yp",
  "whitelist_key": []
}
```

注册时可附带脱敏豁免字段（如 `api_key` 字段值不做脱敏）：

```bash
curl -X POST http://127.0.0.1:18080/__gw__/register \
  -H "Content-Type: application/json" \
  -d '{"upstream_base":"https://your-upstream.example.com/v1","gateway_key":"","whitelist_key":["api_key","secret"]}'
```

### 6.2 What is direct upstream mode? 直连上游（单用户/Agent 快速接入）

在 `config/.env` 中设置：

```env
AEGIS_UPSTREAM_BASE_URL=https://your-upstream.example.com/v1
```

重启后直接请求 `/v1/...`，无需注册 token。`/v2/...` 不支持直连模式，仍需使用 `/v2/__gw__/t//...`：

```bash
curl -X POST http://127.0.0.1:18080/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer " \
  -d '{"model":"gpt-4.1-mini","input":"hello"}'
```

## 7) How to verify the gateway is working? 验证调用

### Token 路由

```bash
curl -X POST "http://127.0.0.1:18080/v1/__gw__/t//responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer " \
  -d '{"model":"gpt-4.1-mini","input":"hello"}'
```

### 直连上游

```bash
curl -X POST "http://127.0.0.1:18080/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer " \
  -d '{"model":"gpt-4.1-mini","input":"hello"}'
```

## 8) How to configure AI agents and clients? 客户端配置模板

### Token 路由

```yaml
provider: openai_compatible
base_url: http://127.0.0.1:18080/v1/__gw__/t/
api_key: 
model: gpt-4.1-mini
```

### 直连上游

```yaml
provider: openai_compatible
base_url: http://127.0.0.1:18080/v1
api_key: 
model: gpt-4.1-mini
```

说明：
- 若客户端默认流式输出，网关会处理 `[DONE]` 断流恢复。
- 直连模式下不需要 `base_url` 携带 token 路径段。

## 9) How to manage tokens and the gateway? 常用管理命令

查看 token（按 `upstream_base` 查询已注册项）：

```bash
curl -X POST http://127.0.0.1:18080/__gw__/lookup \
  -H "Content-Type: application/json" \
  -d '{"upstream_base":"https://your-upstream.example.com/v1","gateway_key":""}'
```

删除 token：

```bash
curl -X POST http://127.0.0.1:18080/__gw__/unregister \
  -H "Content-Type: application/json" \
  -d '{"token":"","gateway_key":""}'
```

查看所有 token（最稳妥：直接读本机映射文件）：

```bash
cat config/gw_tokens.json
```

通过 UI API 查看所有 token（`GET /__ui__/api/tokens` 不是 `X-Gateway-Key` 直调接口；需要 session cookie）：

```bash
# 1) 登录 UI，获取 session cookie
curl -c /tmp/aegisgate-ui.cookie -X POST http://127.0.0.1:18080/__ui__/api/login \
  -H "Content-Type: application/json" \
  -d '{"password":""}'

# 2) 使用已登录 session 查看 token 列表
curl -b /tmp/aegisgate-ui.cookie http://127.0.0.1:18080/__ui__/api/tokens
```

说明：
- 若 `curl` 调用 UI API 返回 401，通常是因为 `AEGIS_LOCAL_UI_SECURE_COOKIE=true`（默认）会下发 `Secure` cookie，`http://127.0.0.1` 场景下 cookie 不会被回传；此时请改用 HTTPS 访问 UI，或临时设置 `AEGIS_LOCAL_UI_SECURE_COOKIE=false` 后重启网关再测试（仅建议开发环境）。
- UI 写接口除 session 外还要求 `x-aegis-ui-csrf`；可通过 `GET /__ui__/api/bootstrap` 读取当前 session 的 csrf token。

查看日志：

```bash
docker compose logs -f aegisgate
```

重启：

```bash
docker compose restart aegisgate
```

升级：

```bash
git pull
docker compose up -d --build
```

## 10) How to troubleshoot issues? 故障排查顺序

1. `health` 是否正常（`curl http://127.0.0.1:18080/health`）。
2. 确认使用哪种路由模式：token 路由（路径含 `/v1/__gw__/t//...`）或直连上游（`AEGIS_UPSTREAM_BASE_URL` 是否已设置）。
3. Token 路由：若只知道 `upstream_base`，用 `POST /__gw__/lookup` 反查 token；若只知道 token，可查看 `config/gw_tokens.json` 或登录 UI 后访问 `/__ui__/api/tokens`。同时确认上游地址与 API key 是否正确。
4. 直连模式：`.env` 中 `AEGIS_UPSTREAM_BASE_URL` 是否正确，是否已重启。
5. 看 `docker compose logs -f aegisgate` 是否有 `upstream` 错误、自动净化（auto-sanitize）、阻断原因。

## 11) What are the security best practices? 安全基线

- 对外仅暴露业务入口，管理接口仅限内网。
- 默认监听建议使用 `127.0.0.1`，通过反向代理做外部暴露控制。
- 不在日志或工单中明文粘贴密钥、token、cookie、私钥、助记词。
- 生产环境定期轮换 `config/aegis_gateway.key`（替换文件内容后重启服务）。
- `whitelist_key` 字段只填真正需要豁免脱敏的字段名，最小化敏感数据明文透传范围。

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ax128](https://github.com/ax128)
- **Source:** [ax128/AegisGate](https://github.com/ax128/AegisGate)
- **License:** MIT
- **Homepage:** https://github.com/ax128/AegisGate

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-ax128-aegisgate-aegisgate
- Seller: https://agentstack.voostack.com/s/ax128
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.