dungnotnull/infisical-enhanced-secrets-intelligence-agent
GitHub: dungnotnull/infisical-enhanced-secrets-intelligence-agent
基于 Infisical 扩展的 AI 密钥情报平台，结合 ML 异常检测与 LLM 报告生成来保障凭证安全并简化合规审计。
Stars: 2 | Forks: 0
# Infisical-Enhanced：机密情报 Agent
## 目录
- [概述](#overview)
- [核心功能](#key-features)
- [架构](#architecture)
- [快速开始](#quick-start)
- [前置条件](#prerequisites)
- [Docker Compose (推荐)](#docker-compose-recommended)
- [本地安装](#local-installation)
- [使用说明](#usage)
- [CLI 命令](#cli-commands)
- [REST API](#rest-api)
- [配置](#configuration)
- [Prompt 模板](#prompt-templates)
- [监控与告警](#monitoring--alerts)
- [知识库更新](#knowledge-base-updates)
- [贡献指南](#contributing)
- [许可证](#license)
- [鸣谢](#acknowledgements)
## 概述
Infisical-Enhanced（本项目）是 Infisical v0.82.7 的一个分支，增加了一个生产级的 AI 情报层。该 Agent 与 Infisical 并行运行，并持续执行以下操作：
* 结合 ML 异常检测（BGE-large embeddings + RoBERTa-MNLI zero-shot 分类器）对访问事件进行评分。
* 通过 LLM（Claude、OpenAI、Ollama）生成自然语言的审计叙述，并支持流式传输。
* 使用正则表达式、信息熵以及 CodeT5+ 验证，扫描 git diff、目录和文件中的硬编码机密。
* 将配置与 SOC2、ISO27001 和 NIST 800-53 控制措施进行映射，生成包含修复指导的差距报告。
* 通过爬取 ArXiv、NVD、NIST 和 Infisical 发布版本，每周更新知识库（SECOND-KNOWLEDGE-BRAIN.md）。
* 暴露 REST API，供其他 Agent 或监控系统查询最新的异常评分。
所有组件均为松耦合、可独立测试，并旨在实现零漏报的安全保障。
## 核心功能
- ML 异常检测 – 对 Infisical 审计日志进行实时评分，支持自定义阈值。
- LLM 驱动的报告 – 提供审计摘要、合规差距分析和机密扫描解释；支持长报告的流式传输。
- 机密扫描 – 分层检测（正则表达式 + 信息熵 + ML 验证），在标准开源仓库中误报率低于 5%。
- 合规映射 – 自动评估 SOC2 CC6/CC7/CC9、ISO27001 A.9/A.12/A.18、NIST 800-53 AC/AU/SI 系列。
- 持续学习 – 每周研究型爬虫会更新内部知识库，进而丰富合规控制措施的描述。
- REST API – 提供轻量级 endpoint（/api/v1/anomalies/latest）供外部调用。
- 可观测性 – 将结构化 JSON 日志写入 ./logs/agent.log，支持 webhook 告警（Slack/通用 HTTP），并进行 LLM 成本/使用量追踪。
- Docker 开箱即用 – 单条命令堆栈（docker compose up）即可拉起 Agent、Infisical、PostgreSQL 和 Redis。
- 可扩展 – 通过 InfisicalOrchestrator 提供插件架构；便于添加新模块或替换模型。
## 架构
```
User Trigger (CLI / Cron / Webhook / Git Hook)
|
v
InfisicalOrchestrator <-- central decision loop
|
+------+-------+
| |
v v
AnomalyDetector AuditSummarizer <-- LLM generates reports
| |
v v
SecretScanner ComplianceMapper <-- framework-specific gap analysis
| |
v v
MemoryManager (SQLite + FAISS) <-- persists events, scans, reports
|
v
HFModelManager (lazy loads BGE, RoBERTa, CodeT5+, BERT-NER, Cross-Encoder)
|
v
LLMClient (Claude -> OpenAI -> Ollama fallback, prompt caching, retries, streaming)
```
所有组件间的通信均通过定义良好的 Python 接口进行；除共享内存管理器外，不存在任何全局状态。
## 快速开始
### 前置条件
- Docker Engine >= 24.0 和 Docker Compose 插件（或独立的 docker-compose）。
- （可选）LLM 提供商的 API 密钥：ANTHROPIC_API_KEY、OPENAI_API_KEY。
- （可选）用于离线模式的本地 Ollama 实例。
### Docker Compose (推荐)
```
# 克隆 repository
git clone https://github.com/dungnotnull/infisical-enhanced-secrets-intelligence-agent.git
cd infisical-enhanced-secrets-intelligence-agent
# 复制 example environment 并根据需要进行调整
cp config/.env.example .env
# 编辑 .env 以设置你的 API keys、webhook URLs 等
vim .env
# 构建并启动 stack
docker compose up -d --build
# 验证服务是否健康
docker compose ps
docker compose logs -f infisical-agent
```
infisical-agent 服务默认运行 serve 命令，并在 http://localhost:8780 上暴露 FastAPI API。
### 本地安装
```
# 创建 virtual environment
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
# 安装 dependencies
pip install -r requirements.txt
# 准备 environment
cp config/.env.example .env
vim .env # set required API keys
# 创建 runtime directories
mkdir -p data models logs reports
# 运行一次性命令（示例：对过去 24 小时进行 anomaly detection）
python -m agent.main anomaly --hours 24
# 启动 API server
python -m agent.main serve --host 0.0.0.0 --port 8780
```
## 使用说明
### CLI 命令
入口为 python -m agent.main（如果您安装了该包，则为 infisical-enhanced）。
| 命令 | 描述 |
|---------|-------------|
| scan | 检测 git diff、目录或文件中的硬编码机密。使用 --mode（git-diff、directory、ile）和 --path。 |
| nomaly | 对 Infisical 访问日志运行 ML 异常检测。选项：--hours、--threshold、--workspace、--output。 |
| audit | 生成 LLM 驱动的审计摘要。选项：--days、--format（markdown/json）、--workspace、--output。 |
| compliance | 根据 SOC2/ISO27001/NIST 评估 Infisical 配置。选项：--framework（逗号分隔的列表）、--output、--workspace。 |
| serve | 启动 FastAPI REST API 服务器。选项：--host、--port。 |
| update_knowledge | 手动触发对 ArXiv、NVD、NIST 和 Infisical 发布的爬取，以更新 SECOND-KNOWLEDGE-BRAIN.md。 |
所有命令均接受 --config 以指向自定义的 gent_config.yaml，以及使用 --verbose 输出调试日志。
### REST API
当 Agent 以服务器模式（serve）运行时，可使用以下 endpoint：
* GET /health → {"status":"ok","version":"1.0.0"}
* GET /api/v1/anomalies/latest → 包含最新异常检测结果的 JSON（默认基于过去 1 小时的回溯记录）。字段：
{
"total_events": 1243,
"flagged_events": 5,
"anomalies": [
{
"actor": {"email":"alice@example.com"},
"metadata": {"secretPath":"prod/db-password"},
"anomaly_score":0.92,
"severity":"HIGH",
"createdAt":"2026-06-10T10:30:00Z"
}
],
"generated_at":"2026-06-10T11:00:00Z"
}
该 API 旨在供其他 Agent、监控系统或内部仪表板调用。系统未内置身份验证；请根据需要将其置于反向代理、API 网关或网络策略的保护之后。
## 配置
配置位于 config/agent_config.yaml 中，可通过环境变量进行覆盖（参见 config/.env.example）。主要部分：
- **llm** – 提供商顺序、模型名称、最大重试次数、重试延迟、每日成本限额。
- **anomaly** – 阈值、评分权重、基线窗口、严重级别。
- **scanner** – 信息熵阈值、文件扩展名、需跳过的目录。
- **compliance** – 默认框架、审计保留期、token 过期阈值。
- **hf_models** – HuggingFace 模型注册表；可通过 model_overrides 进行覆盖。
- **knowledge_updater** – ArXiv 分类、时间表、最大结果数。
- **infisical** – API URL、超时时间、重试次数。
- **output** – 报告目录、webhook URL、Slack 频道。
### .env 示例
```
ANTHROPIC_API_KEY=your_anthropic_key_here
OPENAI_API_KEY=your_openai_key_here
OLLAMA_BASE_URL=http://host.docker.internal:11434
INFISICAL_SERVICE_TOKEN=your_infisical_service_token
INFISICAL_WORKSPACE_ID=your_workspace_id
ALERT_WEBHOOK_URL=https://hooks.slack.com/services/XXX/YYY/ZZZ
SLACK_CHANNEL=#security-alerts
LOG_LEVEL=INFO
```
## Prompt 模板
LLM 的 Prompt 模板存储在 config/prompts.yaml 中。该文件使用 YAML 锚点进行复用；AuditSummarizer 会在运行时加载它们。如需自定义，请编辑 YAML 并重启 Agent。
## 监控与告警
- **日志记录：** 结构化 JSON 日志将写入 ./logs/agent.log。每个日志条目包含时间戳、日志级别、logger 名称、消息以及上下文字段。
- **Webhook 告警：** 当异常检测运行标记了一个或多个事件时，编排器（orchestrator）可选择将 payload 发送到 output.webhook_url（或环境变量 ALERT_WEBHOOK_URL）中配置的 URL。Payload 包含总事件数、被标记的事件数以及异常样本。
- **LLM 使用量：** LLMClient.stats 属性返回调用次数和预估成本（美元）。可以对其进行抓取或记录以便于预算管理。
## 知识库更新
ools/knowledge_updater.py 脚本通过 APScheduler 实现每周定时的爬取（当地时间周日 02:00）。它会抓取：
- ArXiv 中 cs.CR 和 cs.DC 分类下、符合安全相关查询的最新论文。
- 与凭据暴露相关的高严重性 NVD CVE（CVSS >= 7.0，特定 CWE）。
- 最新的 Infisical GitHub 发布版本。
- NIST CSSC 出版物（可选）。
新条目会通过 URL 的 SHA-256 哈希值进行去重，并附加到 SECOND-KNOWLEDGE-BRAIN.md 中带有日期的标题下。调度程序在容器内运行；如需手动触发：
```
docker compose exec infisical-agent python -m agent.main update_knowledge
```
## 许可证
本项目基于 MIT 许可证授权 – 详情请参阅 [LICENSE](LICENSE) 文件。
## 鸣谢
- Infisical – 我们所增强的非常出色的开源机密管理器。
- HuggingFace – 在宽松许可下提供最先进的模型（BGE、RoBERTa、CodeT5+、BERT-NER）。
- Anthropic、OpenAI、Ollama – 为智能报告提供支持的 LLM 提供商。
- 开源社区 – 感谢无数的库（FastAPI、Transformers、Sentence-Transformers、Click、Pyyaml 等），正是它们让本项目成为可能。
*由 Infisical-Enhanced 团队充满 ❤️ 地构建。
标签：DevSecOps, StruQ, 上游代理, 人工智能, 合规报告, 异常检测, 搜索引擎查询, 机密检测, 测试用例, 用户模式Hook绕过, 请求拦截, 逆向工具