BHUVANESH-SSN/sentinel-apk

# Sentinel-APK      Sentinel-APK 是一款由 GenAI 驱动的 Android 恶意软件分析器，专为银行 SOC 团队设计。Sentinel-APK 会接收通常通过 WhatsApp、SMS 和钓鱼活动分发的可疑 APK，使其通过六代理分析 pipeline，并生成包含 IOC、威胁分类、风险评分以及适用于银行的 SOC playbook 的结构化调查报告——全程无需在宿主机上执行 APK。 **当前状态：** 计划 2 已完成——完整的六代理 pipeline 和生产级安全强化。 ## 工作原理 提交的 APK 会依次经过六个代理，每个代理都会基于前一个代理的发现继续工作： | 代理 | 职责 | |---|---| | `reverse_engineer` | 反编译 DEX bytecode，列出类描述符，总结代码意图 | | `static_analyzer` | 提取权限、危险的 API 调用以及嵌入的字符串 | | `dynamic_analyzer` | 查询 VirusTotal 威胁情报；绝不在宿主机上执行 APK | | `threat_classifier` | 对恶意软件家族（banker、RAT、spyware 等）进行分类，并提供置信度分数 | | `risk_scorer` | 生成确定性的 0-100 风险评分，并给出 CRITICAL / HIGH / MEDIUM / LOW 判定 | | `report_generator` | 将确定性的 IOC 提取与 LLM 生成的 SOC 叙述相结合 | IOC 是通过 regex（URL、IP、电子邮件地址、Telegram token、SHA-256 哈希）确定性地提取的，以保证可审计性。LLM 仅用于生成叙述部分。 ## 架构 ``` ┌──────────────────┐ POST /scan ┌──────────────────────┐ │ React Dashboard │ ──────────► │ FastAPI Backend │ │ Vite + TS + │ ◄────────── │ /health │ │ Tailwind 4 │ │ /scan │ └──────────────────┘ │ /scan/{id} │ └──────────┬───────────┘ │ API-key auth │ rate limiting │ upload validation ▼ ┌──────────────────────┐ │ lead_analyst │ │ Orchestrator │ │ (per-scan LLM cap) │ └──────────┬───────────┘ │ ┌────────────────────────┼────────────────────────┐ ▼ ▼ ▼ reverse_engineer static_analyzer dynamic_analyzer │ ▼ threat_classifier │ ▼ risk_scorer │ ▼ report_generator │ ┌──────────────────────────┤ ▼ ▼ IOC extraction SOC report (deterministic regex) (LLM narrative) Postgres — scans, agent_traces, iocs, audit_log Redis — per-client fixed-window rate limiting ``` ## 安全性 | 控制措施 | 实现方式 | |---|---| | 上传验证 | Magic-byte 检查 (`PK\x03\x04`)，100 MB 大小上限，zip-bomb 防御（条目数 + 解压后大小限制） | | API key 认证 | `X-Api-Key` header，常量时间 HMAC 比较；在本地开发中 `API_KEYS` 为空时跳过 | | 限流 | 固定窗口 Redis 计数器，每个客户端 IP 每分钟 30 个请求 | | 安全 header | `X-Content-Type-Options`、`X-Frame-Options`、`Content-Security-Policy`、`Referrer-Policy` | | CORS 限制 | 通过 `CORS_ORIGINS` 设置明确的来源白名单；方法仅限于 `GET` 和 `POST` | | 单次扫描 LLM 预算 | 可配置的调用计数器 (`MAX_LLM_CALLS_PER_SCAN`)；超出时引发 `BudgetExceededError` | | 审计日志 | 只追加的 `audit_log` 表记录每次扫描的开始、完成和错误 | ## 快速开始 要求：**Python 3.12+**、**Node 20+**、**Docker**。 ``` # 1. 启动 Postgres 和 Redis docker compose up -d # 2. Backend 设置 cd backend python3 -m venv .venv source .venv/bin/activate pip install -e ".[dev]" pip install -e ../mcp_servers/mcp-androguard # 3. 构建 test APK fixtures python tests/fixtures/build_test_apk.py # 4. 运行 database migrations alembic upgrade head # 5. 配置 environment variables cd .. cp .env.example .env # 编辑 .env 并设置 GROQ_API_KEY=gsk_... # 6. 启动 backend（终端 1） cd backend && source .venv/bin/activate uvicorn app.main:app --reload --port 8000 # 7. 启动 frontend（终端 2） cd frontend && npm install && npm run dev # 8. 打开 http://localhost:5173 并上传 backend/tests/fixtures/suspicious.apk ``` ### 运行测试 ``` cd backend && source .venv/bin/activate pytest -v # 48 tests (unit + integration) ``` ## 项目布局 ``` sentinel-apk/ ├── CLAUDE.md hard rules and agent roster ├── docker-compose.yml Postgres (port 5434) + Redis (port 6380) ├── .env.example environment variable template ├── backend/ │ ├── app/ │ │ ├── api/ /health, /scan, /scan/{id} │ │ ├── agents/ six agents + shared groq_runner │ │ ├── analysis/ ioc.py (regex IOC extractor), dex.py │ │ ├── orchestrator/ lead_analyst — six-agent sequenced pipeline │ │ ├── security/ auth, ratelimit, middleware, upload limits │ │ ├── runtime_skills/ analyst skill files loaded into agent context │ │ ├── validation/ magic-byte and SHA-256 enforcement │ │ └── db/ SQLAlchemy models (scans, iocs, audit_log) │ ├── alembic/ database migrations │ └── tests/ 48 unit and integration tests │ └── fixtures/ synthetic benign.apk and suspicious.apk ├── mcp_servers/ │ └── mcp-androguard/ FastMCP stdio server — manifest, permissions, │ strings, apk_metadata tools └── frontend/ └── src/ ├── pages/ Home (upload), ScanResult (report viewer) ├── lib/ api.ts, utils.ts └── types/ scan.ts — mirrors backend response schema ``` ## 环境变量 | 变量 | 必填 | 默认值 | 描述 | |---|---|---|---| | `GROQ_API_KEY` | 是 | — | 用于 Llama 3.3 70B 的 Groq API key | | `VIRUSTOTAL_API_KEY` | 否 | — | VirusTotal API key；如果没有，dynamic_analyzer 将平滑降级 | | `DATABASE_URL` | 是 | — | PostgreSQL 异步 URL | | `REDIS_URL` | 是 | — | 用于限流的 Redis URL | | `API_KEYS` | 否 | `` | 逗号分隔的 API key；在开发环境中留空以禁用认证 | | `CORS_ORIGINS` | 否 | `http://localhost:5173` | 逗号分隔的允许来源 | | `MAX_UPLOAD_MB` | 否 | `100` | 最大 APK 上传大小（以兆字节为单位） | | `RATE_LIMIT_PER_MINUTE` | 否 | `30` | 每个客户端 IP 每分钟的请求数 | | `MAX_LLM_CALLS_PER_SCAN` | 否 | `40` | 每次扫描超出预算错误前的最大 LLM 工具调用次数 | ## 分析约束 以下规则在代码中强制执行，无法在运行时覆盖： - APK 绝不会在宿主机上执行——威胁情报仅通过 VirusTotal sandbox 检索 - 在任何处理开始之前，都会验证 Magic byte (`PK\x03\x04`) - 风险评分 >= 70 会产生 CRITICAL 判定，并自动标记以供立即 SOC 审查 - IOC 提取由确定性 regex 执行，而不是由 LLM 执行，从而确保可重现性 ## 路线图 | 计划 | 状态 | 范围 | |---|---|---| | 计划 1 | 已完成 | 基础架构，追踪弹道——单代理，单 MCP server，同步 API | | 计划 2 | 已完成 | 完整的六代理 pipeline，生产级安全强化 | | 计划 3 | 已规划 | 实时 SSE 流式传输，PDF 导出，MalwareBazaar 预检 | | 计划 4 | 已规划 | mcp-yara，mcp-osint，IOC 资源管理器，基于文件的报告存储，趋势仪表板 | | 计划 5 | 已规划 | 评估测试套件，CI 集成 | | 计划 6 | 已规划 | 部署，演示准备 | ## 许可证 保留所有权利。

标签：Android, AV绕过, DAST, DSL, FastAPI, GenAI, 云资产清单, 安全, 恶意软件分析, 搜索引擎查询, 测试用例, 请求拦截, 超时处理, 逆向工具, 逆向工程