Vighnesh-07/honey-scan

# 🍯 HoneyScan — Serverless Malware Triage Pipeline ## 问题 每个云应用程序都接受文件上传。几乎 none 在文件触及生产存储之前进行恶意软件扫描。攻击发生在上传与检测之间的窗口期。 **HoneyScan 将该窗口缩短至 3 秒以内。** ## 功能 - **自动化分类** — 每个上传文件都会自动进行哈希计算、扫描并路由，无需人工干预 - **74 引擎共识** — VirusTotal API v3 同时查询 74 个反病毒引擎，而不仅仅是一个 - **哈希优先隐私** — 仅将 SHA-256 指纹发送到 VirusTotal — 原始文件字节永远不会离开您的 AWS 环境 - **物理隔离** — 威胁文件被移动到带有拒绝所有权限的 IAM 策略的锁定 S3 隔离存储桶 - **不可变的取证日志** — 每个扫描结果都会永久写入 DynamoDB，用于事后审计 - **实时告警** — 检测到威胁后几秒钟内通过 SNS 发送管理员电子邮件 - **实时仪表板** — 支持拖放上传、实时扫描状态和取证日志查看器的 Web UI - **零空闲成本** — 100% 无服务器 — 没有文件处理时无需任何成本 - **一键部署** — 整个基础设施可通过 `sam deploy` 复制 ## 架构 ``` ┌─────────────┐ S3 Event ┌──────────────────┐ JSON Payload │ User Upload │ ──────────────▶ │ hash-scan Lambda │ ──────────────────┐ │ (Browser) │ │ SHA-256 + VT API │ ▼ └─────────────┘ └──────────────────┘ ┌─────────────────────┐ │ Step Functions │ │ State Machine │ └────────┬────────────┘ │ ┌─────────────────────────┼──────────────────────┐ │ detections > 0 │ │ detections = 0 ▼ │ ▼ ┌──────────────────┐ │ ┌─────────────────────┐ │ quarantine-lambda │ │ │ S3 Safe Production │ └────────┬─────────┘ │ └──────────┬──────────┘ │ │ │ ┌─────────────┼──────────────┐ │ ┌───────────┘ ▼ ▼ ▼ │ ▼ ┌──────────────┐ ┌────────┐ ┌──────────┐ │ ┌──────────────┐ │ S3 Quarantine│ │ SNS │ │ DynamoDB │ └──▶│ DynamoDB │ │ (Locked) │ │ Alert │ │ Log │ │ Log │ └──────────────┘ └────────┘ └──────────┘ └──────────────┘ ``` ### AWS 服务 | 服务 | 角色 | |---|---| | **Amazon S3** | 三层存储 — 上传区、生产安全区、隔离区（拒绝所有权限策略） | | **AWS Lambda** | SHA-256 哈希计算、VirusTotal API、隔离操作、REST API 后端 | | **AWS Step Functions** | 编排 — 评估判决并将文件路由到正确的分支 | | **Amazon DynamoDB** | 不可变的取证日志 — 完整的扫描历史记录 | | **Amazon SNS** | 检测到威胁时实时发送安全告警邮件 | | **Amazon API Gateway** | REST API 用于仪表板 — 5 个端点 | | **AWS IAM** | 每个组件的最小权限执行角色 | | **AWS SAM** | 基础设施即代码 — 单命令完整部署 | | **VirusTotal API v3** | 74 引擎恶意软件共识评分 | ## 快速部署 ### 先决条件 - 已配置 CLI 的 AWS 账户（`aws configure`） - AWS SAM CLI（`sam --version`） - Python 3.8+ - VirusTotal 免费 API 密钥 — [在此获取](https://www.virustotal.com) ### 1. 克隆仓库 ``` git clone https://github.com/YOUR_USERNAME/honey-scan.git cd honey-scan ``` ### 2. 构建 ``` sam build ``` ### 3. 部署 ``` sam deploy --guided ``` 提示时： ``` Stack name: honeyscan-pipeline Region: us-east-1 VirusTotalApiKey: [your VirusTotal API key] AlertEmail: [your email address] Confirm changeset: y ``` ### 4. 确认 SNS 订阅 检查您的电子邮件并点击来自 AWS 的确认链接。 ### 5. 测试 ``` # 上传干净文件 aws s3 cp tests/clean_test.txt s3://honeyscan-dropzone-YOUR_ACCOUNT_ID/clean_test.txt # 上传 EICAR 威胁测试文件 aws s3 cp tests/eicar_test.txt s3://honeyscan-dropzone-YOUR_ACCOUNT_ID/eicar_test.txt ``` 检查取证日志： ``` aws dynamodb scan --table-name HoneyScanForensicLog \ --query "Items[*].{file:filename.S,verdict:vt_verdict.S,action:action_taken.S,detections:detections.N}" \ --output table ``` ## 演示 ### 清洁文件 → 批准 ``` Upload: clean_business_doc.docx SHA-256: 060f289611f1a114bb78492f89ab59ff... VirusTotal: 0/0 engines (unknown — hash not in database) Action: APPROVED → moved to safe-production bucket DynamoDB: action_taken = APPROVED Time: ~2 seconds ``` ### EICAR 测试文件 → 隔离 ``` Upload: eicar_test.txt SHA-256: bcb1cc1dd4b78d13d14e4cfdc029f8c1... VirusTotal: 4/74 engines flagged → malicious Action: QUARANTINED → moved to locked quarantine bucket DynamoDB: action_taken = QUARANTINED SNS: Security alert email dispatched Time: ~3 seconds ``` ### 取证日志输出 ``` +-------------------------+------------------+-------------+ | file | verdict | action | +-------------------------+------------------+-------------+ | clean_test.txt | unknown | APPROVED | | DevOps_Report.docx | unknown | APPROVED | | eicar_test.txt | malicious | QUARANTINED | | invoice_Q1_2026.txt | malicious | QUARANTINED | +-------------------------+------------------+-------------+ ``` ## 项目结构 ``` honey-scan/ ├── frontend/ # Web interface files │ └── index.html # Main UI for the scanning dashboard ├── iam/ # AWS IAM Policy and Trust documents (JSON) │ ├── api_lambda_policy.json # Permissions for the API Lambda │ ├── api_role_policy.json # IAM Role definition for the API │ ├── dropzone_cors.json # S3 CORS configuration for file uploads │ ├── hashscan_role_policy.json # Permissions for the scanning engine │ ├── lambda_trust_policy.json # Trust relationship for Lambda execution │ ├── quarantine_bucket_policy.json # Access control for the quarantine S3 bucket │ ├── quarantine_role_policy.json # Permissions for the quarantine logic │ ├── quarantine_trust_policy.json # Trust relationship for quarantine Role │ ├── s3_notification.json # S3 event notification configuration │ ├── stepfunctions_role_policy.json # Permissions for Step Functions execution │ ├── stepfunctions_trust_policy.json # Trust relationship for Step Functions │ ├── ui_bucket_policy.json # Permissions for the static website bucket │ ├── ui_public_access.json # Public access block settings for the UI │ └── ui_website_config.json # S3 Website hosting configuration ├── lambdas/ # AWS Lambda function source code │ ├── api/ # Lambda for handling API requests │ ├── hash_scan/ # Lambda for malware/hash-based scanning │ └── quarantine/ # Lambda for moving flagged files ├── scripts/ # Automation and setup utilities │ └── setup_api_gateway.py # Python script to automate API Gateway creation ├── step_functions/ # Orchestration definitions │ └── state_machine.asl.json # Amazon States Language definition for the scan workflow ├── tests/ # Test files and mock data │ ├── HR_Onboarding_Form.txt # Sample clean file for testing │ ├── SecureVault_Update_v3.2.1.txt # Sample system file for testing │ ├── clean_test.txt # Standard clean file │ ├── eicar_test.txt # Standard anti-malware test file (EICAR string) │ ├── invoice_Q1_2026.txt # Sample business document for testing │ ├── mock_s3_event.json # JSON mock of an S3 PutObject event │ └── threat_test.txt # Simulated malicious file ├── .gitignore # Specifies files for Git to ignore (secrets, builds) ├── LICENSE # Project license information ├── README.md # Project documentation ├── SECURITY.md # Security reporting and policies ├── architecture.md # Detailed architectural documentation └── template.yaml # AWS SAM / CloudFormation infrastructure template ``` ## 技术栈 - **运行时** — Python 3.13 - **AWS 服务** — Lambda、S3、Step Functions、DynamoDB、SNS、API Gateway、IAM、SAM - **威胁情报** — VirusTotal API v3 - **安全框架** — NIST SP 800-61 Rev. 2（事件响应） - **IaC** — AWS SAM / CloudFormation - **前端** — 原生 HTML/CSS/JavaScript（无框架） ## 安全设计 | 原则 | 实施 | |---|---| | 零信任 | 默认将每个文件视为潜在恶意 | | 最小权限 | 每个 Lambda 拥有范围限定的 IAM 角色 — 仅提供所需权限 | | 数据隐私 | 仅向 VirusTotal 提交 SHA-256 哈希 — 不传输原始文件字节 | | 物理隔离 | 隔离存储桶具有拒绝所有权限的策略，仅允许白名单 IAM ARN | | 不可变审计 | DynamoDB 取证日志永不修改或删除 | | 纵深防御 | 74 引擎共识 — 单个引擎绕过不会阻止检测 | ## 符合 NIST 800-61 | 阶段 | HoneyScan 实施 | |---|---| | **检测** | VirusTotal 74 引擎共识评分 | | ** containment** | 文件移动到锁定的 S3 隔离存储桶 | | **清除** | 从上传区删除原始文件 — 无法到达生产环境 | | **记录** | 带有 SHA-256 和时间戳的不可变 DynamoDB 取证日志 | | **通知** | 向管理员发送 SNS 电子邮件告警 | ## 成本估算 | 服务 | 免费额度 | 本项目 | |---|---|---| | Lambda | 每月 100 万次请求 | ~100 次调用 | | S3 | 5 GB 存储 | < 1 GB | | DynamoDB | 25 GB + 25 WCU/RCU | < 1 MB | | SNS | 每月 1,000 封电子邮件 | < 10 | | Step Functions | 每月 4,000 次状态转换 | < 100 | | API Gateway | 每月 100 万次调用 | < 1,000 | **预估每月成本：$0.00**（完全在免费额度内） ## 限制 - VirusTotal 免费层：每分钟 4 次查询，每日 500 次 - 未知文件（不在 VT 数据库中）被视为清洁 — 新型恶意软件可能无法检测 - 单区域部署（us-east-1） - 上传前无文件类型验证 ## 后续增强 - 在 S3 触发器与 Lambda 之间添加 SQS 缓冲队列以处理突发流量 - 对低置信度判决（1–3 个引擎检测）提供人工审查队列 - 在隔离存储桶上使用 S3 Object Lock（WORM）以符合监管要求 - 为管道可观测性添加 CloudWatch 仪表板 - 为 Web 仪表板添加 Amazon Cognito 身份验证 - 使用 Route 53 延迟路由进行多区域部署 ## 参考 - [AWS Lambda 开发者指南](https://docs.aws.amazon.com/lambda/) - [AWS Step Functions 开发者指南](https://docs.aws.amazon.com/step-functions/) - [VirusTotal API v3 文档](https://developers.virustotal.com/reference/overview) - [NIST SP 800-61 Rev. 2](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-61r2.pdf) - [AWS SAM 开发者指南](https://docs.aws.amazon.com/serverless-application-model/) ## 许可证 本项目根据 MIT 许可证授权 — 详细信息请参阅 [LICENSE](LICENSE) 文件。

标签：API集成, Ask搜索, AWS Lambda, AWS Step Functions, DynamoDB, Python, S3, SEO, Serverless, SHA-256, SNS, VirusTotal, Web仪表盘, 事件驱动, 取证日志, 可观测性, 哈希查重, 安全事件响应, 恶意文件扫描, 文件上传安全, 无后门, 时间线生成, 漏洞探索, 自动化威胁分析, 逆向工具, 隔离存储, 零成本