JuzantinoJ/ai-governance-assistant

# AI 治理与事件助手 ## 项目功能 将任何非结构化的安全或治理发现以文本形式输入。系统将自动： 1. **验证与清理** 输入（注入防护、长度检查） 2. **分类** 发现项 — 类型和严重性（严重 / 高 / 中 / 低 / 信息） 3. **摘要** 用 2-3 个专业句子进行总结 4. **提取行动项** 包含责任人和优先级 5. **起草并发送** 专业邮件回复 6. **存储所有结果** 至 Google Sheets 并保留完整审计追踪 所有过程在几秒内自动完成，无需人工操作。 ## 支持的输入类型 | 类型 | 示例 | | ----------------------- | ------------------------------------------------------------- | | 安全事件 | "CPU 持续 20 分钟占用 98%，可能为加密挖矿程序" | | 漏洞发现 | "在防火墙固件 v2.1.4 中发现 CVE-2024-XXXX" | | 治理/合规 | "管理员账户未实施 SOC 2 控制 AC-3" | | 审计发现 | "按策略要求，访问日志保留时间未超过 30 天" | | SSP 发现 | "生产环境系统边界未文档化" | | 供应商响应 | "第三方供应商尚未完成年度安全审查" | | 补丁更新 | "关键补丁 MS24-001 在 14 个端点待处理" | | 运维工单 | "用户报告 VPN 登录时出现 MFA 绕过" | ## 架构概述 ``` User Input (text) ↓ Webhook Trigger ↓ Input Validator ←─── Sanitize · Length check · Injection guard ↓ AI: Classify ←─── Type · Severity · Confidence score ↓ AI: Summarize ←─── 2–3 sentence factual brief ↓ AI: Extract Actions ← Structured JSON with owner + priority ↓ Output Validator ←─── Schema check · Confidence gate · Fallback handler ↓ AI: Draft Email ↓ Send Email (Gmail / SMTP) ↓ Store to Google Sheets ← Full audit row with run_id + timestamp ↓ Respond to User (JSON) ``` 完整分层架构详见 [`ARCHITECTURE.md`](./ARCHITECTURE.md)。 ## 技术栈 | 层级 | 技术 | | ---------------------- | ---------------------------------------------- | | 工作流编排 | [n8n](https://n8n.io)（通过 Docker 自托管） | | AI 模型 | OpenAI GPT-4o 或 Anthropic Claude | | 数据库（V1） | Google Sheets | | 数据库（V2 目标） | Supabase (PostgreSQL) | | 通知 | Gmail / SMTP | | 容器化 | Docker + Docker Compose | ## 项目结构 ``` ai-governance-assistant/ │ ├── docker-compose.yml ← Run n8n locally with Docker ├── .env.example ← Environment variable template ├── .gitignore ├── README.md ← This file ├── ARCHITECTURE.md ← Full system design and decisions │ ├── workflows/ │ ├── v1-main-workflow.json ← Main n8n workflow (export) │ └── v1-error-handler.json ← Error sub-workflow (export) │ ├── prompts/ │ ├── classify-v1.txt ← Classification prompt │ ├── summarize-v1.txt ← Summarization prompt │ ├── extract-actions-v1.txt ← Action item extraction prompt │ └── draft-email-v1.txt ← Email draft prompt │ ├── docs/ │ ├── node-guide.md ← Node-by-node explanation │ └── schema.md ← Google Sheets column schema │ └── tests/ ├── sample-incident.txt ├── sample-vulnerability.txt ├── sample-audit-finding.txt ├── sample-governance.txt ├── sample-ssp.txt ├── sample-vendor.txt ├── sample-patch.txt └── sample-ticket.txt ``` ## 快速开始 ### 前置条件 - 已安装并运行 [Docker Desktop](https://www.docker.com/products/docker-desktop/) - 拥有 OpenAI 或 Anthropic API 密钥 - 拥有 Google 账户（用于 Sheets + Gmail 集成） ### 1. 克隆仓库 ``` git clone https://github.com/JuzantinoJ/ai-governance-assistant.git cd ai-governance-assistant ``` ### 2. 设置环境变量 ``` cp .env.example .env ``` 打开 `.env` 文件并填写您的值。变量描述请参考 `.env.example`。 ### 3. 使用 Docker 启动 n8n ``` docker compose up -d ``` n8n 将运行在：**http://localhost:5678** 首次设置：首次访问时 n8n 会提示您创建管理员账户。 ### 4. 导入工作流 1. 打开 n8n：http://localhost:5678 2. 进入 **工作流 → 从文件导入** 3. 选择 `workflows/v1-main-workflow.json` 4. 在 **凭证** 中添加您的凭证（OpenAI、Gmail、Google Sheets） 5. 激活工作流 ### 5. 测试 ``` curl -X POST http://localhost:5678/webhook-test/incident-intake \ -H "Content-Type: application/json" \ -d '{"text": "Critical vulnerability CVE-2024-9999 found in firewall firmware. Unauthenticated RCE possible. Affects all devices running version < 3.2.1"}' ``` 您应收到一个包含严重性、摘要和行动项的 JSON 响应。 ## 环境变量 完整列表请参阅 `.env.example`。关键变量： | 变量 | 描述 | | -------------------- | --------------------------------------------------------- | | `POSTGRES_USER` | n8n 使用的 PostgreSQL 用户名 | | `POSTGRES_PASSWORD` | PostgreSQL 密码 — **首次运行前请更改** | | `POSTGRES_DB` | 数据库名称 | | `N8N_ENCRYPTION_KEY` | 静态加密凭证 — **设置后不可更改** | | `GENERIC_TIMEZONE` | 您的时区，例如 `Asia/Kuala_Lumpur` | | `N8N_HOST` | n8n 运行主机名（默认：`localhost`） | ## 实施路线图 | 阶段 | 状态 | 描述 | | --------------------------- | -------------- | ------------------------------------ | | 阶段 1 — 基础建设 | ✅ 进行中 | Webhook + 输入验证 | | 阶段 2 — AI 核心 | ⬜ 计划中 | 分类 · 摘要 · 提取 | | 阶段 3 — 输出与存储 | ⬜ 计划中 | 邮件 · Sheets · 响应 | | 阶段 4 — 加固 | ⬜ 计划中 | 错误处理 · 重试 · 审计追踪 | ## 安全说明 - 所有密钥通过环境变量管理 — **无硬编码内容** - 用户输入在到达 AI 模型前经过清理 - AI 输出在执行任何操作前经过验证 - `.env` 文件和任何 `*.key` 文件通过 `.gitignore` 排除在 Git 之外 - Webhook 密钥头部（`X-Webhook-Secret`）将在阶段 4 中添加 ## 学习收获 本项目是以下领域的实践研究： - n8n 工作流设计和节点架构 - AI 编排和提示工程 - 企业工作流模式（模块化设计、错误处理、审计追踪） - API 集成（OpenAI / Anthropic、Google Sheets、Gmail） - 安全优先的自动化习惯 - 基于 Docker 的自托管 ## 未来计划（V2 / V3） - 将存储迁移至 Supabase (PostgreSQL) - 为严重性发现添加 Slack 告警 - 通过 Switch 节点添加按输入类型的路由 - 使用 T1N0 治理文档添加 RAG 层 - 在 Webhook 端点添加 JWT 认证 - 通过 Ollama 部署本地 AI 模型以处理敏感数据 ## 相关资源 - [n8n-setup-macOS](https://github.com/JuzantinoJ/n8n-setup-macOS) — 如何在 macOS 上安装和运行 n8n（n8n 新手请从这里开始） ## 作者 **JuzantinoJ** — 专注于构建 AI 系统、自动化工作流和企业级 AI 基础设施。

标签：AI工作流, API密钥检测, Google Sheets集成, GPT, n8n平台, Webhook触发, 事件管理, 企业安全, 供应商管理, 分类技术, 合规治理, 威胁情报, 安全事件响应, 安全发现, 安全运营, 审计跟踪, 工作流引擎, 开发者工具, 总结生成, 扫描框架, 数据验证, 治理合规, 漏洞管理, 端点安全, 网络安全, 网络资产管理, 自动化处理, 行动项提取, 补丁管理, 请求拦截, 输入验证, 邮件自动化, 隐私保护, 非结构化数据处理