K413MP3R4/CyberSentinel
GitHub: K413MP3R4/CyberSentinel
CyberSentinel 是一款开源的 Linux 防御性入侵检测与安全信息事件管理系统，通过分析日志文件检测安全威胁。
Stars: 0 | Forks: 0
# CyberSentinel 🛡️
[](https://python.org)
[](https://fastapi.tiangolo.com)
[](LICENSE)
[](Dockerfile)
## 概述
CyberSentinel 是一款开源的防御性安全工具，它能监控 Linux 系统日志、检测可疑行为，并通过 REST API 和实时 Web 仪表板暴露警报。
它专为**系统管理员、安全学习者和蓝队实践者**设计，旨在让他们无需部署完整的企业级 SIEM 就能洞察其 Linux 机器上发生的情况。
### 检测能力
| 检测规则 | 等级 | 描述 |
|---|---|---|
| SSH 暴力破解 | `高` | 来自同一 IP 的 N 次失败的 SSH 登录 |
| 无效用户登录 | `中` | 使用不存在的用户名进行的登录尝试 |
| Sudo 失败 | `高` | 未授权或失败的 sudo 命令 |
| Sudo 执行 | `低` | 通过 sudo 执行的特权命令 |
| 密码修改 | `中` | 检测到系统密码被修改 |
| 事件激增 | `严重` | 在短时间内出现异常事件密度 |
## 架构
```
┌──────────────────────────────────────────────────────┐
│ CyberSentinel │
│ │
│ ┌─────────────┐ ┌──────────────┐ │
│ │ log_parser │───▶│ detector │ │
│ │ (regex) │ │ (5 rules) │ │
│ └─────────────┘ └──────┬───────┘ │
│ │ AlertCreate │
│ ┌──────▼───────┐ │
│ │ file_monitor│ │
│ │ (DB writer) │ │
│ └──────┬───────┘ │
│ │ │
│ ┌─────────────▼──────────────┐ │
│ │ SQLite DB │ │
│ └─────────────┬──────────────┘ │
│ │ │
│ ┌─────────────▼──────────────┐ │
│ │ FastAPI REST API │ │
│ │ /alerts /stats /health │ │
│ └─────────────┬──────────────┘ │
│ │ │
│ ┌─────────────▼──────────────┐ │
│ │ Dashboard (Jinja2 + │ │
│ │ TailwindCSS + JS) │ │
│ └────────────────────────────┘ │
│ │
│ Optional: Discord webhook notifier │
└──────────────────────────────────────────────────────┘
```
## 技术栈
- **后端**: Python 3.12 + FastAPI + Uvicorn
- **数据库**: SQLite (通过 SQLAlchemy ORM)
- **仪表板**: Jinja2 + TailwindCSS CDN + Vanilla JS
- **检测**: 纯 Python 正则表达式规则，无外部依赖
- **通知**: Discord webhook (可选)
- **测试**: pytest
- **部署**: Docker + docker-compose
## 安装 — 本地
### 要求
- Python 3.12+
- pip
### 步骤
```
# 1. 克隆仓库
git clone https://github.com/K413MP3R4/CyberSentinel.git
cd CyberSentinel
# 2. 创建虚拟环境
python -m venv .venv
source .venv/bin/activate # Linux/macOS
.venv\Scripts\activate # Windows
# 3. 安装依赖
pip install -r requirements.txt
# 4. 配置环境（可选）
cp .env.example .env
# 编辑 .env 文件以设置 LOG_FILE_PATH、DISCORD_WEBHOOK_URL 等。
# 5. 启动 API + 仪表板
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```
在浏览器中打开 [http://localhost:8000](http://localhost:8000)。
## 演示模式
该仓库包含 `sample_logs/auth.log` — 一个逼真的合成日志文件，内含 SSH 暴力破解尝试、无效用户登录、sudo 命令和一个事件激增示例。
```
# 运行示例日志文件分析
curl -X POST http://localhost:8000/alerts/analyze
# 或在仪表板中点击“运行分析”
```
这将立即生成几个逼真的警报。
## 安装 — Docker
```
# 构建并启动
docker-compose up --build -d
# 查看日志
docker-compose logs -f
# 停止
docker-compose down
```
容器暴露端口 `8000`。SQLite 数据库和日志文件通过挂载卷实现持久化。
可选的 Discord 通知配置：
```
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/xxx docker-compose up -d
```
## API 端点
| 方法 | 端点 | 描述 |
|---|---|---|
| `GET` | `/` | Web 仪表板 |
| `GET` | `/health/` | 服务健康检查 |
| `GET` | `/alerts/` | 列出所有警报（支持 `?level=high&status=new&limit=50`） |
| `GET` | `/alerts/{id}` | 根据 ID 获取警报 |
| `POST` | `/alerts/{id}/review` | 将警报标记为已审阅 |
| `POST` | `/alerts/{id}/ignore` | 将警报标记为已忽略 |
| `POST` | `/alerts/analyze` | 触发日志分析（生成新警报） |
| `GET` | `/stats/` | 汇总统计信息 |
| `GET` | `/docs` | 交互式 Swagger UI |
### API 调用示例
```
# 获取所有高严重性警报
curl http://localhost:8000/alerts/?level=high
# 获取统计数据
curl http://localhost:8000/stats/
# 触发分析
curl -X POST http://localhost:8000/alerts/analyze
# 将警报 #3 标记为已审核
curl -X POST http://localhost:8000/alerts/3/review
```
### 示例警报载荷
```
{
"id": 1,
"title": "SSH Brute-Force detected from 172.16.254.1",
"description": "22 failed SSH login attempts from 172.16.254.1. Possible brute-force attack.",
"level": "high",
"event_type": "ssh_bruteforce",
"source_ip": "172.16.254.1",
"timestamp": "2026-05-17T09:00:21",
"status": "new",
"raw_line": "May 17 09:00:21 webserver sshd[4020]: Failed password for root from 172.16.254.1 port 11129 ssh2"
}
```
## 运行测试
```
pytest tests/ -v
```
预期输出：
```
tests/test_parser.py::test_parse_valid_ssh_fail PASSED
tests/test_parser.py::test_parse_invalid_user PASSED
tests/test_parser.py::test_parse_sudo PASSED
tests/test_parser.py::test_parse_empty_line PASSED
tests/test_parser.py::test_parse_malformed_line PASSED
tests/test_parser.py::test_parse_file_demo PASSED
tests/test_detector.py::test_detect_ssh_bruteforce PASSED
tests/test_detector.py::test_detect_invalid_user PASSED
tests/test_detector.py::test_detect_sudo_fail PASSED
tests/test_detector.py::test_no_bruteforce_below_threshold PASSED
tests/test_detector.py::test_detect_from_sample_logs PASSED
tests/test_api.py::test_health PASSED
tests/test_api.py::test_get_alerts_empty PASSED
tests/test_api.py::test_stats_empty PASSED
tests/test_api.py::test_get_alert_not_found PASSED
tests/test_api.py::test_analyze_and_get_alerts PASSED
```
## 配置
所有设置均从 `.env` 加载（参见 `.env.example`）：
| 变量 | 默认值 | 描述 |
|---|---|---|
| `LOG_FILE_PATH` | `sample_logs/auth.log` | 要监控的日志文件路径 |
| `DISCORD_WEBHOOK_URL` | _(空)_ | 用于通知的 Discord webhook URL |
| `SSH_FAIL_THRESHOLD` | `5` | 触发暴力破解警报前的 SSH 失败次数 |
| `EVENT_SPIKE_THRESHOLD` | `20` | 触发激增警报前的窗口内事件数 |
| `EVENT_SPIKE_WINDOW_SECONDS` | `60` | 激增检测的时间窗口（秒） |
| `DATABASE_URL` | `sqlite:///./cybersentinel.db` | SQLAlchemy 数据库 URL |
| `API_PORT` | `8000` | 监听端口 |
## 项目结构
```
cybersentinel/
├── app/
│ ├── main.py # FastAPI entrypoint
│ ├── config.py # Settings (pydantic-settings)
│ ├── database.py # SQLAlchemy engine + session
│ ├── models.py # Alert ORM model
│ ├── schemas.py # Pydantic schemas
│ ├── services/
│ │ ├── log_parser.py # Regex-based auth.log parser
│ │ ├── detector.py # Detection rules engine
│ │ ├── notifier.py # Discord webhook notifier
│ │ └── file_monitor.py # Analysis orchestrator
│ ├── routes/
│ │ ├── alerts.py # /alerts endpoints
│ │ ├── stats.py # /stats endpoint
│ │ └── health.py # /health endpoint
│ └── templates/
│ └── dashboard.html # Web UI
├── sample_logs/
│ └── auth.log # Demo log file
├── tests/
│ ├── test_parser.py
│ ├── test_detector.py
│ └── test_api.py
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
├── .env.example
└── LICENSE
```
## 路线图
- [x] V1 — 日志解析、检测、REST API、仪表板、Docker、Discord 通知
- [ ] V2 — 实时文件监控 (`watchdog`)，对新日志行自动分析
- [ ] V3 — 防火墙集成 (iptables/ufw) — 可选 IP 封锁（需管理员确认）
- [ ] V4 — 按时间段生成 PDF 报告
- [ ] V5 — 跨会话的 IP/用户风险评分
- [ ] V6 — 管理员身份验证 (JWT)
- [ ] V7 — 多代理支持（从一个仪表板监控多台机器）
- [ ] V8 — 每个警报的 MITRE ATT&CK 战术标记
## 法律与道德免责声明
**CyberSentinel 严格是一款防御性安全工具。**
- 它仅读取日志文件 — 不会修改系统状态、发送网络数据包或与其他机器交互。
- 它不执行暴力破解、扫描、利用或任何攻击性安全操作。
- 它旨在用于您拥有或有权监控的系统。
- 在您不拥有的系统上未经授权使用可能违反当地法律（如 CFAA、GDPR 等）。
作者对滥用此软件不承担任何责任。
## 许可证
MIT 许可证 — 版权所有 (c) 2026 [K413MP3R4](https://github.com/K413MP3R4)
完整文本请参阅 [LICENSE](LICENSE)。
标签：CSV导出, Docker容器, FastAPI框架, Python编程, REST API, SSH安全, TailwindCSS, Web仪表板, 免杀技术, 入侵检测系统, 安全信息与事件管理, 安全数据湖, 安全检测规则, 搜索引擎爬取, 攻击面发现, 暴力破解检测, 网络安全, 网络测绘, 请求拦截, 逆向工具, 隐私保护