R0SH1009/soc-log-analysis-tool
GitHub: R0SH1009/soc-log-analysis-tool
一个用 Python 编写的防御性网络安全日志分析工具，能够解析 Web 和身份验证日志、检测可疑活动并生成警报与 HTML 报告，模拟初级 SOC 分析人员的工作流程。
Stars: 0 | Forks: 0
# SOC 日志分析工具
## 概述
SOC 日志分析工具是一个防御性网络安全项目，它可以解析示例 Web 访问日志和 Linux 风格的身份验证日志，检测可疑行为，生成安全警报，并创建对分析人员友好的报告。
其目标是使用 Python 模拟初级 SOC 分析人员的工作流程：收集日志证据、识别风险活动、记录发生的事件，并生成可供其他分析人员审查的清晰输出结果。
## 项目重要性
本项目直接对应初级 SOC 分析人员的工作内容：
* 审查与安全相关的事件日志
* 识别可疑的登录行为
* 发现暴力破解模式
* 识别可疑的 Web 请求
* 通过警报详情和证据记录调查结果
* 生成分析人员风格的报告以供审查
本项目纯粹出于防御和教育目的。这些示例日志用于练习调查习惯，而不会触及真实系统。
## 功能
* 访问日志解析
* 身份验证日志解析
* 可疑活动检测
* 暴力破解模式检测
* 警报生成
* JSONL 警报输出
* HTML 报告生成
* 命令行界面
* Pytest 测试套件
* 示例日志和示例报告
## 项目结构
```
log-analysis-tool/
|-- analyze.py
|-- alerting/
| |-- __init__.py
| `-- alert_manager.py
|-- config/
| |-- __init__.py
| `-- settings.py
|-- detectors/
| |-- __init__.py
| |-- brute_force.py
| |-- failed_logins.py
| |-- geo_anomaly.py
| |-- mfa_monitor.py
| |-- phishing_and_cookies.py
| `-- web_anomalies.py
|-- parsers/
| |-- __init__.py
| |-- auth_log_parser.py
| `-- web_log_parser.py
|-- reporting/
| |-- __init__.py
| `-- html_report.py
|-- sample_logs/
| |-- access.log
| `-- auth.log
|-- sample_reports/
| |-- access_alerts.jsonl
| |-- access_report.html
| |-- auth_alerts.jsonl
| `-- auth_report.html
|-- tests/
| |-- __init__.py
| `-- test_detectors.py
`-- TASKS.md
```
## 环境设置
在项目文件夹中使用 Windows PowerShell。
如果从 GitHub 克隆：
```
git clone
cd log-analysis-tool
```
如果项目已经存在于你的计算机上：
```
cd "C:\Users\ruben\OneDrive\soc\log-analysis-tool"
```
创建并激活虚拟环境：
```
python -m venv .venv
.\.venv\Scripts\Activate.ps1
```
目前这个代码仓库中没有 `requirements.txt` 或 `pyproject.toml`。该工具本身使用 Python 标准库。安装 `pytest` 以运行测试套件：
```
python -m pip install --upgrade pip
python -m pip install pytest
```
## 运行测试
在项目根目录下运行测试套件：
```
python -m pytest
```
预期状态：
* `39/39` 个测试通过
测试涵盖了解析器、检测器、警报处理、JSONL 输出以及 HTML 报告生成。
## 运行工具
命令行入口是 `analyze.py`。
分析示例 Web 访问日志并将输出写入 `sample_reports/`：
```
python .\analyze.py --file .\sample_logs\access.log --type web --json .\sample_reports\access_alerts.jsonl --report .\sample_reports\access_report.html --no-color
```
分析示例身份验证日志并将输出写入 `sample_reports/`：
```
python .\analyze.py --file .\sample_logs\auth.log --type auth --year 2026 --json .\sample_reports\auth_alerts.jsonl --report .\sample_reports\auth_report.html --no-color
```
你也可以让工具自动检测日志类型：
```
python .\analyze.py --file .\sample_logs\access.log --type auto --report .\sample_reports\access_report.html
```
注意：当发现 HIGH 或 CRITICAL 级别的警报时，`analyze.py` 将以非零状态退出。此行为是故意的，对于 CI 或自动化检查非常有用。
## 输出结果
该工具可以生成：
* 控制台警报摘要
* 使用 `--json` 生成的 JSON Lines 警报文件
* 使用 `--report` 生成的 HTML 报告
示例输出存储在：
```
sample_reports/
|-- access_alerts.jsonl
|-- access_report.html
|-- auth_alerts.jsonl
`-- auth_report.html
```
JSONL 文件适用于结构化的警报审查或下游工具集成。HTML 报告专为生成人类易读的 SOC 风格文档而设计。
## 展示的技能
* Python
* 日志解析
* 防御性网络安全
* 检测逻辑
* 警报生成
* 报告生成
* 命令行工具
* Pytest
* 文档编写
* SOC 调查工作流程
## 作品集 / 简历价值
这个项目可以被描述为一个防御性网络安全实验室，它模拟了 SOC 日志审查和警报报告。它展示了你编写用于安全运营的 Python 工具、解析真实日志、检测可疑行为、生成对分析人员友好的证据以及通过自动化测试验证工作的能力。
简历描述示例：
## 负责任的使用
本项目仅用于防御性网络安全教育、SOC 分析人员练习和作品集开发。
标签：AMSI绕过, Python, 多模态安全, 威胁检测, 安全运营, 扫描框架, 文档结构分析, 无后门, 红队行动, 逆向工具