Sachin30102006/Hireshield

# 🛡️ HireShield - AI 招聘威胁情报平台 **用于检测招聘欺诈的生产级 AI 安全平台** ## 📋 目录 - [项目概述](#project-overview) - [系统架构](#system-architecture) - [功能](#features) - [快速开始](#quick-start) - [API 文档](#api-documentation) - [项目结构](#project-structure) - [安装说明](#installation) - [配置](#configuration) - [开发指南](#development) - [部署说明](#deployment) - [贡献指南](#contributing) ## 🚀 项目概述 HireShield 是一个综合性的 AI 驱动平台，旨在检测和分析与招聘相关的威胁，包括： - **虚假录用通知** - AI 检测冒充和欺诈性职位 - **钓鱼邮件** - 检测凭证窃取企图 - **支付诈骗** - 识别预付款和费用请求 - **社会工程学** - 分析操纵和紧迫感策略 - **身份盗窃** - 识别身份验证请求 - **招聘人员冒充** - 验证招聘人员的合法性 ### 核心技术 - **AI/ML**: scikit-learn, XGBoost, SHAP - **NLP**: spaCy, NLTK, Transformers (DistilBERT) - **后端**: FastAPI, SQLAlchemy - **前端**: Streamlit - **数据库**: SQLite (兼容 PostgreSQL) - **部署**: Docker, Docker Compose ## 🏗️ 系统架构 ### 分层架构 ``` ┌─────────────────────────────────────────────────────────────┐ │ FRONTEND LAYER │ │ (Streamlit Web Application) │ └────────────────────┬────────────────────────────────────────┘ │ HTTP/REST API ┌────────────────────▼────────────────────────────────────────┐ │ API LAYER │ │ (FastAPI - RESTful Endpoints) │ ├─────────┬──────────┬──────────┬──────────┬──────────────────┤ │ Analyze │ Explain │ Logs │ Threat │ Health/Status │ │ /analyze│ /explain │ /logs │ /stats │ /health │ └────────────────────┬────────────────────────────────────────┘ │ Service Injection ┌────────────────────▼────────────────────────────────────────┐ │ SERVICE LAYER │ ├──────────────┬──────────┬──────────┬───────┬─────────────────┤ │ Inference │ Features │ Explain- │ Threat│ Logging │ │ (Models) │ (Eng.) │ ability │(Intel)│ (Persistence) │ └────────────────────┬────────────────────────────────────────┘ │ Dependency Injection ┌────────────────────▼────────────────────────────────────────┐ │ AI/NLP LAYER │ ├──────────────┬──────────────┬───────────────────────────────┤ │ Preprocessing│ Feature Eng. │ ML Inference │ │ (Cleaning) │ (Extraction) │ (XGBoost, Logistic Reg.) │ └────────────────────┬────────────────────────────────────────┘ │ ┌────────────────────▼────────────────────────────────────────┐ │ DATABASE LAYER │ │ (SQLAlchemy ORM + SQLite/PostgreSQL) │ ├──────────────┬──────────────┬──────────────────────────────┤ │ Scan Logs │ Recruiter │ Threat Intelligence / Models │ │ │ Profiles │ Training Logs │ └──────────────┴──────────────┴──────────────────────────────┘ ``` ### 关键设计决策 1. **关注点分离**: 前端、API、服务和数据层之间明确分离 2. **依赖注入**: 服务之间松耦合，易于测试 3. **异步 API**: FastAPI 实现高性能异步端点 4. **数据库抽象**: SQLAlchemy ORM 允许轻松迁移到 PostgreSQL 5. **模块化服务**: 每个服务处理特定的职责 6. **类型安全**: Pydantic 模型确保请求/响应验证 ## ✨ 功能 ### 分析引擎 - **多模型推理**: XGBoost（主要）+ 逻辑回归（基准） - **实时处理**: 分析在 <500ms 内完成 - **置信度评分**: 校准后的概率估计 - **丰富的特征检测**: 23+ 项行为和语言特征 ### 可解释性 - **SHAP 集成**: 特征重要性和局部解释 - **人类可读的推理**: 逐步的决策解释 - **置信度评估**: 解释模型为何对其预测具有信心 - **主要贡献特征**: 识别关键欺诈信号 ### 威胁情报 - **招聘人员画像**: 信任评分和历史记录追踪 - **威胁分类**: 分为 8+ 种威胁类型 - **模式识别**: 识别反复出现的欺诈模式 - **分析仪表板**: 趋势分析和统计 ### 日志与监控 - **全面的审计跟踪**: 记录带有元数据的所有扫描 - **搜索与过滤**: 具有多种过滤器的高级日志查询 - **分析快照**: 定期的威胁情报摘要 - **模型训练历史**: 追踪模型性能随时间的变化 ### 安全与合规 - **数据持久化**: 安全存储在 SQLite/PostgreSQL 中 - **访问日志**: 完整的系统活动审计跟踪 - **错误处理**: 优雅降级和错误报告 - **健康监控**: 实时系统状态检查 ## 🚀 快速开始 ### 前置条件 - Python 3.11+ - Docker & Docker Compose（用于容器化部署） - 2GB+ RAM ### 安装说明 1. **克隆仓库** git clone https://github.com/yourusername/hireshield.git cd hireshield 2. **创建虚拟环境** python -m venv .venv source .venv/bin/activate # 在 Windows 上: .venv\Scripts\activate 3. **安装依赖** pip install -r requirements.txt python -m spacy download en_core_web_sm 4. **初始化数据库** python -c "from backend.database import init_db; init_db()" 5. **训练模型**（如果需要） python -m models.train_model ### 运行应用 #### 选项 1：本地开发（分离服务） **终端 1 - 后端 API:** ``` uvicorn backend.main:app --host 0.0.0.0 --port 8000 --reload ``` **终端 2 - 前端:** ``` streamlit run frontend/app.py ``` 然后访问： - **前端**: http://localhost:8501 - **API 文档**: http://localhost:8000/api/docs - **API ReDoc**: http://localhost:8000/api/redoc #### 选项 2：Docker Compose（推荐） ``` docker-compose up --build ``` 然后访问： - **前端**: http://localhost:8501 - **后端**: http://localhost:8000 - **API 文档**: http://localhost:8000/api/docs ## 📚 API 文档 ### Base URL ``` http://localhost:8000/api ``` ### 身份验证 目前无需身份验证。在生产环境中添加 JWT/OAuth。 ### 端点 #### 分析端点 **POST /analyze** - 基础诈骗分析 ``` Request: { "text": "Your recruitment message here...", "recruiter_email": "recruiter@company.com", "recruiter_name": "John Doe", "job_title": "Senior Engineer", "company_name": "TechCorp" } Response: { "scam_probability": 87.5, "risk_level": "HIGH RISK", "confidence": 0.94, "detected_indicators": [...], "highlighted_phrases": [...], "feature_scores": {...}, "processing_time_ms": 125.5 } ``` **POST /deep-scan** - 结合 SHAP 的高级分析 ``` Request: { "text": "...", "recruiter_email": "...", "include_shap": true, "confidence_threshold": 0.7 } Response: Same as /analyze with enhanced feature importance ``` #### 可解释性端点 **POST /explain** - 获取基于 SHAP 的解释 ``` Request: { "text": "...", "recruiter_email": "..." } Response: { "scam_probability": 87.5, "risk_level": "HIGH RISK", "shap_available": true, "feature_importance": [...], "top_contributing_features": ["urgency_score", "payment_request"], "explanation_text": "The AI detected multiple fraud indicators...", "reasoning": [...] } ``` #### 日志端点 **GET /logs** - 获取扫描历史 ``` Query Parameters: - limit: 50 (max 1000) - offset: 0 - severity_level: CRITICAL|HIGH RISK|SUSPICIOUS|SAFE - status: Blocked|Quarantined|Flagged|Verified - search_query: Search in email/category Response: { "logs": [...], "total_count": 145, "limit": 50, "offset": 0 } ``` **GET /logs/{log_id}** - 获取特定日志详情 **DELETE /logs/{log_id}** - 删除日志条目 #### 威胁情报端点 **GET /threat-stats** - 聚合的威胁统计信息 ``` Query Parameters: - days: 30 (lookback period) Response: { "total_scans": 1250, "critical_count": 145, "high_risk_count": 340, "average_scam_probability": 45.3, "top_threat_categories": [...] } ``` **GET /threat-summary** - 快速威胁摘要 #### 健康与状态端点 **GET /health** - API 健康检查 ``` Response: { "status": "healthy", "api_version": "1.0.0", "models_loaded": true, "database_connected": true, "message": "All systems operational" } ``` **GET /model-info** - 模型信息 **GET /status** - 综合系统状态 ### 错误响应 所有错误均遵循标准格式： ``` { "error": "Error type", "status_code": 400, "timestamp": "2026-05-21T10:30:00Z", "details": {...} } ``` ## 📁 项目结构 ``` HireShield/ │ ├── frontend/ │ ├── app.py # Streamlit main application │ ├── api_client.py # API client for REST communication │ └── views/ │ ├── dashboard.py # Dashboard view │ ├── analysis.py # Scam analysis view │ ├── threat_intel.py # Threat intelligence view │ ├── explainability.py # Explainability view │ ├── logs.py # Detection logs view │ └── settings.py # Settings view │ ├── backend/ │ ├── main.py # FastAPI application entry point │ │ │ ├── routers/ │ │ ├── analyze.py # Analysis endpoints │ │ ├── explain.py # Explainability endpoints │ │ ├── logs.py # Log management endpoints │ │ ├── threat.py # Threat intelligence endpoints │ │ └── health.py # Health & status endpoints │ │ │ ├── services/ │ │ ├── inference_service.py # ML model inference │ │ ├── feature_service.py # Feature extraction │ │ ├── explainability_service.py # SHAP explanations │ │ ├── logging_service.py # Log persistence │ │ └── threat_service.py # Threat intelligence │ │ │ ├── models/ │ │ ├── request_models.py # Pydantic request schemas │ │ └── response_models.py # Pydantic response schemas │ │ │ ├── database/ │ │ ├── db.py # Database connection & config │ │ ├── schemas.py # SQLAlchemy ORM models │ │ └── operations.py # Database CRUD operations │ │ │ └── utils/ │ └── config.py # Configuration utilities │ ├── ai/ │ ├── preprocessing/ │ │ ├── cleaner.py │ │ ├── tokenizer.py │ │ └── lemmatizer.py │ │ │ ├── feature_engineering/ │ │ ├── payment_detector.py │ │ ├── urgency_detector.py │ │ └── ...feature modules... │ │ │ ├── ml/ │ │ ├── train_xgboost.py │ │ ├── train_logistic.py │ │ └── inference.py │ │ │ └── explainability/ │ └── shap_explainer.py │ ├── models/ │ ├── xgboost_model.pkl # Trained XGBoost model │ ├── logistic_model.pkl # Logistic regression model │ ├── vectorizer.pkl # Feature vectorizer │ └── feature_order.pkl # Feature column order │ ├── data/ │ ├── raw/ # Raw data files │ └── sample_scams.csv # Training data │ ├── tests/ │ ├── test_api.py │ ├── test_preprocessing.py │ └── test_models.py │ ├── docker/ │ └── Dockerfile │ ├── docker-compose.yml ├── requirements.txt ├── README.md ├── .gitignore └── hireshield.db # SQLite database (auto-created) ``` ## ⚙️ 安装说明 ### 前置条件 - **Python**: 3.11 或更高版本 - **pip**: Python 包管理器 - **虚拟环境**（推荐）: venv 或 conda ### 步骤 1：克隆仓库 ``` git clone https://github.com/yourusername/hireshield.git cd hireshield ``` ### 步骤 2：创建虚拟环境 ``` # 使用 venv python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate # 或者使用 conda conda create -n hireshield python=3.11 conda activate hireshield ``` ### 步骤 3：安装依赖 ``` pip install -r requirements.txt ``` ### 步骤 4：下载 NLP 模型 ``` python -m spacy download en_core_web_sm python -m nltk.downloader punkt averaged_perceptron_tagger ``` ### 步骤 5：初始化数据库 ``` python -c "from backend.database import init_db; init_db()" ``` ### 步骤 6：训练模型（可选） 如果 `/models/` 中不存在模型： ``` python -m models.train_model ``` ## 🔧 配置 ### 环境变量 在项目根目录创建一个 `.env` 文件： ``` # Database DATABASE_URL=sqlite:///./hireshield.db # DATABASE_URL=postgresql://user:password@localhost/hireshield # API API_PORT=8000 API_HOST=0.0.0.0 # Frontend STREAMLIT_PORT=8501 # Logging LOG_LEVEL=INFO # ML MODEL_CONFIDENCE_THRESHOLD=0.5 ``` ### 数据库配置 #### SQLite（默认） ``` DATABASE_URL = "sqlite:///./hireshield.db" ``` #### PostgreSQL（生产环境） ``` DATABASE_URL = "postgresql://user:password@localhost:5432/hireshield" ``` ## 👨‍💻 开发指南 ### 运行测试 ``` # 运行所有测试 pytest # 包含覆盖率 pytest --cov=backend --cov=frontend # 特定测试 pytest tests/test_api.py::test_analyze ``` ### 代码质量 ``` # 格式化代码 black . # Lint 代码 flake8 . # 类型检查 mypy backend/ ``` ### 添加新功能 1. 创建功能分支：`git checkout -b feature/my-feature` 2. 先编写测试（TDD） 3. 实现功能 4. 更新文档 5. 提交 Pull Request ## 🚀 部署说明 ### Docker 部署 ``` # 构建并运行 docker-compose up --build # 以 detached 模式运行 docker-compose up -d # 查看日志 docker-compose logs -f # 停止服务 docker-compose down ``` ### 云部署选项 #### Render.com ``` # 创建指向 backend/main.py 的 web service # 设置启动命令: uvicorn backend.main:app --host 0.0.0.0 --port $PORT ``` #### Railway.app ``` # 使用 Railway CLI 部署 railway up ``` #### HuggingFace Spaces ``` # 推送到 HuggingFace Spaces repo # Streamlit 将自动部署 frontend ``` #### AWS EC2 ``` # 安装依赖项，clone repo，使用 Docker Compose 运行 # 为端口 8000 和 8501 配置 security groups ``` ### 生产环境检查清单 - [ ] 使用 PostgreSQL 替代 SQLite - [ ] 针对特定来源启用 CORS - [ ] 添加身份验证（JWT/OAuth） - [ ] 设置 HTTPS/SSL - [ ] 配置日志和监控 - [ ] 设置资源限制 - [ ] 定期备份数据库 - [ ] 负载测试 - [ ] 安全审计 ## 📊 性能指标 - **API 响应时间**: <500ms /请求 - **模型准确率**: 在测试集上达到 97.82% - **F1 分数**: 0.9801 - **吞吐量**: 100+ 请求/秒（单实例） - **数据库查询**: 平均 <50ms ## 🤝 贡献指南 欢迎贡献！请遵循以下步骤： 1. Fork 该仓库 2. 创建功能分支 3. 进行更改 4. 编写测试 5. 提交 Pull Request ## 🙏 致谢 - 怀着 ❤️ 为网络安全而构建 - 受企业级 SaaS 平台启发 - 欢迎社区贡献

标签：Apex, AV绕过, FastAPI, Kubernetes, NLP, Streamlit, 反欺诈, 威胁情报, 开发者工具, 机器学习, 测试用例, 版权保护, 系统调用监控, 访问控制, 请求拦截, 逆向工具