meriembarhi/NetPulse-Shield

# NetPulse-Shield NetPulse-Shield 是一个用于异常检测、告警存储、修复建议和报告的本地网络安全工作流。本仓库支持以三种方式运行该系统： - 通过 `dashboard.py` 进行交互式仪表盘操作 - 通过 `pipeline.py` 进行一键式自动化 - 使用 Redis/RQ 和 RAG 层进行后台建议生成 当前的实现具有标签感知能力，当存在标签时会自动调整 contamination，在没有标签时也能安全回退。 ## 项目功能 1. 清洗原始 UNSW-NB15 数据。 2. 选择固定的、领域指导的特征集。 3. 训练或加载 Isolation Forest 检测器。 4. 标记异常并持久化告警。 5. 通过 RAG 或可选的 LLM 路径生成修复建议。 6. 在 Streamlit 仪表盘、CSV 输出和 SQLite 数据库中展示结果。 ## 流水线模式 ### 1. 数据准备流水线 ``` raw UNSW-NB15 CSV -> clean_data.py -> feature selection + filtering -> data/final_project_data.csv ``` 目的： - 保持项目输入模式一致 - 将原始数据集缩减为检测器实际使用的字段 - 使下游检测器具有可预测性和可重复性 当前选择的特征集： ``` sttl, dttl, sbytes, dbytes, Sload, Dload, sloss, dloss, Spkts, Dpkts, tcprtt, Sjit, Label ``` ### 2. 检测流水线 ``` data/final_project_data.csv -> detector.py -> preprocess() -> train() or load saved model -> analyze() -> anomaly score + anomaly flag -> alerts.csv + alerts.db ``` 目的： - 标准化数值特征 - 拟合或重用 Isolation Forest 模型 - 检测可疑流量 - 保存机器可读和人类可读的输出 ### 3. Contamination 选择流水线 ``` Label column present -> use real attack rate No usable labels -> tune_contamination() on validation split If tuning fails -> fallback contamination = 0.05 ``` 目的： - 避免为每个数据集硬编码一个异常率 - 在存在标签时优先使用标签 - 当标签可用但需要优化时，使用基于 F1 的调优 - 即使在缺少标签的情况下也能保持系统正常工作 ### 4. 修复与建议流水线 ``` alert row -> tasks.py -> advisor.py -> knowledge_base.py + embeddings.py -> FAISS retrieval or TF-IDF fallback -> remediation text -> alerts.db audit/update ``` 目的： - 将原始异常转化为对分析人员友好的指导 - 使用语义检索而不是仅仅依赖关键字匹配 - 通过 TF-IDF 回退保持离线功能可用 ### 5. 可选的 LLM 修复流水线 ``` alert / anomaly text -> remediator.py or auto_remediator.py -> Ollama / Llama 3 -> structured security report -> Security_Report.txt ``` 目的： - 生成更具创造性、自由格式的修复说明 - 在 Ollama 可用时提供 Cisco 风格的指导 - 提供一条独立于 RAG 系统的路径 ## 运行时编排 ### 交互式仪表盘流程 ``` open dashboard.py -> auto-run detection on page load -> tune contamination if Label exists -> run analysis -> write alerts.csv -> persist alerts in alerts.db -> allow advice generation through Redis/RQ or sync fallback ``` ### 批量流水线流程 ``` python pipeline.py -> validate CSV -> run detection -> save alerts.csv -> generate Security_Report.txt ``` ### 后台工作进程流程 ``` dashboard.py -> queue advice job -> Redis broker -> rq worker advisor -> tasks.generate_advice_for_alert() -> advisor.py RAG lookup -> write advice to alerts.db ``` ## 仓库结构与用途 - `clean_data.py` 准备检测器使用的最终数据集。 - `detector.py` 训练、加载并运行异常检测器。它保存以下内容： - `models/netpulse_model.joblib` - `models/netpulse_model_scaler.joblib` - `models/netpulse_model_features.joblib` - `models/netpulse_model_metadata.json` - `dashboard.py` 是 Streamlit UI。它现在在加载时会自动运行分析，并支持手动重新运行和生成建议。 - `pipeline.py` 是用于完全自动化和报告生成的标准 CLI。 - `db.py` 定义了 `Alert` 和 `AuditLog` 的 SQLite 持久化。 - `tasks.py` 包含用于异步建议生成的 RQ 任务函数。 - `advisor.py` 实现了 RAG 风格的修复顾问。 - `embeddings.py` 构建向量存储并处理嵌入回退。 - `knowledge_base.py` 存储内置的修复知识。 - `remediator.py` 和 `auto_remediator.py` 提供可选的 Ollama / 基于 LLM 的修复路径。 - `system_utils.py` 提供 Redis 健康检查、队列统计信息和入队辅助工具。 - `docker-compose.yml` 定义了 `redis`、`web` 和 `worker` 服务。 - `Dockerfile` 构建 Streamlit 应用程序镜像。 - `tests/` 包含检测器和流水线测试。 ## 重要输出 - `data/final_project_data.csv` - 检测器使用的已清理数据集 - `alerts.csv` - 由检测器或流水线写入的顶部告警 - `alerts.db` - 用于告警和审计日志的 SQLite 数据库 - `models/` - 保存的模型组件和元数据 - `Security_Report.txt` - 从流水线或 LLM 路径生成的修复报告 ## 主要模块工作原理 ### `clean_data.py` 目的：将原始数据转换为稳定的 12 特征数据集。 重要性： - 保持检测器模式可预测 - 减少未使用的原始列产生的噪音 - 确保模型每次都在相同的核心输入上进行训练 ### `detector.py` 目的：检测异常并持久化已训练的检测器。 行为： - 如果可用，则加载现有的模型组件 - 在训练期间发现数值特征 - 保存训练时使用的确切特征列表 - 根据标签、调优或回退选择 contamination - 为每行写入异常分数和异常标志 ### `advisor.py` 目的：将告警描述转换为修复指导。 行为： - 加载知识库 - 将其分割成块 - 构建 FAISS 向量存储 - 检索最相关的修复片段 - 如果检索失败，则回退到通用建议 ### `embeddings.py` 目的：为语义搜索提供向量嵌入。 行为： - 首先尝试 HuggingFace sentence-transformer 嵌入 - 如果需要，回退到本地 TF-IDF 嵌入 - 保持 RAG 层可离线使用 ### `tasks.py` 目的：在后台运行建议生成。 行为： - 从数据库加载告警 - 创建简短的异常描述 - 调用 `NetworkSecurityAdvisor` - 存储建议和审计日志条目 ### `dashboard.py` 目的：提供面向用户的控制界面。 行为： - 在页面加载时自动运行检测 - 允许手动重新运行分析 - 当 Redis 可用时，将建议任务入队 - 当 Redis 不可用时，回退到同步建议生成 ### `pipeline.py` 目的：以非交互方式运行完整项目。 行为： - 验证输入的 CSV - 运行异常检测 - 保存告警 - 生成安全报告 - 是自动化、CI 和批量执行的最佳入口 ### `db.py` 目的：在 SQLite 中存储告警和审计日志。 数据表： - `Alert` 存储每个异常、其分数、其序列化特征以及建议字段。 - `AuditLog` 存储用户和工作进程的操作，以保证可追溯性。 ## 部署选项 ### 本地开发 ``` python -m venv .venv .\.venv\Scripts\Activate.ps1 pip install -r requirements.txt python clean_data.py streamlit run dashboard.py ``` ### 批量自动化 ``` python pipeline.py ``` 可选标志： - `--no-persist` - 跳过数据库写入 - `--alerts-csv ` - 更改告警输出路径 - `--report ` - 更改报告输出路径 ### Docker Compose 部署 ``` docker-compose up --build ``` 服务： - `redis` - 队列代理 - `web` - Streamlit 仪表盘 - `worker` - 后台 RQ 工作进程 ### 可选 Ollama / LLM 路径 ``` ollama serve python remediator.py python auto_remediator.py ``` ## 依赖项 核心包来自 `requirements.txt`： - `scikit-learn`、`pandas`、`numpy`、`joblib` 用于检测 - `streamlit`、`plotly` 用于仪表盘 - `SQLAlchemy` 用于 SQLite 持久化 - `langchain`、`langchain-community`、`langchain-core`、`langchain-text-splitters` 用于 RAG 编排 - `sentence-transformers` 和 `faiss-cpu` 用于语义检索 - `redis` 和 `rq` 用于后台作业 - `ollama` 用于可选的本地 LLM 路径 ## 推荐使用方式 1. 如果你想要最简单的完整运行，请使用 `python pipeline.py`。 2. 如果你想要交互式分类，请使用 `streamlit run dashboard.py`。 3. 如果你想要后台建议生成，请运行 Redis 和 RQ worker。 4. 如果你仅想要 LLM 路径，请启动 Ollama 并运行 `remediator.py` 或 `auto_remediator.py`。 ## 测试与验证 ``` pytest tests/ -q ruff check . ``` ## 故障排除 - 如果 `alerts.csv` 缺失，请运行 `python detector.py` 或 `python pipeline.py`。 - 如果 contamination 调优失败，检测器将回退到 `0.05`。 - 如果 Redis 不可用，仪表盘将使用同步建议生成。 - 如果 Ollama 不可用，RAG 顾问仍能工作，LLM 路径将被直接跳过。 - 如果检测器提示模式不匹配，请重新生成 `data/final_project_data.csv` 并重新训练，以便保存的特征列表与输入匹配。 ## 许可证 MIT 许可证

标签：AI安全, AI风险缓解, Apex, Chat Copilot, DLL 劫持, F1 Score, IP 地址批量处理, Isolation Forest, Kubernetes, Llama 3, LLM, Python, RAG, Redis, RQ, SOAR, SQLite, Streamlit, Unmanaged PE, UNSW-NB15, 仪表盘, 告警 Remediation, 大语言模型, 孤立森林, 安全报告, 异常分数, 异常检测, 搜索引擎查询, 数据清洗, 数据科学, 无后门, 无监督学习, 智能安防, 机器学习, 检索增强生成, 污点率, 流数据处理, 漏洞修复建议, 特征选择, 网络安全, 网络安全自动化, 网络流量分析, 访问控制, 请求拦截, 资源验证, 逆向工具, 防御绕过, 隐私保护