vasan06/Intelligent-Log-Forensics
GitHub: vasan06/Intelligent-Log-Forensics
一款基于 Flask 的 Web 日志取证平台，将多格式原始日志自动标准化、检测风险、映射 MITRE ATT&CK 并生成取证报告。
Stars: 0 | Forks: 0
# 智能日志取证
## 目录
1. [概述](#overview)
2. [业务问题](#business-problem)
3. [解决方案](#solution)
4. [核心能力](#core-capabilities)
5. [技术栈](#technology-stack)
6. [系统架构](#system-architecture)
7. [项目结构](#project-structure)
8. [处理工作流](#processing-workflow)
9. [功能参考](#feature-reference)
10. [风险分类](#risk-classification)
11. [MITRE ATT&CK 映射](#mitre-attck-mapping)
12. [数据库设计](#database-design)
13. [安装](#installation)
14. [PostgreSQL 配置](#postgresql-setup)
15. [配置说明](#configuration)
16. [运行应用](#running-the-application)
17. [用户指南](#user-guide)
18. [API 参考](#api-reference)
19. [认证与授权](#authentication-and-authorization)
20. [测试](#testing)
21. [运维指南](#operational-guidance)
22. [故障排除](#troubleshooting)
23. [安全注意事项](#security-considerations)
24. [可扩展性路线图](#scalability-roadmap)
25. [开发指南](#development-guidelines)
26. [已知限制](#known-limitations)
27. [术语表](#glossary)
## 概述
智能日志取证是一个基于 Web 的调查平台，用于处理
应用程序和基础设施日志。它将异构证据转换为
一致的分析模型，并展示运营故障、安全风险、
MITRE ATT&CK 映射、关联事件以及可下载的报告。
该平台专为以下用户设计：
- 调查可疑应用程序活动的安全分析师。
- 诊断 API、后端和前端故障的开发人员。
- 监控可靠性和响应时间下降的运维团队。
- 展示实际日志分析和网络取证的学术团队。
- 需要在不运行完整 SIEM 的情况下进行针对性分析的小型组织。
应用程序使用 PostgreSQL 作为其主要数据库。SQLite 仅被独立的
自动化测试配置使用。
## 业务问题
现代应用程序从身份验证服务、API 网关、
Web 服务器、数据库、前端 runtime 以及后台 worker 产生日志。这些日志
通常使用不同的字段名称和格式。手动分析速度缓慢，因为：
- 重要的证据分散在大文件中。
- 时间戳、身份、状态码和 endpoint 不一致。
- 运营故障和安全事件混合在一起。
- 单个事件无法解释完整的事件序列。
- 原始证据很少包含修复指导。
- 传统查看器只显示文本，但不解释其重要性。
企业级 SIEM 产品解决了此问题的部分内容，但对于小型团队和学术环境来说可能过于昂贵、
复杂或基础设施繁重。
## 解决方案
智能日志取证提供了一个端到端的证据工作流：
1. 接收 CSV、JSON、TXT 和 LOG 文件。
2. 验证上传的证据。
3. 根据源格式解析记录。
4. 将字段标准化为通用 schema。
5. 衡量数据质量和应用程序健康度。
6. 提取有用的行为和运营特征。
7. 应用可解释的风险检测规则。
8. 将安全发现映射到选定的 MITRE ATT&CK 技术。
9. 将相关发现关联到事件时间线中。
10. 通过 JSON API 展示实时仪表盘分析。
11. 生成可下载的 PDF 取证报告。
## 核心能力
| 能力 | 描述 |
| --- | --- |
| 多格式接入 | 处理 CSV、JSON、换行分隔 JSON、键值对文本以及常见的 Web 访问日志记录。 |
| Schema 标准化 | 映射备用字段名称，例如 `ip`、`client_ip`、`remote_addr`、`path`、`url` 和 `route`。 |
| 数据质量分析 | 衡量有效性、重复项、缺失时间戳和缺失源地址。 |
| 健康度评估 | 对服务器故障和缓慢的应用程序响应进行评分。 |
| 可解释的检测 | 每一项发现都包含类别、严重程度、分数、原因、证据和建议。 |
| 安全映射 | 将适用的发现映射到 MITRE ATT&CK 战略和技术。 |
| 事件关联 | 按源身份和风险类别对相关发现进行分组。 |
| 证据探索 | 提供可搜索和可过滤的标准化日志表。 |
| 实时分析 | 使用 JSON endpoint 和 Chart.js，无需全页面刷新仪表盘。 |
| PDF 报告 | 生成包含分数、发现、ATT&CK 映射和操作的便携式报告。 |
| 访问控制 | 使用 Flask-Login 和所有权检查来隔离分析师数据。 |
| PostgreSQL 持久化 | 存储用户、上传内容、证据、发现、映射、事件和报告。 |
## 技术栈
### 后端
- Python 3.10 或更高版本
- Flask 3
- Flask-SQLAlchemy
- Flask-Login
- Werkzeug 密码哈希
- psycopg2 PostgreSQL 驱动
- python-dotenv
- ReportLab
### 前端
- Jinja2 服务器渲染模板
- 语义化 HTML
- 响应式 CSS
- JavaScript Fetch API
- Chart.js
- Lucide 图标
### 数据与基础设施
- PostgreSQL 17
- SQLAlchemy ORM
- 本地文件系统证据和报告存储
- Python `unittest` 测试套件
## 系统架构
应用程序遵循分层模块化架构。
```
Browser / Analyst Interface
|
v
Jinja Page Routes + JSON API Routes
|
v
Application Service Layer
|
v
Forensic Engine Layer
|
v
Repository / SQLAlchemy Layer
|
v
PostgreSQL Database + Local Evidence Storage
```
### 前端层
渲染身份验证、仪表盘、上传、证据、事件和报告视图。
JavaScript 从受保护的 API 路由请求仪表盘指标，并在不重新加载整个页面的情况下更新图表。
### 路由层
Flask blueprint 将身份验证、上传、仪表盘、日志、事件、
报告和 API 分离。路由验证请求并将处理委托给服务。
### 服务层
服务协调完整的工作流，例如保存上传内容、运行
分析引擎、持久化结果、准备仪表盘指标以及生成
PDF 报告。
### 引擎层
引擎包含专注的取证逻辑：
- 解析
- 标准化
- 数据质量评分
- 特征提取
- 基于规则的风险检测
- 兼容 ML 的分类接口
- 异常检测接口
- MITRE 映射
- 时间线关联
- 建议生成
### 持久化层
SQLAlchemy 模型定义了关系数据模型。Repository 模块提供了
放置可重用数据库访问逻辑的位置。PostgreSQL 存储所有结构化的
应用程序状态。
### 存储层
上传的证据存储在 `instance/uploads` 下。生成的 PDF 报告
存储在 `instance/reports` 下。这些运行时文件被排除在 Git 之外。
## 项目结构
```
MAJOR-PROJECT/
|-- app/
| |-- engines/ # Parsing and forensic intelligence logic
| |-- knowledge_base/ # Local MITRE ATT&CK mapping data
| |-- models/ # SQLAlchemy entities
| |-- repositories/ # Reusable database queries
| |-- routes/ # Page and JSON API blueprints
| |-- services/ # Business workflow orchestration
| |-- static/
| | |-- css/ # Application visual system
| | `-- js/ # Dashboard and upload behavior
| |-- templates/ # Jinja2 interface templates
| |-- utils/ # Validation, security, and response helpers
| |-- __init__.py # Flask application factory
| `-- extensions.py # Shared Flask extensions
|-- instance/
| |-- reports/ # Generated PDF reports
| `-- uploads/ # Uploaded evidence files
|-- sample_logs/ # Demonstration evidence
|-- scripts/
| `-- setup_postgres.ps1 # PostgreSQL database initializer
|-- tests/ # Automated application tests
|-- .env.example # Configuration template
|-- config.py # Runtime configuration
|-- requirements.txt # Python dependencies
|-- run.py # Development entry point
`-- README.md # Technical documentation
```
## 处理工作流
```
Upload
-> Extension and size validation
-> Secure filename generation
-> File metadata persistence
-> Format-specific parsing
-> Common-schema normalization
-> Data quality analysis
-> Feature extraction
-> Explainable risk detection
-> MITRE ATT&CK mapping
-> Incident correlation
-> PostgreSQL transaction commit
-> Dashboard and evidence presentation
-> Optional PDF report generation
```
上传状态依次经历：
- `uploaded`：存在元数据且尚未开始处理。
- `processing`：取证引擎正在运行。
- `completed`：证据和分析结果已成功持久化。
- `failed`：处理已停止，并且 `error_message` 包含诊断详细信息。
## 功能参考
### 身份验证
应用程序在首次进行数据库
初始化且不存在用户时，会创建一个演示分析师：
```
Email: analyst@example.com
Password: analyst123
```
在任何非开发部署之前，请更改或删除此账户。
### 文件上传与验证
接受的扩展名：
- `.csv`
- `.json`
- `.txt`
- `.log`
默认的最大上传大小为 10 MB。上传的名称经过清理，并且
存储的文件名使用生成的 UUID 以防止冲突。
### 解析
解析器支持：
- 带有 header row 的 CSV 记录。
- JSON 对象数组。
- 包含 `logs`、`events`、`records` 或 `data` 数组的 JSON 对象。
- 每行一个 JSON 对象。
- 常见的 Apache 风格访问日志记录。
- 键值对记录，例如 `ip=10.0.0.1 status=401`。
- 带有时间戳的纯文本应用程序消息。
### 标准化
源字段将转换为此共享结构：
| 规范字段 | 示例别名 |
| --- | --- |
| `timestamp` | `time`, `datetime`, `date`, `@timestamp`, `created_at` |
| `source_ip` | `ip`, `ip_address`, `client_ip`, `remote_addr`, `host` |
| `user_identifier` | `user`, `user_id`, `username`, `email` |
| `method` | `http_method`, `verb` |
| `endpoint` | `path`, `url`, `route`, `request_uri` |
| `status_code` | `status`, `http_status`, `response_code` |
| `response_time` | `latency`, `duration`, `elapsed`, `response_ms` |
| `event_type` | `event`, `type`, `action` |
| `level` | `severity`, `log_level` |
| `message` | `msg`, `error`, `description`, `detail` |
响应时间统一标准化为毫秒。ISO 时间戳和常见的访问
日志时间戳格式在持久化之前将转换为 Python 的 datetime 对象。
### 数据质量得分
得分从 100 开始，并对以下情况应用权重惩罚：
- 无效记录
- 重复的原始记录
- 缺失时间戳
- 缺失源 IP 地址
得分范围限制在 0 到 100 之间。它衡量的是证据的可用性，而不是
应用程序的安全状态。
### 应用程序健康得分
健康得分评估运营症状，特别是：
- HTTP 5xx 响应
- 响应时间等于或超过 1000 毫秒
它被特意与安全风险得分分开。缓慢的 endpoint 是
一个运营问题，不应自动获得 MITRE 映射。
### 证据浏览器
证据视图显示标准化记录，包含：
- 时间戳
- 源地址
- HTTP 请求或事件名称
- 状态码
- 响应时间
- 风险评估
分析师可以搜索原始证据和 endpoint，或按状态码进行过滤。
### 事件时间线
风险事件按源 IP 和类别进行分组。每个事件记录：
- 事件标题
- 源 IP
- 受影响的用户（如果有）
- 开始和结束时间
- 汇总风险得分
- 严重程度
- 摘要
- 按时间顺序排列的事件
- 关联的 MITRE 战略和技术
### 仪表盘
仪表盘展示：
- 标准化记录总数
- 风险事件数
- 关联事件数
- 平均风险得分
- 风险类别分布
- MITRE 战略分布
- 七天错误趋势
- 风险最高的源 IP 地址
- 最近的上传历史
### PDF 报告
生成的报告包括：
- 证据源名称
- 日志计数
- 数据质量得分
- 应用程序健康得分
- 风险事件计数
- 事件计数
- 已区分优先级的发现
- MITRE ATT&CK 映射
- 建议的修复步骤
## 风险分类
检测是确定性和可解释的。这使得每个得分均可重现，
并且适合进行学术评估。
| 类别 | 示例信号 | 典型操作 |
| --- | --- | --- |
| 身份验证风险 | 重复的 HTTP 401 或 403 响应 | 对登录进行限流，启用 MFA，审查身份和 IP。 |
| API 路由风险 | 来自同一源的重复 HTTP 404 访问 | 审查探测行为并屏蔽已确认的自动化操作。 |
| 安全风险 | 明确的 XSS、SQL 注入、路径遍历或未经授权的访问指示 | 保留证据并立即调查。 |
| 运营风险 | HTTP 5xx 响应 | 检查 stack trace、依赖项和部署。 |
| 性能风险 | 响应时间达到或超过 1000 毫秒 | 分析 endpoint 并检查下游延迟。 |
| 前端 Runtime 风险 | JavaScript、hydration、未捕获异常或 TypeError 信号 | 使用 source map 复现并改善客户端遥测。 |
| 警告 | Error、critical 或 fatal 日志级别 | 结合上下文进行审查并监控复发情况。 |
### 严重性阈值
| 得分 | 严重程度 |
| --- | --- |
| 80-100 | Critical |
| 60-79.9 | High |
| 40-59.9 | Medium |
| 低于 40 | Low |
`ml_engine.py` 和 `anomaly_engine.py` 中的接口允许在不更改路由逻辑的情况下引入
训练过的模型或高级统计检测器。
## MITRE ATT&CK 映射
只有与安全相关的发现才会获得 ATT&CK 映射。
| 风险类别 | 战略 | 技术 |
| --- | --- | --- |
| 身份验证风险 | 凭证访问 | T1110 - 暴力破解 |
| API 路由风险 | | T1595 - 主动扫描 |
| 安全风险 | 初始访问 | T1190 - 利用面向公众的应用程序 |
映射经过刻意的保守处理。运营故障、性能
下降和前端 runtime 错误不会被强行归入 ATT&CK 类别。
本地映射知识库存储在以下位置：
```
app/knowledge_base/mitre_attack_mapping.json
```
## 数据库设计
PostgreSQL 存储以下实体。
### `users`
存储分析师身份和访问角色。
| 列 | 用途 |
| --- | --- |
| `id` | 主键 |
| `name` | 显示名称 |
| `email` | 唯一的登录标识符 |
| `password_hash` | Werkzeug 生成的密码哈希 |
| `role` | `analyst` 或 `admin` |
| `created_at` | 账户创建时间戳 |
| `last_login` | 最近一次成功登录时间 |
| `is_active_account` | 账户可用性标志 |
### `uploaded_files`
存储证据元数据、所有权、处理状态和记录总数。
### `normalized_logs`
存储标准化证据和原始记录。索引字段包括
`file_id` 和 `timestamp`，以实现高效的调查查询。
### `data_quality_results`
为每个上传的文件存储一个质量配置文件，包括质量和健康得分。
### `risk_events`
存储已分类的发现，包含得分、严重程度、原因、证据和建议。
### `mitre_mappings`
存储与安全风险事件关联的可选 ATT&CK 映射。
### `incidents`
存储关联的事件摘要和总体风险信息。
### `incident_events`
存储与事件关联的按时间顺序排列的事件详情。
### `reports`
存储生成的报告元数据和文件系统位置。
### 关系
```
users 1 ------ * uploaded_files
uploaded_files 1 ------ * normalized_logs
uploaded_files 1 ------ 1 data_quality_results
uploaded_files 1 ------ * risk_events
normalized_logs 1 ------ * risk_events
risk_events 1 ------ 0..1 mitre_mappings
uploaded_files 1 ------ * incidents
incidents 1 ------ * incident_events
uploaded_files 1 ------ * reports
```
通过 ORM 删除上传内容时，配置为级联删除其标准化
日志、质量结果、风险事件、关联事件和报告记录。
## 安装
### 前置条件
- Windows 10/11、Linux 或 macOS
- Python 3.10+
- PostgreSQL 17
- Git
- 现代浏览器
### 克隆并创建环境
```
git clone
cd MAJOR-PROJECT
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -r requirements.txt
```
对于命令提示符：
```
.venv\Scripts\activate.bat
```
对于 Linux 或 macOS：
```
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```
## PostgreSQL 配置
### 自动化 Windows 配置
必须安装 PostgreSQL 17 并且其服务必须正在运行。然后执行：
```
.\scripts\setup_postgres.ps1 -Password "your-postgresql-password"
```
可选参数：
```
.\scripts\setup_postgres.ps1 `
-Password "your-postgresql-password" `
-User "postgres" `
-Database "intelligent_log_forensics" `
-Port 5432
```
该脚本：
1. 在 `PATH` 或 `C:\Program Files\PostgreSQL` 下查找 `psql.exe`。
2. 对 PostgreSQL 服务器进行身份验证。
3. 如果 `intelligent_log_forensics` 不存在，则创建它。
4. 将应用程序连接 URL 写入 `.env`。
5. 将建表工作留给 Flask 应用工厂处理。
### 手动 PostgreSQL 配置
打开 pgAdmin Query Tool 或 `psql` 并运行：
```
CREATE DATABASE intelligent_log_forensics;
```
创建本地环境文件：
```
Copy-Item .env.example .env
```
编辑 `.env`：
```
DATABASE_URL=postgresql+psycopg2://postgres:YOUR_PASSWORD@localhost:5432/intelligent_log_forensics
```
如果密码包含诸如 `@`、`:`、`/` 或 `#` 等保留 URL 字符，
请对其进行 URL 编码。安装脚本会自动执行此编码。
### 验证 PostgreSQL
```
Get-Service postgresql*
```
预期状态：
```
Status Name
------ ----
Running postgresql-x64-17
```
应用程序在启动时调用 `db.create_all()`。这会创建缺失的表，
但并不能替代用于生产环境升级的版本化迁移策略。
## 配置说明
配置通过 `config.py` 从环境变量和 `.env` 加载。
| 变量 | 必填 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `FLASK_APP` | 否 | `run.py` | Flask CLI 应用程序入口点 |
| `SECRET_KEY` | 生产环境中必填 | 开发占位符 | 会话签名密钥 |
| `DATABASE_URL` | 是 | 本地 PostgreSQL URL | SQLAlchemy PostgreSQL 连接 URL |
| `UPLOAD_FOLDER` | 否 | `instance/uploads` | 上传的证据目录 |
| `REPORT_FOLDER` | 否 | `instance/reports` | 生成的报告目录 |
| `MAX_CONTENT_LENGTH` | 否 | `10485760` | 最大请求大小（以字节为单位） |
示例：
```
FLASK_APP=run.py
SECRET_KEY=replace-with-a-long-random-value
DATABASE_URL=postgresql+psycopg2://postgres:password@localhost:5432/intelligent_log_forensics
UPLOAD_FOLDER=instance/uploads
REPORT_FOLDER=instance/reports
MAX_CONTENT_LENGTH=10485760
```
生成安全的 secret key：
```
python -c "import secrets; print(secrets.token_hex(32))"
```
切勿提交 `.env`。它已被 `.gitignore` 排除。
## 运行应用程序
### 开发服务器
```
python run.py
```
打开：
```
http://127.0.0.1:5000
```
### Flask CLI
```
$env:FLASK_APP = "run.py"
flask run
```
### 首次登录
```
Email: analyst@example.com
Password: analyst123
```
### 演示数据集
上传：
```
sample_logs/security_incident.csv
```
它包含身份验证失败、路由探测、后端故障、缓慢的 API
响应、前端 runtime 错误以及一个正常请求。
## 用户指南
### 分析证据
1. 登录。
2. 选择 **Analyze logs**。
3. 拖放或浏览以查找受支持的文件。
4. 选择 **Start analysis**。
5. 查看质量、健康状况、发现结果和标准化证据。
### 过滤证据
1. 打开一个已完成的上传。
2. 输入 IP、endpoint、消息或原始证据关键词。
3. 可选择一个状态码。
4. 选择 **Filter**。
### 审查事件
1. 打开一个分析记录。
2. 选择 **Incidents**。
3. 查看严重程度、总风险、来源、事件顺序和 ATT&CK 映射。
### 生成报告
1. 打开一个分析记录。
2. 选择 **Report**。
3. 查看报告预览。
4. 选择 **Download PDF**。
## API 参考
所有 API endpoint 都需要经过身份验证的 Flask 会话。未经授权的请求
将被重定向到 `/auth/login`。分析师只能访问自己的上传 ID；
管理员可以访问所有上传内容。
### 仪表盘摘要
```
GET /api/dashboard/summary
```
响应：
```
{
"total_logs": 1250,
"risk_events": 43,
"incidents": 8,
"average_risk": 68.4
}
```
### 风险分布
```
GET /api/dashboard/risk-distribution
```
响应：
```
{
"Authentication Risk": 12,
"Operational Risk": 19,
"Performance Risk": 7
}
```
### MITRE 统计信息
```
GET /api/dashboard/mitre-stats
```
响应：
```
{
"Credential Access": 8,
"Discovery": 4
}
```
### 错误趋势
```
GET /api/dashboard/error-trends
```
响应：
```
{
"labels": ["2026-06-26", "2026-06-27", "2026-06-28"],
"values": [3, 7, 4]
}
```
生产环境的响应包含七个每日标签和值。
### 高风险 IP 地址
```
GET /api/dashboard/top-risky-ips
```
响应：
```
[
{
"ip": "203.0.113.42",
"events": 4,
"score": 82.0
}
]
```
### 事件时间线
```
GET /api/dashboard/timeline/{file_id}
```
响应：
```
[
{
"id": 1,
"title": "Authentication Risk from 203.0.113.42",
"severity": "Critical",
"score": 82.0,
"start": "2026-07-01T10:00:00",
"end": "2026-07-01T10:00:13"
}
]
```
### 上传状态
```
GET /api/upload/status/{file_id}
```
响应：
```
{
"status": "completed",
"total_records": 13,
"error": null
}
```
### 过滤日志
```
GET /api/logs/filter?file_id=1&status=401
```
查询参数：
| 参数 | 类型 | 必填 | 描述 |
| --- | --- | --- | --- |
| `file_id` | 整数 | 是 | 上传文件的标识符 |
| `status` | 整数 | 否 | 精确的 HTTP 状态码 |
响应：
```
[
{
"id": 1,
"timestamp": "2026-07-01T10:00:00",
"source_ip": "203.0.113.42",
"endpoint": "/auth/login",
"status_code": 401,
"response_time": 142.0,
"message": "Invalid password"
}
]
```
### 事件
```
GET /api/incidents/{file_id}
```
响应：
```
[
{
"id": 1,
"title": "Authentication Risk from 203.0.113.42",
"severity": "Critical",
"score": 82.0,
"summary": "4 related authentication risk event(s) were correlated."
}
]
```
### 页面和操作路由
| 方法 | 路由 | 用途 |
| --- | --- | --- |
| `GET`, `POST` | `/auth/login` | 对用户进行身份验证 |
| `GET` | `/auth/logout` | 结束当前会话 |
| `GET` | `/dashboard` | 渲染分析师仪表盘 |
| `GET` | `/admin/dashboard` | 将管理员重定向到仪表盘 |
| `GET`, `POST` | `/upload` | 渲染接收界面或处理证据 |
| `GET` | `/upload/history` | 显示可访问的上传记录 |
| `GET` | `/logs/{file_id}` | 显示标准化证据 |
| `GET` | `/incidents/{file_id}` | 显示关联的时间线 |
| `GET` | `/reports/{file_id}` | 预览报告内容 |
| `POST` | `/reports/generate/{file_id}` | 生成并下载 PDF |
| `GET` | `/reports/download/{report_id}` | 下载现有报告 |
### 错误行为
- `302`：未经验证的请求被重定向到登录页面。
- `403`：经过验证的用户尝试访问其他分析师的数据。
- `404`：上传内容或报告不存在。
- `413`：上传内容超过 `MAX_CONTENT_LENGTH`。
- `500`：意外的解析、持久化或报告错误。
## 认证与授权
Flask-Login 管理会话身份验证。密码从不直接存储；
Werkzeug 存储加盐密码哈希。
授权规则：
- 分析师可以上传文件并访问自己的证据、事件和报告。
- 管理员可以访问属于所有用户的记录。
- 在返回页面或 API 数据之前会检查所有权。
- API 路由使用与 Web 界面相同的经过身份验证的会话。
当前项目包含基于角色的访问控制，但不包含完整的管理员
用户管理界面。
## 测试
运行完整的测试套件：
```
python -m unittest discover -s tests -v
```
运行语法编译检查：
```
python -m compileall app tests run.py config.py
```
测试使用隔离的内存 SQLite 数据库。这可以防止测试数据
修改 PostgreSQL 开发数据库，同时保留 SQLAlchemy 的行为。
当前的自动化覆盖率验证了：
- 初始演示用户的创建
- 成功的身份验证
- 仪表盘渲染
- Multipart 证据上传
- CSV 解析和标准化
- 身份验证和操作风险检测
- 事件关联
- 仪表盘摘要 API 输出
- 事件 API 输出
为了进行版本发布验证，还应使用专用的测试数据库执行 PostgreSQL 集成冒烟测试。
## 运维指南
### 运行时目录
确保应用程序进程有权写入：
```
instance/uploads
instance/reports
```
### 数据库备份
PostgreSQL 备份示例：
```
& "C:\Program Files\PostgreSQL\17\bin\pg_dump.exe" `
-U postgres `
-d intelligent_log_forensics `
-F c `
-f intelligent_log_forensics.backup
```
恢复到现有的空数据库：
```
& "C:\Program Files\PostgreSQL\17\bin\pg_restore.exe" `
-U postgres `
-d intelligent_log_forensics `
--clean `
intelligent_log_forensics.backup
```
### 证据保留
数据库记录和文件系统证据必须一起保留或删除。
删除数据库上传记录不会自动从磁盘中擦除原始文件
或生成的 PDF。生产部署应添加经过审计的保留
任务，并设定符合法律和组织规定的保留期限。
### 日志与监控
对于生产环境，请将应用程序日志转发到集中目标位置并监控：
- HTTP 错误率
- 上传失败率
- 处理持续时间
- 数据库连接饱和度
- 证据存储利用率
- 身份验证失败
- 报告生成失败
## 故障排除
### PostgreSQL 连接被拒绝
检查服务：
```
Get-Service postgresql*
Start-Service postgresql-x64-17
```
确认预期端口：
```
Get-NetTCPConnection -LocalPort 5432
```
### 密码验证失败
使用 `psql` 验证用户名和密码：
```
$env:PGPASSWORD = "your-password"
& "C:\Program Files\PostgreSQL\17\bin\psql.exe" `
-h localhost -p 5432 -U postgres -d postgres -c "SELECT version();"
Remove-Item Env:PGPASSWORD
```
然后重新运行：
```
.\scripts\setup_postgres.ps1 -Password "your-password"
```
### 数据库不存在
```
CREATE DATABASE intelligent_log_forensics;
```
或者使用安装脚本。
### 密码包含特殊字符
请使用会自动对密码进行 URL 编码的安装脚本。如果手动编辑 `.env`，
请先将保留字符进行编码，然后再将密码放入 `DATABASE_URL`。
### 端口 5000 已被占用
```
$env:FLASK_RUN_PORT = 5001
flask run
```
然后打开 `http://127.0.0.1:5001`。
### 上传被拒绝
确认：
- 扩展名为 CSV、JSON、TXT 或 LOG。
- 文件小于 `MAX_CONTENT_LENGTH`。
- 上传目录可写。
- CSV 文件包含 header row。
- JSON 内容是有效的 UTF-8 JSON 或换行分隔 JSON。
### 仪表盘图表为空
- 至少分析一个证据文件。
- 确认仪表盘 API 请求返回 HTTP 200。
- 确保浏览器可以加载 Chart.js。
- 检查浏览器开发者控制台是否存在网络错误。
### PDF 生成失败
- 确认已安装 ReportLab。
- 确认 `instance/reports` 可写。
- 检查关联的上传内容是否仍然存在。
- 查看 Flask 控制台以获取有关 ReportLab 的异常信息。
## 安全注意事项
在本地开发之外的部署之前：
1. 替换开发环境的 `SECRET_KEY`。
2. 更改或删除演示分析师密码。
3. 仅通过 HTTPS 提供应用程序服务。
4. 为表单添加 CSRF 保护。
5. 应用登录速率限制和账户锁定策略。
6. 使用 MIME 和结构检查来验证上传的内容，而不仅仅是检查扩展名。
7. 将证据存储在公开提供的静态目录之外。
8. 限制上传和报告的文件系统权限。
9. 使用具有最低权限的专用 PostgreSQL 角色。
10. 轮换数据库凭证和密钥。
11. 在需要时为上传的证据添加恶意软件扫描。
12. 添加针对登录、上传、报告和管理操作的审计日志。
13. 配置安全的 session cookie。
14. 通过应用程序或反向代理添加安全 header。
15. 建立证据保留和删除策略。
推荐的生产环境 cookie 设置：
```
SESSION_COOKIE_SECURE = True
SESSION_COOKIE_HTTPONLY = True
SESSION_COOKIE_SAMESITE = "Lax"
```
## 可扩展性路线图
### 当前架构
- Flask 应用工厂
- Jinja2 前端
- 同步处理
- PostgreSQL 持久化
- 本地文件系统存储
- 可轮询的 JSON API
### 推荐的发展路径
#### 后台处理
将解析和分析移至 Celery 或 RQ worker 中。使用 Redis 作为任务 broker，
并保留现有的 `processing_status` API 以进行进度更新。
#### 对象存储
使用兼容 S3 的对象存储替换本地上传和报告存储。在 PostgreSQL 中存储
object key 和完整性哈希值。
#### 数据库迁移
在将 schema 更改应用于共享数据库之前，添加 Flaskigrate 和 Alembic。
#### 检测框架
引入版本化检测规则、训练有素的 scikit-learn pipeline、特征模型
元数据、置信度校准以及分析师反馈。
#### 准实时更新
在运营需求证明持久连接合理的情况下，使用 Server-Sent Events 或 WebSocket 替换定期的仪表盘获取请求。
#### API 分离
仅在独立部署或外部集成变得必要时，才公开版本化的 REST API 并将前端移至单独的客户端。
#### 企业身份
针对受监管环境，添加 OpenID Connect 或 SAML、组织租户、细粒度权限和审计
日志记录。
## 开发指南
### 添加解析器
1. 在 `app/engines/parser_engine.py` 中添加格式检测。
2. 返回一个字典列表。
3. 尽可能将原始记录保留在 `raw_log` 中。
4. 添加代表性的 fixture 和测试。
5. 确认格式错误的记录能够安全失败。
### 添加标准化字段别名
更新 `app/engines/normalizer_engine.py` 中的 `ALIASES`。保持规范名称稳定，
因为数据库模型、模板和检测规则都依赖于它们。
### 添加检测规则
1. 在 `rule_engine.py` 中添加条件和解释。
2. 选择合适的类别和分数。
3. 添加修复建议。
4. 仅当行为与安全相关时才添加 MITRE 映射。
5. 添加正面和负面测试，以防止误报回归。
### 添加 API Endpoint
1. 将仪表盘或证据 JSON 路由放置在 `api_routes.py` 中。
2. 要求进行身份验证。
3. 强制执行上传所有权检查。
4. 返回稳定且有文档记录的 JSON 字段。
5. 添加针对成功、未经授权和资源缺失情况的测试。
### 代码质量期望
- 保持路由精简，并将工作流保留在服务中。
- 将取证决策保留在引擎中。
- 避免在模板中进行数据库查询。
- 保留原始证据以实现可解释性。
- 将运营分类和安全分类分开。
- 使用参数化 ORM 查询。
- 根据行为风险程度相应地添加测试。
## 已知限制
- 处理是同步的，可能会延迟大型上传。
- 规则引擎是一个透明的基础版本，而不是训练有素的生产模型。
- 事件分组目前使用源 IP 和风险类别。
- 所选的 MITRE 知识库被刻意限制。
- admin 路由尚未提供完整的用户管理功能。
- 仪表盘使用定期 API 请求，而不是流式更新。
- Runtime 证据使用本地文件系统存储。
- `db.create_all()` 不提供版本化的 schema 迁移。
- 文件验证目前主要依赖于扩展名和解析器行为。
- 自动化测试使用 SQLite；应为 CI 添加 PostgreSQL 集成测试。
## 术语表
| 术语 | 含义 |
| --- | --- |
| Evidence（证据） | 用于分析的原始或标准化日志记录。 |
| Finding（发现） | 由检测规则生成的风险事件。 |
| Incident（事件） | 一组相关联的发现的集合。 |
| Normalization（标准化） | 将特定于源的字段转换为通用 schema。 |
| Data quality score（数据质量得分） | 对证据完整性和一致性的衡量。 |
| Health score（健康得分） | 对应用程序可靠性和性能的衡量。 |
| Risk score（风险得分） | 从 0 到 100 对发现重要性的数值估计。 |
| MITRE ATT&CK | 对抗战术和技术的知识库。 |
| Tactic（战略） | 对手的高层级目标。 |
| Technique（技术） | 用于实现对手目标的方法。 |
| SIEM | 安全信息与事件管理平台。 |
## 项目状态
该代码库包含一个功能完备的、面向学术和小型团队的 MVP。身份验证、
多格式处理、质量评估、可解释的检测、ATT&CK 映射、
事件关联、仪表盘分析和 PDF 报告功能均已实现。
推荐的生产环境下一个里程碑是 PostgreSQL 集成测试、
采用 Flask-Migrate、CSRF 保护、后台处理以及加强
上传验证。
标签：Cloudflare, MITRE ATT&CK, Mutation, 可视化, 安全运营, 扫描框架, 数字取证, 测试用例, 自动化脚本, 逆向工具