SrushtiGunjal/IRIS-Smart-Cyber-IR-Agent

# IRIS-Smart-Cyber-IR-Agent 离线网络事件响应 Agent，使用 FastAPI 和 PostgreSQL (pgvector) 构建，用于日志摄取、事件关联、确定性风险评分和自动化 runbook 生成。包含 Web 仪表板、调查工作流，以及可选的用于增强 playbook 输出的本地 LLM。      ## 概述 一个最小化的端到端离线事件响应自动化系统，专为网络安全事件响应工作流设计。本项目演示了： - **日志摄取**：通过 FastAPI 处理 SIEM/EDR/IAM/NET 事件 - **本地存储**：带有 pgvector 的 PostgreSQL，用于语义搜索 - **关联分析**：事件 → 事件（实体 + 时间窗口图谱） - **排名**：确定性评分 + UEBA 异常检测（tsfresh + PyOD） - **Playbooks**：从 YAML 模板自动生成 runbook（可选 Ollama 重写） - **调查**：用于证据验证和遥测差距分析的 Agent 风格接口 ## 目录 - [前置条件](#prerequisites) - [克隆仓库](#clone-repository) - [安装说明](#installation) - [配置说明](#configuration) - [快速入门](#quickstart) - [API 端点](#api-endpoints) - [项目结构](#project-structure) - [事件格式](#event-format) - [Runbook 模板](#runbook-templates) - [可选：本地 LLM](#optional-local-llm-ollama) - [使用示例](#usage-examples) - [故障排除](#troubleshooting) - [贡献指南](#contributing) - [许可证](#license) - [作者](#authors) ## 前置条件 - **Docker 和 Docker Compose** (v20.10+) - **Python** 3.10+（用于本地开发） - **Git** - **PostgreSQL**（包含在 Docker Compose 中） - 建议至少配备 **4GB RAM** ## 克隆仓库 通过 HTTPS 克隆： ``` git clone https://github.com/yourusername/incident-response-agent.git cd incident-response-agent ``` 或者通过 SSH 克隆： ``` git clone git@github.com:yourusername/incident-response-agent.git cd incident-response-agent ``` ## 安装说明 ### 选项 1：Docker（推荐） 最快上手的方式，所有依赖项均已预配置： ``` docker compose up --build ``` 这使用了启用了 pgvector 的本地 Postgres 镜像（`pgvector/pgvector:pg16`）用于 embeddings 和语义搜索，所有操作均在隔离的容器中运行。 ### 选项 2：本地开发 1. **创建 Python 虚拟环境：** ``` python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\Activate.ps1 ``` 2. **安装依赖项：** ``` pip install -r requirements.txt ``` 3. **配置带有 pgvector 的 PostgreSQL：** 确保本地运行的 PostgreSQL 已启用 pgvector 扩展，或者调整连接字符串： ``` export DB_URL="postgresql://user:password@localhost/incident_response" ``` 4. **启动 API 服务器：** ``` python -m ir_agent.main ``` API 将在 `http://localhost:8000/` 上可用 ## 配置说明 ### 配置文件 创建或编辑 `config/config.yml` 以自定义设置： ``` database: url: "postgresql://user:password@localhost/incident_response" pool_size: 10 echo: false server: host: "0.0.0.0" port: 8000 debug: false workers: 4 logging: level: "INFO" format: "json" correlation: time_window_seconds: 3600 entity_window_seconds: 86400 optional: ollama_base_url: "" # e.g., http://localhost:11434 ollama_model: "" # e.g., llama3.2:3b ``` ### 环境变量 环境变量会覆盖配置文件中的设置： ``` export DB_URL="postgresql://user:password@localhost/incident_response" export OLLAMA_BASE_URL="http://localhost:11434" export OLLAMA_MODEL="llama3.2:3b" export CORRELATION_TIME_WINDOW=3600 ``` ## 快速入门 ### 使用 Docker 1. **启动所有服务：** ``` docker compose up --build ``` 2. **运行端到端演示**（从另一个终端执行）： ``` python3 scripts/demo.py ``` 或者一次性运行两者： ``` ./scripts/demo.sh ``` 您将看到： - 事件已摄取到数据库中 - 事件已关联并排名 - 为首要事件生成了 runbook 3. **查看仪表板：** 在浏览器中打开 `http://localhost:8000/` 以查看事件仪表板 ## API 端点 ### 健康与状态 - `GET /health` - 服务健康检查 - `GET /status` - 系统状态 ### 事件管理 - `POST /ingest` - 摄取单个事件 - `POST /ingest/batch` - 批量摄取事件 - `POST /ingest/raw` - 将原始日志行转换为标准化事件 ### 事件管理 - `POST /correlate` - 从事件重建 incidents - `GET /incidents` - 列出所有 incidents - `GET /incidents/{incident_id}` - 获取特定 incident 的详细信息 - `GET /incidents/{incident_id}/evidence` - 获取 incident 的证据链 ### 调查与响应 - `POST /incidents/{incident_id}/investigate` - 运行调查 Agent - `POST /incidents/{incident_id}/playbook?mode=runbook|ollama` - 生成响应 playbook - `GET /runbooks` - 列出可用的 runbook 模板 ### 搜索 - `GET /events/search?q=...` - 跨事件进行语义搜索（在可用时使用 pgvector） ## 项目结构 ``` incident-response-agent/ ├── ir_agent/ # Main application package │ ├── __init__.py │ ├── main.py # FastAPI application entry point │ ├── config.py # Configuration loader │ ├── db.py # Database connection & models │ ├── models.py # Pydantic data models │ ├── schema.py # Database schema definitions │ ├── ingest.py # Event ingestion logic │ ├── parse_raw.py # Raw log parsing │ ├── correlate.py # Incident correlation engine │ ├── scoring.py # Incident scoring & ranking │ ├── ueba.py # Anomaly detection (UEBA) │ ├── embeddings.py # Semantic search (pgvector) │ ├── investigate.py # Investigation agent │ ├── playbook.py # Playbook generation │ ├── runbooks.py # Runbook template handling │ ├── utils.py # Utility functions │ └── templates/ # HTML templates │ ├── index.html # Dashboard UI │ └── incident.html # Incident detail view ├── runbooks/ # Runbook YAML templates │ ├── command_and_control.yml │ ├── credential_abuse.yml │ ├── malware_execution.yml │ └── suspicious_activity.yml ├── scripts/ # Utility scripts │ ├── demo.py # End-to-end demo │ └── demo.sh # Shell script wrapper ├── examples/ # Example data │ └── events.jsonl # Sample incident scenario ├── config/ # Configuration files │ └── config.yml # Main configuration ├── docker-compose.yml # Docker Compose setup ├── Dockerfile # Application container ├── requirements.txt # Python dependencies └── README.md # This file ``` ## 事件格式 ### 事件 Schema 通过 `/ingest` 或 `/ingest/batch` 摄取的每个事件必须是具有以下结构的 JSON： ``` { "timestamp": "2026-02-14T09:10:00Z", "source": "iam", "event_type": "auth_failed", "severity": 20, "host": "WKS-12", "user": "alice", "ip": "203.0.113.10", "process": null, "message": "Invalid password", "raw": { "provider": "sso", "app": "payments", "extra_field": "any_value" } } ``` ### 字段说明 | 字段 | 类型 | 必填 | 说明 | |-------|------|----------|-------------| | `timestamp` | ISO 8601 | 是 | 事件发生的时间 | | `source` | string | 是 | 来源系统 (iam, siem, edr, net) | | `event_type` | string | 是 | 安全事件的类型 | | `severity` | integer | 是 | 0-100 的严重性评分 | | `host` | string | 否 | 主机名或设备 | | `user` | string | 否 | 涉及的用户名 | | `ip` | string | 否 | IP 地址 | | `process` | string | 否 | 进程名或路径 | | `message` | string | 否 | 人类可读的描述 | | `raw` | object | 否 | 原始事件数据（任意结构） | ### 批量摄取示例 ``` curl -X POST http://localhost:8000/ingest/batch \ -H "Content-Type: application/json" \ -d '[ { "timestamp": "2026-02-14T09:10:00Z", "source": "iam", "event_type": "auth_failed", "severity": 20, "user": "alice", "ip": "203.0.113.10", "message": "Failed login attempt" }, { "timestamp": "2026-02-14T09:11:00Z", "source": "edr", "event_type": "process_create", "severity": 50, "host": "WKS-12", "process": "cmd.exe", "message": "Suspicious command shell launched" } ]' ``` 请参阅 `examples/events.jsonl` 获取完整的端到端场景。 ## Runbook 模板 ### 模板系统 Runbook 位于 `runbooks/*.yml` 中。系统会根据 `incident_type` 选择模板，并自动填充字段占位符： - `{{ hosts_fmt }}` - 受影响主机的逗号分隔列表 - `{{ users_fmt }}` - 相关用户的逗号分隔列表 - `{{ ips_fmt }}` - IP 地址的逗号分隔列表 - `{{ processes_fmt }}` - 进程的逗号分隔列表 - `{{ domains_fmt }}` - 域名的逗号分隔列表 ### Runbook 模板示例 ``` --- name: "Credential Abuse Response" incident_types: - "credential_abuse" - "brute_force" steps: - id: "step_1" title: "Isolate Affected Hosts" description: "Immediately isolate {{ hosts_fmt }} from network" actions: - isolate_host - disable_network evidence_types: - auth_failed - login_success - id: "step_2" title: "Reset Compromised User Credentials" description: "Force password reset for users: {{ users_fmt }}" actions: - reset_password - invalidate_sessions evidence_types: - auth_success - id: "step_3" title: "Hunt for Lateral Movement" description: "Search for suspicious activity from {{ ips_fmt }}" actions: - hunt_lateral_movement evidence_types: - process_create - network_connection ``` ## 可选：本地 LLM (Ollama) 该系统完全可以脱离 LLM 运行。但是，如果您运行本地的 Ollama 服务器，则可以增强 playbook 生成： ### 设置 1. **在本地安装并运行 Ollama：** ``` # 在 macOS/Linux 上 curl https://ollama.ai/install.sh | sh ollama pull llama3.2:3b ollama serve # 在 Windows 上，从 https://ollama.ai 下载 ``` 2. **配置连接：** ``` export OLLAMA_BASE_URL="http://localhost:11434" export OLLAMA_MODEL="llama3.2:3b" ``` 或者在 Docker 中 (macOS)： ``` # docker-compose.yml services: api: environment: OLLAMA_BASE_URL: "http://host.docker.internal:11434" OLLAMA_MODEL: "llama3.2:3b" ``` ### 使用方法 ``` # 使用 LLM 重写生成 playbook curl -X POST http://localhost:8000/incidents/incident-123/playbook?mode=ollama ``` ### 限制措施 **重要：** 关联和评分是确定性的，绝不依赖于 LLM。LLM 仅重写 playbook 文本并起草叙述性描述——它不能影响核心的事件检测或排名逻辑。 ## 使用示例 ### 1. 摄取单个事件 ``` curl -X POST http://localhost:8000/ingest \ -H "Content-Type: application/json" \ -d '{ "timestamp": "2026-02-14T09:10:00Z", "source": "edr", "event_type": "process_create", "severity": 75, "host": "WKS-01", "process": "powershell.exe", "message": "Suspicious PowerShell execution" }' ``` ### 2. 检查服务健康状态 ``` curl http://localhost:8000/health ``` ### 3. 列出所有 incidents ``` curl http://localhost:8000/incidents ``` ### 4. 获取 Incident 详情 ``` curl http://localhost:8000/incidents/{incident_id} ``` ### 5. 触发调查 ``` curl -X POST http://localhost:8000/incidents/{incident_id}/investigate ``` ### 6. 生成 Playbook ``` # 标准 playbook curl -X POST http://localhost:8000/incidents/{incident_id}/playbook?mode=runbook # 带 LLM 增强（需要 Ollama） curl -X POST http://localhost:8000/incidents/{incident_id}/playbook?mode=ollama ``` ### 7. 语义搜索 ``` curl "http://localhost:8000/events/search?q=suspicious+powershell" ``` ## 故障排除 ### 数据库连接问题 **错误：** `Connection refused: postgresql://localhost/incident_response` **解决方案：** 确保 PostgreSQL 正在运行： ``` # Docker docker compose up -d # 本地 PostgreSQL sudo systemctl start postgresql # Linux brew services start postgresql # macOS ``` ### 端口已被占用 **错误：** `Address already in use: 0.0.0.0:8000` **解决方案：** 释放端口或使用其他端口： ``` # Linux/macOS：终止端口 8000 上的进程 sudo lsof -ti:8000 | xargs kill -9 # 或使用其他端口 export SERVER_PORT=8001 ``` ### 找不到 pgvector 扩展 **错误：** `pgvector extension not available for semantic search` **解决方案：** Docker Compose 会自动使用 `pgvector/pgvector:pg16`。对于本地设置： ``` # PostgreSQL 必须安装 pgvector 扩展 psql -U postgres -c "CREATE EXTENSION IF NOT EXISTS pgvector;" ``` ### Docker 构建失败 **解决方案：** 清理并重新构建： ``` docker compose down --volumes docker compose up --build ``` ## 贡献指南 欢迎贡献！请遵循以下指南： ### 如何贡献 1. Fork 本仓库 2. 创建功能分支：`git checkout -b feature/your-feature-name` 3. 进行更改并附带清晰的提交信息 4. 如适用，请添加测试 5. 提交带有清晰描述的 pull request ### 开发环境设置 ``` git clone https://github.com/yourusername/incident-response-agent.git cd incident-response-agent python -m venv .venv source .venv/bin/activate pip install -r requirements.txt ``` ### 代码风格 - 遵循 PEP 8 规范 - 为函数参数和返回值使用 type hints - 为函数和类添加 docstrings ### 测试 ``` # 运行测试 pytest # 带有覆盖率 pytest --cov=ir_agent ``` ## 许可证 本项目根据 MIT 许可证授权 - 有关详细信息，请参阅 [LICENSE](LICENSE) 文件。 ## 作者 - **Your Name** - 项目负责人和核心开发 - 欢迎贡献者！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) ## 支持 如有问题、疑问或建议： - **问题**：[GitHub Issues](https://github.com/yourusername/incident-response-agent/issues) - **电子邮件**：your.email@example.com - **文档**：完整的 API 文档可在 `http://localhost:8000/docs` (Swagger UI) 获取 ## 致谢 - pgvector 团队提供的语义搜索功能 - FastAPI 提供的 Web 框架 - PostgreSQL 提供的可靠数据存储 - 社区提供的反馈和贡献 **最后更新：** 2026 年 2 月

标签：AI安全, AI风险缓解, AV绕过, Chat Copilot, DLL 劫持, Docker, EDR, FastAPI, FOFA, HTTP/HTTPS抓包, IP 地址批量处理, IR系统, LLM, LLM评估, NIDS, Ollama, pgvector, PostgreSQL, PyOD, Python, SOAR, tsfresh, UEBA, Unmanaged PE, Web控制台, 事件关联, 人工智能, 向量数据库, 响应剧本, 大语言模型, 威胁关联, 子域名变形, 安全信息与事件管理, 安全图分析, 安全防御评估, 安全预案, 容器化, 开源, 异常检测, 态势感知, 插件系统, 搜索引擎爬取, 数据科学, 无后门, 日志摄取, 本地大模型, 测试用例, 用户实体行为分析, 用户模式Hook绕过, 确定性评分, 离线部署, 管理面板, 终端检测与响应, 网络安全, 网络安全审计, 脆弱性评估, 自动生成Runbook, 语义搜索, 请求拦截, 调查取证, 调查工作流, 资源验证, 逆向工具, 隐私保护, 风险评分