Akash-2615/credguard-ai

# CredGuard AI — 凭据填充检测系统 CredGuard AI 使用机器学习异常检测技术，从登录活动日志中检测**凭据填充**（credential stuffing）攻击。它将每个 IP 的风险评分定为 **NORMAL**（正常）、**SUSPICIOUS**（可疑）或 **ATTACK**（攻击），并在实时仪表板中展示结果。 ## 什么是凭据填充？ 攻击者获取泄露的用户名/密码对，并使用脚本（机器人）在你的登录页面上进行尝试。典型特征包括： - 单个 IP 尝试**许多不同的用户名** - 尝试速度极快（间隔不到一秒或几秒） - 高失败率 - 非浏览器 user agent（如 `curl`、`python-requests` 等） - 通常为非工作时间流量 本实验构建了一个完整的流水线：合成数据 → 特征工程 → ML 模型 → Flask API → Web 仪表板。 ## 项目结构 ``` credential_stuffing/ ├── generate_dataset.py # Creates synthetic login logs ├── train.py # Feature engineering + model training ├── create_sample_logs.py # Extra CSV samples for upload testing ├── app.py # Flask backend (port 5003) ├── index.html # Dashboard UI ├── app.js # Frontend logic ├── style.css # Styles ├── data/ │ └── login_logs.csv # Main training / demo dataset ├── models/ │ ├── iso_forest.pkl # Isolation Forest │ ├── lof_model.pkl # Local Outlier Factor │ ├── scaler.pkl # StandardScaler │ └── feature_cols.pkl # Feature column names └── sample_logs/ # Ready-made CSVs to upload ├── heavy_attack_log.csv ├── stealth_attack_log.csv ├── mixed_scenario_log.csv └── normal_traffic_log.csv ``` ## 工作原理（从上到下） ### 1. 数据集生成 (`generate_dataset.py`) 创建包含以下内容的 `data/login_logs.csv`： | 流量类型 | 行为特征 | |---------|----------| | **Normal** | 真实浏览器，每个 IP 用户数少，节奏较慢，多在白天 | | **Credential stuffing 突发** | 少量 IP，大量用户名，机器人 user agent，快速重试，非工作时间 | | **代理轮换攻击** | 相同的机器人行为模式分散在不同的代理 IP 上 | 每行数据包括：`timestamp`、`ip_address`、`username`、`user_agent`、`endpoint`、`country`、`success`、`response_ms` 和 `is_attack`（仅用于训练的标签）。 ### 2. 特征工程 (`train.py`) 模型**不会**对单次登录进行评分。系统会**按 IP 在 60 分钟的滚动时间窗口内**聚合活动行为： | 特征 | 含义 | 重要性说明 | |---------|---------|----------------| | `attempts_last_1h` | 来自该 IP 的登录次数 | 攻击者会疯狂请求 endpoint | | `failure_rate` | 失败登录的百分比 | 凭据填充尝试大多会失败 | | `uniq_users_1h` | 不同用户名的数量 | 经典的凭据填充信号 | | `uniq_agents_1h` | 不同 user-agent 的数量 | 机器人通常只使用一种 agent | | `inter_arrival_s` | 尝试之间的间隔时间 | 人类会停顿；机器人速度很快 | | `avg_resp_ms` | 平均响应时间 | 脚本流量特征 | | `is_offhours` | 夜间 / 异常时段 | 常见的攻击时间窗口 | | `is_fast` | 间隔时间 < 3 秒 | 强烈的机器人标志 | | `is_bot_agent` | 类似脚本的 UA | 不是正常的浏览器 | ### 3. 模型 (`train.py` → `models/`) 1. **StandardScaler** — 规范化特征数据尺度 2. **Isolation Forest**（占 ensemble 的 60%）— 查找罕见 / 极端的 IP 3. **Local Outlier Factor**（占 40%）— 查找相对于邻居的密度异常点 4. **集成风险评分（Ensemble risk score）** → 0–100，然后得出结论： | 风险评分 | 判定结果 | |------------|---------| | ≥ 65 | **ATTACK** | | 35–64 | **SUSPICIOUS** | | < 35 | **NORMAL** | ### 4. 后端 API (`app.py` — 端口 `5003`) | Endpoint | 方法 | 用途 | |----------|--------|---------| | `/analyze` | POST | 对 JSON 格式的登录事件数组进行评分 | | `/upload_csv` | POST | 对上传的 CSV 文件进行评分 | | `/sample_data` | GET | 分析 `data/login_logs.csv` | | `/live_stream` | GET | 模拟实时登录及评分的 SSE 流 | | `/live_reset` | POST | 重置实时监控的 IP 状态 | ### 5. 前端仪表板 (`index.html` + `app.js`) - **加载演示数据** — 批量分析主数据集 - **上传 CSV 日志** — 对你自己的 / 示例 CSV 文件进行评分 - **实时监控** — 包含固定表头和滚动事件的实时模拟数据流 - IP 风险排行榜、过滤器和技术摘要面板 ## 环境要求 - Python 3.9+ - 依赖包： ``` pip install flask flask-cors pandas numpy scikit-learn ``` ## 运行方式 在项目文件夹下执行： ``` cd "/path/to/credential_stuffing" ``` ### 选项 A — 快速启动（模型已存在） 如果 `data/login_logs.csv` 和 `models/*.pkl` 已经存在： **终端 1 — 后端** ``` python3 app.py ``` 后端运行地址：http://127.0.0.1:5003 **终端 2 — 前端** ``` python3 -m http.server 8080 ``` 打开：http://127.0.0.1:8080/index.html ### 选项 B — 从零开始完整重新构建 ``` # 1) 生成 dataset python3 generate_dataset.py # 2) 训练 models python3 train.py # 3) (可选) 创建示例上传 CSV python3 create_sample_logs.py # 4) 启动 backend python3 app.py # 5) 在另一个 terminal 中 — 启动 frontend python3 -m http.server 8080 ``` 然后打开 http://127.0.0.1:8080/index.html ## 使用仪表板 1. 启动后端 + 前端（使用上述命令）。 2. 点击 **Load Demo Data** 查看来自训练数据集的 IP 评分。 3. 或者点击 **Upload CSV Log** — 尝试上传 `sample_logs/` 中的文件。 4. 或者点击 **Live Monitor** 观看实时评分的模拟登录。 5. 在排行榜上使用过滤器 / IP 搜索；点击某行查看 IP 详情。 ### 上传所需的 CSV 列 ``` timestamp, ip_address, username, user_agent, success ``` 可选但有用的字段：`country`、`response_ms`、`endpoint` ## 快速 API 冒烟测试 在后端运行的情况下： ``` curl http://127.0.0.1:5003/sample_data | head -c 500 ``` 你应该会得到包含 `summary` 和 `results` 的 JSON 响应。 ## 用户故事（用于演示 / 培训人员） ## 实验说明 - 这是一个**网络安全实验 / 演示**。仅限用于合成或已授权的日志。 - 已包含模型和数据集，因此无需重新训练即可运行。 - 在更改特征或重新生成数据（`train.py`）后，请重新训练模型。 - Live Monitor 会生成**模拟**事件用于演示目的；它未连接到真实的内部生产登录服务。

标签：Apex, Flask, 异常检测, 撞库防护, 数据可视化, 机器学习, 网络安全, 调试辅助, 逆向工具, 隐私保护