patrese-procopio/agent-bastos

## 📋 关于本项目 **Agent Bastos** 是一款情报助手，旨在协助公共安全分析师执行查询理论文献、音频转录生成报告以及分析操作情报等任务。 本项目的独特之处不仅在于其 AI 功能，更在于其背后的**工程化设计**：强大的身份验证、基于模块的访问控制、敏感数据加密、取证审计追踪以及符合 LGPD 规范——所有这些都通过了记录在案的安全审计验证（[`AUDIT.md`](./AUDIT.md)）。 ## 🖥️ 界面 ## ✨ 功能 | 模块 | 描述 | 核心技术 | |---|---|---| | 💬 **基于 RAG 的聊天** | 对已索引的理论文献进行语义查询，支持加密的对话记录 | ChromaDB + 多语言 embeddings | | 🎙️ **转录** | 将音频转换为文本，并生成用于报告的结构化分析 | Whisper + LLM | | ✍️ **笔迹分析** | 手写文档分析 | 计算机视觉 + LLM | | 📊 **仪表盘** | 包含指标和综合视图的操作面板 | React + Recharts | | 🕸️ **图分析** | 映射实体间的关系 | SQLite + 可视化 | | 👥 **用户管理** | 具备基于模块访问控制的用户 CRUD | SQLite + JWT | ## 🏗️ 架构 ``` ┌─────────────────────────────────────────────────────────────┐ │ Frontend (Electron + React) │ │ Interface desktop multiplataforma │ └───────────────────────────┬─────────────────────────────────┘ │ HTTPS + JWT Bearer ┌───────────────────────────▼─────────────────────────────────┐ │ API (FastAPI) │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ Middlewares: SecurityHeaders · RateLimit · CORS │ │ │ ├─────────────────────────────────────────────────────┤ │ │ │ Auth: JWT (HS256) · bcrypt · Blacklist persistente │ │ │ │ RBAC: controle de acesso por módulo (require_module)│ │ │ └─────────────────────────────────────────────────────┘ │ │ │ │ 14 routers organizados por domínio de responsabilidade │ └──────┬───────────────┬──────────────┬───────────────────────┘ │ │ │ ┌──────▼──────┐ ┌──────▼──────┐ ┌─────▼──────────┐ │ ChromaDB │ │ SQLite │ │ Logs (Fernet) │ │ (vetorial) │ │ (usuários + │ │ criptografados│ │ doutrinas │ │ blacklist) │ │ + auditoria │ └─────────────┘ └─────────────┘ └────────────────┘ ``` ### 架构决策 - **分层架构：** `routers/` 仅负责处理 HTTP；`services/` 集中处理业务逻辑；`modules/` 封装 AI 能力。路由中零业务逻辑。 - **向量 RAG：** 理论文献库被分割为 *chunks*，转换为 embeddings 并在 ChromaDB 中建立索引以进行语义搜索——而非基于关键字的搜索。 - **感知持久化：** 需要在重启后保留的数据（用户、已撤销的 tokens）存入 SQLite；临时性数据保留在内存中。 ## 🔐 安全性与合规 安全性不是事后补充的细节——它是本项目的核心。主要实施的控件包括： ### 身份验证与授权 - **JWT 与 token 轮换** — 短时效的 access token (15 分钟) + refresh token，每次续期强制进行轮换，以缩小攻击窗口。 - **持久化黑名单** — 已撤销的 tokens（登出）以 SHA-256 *hash* 形式存储在 SQLite 中，在服务器重启后依然存在。即使数据库泄露，这些 hashes 也无法用于身份验证。 - **基于模块的 RBAC** — 每个敏感路由都要求 token 中包含特定模块权限（`require_module`），实施最小权限原则。 - **使用 bcrypt 加密的密码**（成本因子 12）— 绝不以明文形式存储。 ### 数据保护 (LGPD) - **日志加密** — 操作对话在触及磁盘之前使用 Fernet (AES-128) 进行加密。 - **取证审计追踪** — 敏感操作（包括数据销毁）会生成不可变的明文记录，包含 UTC 时间戳、操作者、主机和 PID。该日志甚至在执行彻底清除命令后也能存活。 - **破坏性操作需明确确认** — 数据销毁需要执行*区分大小写*的明确确认，防止意外触发。 - **自动日志轮转** — 防止数据无限增长。 ### 攻击防御强化 - **输入净化** — 上传的文件名在任何使用前都会进行净化处理，防止 *prompt injection*。 - **Rate limiting** — 保护身份验证 endpoints 免受暴力破解。 - **Fail-fast** — 如果未配置关键密钥（JWT、加密密钥），系统将拒绝启动，而不是在不安全的状态下运行。 ## 🛠️ 技术栈 **Backend** - Python 3.14 · FastAPI · Uvicorn - ChromaDB (向量数据库) · 多语言 embeddings - SQLite (用户、token 黑名单) - JWT (python-jose) · bcrypt (passlib) · Fernet (cryptography) **IA / ML** - 具备语义搜索的 RAG (Retrieval-Augmented Generation) - 音频转录 (Whisper) - 通过 API 调用的大语言模型 **Frontend** - React · Vite · Electron (桌面应用程序) - Recharts (数据可视化) **自动化与基础设施** - n8n (工作流编排) - pytest (测试) ## 🚀 运行说明 ### 1. Backend ``` # 克隆仓库 git clone https://github.com/patrese-procopio/agent-bastos.git cd agent-bastos # 创建并激活虚拟环境 python -m venv .venv source .venv/bin/activate # Linux/Mac # .venv\Scripts\Activate.ps1 # Windows PowerShell # 安装依赖 pip install -r requirements.txt # 配置环境变量（参见 .env.example） cp .env.example .env # 使用您的密钥编辑 .env # 索引知识库 python -m modules.ingestor # 启动 API python api.py ``` API 将在 `http://127.0.0.1:8000` 上提供。 交互式文档 (Swagger) 位于 `http://127.0.0.1:8000/docs`。 ### 2. Frontend ``` cd frontend npm install npm run dev ``` ## ⚙️ 配置 系统对所有敏感配置使用环境变量。`.env.example` 文件记录了所需的变量——**切勿**将您真实的 `.env` 纳入版本控制。 关键密钥（身份验证和加密）遵循 *fail-fast* 原则：如果没有它们，应用程序将无法启动，从而避免在不安全状态下运行。 生成具有安全 hash 的用户密码： ``` python scripts/setar_senha.py ``` ## 📂 项目结构 ``` agent-bastos/ ├── api.py # Entry point — registra middlewares e routers ├── dependencies.py # Dependências compartilhadas (auth, RBAC) ├── config/ # Configurações centralizadas ├── routers/ # Camada HTTP — 14 routers por domínio ├── services/ # Lógica de negócio (auth, rate limit, logging) ├── modules/ # Capacidades de IA (RAG, ingestão, transcrição) ├── frontend/ # Aplicação React + Electron ├── scripts/ # Utilitários (gestão de senhas, manutenção) ├── tests/ # Testes automatizados (pytest) ├── automacao_n8n/ # Fluxos de automação ├── AUDIT.md # Relatório de auditoria de segurança └── requirements.txt ``` ## 🗺️ 路线图 - [x] 完整的安全审计（记录了 12 项修复） - [x] SQLite 中的持久化 JWT 黑名单 - [x] 通过 API 实现带有 RBAC 的用户管理 - [x] 加密日志的自动轮转 - [ ] 容器化 - [ ] RAG 中的混合搜索（向量 + 关键字）并加入 reranking - [ ] 使用 GitHub Actions 的 CI/CD - [ ] 扩大测试覆盖率 ## 👤 作者 **Patrese Procópio** 数据工程 · 安全情报 · 企业级 AI 解决方案 [](https://github.com/patrese-procopio) ## 📄 许可证 本项目用于演示和作品集目的。如需特定用途，请咨询作者。

*秉承对安全性、隐私保护和卓越工程的关注而构建。*

标签：AV绕过, ChromaDB, FastAPI, RAG, React, Syscalls, 情报分析系统, 数据合规, 文档分析, 逆向工具