ThreatDetect

ThreatDetect 是一个基于 Streamlit 的内部威胁检测原型，用于分析员工活动数据并标记潜在风险行为。它使用训练好的 XGBoost 分类器结合孤立森林异常检测器，生成组织级风险摘要和可解释的员工级洞察。

演示

该应用可以使用 Streamlit 本地运行。之前发布了一个部署演示，地址为：

• https://threatdetectcos720.streamlit.app/

主要功能

• 从上传的 CSV 文件进行批量风险检测
• 组织威胁摘要，包含数量、概率分布和风险等级
• 使用 SHAP 值对每位员工进行可解释性分析
• 对上传或样本数据集进行探索性数据分析（EDA）
• 预测结果的 CSV 导出
• 特征重要性、风险分布和异常检测的可视化

仓库结构

• streamlit_app.py — 主要的 Streamlit 应用程序
• requirements.txt — Python 包依赖
• AI_Model_Code/insider_threat_model.pkl — 保存的推理管道和训练好的模型工件
• AI_Model_Code/insider_threat_clean_dataset.csv — 用于 EDA 的捆绑样本数据集
• AI_Model_Code/cos720_ai_model_FINAL.ipynb — 模型开发笔记本
• assets/app_styling.css — Streamlit 应用的自定义 UI 样式
• unit testing/ — 特征准备和解释逻辑的测试文件
• docs/TECHNICAL_DOCUMENTATION.md — 项目的技术文档

软件要求

• Python 3.8 或更高版本
• streamlit
• pandas
• numpy
• scikit-learn
• matplotlib
• seaborn
• plotly
• xgboost
• shap

使用以下命令安装所有依赖：

pip install -r requirements.txt

安装

1. 克隆仓库：

git clone https://github.com/jazbengu/ThreatDetect.git
cd ThreatDetect

2. 创建并激活虚拟环境（推荐）：

python3 -m venv venv
source venv/bin/activate

3. 安装依赖：

pip install -r requirements.txt

运行应用

使用以下命令启动应用：

streamlit run streamlit_app.py

然后打开终端中显示的本地 URL（通常是 http://localhost:8501）。

使用 ThreatDetect

通过 CSV 进行组织搜索

• 上传包含员工和活动特征的 CSV 文件。
• 点击“运行威胁检测”以计算每条记录的风险概率。
• 应用会显示总体恶意 vs 正常预测的摘要、风险概率分布以及特征重要性。
• 您可以展开详细结果表格，并将输出下载为 CSV。
• 使用每条记录的解释部分查看特定员工被标记的原因。

探索性数据分析

• 上传您自己的 CSV 文件，或使用 AI_Model_Code/insider_threat_clean_dataset.csv 中捆绑的样本数据集。
• 页面会显示数据集形状、描述性统计、缺失值信息和特征图。
• 可以通过直方图、箱线图、散点关系图和相关性热力图探索数值列。
• 快速的孤立森林异常扫描可以突出显示不寻常的记录。

侧边栏页面

• 通过 CSV 进行组织搜索 是主要的批量威胁检测工作流。
• 单条搜索 在侧边栏中显示，但当前未在应用逻辑中实现。
• 探索性数据分析 可用于数据集探索和快速异常检查。

模型工件

AI_Model_Code/insider_threat_model.pkl 包含一个序列化的模型包，其中包含：

• xgb_model：训练好的 XGBoost 分类器
• iso_forest：训练好的孤立森林异常检测器
• scaler：用于数值输入的 StandardScaler
• label_encoders：类别特征的编码器
• feature_columns：有序的特征列表
• cat_cols、num_cols、bin_cols：特征分组
• best_threshold：用于风险决策的分类阈值
• shap_explainer：用于可解释性的 SHAP 解释器

模型文件由 streamlit_app.py 加载，并用于预处理输入、计算风险概率和生成解释。

测试

仓库包含 unit testing/ 下的测试。

使用以下命令运行测试套件：

pytest "unit testing/"

注意事项与故障排除

• 如果 Streamlit 无法启动，请确保您的虚拟环境已激活且依赖已安装。
• 如果应用报告缺少必需的列，请验证您上传的 CSV 是否包含预期的员工和活动字段。
• 模型文件使用较旧版本的 scikit-learn 序列化，如果您的环境使用较新版本，加载时可能会产生兼容性警告。
• 如果内置样本数据集不可用，请上传您自己的 CSV 以继续使用 EDA 页面。

贡献

此仓库已配置用于增强和测试。未来的改进可能包括扩展特征覆盖范围，并使用更多内部威胁数据重新训练模型。