rakshit-737/warden-supply-chain-firewall

## 为什么开发此项目 现代应用程序主要由第三方代码组成，而仅仅一次 `pip install` 就会以开发者或 CI 运行器的完整权限执行代码。攻击者利用这一点，通过恶意发布（在安装时窃取机密信息的代码）、**typosquat**（域名/包名抢注，例如用 `reqeusts` 伪装 `requests`）以及**依赖混淆**来进行武器化攻击。 传统的漏洞扫描器**根本无法捕捉到这些威胁** —— 因为对于尚未有人报告的包，是不存在 CVE 记录的。Warden 是一种*行为*控制措施：它根据**包的构建方式及其具体行为**来决定一个包是否可信，而不是依赖漏洞数据库。这一区别正是该项目的核心所在。 ## 它的功能 ``` flowchart LR CLI["warden CLI / CI gate"] -->|POST /scan| API UI["Security dashboard"] -->|REST + JWT| API subgraph API["FastAPI backend"] direction TB O["Orchestrator"] --> F["PyPI fetcher
(safe extraction)"] F --> AZ["6 analyzers →
signals"] AZ --> SC["Hybrid scorer
rules + ML"] SC --> PE["Policy engine"] end API --> DB[("PostgreSQL")] API --> RC[("Redis")] SC --> ML["scikit-learn model"] ``` 对于一个给定的 `(name, version)`（名称与版本），它能够在几百毫秒内完成： 1. **获取**从 PyPI 下载的真实源代码发行版，并在严格的防 zip 炸弹 / 防路径遍历保护下进行解压 —— **全程绝不执行包内的代码**。 2. **分析**通过六个独立的 analyzer 生成可解释的*信号*：元数据/来源信息、基于 AST 的行为分析、安装时执行行为、typosquat 检测、代码混淆检测以及已知 IOC 匹配。 3. **评分**使用*分层*规则引擎 **以及**经过校准的 ML 模型（RandomForest + IsolationForest）对信号进行评分，并采取保守的融合策略。 4. **决策**根据可调的组织策略决定是允许 / 警告 / 拦截，并记录一条可审计的判定结果，同时附上驱动该决策的具体信号。 ## 供审阅者查看的亮点 - **基于行为而非签名** — 能够捕捉前所未见的恶意包。 - **全程可解释** — 每一项判定都会列出触发信号及策略规则；仪表板会同时显示规则评分和 ML 评分。 - **ML 的合理运用** — 非线性风险概率预测 + 无监督异常检测，如果模型缺失则能优雅降级为仅使用规则。（参见 [`ML_MODEL.md`](docs/ML_MODEL.md)。） - **针对恶意输入的加固** — analyzer 的设计初衷就是考虑到其输入是由攻击者伪造的：安全的解压机制、严格的体积/时间/数量上限，并且**不执行任何代码**。（参见 [`THREAT_MODEL.md`](docs/THREAT_MODEL.md)。） - **符合生产级标准** — 带有 refresh 轮换的 JWT 认证、argon2id 哈希加密、RBAC、带有请求 ID 的结构化日志、速率限制、追加式审计追踪、Alembic 数据库迁移、完整的测试套件、采用只读非 root runtime 的容器化部署，以及 CI 流水线。 ## 技术栈 | 层级 | 技术选型 | |-------|---------| | Backend | Python 3.12, FastAPI, SQLAlchemy 2, Alembic, pydantic v2 | | 分析 / ML | Python `ast`, scikit-learn (RandomForest + IsolationForest), joblib | | 数据 | PostgreSQL, Redis (cache + rate limiter) | | Frontend | React 18, TypeScript, Vite, Tailwind CSS, Recharts | | 交付 | Docker + docker-compose, GitHub Actions CI, `warden` CLI | ## 快速开始 (Docker — 全栈) ``` git clone warden && cd warden export SECRET_KEY=$(python -c "import secrets;print(secrets.token_urlsafe(48))") docker compose up --build ``` - 仪表板: - API + Swagger 文档: - 使用初始管理员账号登录 (`admin@warden.io` / `ChangeMe_Warden!2026` — 可通过 `FIRST_ADMIN_EMAIL` / `FIRST_ADMIN_PASSWORD` 覆盖设置)。 ## 快速开始 (仅后端，无外部服务) 后端可以在 SQLite 和进程内 cache 的支持下运行 —— 无需 Postgres/Redis —— 这也正是测试套件运行的方式。 ``` cd backend pip install -r requirements-dev.txt python -m ml.train # generate dataset + train the model (a few seconds) uvicorn app.main:app --reload # http://localhost:8000/docs pytest -q # 40 tests, fully offline ``` 前端: ``` cd frontend && npm install && npm run dev # http://localhost:5173 ``` ## 将 CLI 用作 CI 拦截机制 ``` # 一个 package python -m cli.warden_cli scan requests==2.32.3 --api http://localhost:8000 --token "$WARDEN_TOKEN" # 拦截整个 requirements 文件 —— 如果有任何内容被 BLOCKED，则以非零状态退出 python -m cli.warden_cli gate -r requirements.txt --api "$WARDEN_API" --token "$WARDEN_TOKEN" --fail-on block ``` 输出示例： ``` ALLOW risk= 25 requests==2.32.3 [SINGLE_MAINTAINER; NETWORK_EGRESS] BLOCK risk=100 reqeusts==1.0.0 [TYPOSQUAT; INSTALL_HOOK_EXEC; IOC_MATCH] Gate FAILED (fail-on=block): reqeusts==1.0.0 ``` ## 检测调优的工作原理 (核心亮点) 合法的库*确实会*调用网络、启动 shell 并读取环境变量 —— 因此简单地标记这些行为会产生误报。Warden 将信号划分为两个层级： - **主要指标** (安装时的网络/eval 调用、IOC 匹配、typosquat、混淆的 loader、敏感凭据访问) — *任意一个*指标就可以将包的风险等级提升至高/危险。 - **辅助能力** (常规网络访问、subprocess、动态 exec、来源验证) — 这些信号的累加上限被**限制在一个阈值内**，因此像 `numpy` 这样复杂但无害的包其风险评级只会是*中等*，绝不会达到*危险*级别。 已发布的模型 + 规则在真实 PyPI 包上的实测表现： | 包名 | 风险分 | 判定 | 包名 | 风险分 | 判定 | |---------|-----:|---------|---------|-----:|---------| | `requests` | 25 | 低 | typosquat + 安装时数据窃取 (合成包) | 100 | **拦截** | | `flask` | 31 | 低 | 混淆的 base64 loader (合成包) | 100 | **拦截** | | `numpy` | 40 | 中等 | 凭据窃取程序 (合成包) | 100 | **拦截** | ## 代码库结构 ``` warden/ ├── backend/ │ ├── app/ │ │ ├── analysis/ # fetcher, analyzers, scoring, ML serving │ │ │ └── analyzers/ # metadata, static_code, install_script, typosquat, obfuscation, ioc │ │ ├── api/ # routers, deps (RBAC), middleware │ │ ├── core/ # config, security, logging, errors, cache/rate-limit │ │ ├── db/ # models, session, portable types, seed │ │ ├── policy/ # policy engine │ │ └── main.py # app factory │ ├── ml/ # dataset generator + training pipeline │ ├── cli/ # `warden` CI gate │ ├── alembic/ # migrations │ └── tests/ # 40 tests incl. adversarial-extraction security tests ├── frontend/ # React + TS + Tailwind dashboard ├── docs/ # ideation, architecture, threat model, data model, ML, API ├── docker-compose.yml └── .github/workflows/ci.yml ``` ## 文档 - [`IDEATION.md`](docs/IDEATION.md) — 20 个候选创意、评分机制以及该方案胜出的原因。 - [`ARCHITECTURE.md`](docs/ARCHITECTURE.md) — 组件构成、请求生命周期及权衡取舍。 - [`THREAT_MODEL.md`](docs/THREAT_MODEL.md) — STRIDE 模型 + 对抗性输入处理。 - [`DATA_MODEL.md`](docs/DATA_MODEL.md) — ER 图与 schema 设计依据。 - [`ML_MODEL.md`](docs/ML_MODEL.md) — 特征、训练过程、评估及坦诚的局限性说明。 - [`API.md`](docs/API.md) — endpoint 参考 (实时 OpenAPI 文档位于 `/docs`)。 ## 路线图 npm 生态系统的 analyzer · 动态沙箱引爆 (gVisor/Firecracker) · 完整的传递依赖树扫描 · PEP 503 内联拦截 registry 代理 · 分析师人工干预的重训练闭环。参见 [`ARCHITECTURE.md`](docs/ARCHITECTURE.md#9-roadmap-documented-extensions)。 ## 许可证 MIT — 详见 [`LICENSE`](LICENSE)。

标签：Apex, AV绕过, FastAPI, Python, React, Syscalls, 云安全监控, 域名收集, 恶意依赖检测, 搜索引擎查询, 文档安全, 无后门, 机器学习, 测试用例, 请求拦截, 软件供应链安全, 远程方法调用, 逆向工具, 配置审计, 静态分析