admina-org/admina
GitHub: admina-org/admina
Admina 是一个 AI 应用治理框架，通过 PII 脱敏、提示注入拦截、操作审计和欧盟 AI 法案合规分析，帮助团队实现「受治理的 AI」开发。
Stars: 3 | Forks: 1
P
A2["AI agent → POST /mcp"] --> P
P["governance pipeline"]
P --> U1["Ollama / OpenAI"]
P --> U2["MCP server / LLM"]
classDef pipe fill:#0ea5e9,stroke:#0369a1,color:#fff;
class P pipe;
```
Pipeline（在两种模式下完全相同）：`loop-breaker → firewall → PII 脱敏 → guards → 审计 → 取证链 (SHA-256) → OTEL`
## 4 大治理领域
| 领域 | 功能 | 引擎 |
|--------|-------------|--------|
| **Agent 安全** | 防注入 firewall（15 个 regex + 启发式评分），loop breaker（TF-IDF 余弦相似度） | Rust + Python |
| **数据主权** | PII 脱敏（email、SSN、credit cards、IBAN、phone、IP），驻留地强制执行，数据分类 | Rust + spaCy NER |
| **合规性** | 欧盟 AI 法案风险分类（第 6 条）和差距分析（第 9-15 条），取证黑匣子（SHA-256 哈希链），OTEL 原生 spans | Rust + Python |
| **AI 基础设施** | LLM 引擎（Ollama、OpenAI），RAG pipeline (ChromaDB)，Open WebUI | Python |
所有治理领域均**双向**运作 —— 同时扫描出站请求和入站响应。
## SDK
四种受治理的基础组件，每种均提供 async + sync 接口：
```
from admina import GovernedModel, GovernedData, GovernedAgent, ComplianceKit
```
| 组件 | 用途 | 应用的治理 |
|-----------|---------|-------------------|
| `GovernedModel` | LLM 调用 (Ollama, OpenAI) | 对 prompt 和响应进行 PII 脱敏，事件审计 |
| `GovernedData` | 数据摄取和查询 | PII 分类，驻留地强制执行，访问审计 |
| `GovernedAgent` | MCP/A2A agent 调用 | firewall，PII，loop breaker —— 进程内的完整 proxy pipeline |
| `ComplianceKit` | 监管合规 | 欧盟 AI 法案风险分类，差距分析，报告生成 |
## 插件系统
9 个插件接口，可从 `plugins/builtin/` 自动发现或通过 CLI 安装：
| 接口 | 内置实现 |
|-----------|------------------------|
| Model Adapter | Ollama, OpenAI |
| Data Connector | ChromaDB, Filesystem |
| Governance Domain | GuardrailsAI (toxic, jailbreak, bias, PII) |
| Compliance Template | 欧盟 AI 法案 |
| Transport Adapter | MCP, HTTP REST |
| Forensic Store | Filesystem, S3-compatible (boto3 — AWS S3, MinIO, R2, …) |
| Auth Provider | API Key |
| PII Engine | spaCy + Regex |
| Alert Channel | Log, Webhook |
```
admina plugin list # List registered plugins
admina plugin install ./my-plugin # Install a custom plugin
admina plugin create my-domain # Scaffold a new plugin
```
## CLI
```
admina init my-project # Scaffold project with admina.yaml + docker-compose.yml
admina dev # Local mode: proxy + dashboard on :3000 (no Docker)
admina dev --stack # Docker stack: + redis + clickhouse + grafana
admina dev --with-llm # --stack + ollama + chromadb + open-webui
admina plugin list # List all registered plugins
admina plugin install X # Install a plugin from path or registry
admina plugin create X # Scaffold a new plugin from template
```
`admina dev` 默认采用**单进程本地模式**，完全没有 Docker
依赖：一个 uvicorn 实例在同一端口上提供 proxy API 和
仪表板 SPA。使用 `--stack` 获取类似生产环境的 Docker compose，或
使用 `--with-llm` 同时启动本地 LLM 服务。
## 仪表板
端口 3000 上的实时治理仪表板：
- **治理评分** —— 0-100 综合指标（数据驻留地、审计覆盖率、攻击率、取证完整性、欧盟 AI 法案合规性）
- **实时信息流** —— 通过 WebSocket 流式传输治理事件
- **合规差距** —— 带有条款级别详情的欧盟 AI 法案差距分析
- **基础设施健康度** —— proxy、Redis、forensic store、ClickHouse、OTEL 状态
API 后端：`GET /api/dashboard/score`, `/feed`, `/compliance`, `/sovereignty`, `/infra`, `/models`
## 配置
Admina 使用 `admina.yaml` 作为主要配置文件（为了向后兼容，可通过 `.env` 作为回退）：
```
cp admina.yaml.example admina.yaml # Copy and customize
```
查看 [`admina.yaml.example`](https://github.com/admina-org/admina/blob/main/admina.yaml.example) 了解所有选项，包括 domains、AI infra、plugins、dashboard、forensic storage、alert channels 和 integrations。
## 集成
基于 ML 的内容验证（toxic 语言、jailbreak、bias、通过 Presidio 检测 PII）作为治理域插件： ``` # Upstream guardrails-ai is currently in PyPI quarantine. Install it # manually from your local mirror or wheel cache; once available, the # plugin in admina/plugins/builtin/guards/guardrailsai_guard.py will # detect it automatically. pip install
```
在 `admina.yaml` 中的 `agent_security.domains.guardrailsai` 下启用。所有推理默认都在本地运行 —— 不会有数据离开部署边界。
通过 Admina proxy 治理 OpenClaw agent 操作。每一个工具调用、shell 命令和 API 请求在执行前都会经过验证： ``` cd integrations/openclaw/admina-governance chmod +x setup.sh && ./setup.sh ``` 该技能使用 `POST /api/v1/validate`（执行前）和 `POST /api/v1/audit`（执行后）endpoint。
| Node | 用途 | |------|---------| | **Admina Govern** | 内联治理检查 —— 验证工作流数据，拦截注入，脱敏 PII | | **Admina Audit** | 将工作流事件连同欧盟 AI 法案风险分类记录到 forensic 黑匣子中 | | **Admina Dashboard** | 触发节点 —— 在发生治理事件时通过 WebSocket 触发 | 安装：在你的 n8n 实例中运行 `npm install n8n-nodes-admina`。
三个 Python hooks（`agent_fast_reply`、`before_cat_sends_message`、`before_cat_recalls_memories`）： ``` cd integrations/cheshirecat/admina-plugin ./setup.sh # Start Admina sidecar # Copy plugin into Cheshire Cat plugins/ directory ```
在进程内治理每一个 LLM 调用和工具调用： ``` from admina.integrations.langchain.callbacks import AdminaCallbackHandler handler = AdminaCallbackHandler() llm = ChatOpenAI(callbacks=[handler]) ```
``` from admina.integrations.crewai.callbacks import admina_step_callback, admina_task_callback agent = Agent(role="Researcher", step_callback=admina_step_callback) crew = Crew(agents=[agent], tasks=[task], task_callback=admina_task_callback) ```
详情请参阅[完整集成文档](https://github.com/admina-org/admina/blob/main/docs/guides/integrations.md)。
## 性能 —— 混合 Python + Rust 引擎
Rust 核心引擎是一个可选的加速器。默认的
`pip install admina-framework` 仅提供纯 Python 实现；
通过可选的额外依赖启用 Rust 引擎 `pip install
"admina-framework[rust]"`（或者为了本地开发从源码构建 ——
`maturin develop --release --manifest-path core-rust/Cargo.toml`，请参阅
[CONTRIBUTING.md](https://github.com/admina-org/admina/blob/main/CONTRIBUTING.md)）。在运行时，Admina 会自动检测
可用的引擎，如果未安装 Rust 扩展，则透明地回退到 Python。
以下测量数据假设已加载 Rust 引擎：
```
Component Rust (median) P95 P99
----------------- ------------- --------- ---------
Firewall (regex) 2.08us 2.33us 2.50us
PII Scanner 0.62us 0.67us 0.71us
Loop Breaker 2.38us 2.67us 2.75us
Hash Chain 1.00us 1.12us 1.25us
----------------- ------------- --------- ---------
4-Domain pipeline 6.25us 7.04us 7.29us
```
## 流量模拟器
生成逼真的治理流量，以测试和演示该平台：
```
# Start the proxy
docker compose up -d
# Default: 60s at 2 req/s
python scripts/simulate.py
# Intense: 5 minutes at 10 req/s
python scripts/simulate.py --duration 300 --rate 10
```
生成加权的混合流量：干净的 MCP 请求、注入尝试、PII 内容、循环触发、REST validate/audit 调用、欧盟 AI 法案分类以及仪表板读取。带有每个事件操作和摘要计数器的彩色终端输出。
## 基础设施与服务
完整技术栈（`docker compose up`）运行 9 个容器：
| 端口 | 服务 | 描述 |
|------|---------|-------------|
| `8080` | Proxy | MCP proxy + REST API + OpenAPI 文档 |
| `3000` | Dashboard | 实时治理 Web UI |
| `3001` | Grafana | 指标仪表板 |
| `4317` | OTEL Collector | OTLP gRPC 摄取 |
ClickHouse 和 Redis 仅供内部使用（未暴露给主机）。
Forensic 黑匣子（使审计追踪防篡改的 SHA-256 哈希链） 支持三种后端。在生产环境中选择之前请阅读此说明。 | Backend | 许可证 | 何时使用 | 注意事项 | |---------|---------|-------------|---------| | **`memory`** *(默认)* | 无 | 本地开发、测试、演示 | 重启后会丢失记录 —— 无审计持久性。启动时会发出响亮的警告。 | | **`filesystem`** | 无 | 单主机内部部署、air-gapped、较小规模部署 | 持久性取决于主机文件系统；不适合 HA。需要 `FORENSIC_BASE_DIR`。 | | **`s3`** *(boto3)* | Apache 2.0 (boto3) | 生产环境 / HA / 多区域 | 适用于**任何兼容 S3 的服务** —— AWS S3、**MinIO** 服务器、Cloudflare R2、Backblaze B2、**SeaweedFS** (Apache 2.0)、**Garage** (AGPLv3)、**Ceph RGW** (LGPLv2)。支持 WORM Object Lock。 |
| 变量 | 默认值 | 描述 | |----------|---------|-------------| | `ADMINA_API_KEY` | *(空)* | 所有 endpoint 的 API 密钥 | | `UPSTREAM_MCP_URL` | `http://localhost:9000` | 默认的上游 MCP 服务器 | | `REDIS_URL` | `redis://localhost:6379/0` | Session 状态 + 速率限制 | | `FORENSIC_BACKEND` | `memory` | Forensic 存储：`memory` \| `filesystem` \| `s3` | | `LOG_LEVEL` | `INFO` | 日志详细程度 |
``` # Health check (always public) curl http://localhost:8080/health # Governance stats curl http://localhost:8080/api/stats -H "X-API-Key: $ADMINA_API_KEY" # Proxy an MCP call (all governance domains applied) curl -X POST http://localhost:8080/mcp \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{...}}' # Validate content (REST API for integrations) curl -X POST http://localhost:8080/api/v1/validate \ -H "Content-Type: application/json" \ -d '{"content": "Check this text for governance issues"}' # Audit an action (forensic logging) curl -X POST http://localhost:8080/api/v1/audit \ -H "Content-Type: application/json" \ -d '{"event": {"action": "llm_call", "status": "success"}}' # EU AI Act risk classification curl -X POST http://localhost:8080/api/compliance/classify \ -H "Content-Type: application/json" \ -d '{"description":"AI credit scoring","use_case":"lending","data_types":["financial"]}' # Dashboard governance score curl http://localhost:8080/api/dashboard/score ```
## 项目文档
- [CONTRIBUTING.md](https://github.com/admina-org/admina/blob/main/CONTRIBUTING.md) —— 开发环境设置、测试和 pull request 工作流
- [MODEL_CARD.md](https://github.com/admina-org/admina/blob/main/MODEL_CARD.md) —— 每个 Admina 治理组件的透明度文档（预期用途、范围、局限性、已知失败模式），符合欧盟 AI 法案第 13 条和 NIST AI RMF
- [ROADMAP.md](https://github.com/admina-org/admina/blob/main/ROADMAP.md) —— 从 0.9.x 到 1.0 及更高版本的规划里程碑
- [CHANGELOG.md](https://github.com/admina-org/admina/blob/main/CHANGELOG.md) —— 发布说明
- [SECURITY.md](https://github.com/admina-org/admina/blob/main/SECURITY.md) —— 协调披露政策
- [CODE_OF_CONDUCT.md](https://github.com/admina-org/admina/blob/main/CODE_OF_CONDUCT.md) —— Contributor Covenant 2.1
- **浏览 AI 生成的 wiki** → [deepwiki.com/admina-org/admina](https://deepwiki.com/admina-org/admina)
Admina 采用 Apache 2.0 协议。欢迎积极贡献。
## 许可证
Copyright © 2025–2026 [Stefano Noferi](https://github.com/stefanoferi) & Admina 贡献者
基于 Apache License, Version 2.0 授权。完整文本请参见 [LICENSE](https://github.com/admina-org/admina/blob/main/LICENSE)。
⚖️ 合规范围与免责声明 —— Admina 在法律上能做和不能做的事
GuardrailsAI —— 作为治理插件的基于 ML 的内容验证
基于 ML 的内容验证（toxic 语言、jailbreak、bias、通过 Presidio 检测 PII）作为治理域插件： ``` # Upstream guardrails-ai is currently in PyPI quarantine. Install it # manually from your local mirror or wheel cache; once available, the # plugin in admina/plugins/builtin/guards/guardrailsai_guard.py will # detect it automatically. pip install
OpenClaw —— 通过 pre/post-action hooks 治理 OpenClaw agent 操作
通过 Admina proxy 治理 OpenClaw agent 操作。每一个工具调用、shell 命令和 API 请求在执行前都会经过验证： ``` cd integrations/openclaw/admina-governance chmod +x setup.sh && ./setup.sh ``` 该技能使用 `POST /api/v1/validate`（执行前）和 `POST /api/v1/audit`（执行后）endpoint。
n8n —— 用于 n8n 工作流自动化的社区节点
| Node | 用途 | |------|---------| | **Admina Govern** | 内联治理检查 —— 验证工作流数据，拦截注入，脱敏 PII | | **Admina Audit** | 将工作流事件连同欧盟 AI 法案风险分类记录到 forensic 黑匣子中 | | **Admina Dashboard** | 触发节点 —— 在发生治理事件时通过 WebSocket 触发 | 安装：在你的 n8n 实例中运行 `npm install n8n-nodes-admina`。
Cheshire Cat AI —— 通过 Python hooks 治理所有 Cheshire Cat 交互
三个 Python hooks（`agent_fast_reply`、`before_cat_sends_message`、`before_cat_recalls_memories`）： ``` cd integrations/cheshirecat/admina-plugin ./setup.sh # Start Admina sidecar # Copy plugin into Cheshire Cat plugins/ directory ```
LangChain —— 即插即用的 callback handler
在进程内治理每一个 LLM 调用和工具调用： ``` from admina.integrations.langchain.callbacks import AdminaCallbackHandler handler = AdminaCallbackHandler() llm = ChatOpenAI(callbacks=[handler]) ```
CrewAI —— 用于多 agent 治理的 step 和 task callback
``` from admina.integrations.crewai.callbacks import admina_step_callback, admina_task_callback agent = Agent(role="Researcher", step_callback=admina_step_callback) crew = Crew(agents=[agent], tasks=[task], task_callback=admina_task_callback) ```
Rust 与 Python 对比（点击展开）
``` Component Python (median) Rust (median) Speedup ----------------- --------------- ------------- -------- Firewall 7.79us 2.08us 3.7x PII (regex-only) 8.21us 0.62us 13.2x PII (with spaCy) 1 992us 0.62us 3 213x Loop (sklearn) 505us 2.38us 212x ----------------- --------------- ------------- -------- Full pipeline 2 261us 5.21us 434x ```🗄️ Forensic 后端（4 种选项）—— 慎重选择
Forensic 黑匣子（使审计追踪防篡改的 SHA-256 哈希链） 支持三种后端。在生产环境中选择之前请阅读此说明。 | Backend | 许可证 | 何时使用 | 注意事项 | |---------|---------|-------------|---------| | **`memory`** *(默认)* | 无 | 本地开发、测试、演示 | 重启后会丢失记录 —— 无审计持久性。启动时会发出响亮的警告。 | | **`filesystem`** | 无 | 单主机内部部署、air-gapped、较小规模部署 | 持久性取决于主机文件系统；不适合 HA。需要 `FORENSIC_BASE_DIR`。 | | **`s3`** *(boto3)* | Apache 2.0 (boto3) | 生产环境 / HA / 多区域 | 适用于**任何兼容 S3 的服务** —— AWS S3、**MinIO** 服务器、Cloudflare R2、Backblaze B2、**SeaweedFS** (Apache 2.0)、**Garage** (AGPLv3)、**Ceph RGW** (LGPLv2)。支持 WORM Object Lock。 |
⚙️ 环境变量 (Docker / .env)
| 变量 | 默认值 | 描述 | |----------|---------|-------------| | `ADMINA_API_KEY` | *(空)* | 所有 endpoint 的 API 密钥 | | `UPSTREAM_MCP_URL` | `http://localhost:9000` | 默认的上游 MCP 服务器 | | `REDIS_URL` | `redis://localhost:6379/0` | Session 状态 + 速率限制 | | `FORENSIC_BACKEND` | `memory` | Forensic 存储：`memory` \| `filesystem` \| `s3` | | `LOG_LEVEL` | `INFO` | 日志详细程度 |
📁 完整项目结构 ``` admina/ +-- admina/ SDK package (GovernedModel, GovernedData, GovernedAgent, ComplianceKit) | +-- plugins/ Plugin base classes + registry +-- domains/ 4 governance domains | +-- data_sovereignty/ PII, residency, classification | +-- ai_infra/ LLM engine, RAG pipeline, Web UI | +-- agent_security/ Firewall, loop breaker, proxy | +-- compliance/ EU AI Act, forensic, OTEL +-- plugins/builtin/ Reference plugin implementations | +-- adapters/ Ollama, OpenAI | +-- connectors/ ChromaDB, Filesystem | +-- domains/ GuardrailsAI | +-- compliance/ EU AI Act template | +-- transports/ MCP, HTTP REST | +-- forensic/ Filesystem | +-- auth/ API Key | +-- pii/ spaCy + Regex | +-- alerts/ Log, Webhook +-- proxy/ FastAPI proxy + Rust engine bridge | +-- api/ Dashboard + integration REST endpoints +-- cli/ CLI commands (init, dev, plugin) +-- core/ Config, types, event bus +-- core-rust/ Rust governance engines (PyO3) +-- dashboard/ Real-time governance web UI +-- integrations/ | +-- openclaw/ OpenClaw governance skill | +-- n8n/ n8n community nodes +-- tests/ 800+ tests (pytest) +-- docker-compose.yml Full stack deployment (9 containers) ```
🔌 API 示例 (curl)
``` # Health check (always public) curl http://localhost:8080/health # Governance stats curl http://localhost:8080/api/stats -H "X-API-Key: $ADMINA_API_KEY" # Proxy an MCP call (all governance domains applied) curl -X POST http://localhost:8080/mcp \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{...}}' # Validate content (REST API for integrations) curl -X POST http://localhost:8080/api/v1/validate \ -H "Content-Type: application/json" \ -d '{"content": "Check this text for governance issues"}' # Audit an action (forensic logging) curl -X POST http://localhost:8080/api/v1/audit \ -H "Content-Type: application/json" \ -d '{"event": {"action": "llm_call", "status": "success"}}' # EU AI Act risk classification curl -X POST http://localhost:8080/api/compliance/classify \ -H "Content-Type: application/json" \ -d '{"description":"AI credit scoring","use_case":"lending","data_types":["financial"]}' # Dashboard governance score curl http://localhost:8080/api/dashboard/score ```
Heimdall — the Governance Owl
admina.org · Created by Stefano Noferi · Pisa, Italy
标签：AI安全, AI风险缓解, Chat Copilot, DLL 劫持, Python, Rust, 可视化界面, 合规治理, 大语言模型, 提示词注入防护, 无后门, 用户代理, 网络安全, 网络流量审计, 请求拦截, 逆向工具, 隐私保护