josebright/iot-deviceshield

# IoT-DeviceShield 智能家居设备漏洞查询工具，基于 NIST NVD 数据支持，并由本地托管的 LLM 提供增强功能。包含 NestJS API、Next.js 仪表盘、PostgreSQL，全部通过 Docker Compose 串联在一起。 该项目的核心目的：选择一款智能家居设备，查看针对其发布的 CVE，并阅读关于每个漏洞含义的通俗语言摘要。无需托管的 AI 提供商，无需注册 API 密钥，也没有请求配额限制。语言模型完全在你的本地机器上运行。 ## 状态 这是我为了提升后端和 DevSecOps 技能而构建的个人项目。它支持在本地端到端完整运行。该项目没有部署在任何公共环境，也没有针对多租户工作负载进行生产级别的强化。 - CVE 数据源：NIST NVD REST API 2.0（公开，无需身份验证，可选的 API 密钥可提高速率限制）。 - AI 增强：运行 Qwen 2.5 3B 开源权重模型的 [Ollama](https://ollama.com)。所有处理都在你的机器上完成；不会有任何数据离开你的网络。 - 存储：PostgreSQL 16。 ## 快速开始 前置条件：Docker Desktop（或 Docker Engine + Compose v2）。建议在具有 8 GB 或更多内存的笔记本电脑上运行。 ``` git clone https://github.com/josebright/iot-deviceshield.git cd iot-deviceshield cp .env.example .env # 生成用于保护 admin/catalog mutation routes 的 admin token： printf "ADMIN_API_TOKEN=%s\n" "$(openssl rand -hex 32)" >> .env docker compose --env-file .env -f infra/docker/docker-compose.yml up -d ``` 首次启动时会下载 Ollama 镜像（约 1 GB）和 Qwen 2.5 3B 模型（约 1.9 GB）。在全新克隆的情况下大约需要 5–10 分钟。由于 volume 会同时缓存这两者，随后的启动将是瞬间完成的。 然后打开 [http://localhost:3001](http://localhost:3001)。 ## 功能说明 1. 首次启动时，API 会遍历一个包含约 18 个智能家居设备的精选目录（`packages/catalog/src/catalog.json`），将它们 upsert 到 Postgres 中，并请求 NIST CPE 字典为每个设备解析标准的 CPE 标识符。具有较高置信度的匹配项将用于后续的 CVE 查找。 2. 当用户在 Web 应用上选择一个设备时，API 会查询 NIST NVD 以获取与该设备匹配的 CVE（如果可用，则通过 `cpeName` 查询，否则通过关键字搜索）。 3. 对于每个 CVE，API 会将描述发送到本地运行的 Qwen 2.5 模型，并以 JSON 格式请求生成五个通俗字段：漏洞内容、威胁、影响、受影响的系统以及建议。 4. 结果会按设备缓存在数据库中（默认 30 分钟）。在 TTL 时间内对同一设备的后续查询将从缓存中提供，只需几十毫秒。 5. 每个传入的请求都会被提取指纹（IP、user agent、`X-Client-Id`）并按客户端进行速率限制。屡次滥用者可以通过管理员 endpoint 自动限流或手动拉黑。 ## 技术栈（实际运行的内容） | 层级 | 选择 | | ---------- | ----------------------------------------------------------- | | Monorepo | pnpm workspaces + Turborepo | | API | NestJS 11 · TypeORM · PostgreSQL 16 · Zod 环境变量验证 | | Web | Next.js 15 App Router · React 19 · MUI 6 | | Shared | `@iot-deviceshield/types`, `@iot-deviceshield/catalog` | | AI | 运行 Qwen 2.5 3B 的 Ollama（Q4_K_M 量化） | | CVE feed | NIST NVD REST API 2.0 | | Container | 多阶段 Alpine Dockerfile，非 root 用户，healthchecks | | Rate limit | 基于指纹密钥的客户端限流 + 管理员黑名单 | | Observ. | nestjs-pino JSON 日志 · Web 端的 Sentry（通过 DSN 选择性启用） | ## 端点 公开端点（受速率限制，无需身份验证）： - `GET /v1/category` — 包含相关设备的类别 - `GET /v1/devices/:slug` — 通过 slug 获取单个设备 - `GET /v1/vulnerabilities?slug=` — 某设备的 CVE 及 AI 增强信息 - `GET /v1/health` — 存活状态 - `GET /v1/health/ready` — 就绪状态（数据库检查） 管理员端点（需要来自 `ADMIN_API_TOKEN` 的 bearer token）： - `POST /v1/catalog/refresh` — 强制重新同步目录和 CPE - `POST /v1/catalog/devices/:slug/resolve-cpe` — 为单个设备重试 CPE 解析 - `GET /v1/catalog/status` — 上次刷新时间、未解析的设备、错误日志 - `GET /v1/admin/clients` — 分页的指纹注册表 - `POST /v1/admin/clients/:id/blacklist` - `POST /v1/admin/clients/:id/unblacklist` 在开发环境中，Swagger UI 位于 [http://localhost:3000/v1/docs](http://localhost:3000/v1/docs)。 ## 仓库布局 ``` iot-deviceshield/ ├── apps/ │ ├── api/ # NestJS backend │ └── web/ # Next.js dashboard ├── packages/ │ ├── catalog/ # Curated device catalog + Zod schema │ ├── types/ # Shared DTOs and domain types │ ├── tsconfig/ # Shared TSConfig presets │ └── eslint-config/ # Shared ESLint config ├── infra/ │ └── docker/ # docker-compose stack ├── docs/ # ARCHITECTURE, SETUP, SECURITY └── .github/workflows/ # CI: lint, typecheck, test, security scans ``` ## 常用命令 ``` pnpm install # install workspaces pnpm dev # run api + web in watch mode pnpm build # production build for every workspace pnpm typecheck # tsc --noEmit across the monorepo pnpm lint # ESLint / next lint pnpm test # jest suites # Docker stack pnpm docker:up # start postgres + ollama + api + web pnpm docker:down # stop everything (keeps volumes) pnpm docker:rebuild # rebuild images without cache ``` ## 已测试与未测试内容 本次提交时的实际情况： | 领域 | 测试情况 | | --------------------------------------- | ---------------------------------------------------------------- | | 目录 schema（Zod 验证） | 是 | | CVSS 指标标准化 | 是 | | 漏洞服务（NIST + Ollama） | 否，通过 curl 和 UI 手动测试 | | 目录同步（upserts + CPE 解析） | 否，在首次启动时手动测试 | | 客户端指纹注册表 | 否，手动测试 | | 管理员端点 | 否，通过 `curl -H "Authorization: Bearer ..."` 手动测试 | | Web UI | 通过 Playwright 冒烟测试在本地构建和渲染 | 测试目录并不是这里的重点。真正的亮点在于系统架构，以及 AI 增强功能完全实现了离线运行。 ## 历史 该项目整合并替代了之前两个大学的论文代码库，这两个代码库将作为历史保留在线上： - [cve-vulnerability-api](https://github.com/josebright/smart-home-vulnerabilities) — 原始的 NestJS 后端 - [shd-risk-assessment](https://github.com/josebright/shd-risk-assessment) — 原始的 Next.js 仪表盘 这两个旧版代码库仍保持公开以供参考。均不再进行维护。 ## 文档 - [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — 数据模型、请求流程、安全态势、决策和权衡 - [docs/SETUP.md](docs/SETUP.md) — 本地开发、环境变量、常见坑 - [CONTRIBUTING.md](CONTRIBUTING.md) — 代码规范、工作流、PR 预期 - [SECURITY.md](SECURITY.md) — 漏洞披露政策 ## 许可证 该项目基于 **PolyForm Noncommercial License 1.0.0** 发布。你可以出于个人、研究或教育目的阅读、运行、复刻和修改代码。商业用途（包括托管公共部署）需要获得我的书面许可。详情请参阅 [LICENSE](LICENSE)。

标签：AI风险缓解, CVE, Docker Compose, NestJS, 数字签名, 本地大模型, 测试用例, 漏洞查询, 物联网, 自动化攻击, 请求拦截