HarshavardhanVemali/secure-biometric-attendance-system

# 安全的生物识别考勤系统 ### 结合 AES-256 加密和 AI 驱动分析的混合云边协同 IoT 框架 [](LICENSE) [](SECURITY.md) []() []() []() []() ## 目录 - [概述](#overview) - [问题陈述](#problem-statement) - [提出的解决方案](#proposed-solution) - [系统架构](#system-architecture) - [安全框架 (零信任)](#security-framework-zero-trust) - [AI 驱动的分析引擎](#ai-powered-analytics-engine) - [技术栈](#technology-stack) - [项目结构](#project-structure) - [入门指南](#getting-started) - [云后端设置](#1-cloud-backend-django-server) - [边缘网关设置](#2-edge-gateway-raspberry-pi-client) - [测试与模拟](#testing-and-simulations) - [环境变量](#environment-variables) - [开发阶段](#development-phases) - [未来工作](#future-work) - [贡献指南](#contributing) - [安全政策](#security-policy) - [许可证](#license) - [参考文献](#references) ## 概述 本项目通过引入由 Raspberry Pi 安全网关驱动的**混合云边架构**，解决了传统生物识别考勤系统中的关键安全漏洞。该系统确保敏感的生物识别考勤数据在边缘进行加密，在网络中断期间进行本地缓冲，并安全地同步到 Django 云后端——从而实现**零数据丢失**和**端到端的机密性**。 该平台还集成了本地 AI 引擎 (Ollama / Llama 3.2)，用于执行自动化的考勤风险评估，通过风险评分和经由 AWS SES 的自动化利益相关者警报，将原始打卡日志转化为可操作的情报。 ## 问题陈述 现有的生物识别考勤系统存在根本性的架构弱点： | 漏洞 | 描述 | |---|---| | **未加密的传输** | 考勤数据通过 HTTP 以明文 JSON 形式发送，容易遭到拦截和中间人攻击。 | | **无设备身份验证** | 网络上的任何设备都可以伪装成生物识别机并注入虚假记录。 | | **依赖互联网** | 在网络中断期间，直连云端的模型会完全失效，导致永久性的数据丢失。 | | **重放攻击** | 没有 nonce 或时间戳验证，捕获的数据包可以被重新发送以复制考勤记录。 | | **不可逆的泄露影响** | 生物识别特征（指纹、面部数据）一旦泄露便无法更改，这与密码不同。 | 这些漏洞使得传统系统在处理生产环境中的敏感生物识别数据时不再安全。 ## 提出的解决方案 本系统在生物识别设备和云服务器之间引入了**本地安全网关** (Raspberry Pi)： ``` Biometric Device --> [LAN] --> Raspberry Pi Gateway --> [Encrypted/Internet] --> Django Cloud Server | | Local SQLite Buffer AI Analytics + Dashboard AES-256 Encryption Decryption + Verification Device Validation Alert Notifications (SES) ``` **主要创新点：** - 数据在离开本地网络时绝不会处于未加密状态。 - 网络中断导致零数据丢失（本地 SQLite 缓冲）。 - 每次同步都需要全新的加密握手。 - AI 引擎执行自动化的考勤风险分析。 ## 系统架构 该系统跨三个层级运行： ### 第 1 层：边缘（生物识别设备） 标准的 eSSL/ZKTeco 生物识别机器通过 HTTP 端口 80 使用 ADMS 协议推送原始考勤日志。支持的验证模式包括指纹（模式 1）、面部识别（模式 15）和密码回退（模式 0）。 ### 第 2 层：网关 基于 Python 的网关拦截 HTTP 流量并执行： 1. **设备验证** -- 验证生物识别机器是否已注册并获得授权。 2. **本地缓冲** -- 将所有打卡记录存储在本地 SQLite 数据库中。 3. **AES-256-CBC 加密** -- 使用动态派生的会话密钥对 payload 进行加密。 4. **安全同步** -- 将加密的 payload 连同 nonce 和时间戳一起传输到 Django 服务器。 ### 第 3 层：云端 (Django 后端) Django REST API 接收加密的 payload 并执行： 1. **网关身份验证** -- 在零信任模型下验证 MAC 地址和 API 密钥。 2. **Nonce 验证** -- 确认一次性 nonce 未被使用过。 3. **时间戳验证** -- 拒绝超出可配置时间窗口的请求（防重放）。 4. **AES-256 解密** -- 派生相同的会话密钥并解密 payload。 5. **去重** -- 使用复合唯一约束防止生成重复的日志条目。 6. **AI 分析** -- 将验证过的记录转发到分析引擎进行风险评分。 7. **自动警报** -- 当超过风险阈值时，通过 AWS SES 触发电子邮件通知。 ## 安全框架 (零信任) 该系统实施多层零信任安全模型，在授予访问权限之前会对每个请求进行验证。 ### 挑战-响应握手 三因素身份验证机制在任何数据同步之前验证设备： | 因素 | 目的 | |---|---| | **MAC 地址** | 网关设备的唯一网络标识符 | | **硬件序列号** | CPU 序列号确保物理设备的真实性并防止欺骗 | | **一次性 Nonce** | 64 个字符的加密 token 可防止重放攻击 | ### 动态密钥派生 (PBKDF2) 会话加密密钥从不被存储——它们是在每次同步时动态派生的： ``` Session Key = PBKDF2-HMAC-SHA256( password = API_KEY (stripped of hyphens), salt = One-Time Nonce, iterations = 600,000, key_length = 32 bytes ) ``` 600,000 次的迭代次数遵循了 NIST 对高安全性密钥拉伸的建议，使暴力破解攻击在计算上变得不可行。 ### AES-256-CBC 加密 所有考勤数据在传输前都会在网关层进行加密： - **算法**：CBC (Cipher Block Chaining) 模式下的 AES-256 - **密钥长度**：256 位（2^256 种可能的组合） - **IV**：每个 payload 随机生成的 16 字节初始化向量 - **填充**：PKCS7 块填充 ### 防重放保护 每个同步请求包括： - 一个在使用后即失效的**一次性 nonce** - 一个必须落在可配置窗口内的**经服务器验证的时间戳** - 关于 (user_id, machine, timestamp) 的复合唯一约束，以防止重复条目 ## AI 驱动的分析引擎 该系统与本地 LLM（运行 Llama 3.2 的 Ollama）集成，以执行自动化的考勤分析： ### 绩效评分 (0-100) 每位员工都会获得一个加权绩效评分： - **守时性（40% 权重）**：上午 09:05 之前打卡的百分比 - **一致性（60% 权重）**：过去 30 个工作日的出勤频率 ### 风险分类 | 分数范围 | 风险等级 | 操作 | |---|---|---| | 70-100 | 低 | 无需采取行动 | | 40-69 | 中 | 生成监控建议 | | 0-39 | 高 | 通过 AWS SES 向家长/教职员工发送自动警报 | ### 优雅降级 如果 Ollama 服务离线，系统将回退到统计启发式方法，而不会中断考勤处理。 ## 技术栈 | 组件 | 技术 | 目的 | |---|---|---| | **后端框架** | Django 5.x + Django REST Framework | REST API、管理后台、ORM | | **管理界面** | django-unfold | 现代、响应式的管理 UI | | **任务队列** | Celery + Redis | 异步日志处理和计划警报 | | **计划任务** | django-celery-beat | 基于 Crontab 的每日安全检查 | | **加密** | PyCryptodome (AES-256-CBC) | Payload 加密/解密 | | **密钥派生** | hashlib (PBKDF2-HMAC-SHA256) | 动态会话密钥生成 | | **电子邮件警报** | 经由 django-ses 的 AWS SES | 自动缺勤通知 | | **AI 分析** | Ollama (Llama 3.2:1b) | 用于风险评估的本地 LLM | | **边缘数据库** | SQLite | Raspberry Pi 上的离线缓冲 | | **边缘硬件** | Raspberry Pi 4/5 | 本地安全网关 | | **生物识别设备** | eSSL / ZKTeco (ADMS 协议) | 指纹、人脸、密码验证 | ## 项目结构 ``` . |-- attendance_dashboard/ # Core Django application | |-- models.py # Data models (Gateway, Employee, Logs, Analytics) | |-- views.py # Handshake and Sync API endpoints | |-- api_views.py # Additional REST API views | |-- tasks.py # Celery tasks (safety checks, scheduling) | |-- analytics_engine.py # AI performance scoring (Ollama integration) | |-- admin.py # Django Unfold admin configuration | |-- tests.py # Unit tests (crypto, handshake, sync) | `-- templates/ # HTML templates (simulation report) | |-- backend/ # Django project configuration | |-- settings.py # Settings (env-based, no hardcoded secrets) | |-- celery.py # Celery application setup | `-- urls.py # URL routing | |-- gateway_client/ # Raspberry Pi Edge Client | |-- main.py # Gateway entry point and ADMS listener | |-- sync_client.py # Handshake, encryption, and cloud sync | |-- buffer_manager.py # Local SQLite offline buffer | |-- biometric_gateway.service # systemd service file for auto-start | `-- .env.example # Gateway environment template | |-- tests_and_simulations/ # Testing and validation suite | |-- security_audit.py # Replay attack and MFA failure tests | |-- run_simulation.py # Network outage resilience simulation | |-- seed_demo_data.py # Demo data generator (30 days + AI scores) | |-- test_sync_flow.py # End-to-end sync flow test | `-- get_gateway_creds.py # Gateway credential provisioning utility | |-- scripts/ # Operational utilities |-- .env.example # Root environment template |-- requirements.txt # Python dependencies |-- manage.py # Django management entry point |-- LICENSE # MIT License |-- CONTRIBUTING.md # Contribution guidelines |-- SECURITY.md # Security policy and vulnerability reporting `-- CODE_OF_CONDUCT.md # Contributor Covenant ``` ## 入门指南 ### 前置条件 - Python 3.10 或更高版本 - Redis 服务器（用于 Celery 任务队列） - 带有 Llama 3.2 模型的 Ollama（可选，用于 AI 分析） - 一台 Raspberry Pi 4/5（用于生产环境的边缘部署） ### 1. 云后端 ``` # 克隆仓库 git clone https://github.com/your-username/secure-biometric-attendance.git cd secure-biometric-attendance # 创建并激活虚拟环境 python -m venv venv source venv/bin/activate # macOS/Linux # venv\Scripts\activate # Windows # 安装依赖 pip install -r requirements.txt # 配置环境变量 cp .env.example .env # 使用你的 SECRET_KEY、AWS credentials 和 Redis URL 编辑 .env # 初始化数据库 python manage.py migrate # 创建管理员超级用户 python manage.py createsuperuser # 启动开发服务器 python manage.py runserver # 在单独的终端中，启动 Celery workers： celery -A backend worker -l info # Log processing worker celery -A backend beat -l info # Scheduled task scheduler ``` 访问 `http://127.0.0.1:8000/admin/` 的管理仪表板。 ### 2. 边缘网关 (Raspberry Pi 客户端) ``` cd gateway_client # 创建并激活虚拟环境 python -m venv venv source venv/bin/activate # 安装依赖 pip install -r requirements.txt # 配置环境变量 cp .env.example .env # 使用你的 DJANGO_SERVER_URL、GATEWAY_MAC 和 GATEWAY_API_KEY 编辑 .env # 启动 gateway python main.py ``` **为了在 Raspberry Pi 上进行生产部署**，请将其安装为 systemd 服务以实现自动启动： ``` sudo cp biometric_gateway.service /etc/systemd/system/ sudo systemctl enable biometric_gateway sudo systemctl start biometric_gateway ``` ## 测试与模拟 在 `tests_and_simulations/` 目录中提供了一套全面的套件，用于验证安全性、弹性和正确性： | 脚本 | 目的 | 命令 | |---|---|---| | **单元测试** | 验证加密握手、密钥派生、加密/解密和 API 身份验证 | `python manage.py test` | | **安全审计** | 测试 6 种攻击场景：有效同步、缺少 nonce、无效 nonce、重放攻击、过期时间戳、硬件认证失败 | `python tests_and_simulations/security_audit.py` | | **中断模拟** | 模拟长达 4 小时的网络中断，以验证零数据丢失缓冲和自动恢复同步 | `python tests_and_simulations/run_simulation.py` | | **演示数据填充** | 为 5 个员工配置文件填充 30 天的考勤数据，包含 AI 生成的绩效分数 | `python tests_and_simulations/seed_demo_data.py` | | **同步流程测试** | 缓冲-加密-同步管道的端到端测试 | `python tests_and_simulations/test_sync_flow.py` | ## 环境变量 所有敏感配置均通过环境变量进行管理。复制 `.env.example` 到 `.env` 并进行配置： ### 云后端 | 变量 | 描述 | 默认值 | |---|---|---| | `SECRET_KEY` | Django 密钥 | *(必填)* | | `DEBUG` | 调试模式开关 | `True` | | `CELERY_BROKER_URL` | Celery 的 Redis broker URL | `redis://localhost:6379/0` | | `PBKDF2_ITERATIONS` | 密钥派生迭代次数 | `600000` | | `AWS_ACCESS_KEY_ID` | SES 的 AWS 访问密钥 | *(发送警报必填)* | | `AWS_SECRET_ACCESS_KEY` | SES 的 AWS 秘密密钥 | *(发送警报必填)* | | `AWS_SES_FROM_EMAIL` | 已验证的 SES 发件人电子邮件 | *(发送警报必填)* | | `OLLAMA_BASE_URL` | Ollama API 端点 | `http://localhost:11434` | | `OLLAMA_MODEL` | 用于风险分析的 LLM 模型 | `llama3.2` | ### 边缘网关 (gateway_client/.env) | 变量 | 描述 | 默认值 | |---|---|---| | `DJANGO_SERVER_URL` | 云后端同步端点 | *(必填)* | | `GATEWAY_MAC` | 此网关的 MAC 地址 | *(必填)* | | `GATEWAY_API_KEY` | 由云后端颁发的 API 密钥 | *(必填)* | ## 开发阶段 该项目采用结构化的分阶段方法进行开发： **阶段 1 -- 规划与架构** 设计了系统架构（从生物识别设备到 Raspberry Pi 再到 Django 仪表板），定义了安全的网络流和安全边界，并分析了生物识别设备的通信协议。 **阶段 2 -- Raspberry Pi 安全网关 (边缘层)** 开发了带有本地 SQLite 缓冲、AES-256-CBC 加密、安全云同步以及 systemd 自动启动配置的基于 Python 的网关系统。 **阶段 3 -- Django 服务器与仪表板 (云端层)** 使用 Django 5 构建了带有安全 REST API 的后端，实现了服务器端的解密和验证逻辑，并使用 django-unfold 创建了具有实时监控和分析功能的响应式管理仪表板。 **阶段 4 -- 测试与安全验证** 测试了设备到网关的通信，验证了网络故障期间的离线缓冲，针对 MitM 和重放攻击进行了安全测试，并进行了从生物识别扫描仪表板输出的端到端系统测试。 ## 贡献指南 我们欢迎各种贡献。在提交 Pull Request 之前，请阅读我们的[贡献指南](CONTRIBUTING.md)。 ## 安全政策 有关漏洞报告，请参阅我们的[安全政策](SECURITY.md)。不要为安全漏洞创建公开的 Issues。 ## 许可证 本项目采用 MIT 许可证授权。详情请参见 [LICENSE](LICENSE)。 ## 参考文献 1. J. Galbally, J. Fierrez, 和 J. Ortega-Garcia, "On the Resilience of Biometric Authentication Systems against Random Inputs," *IEEE Transactions on Information Forensics and Security*, vol. 7, no. 3, pp. 1124-1136, 2012. 2. A. Alrawais, A. Alhothaily, C. Hu, 和 X. Cheng, "A Secure, Hybrid, Cloud-Enabled Architecture for Internet of Things," *IEEE Access*, vol. 5, pp. 258-273, 2017. 3. M. Abomhara 和 G. M. Koien, "Security and Privacy in the Internet of Things: Current Status and Open Issues," *PRISMS*, 2014. 4. A. K. Jain, K. Nandakumar, 和 A. Nagar, "Biometric Template Security," *EURASIP Journal on Advances in Signal Processing*, 2008. 5. NIST, "Recommendation for Block Cipher Modes of Operation," *NIST Special Publication 800-38A*, 2001. 6. S. Freeman 等, "Active Learning Increases Student Performance in Science, Engineering, and Mathematics," *PNAS*, vol. 111, no. 23, pp. 8410-8415, 2014. *作为一个专注于 IoT 安全、云边混合系统以及 AI 驱动考勤分析的主要项目而开发。*

标签：AES-256, AI分析, AI风险缓解, Django, IoT, JSONLines, PBKDF2, Python, Raspberry Pi, SQLite, 云网关, 人工智能, 企业考勤, 内存执行, 加密, 子域名变形, 搜索引擎查询, 数据同步, 无后门, 无数据丢失, 智能安防, 本地存储, 混合云边架构, 漏洞扫描器, 漏洞评估, 物联网, 生物识别, 用户模式Hook绕过, 离线缓冲, 端到端加密, 系统架构, 网络安全, 考勤系统, 边缘计算, 逆向工具, 防御绕过, 隐私保护, 零信任, 风险分析