maxgfr/ultrasec

# ultrasec `ultrasec` 是 `ultra*` 系列中的一个 [agent skill](https://skills.sh) （[ultraindex](https://github.com/maxgfr/ultraindex) 和 [ultrasearch](https://github.com/maxgfr/ultrasearch) 的兄弟项目）。它遵循相同的 分工原则： - 一个**确定性的、零依赖引擎**（`scripts/ultrasec.mjs`，使用 `node` 运行，无需 `npm install`，也无需 API keys）负责机械性工作 —— 扫描 代码库，构建一个**跨文件/函数的 link-graph**，枚举候选的 **source→sink taint paths**，运行并标准化任何已安装的外部 scanners， 并为每个发现组装 **evidence packets**； - **AI** 负责安全推理 —— 判断哪些候选流是真实的且可跨文件利用的，寻找 工具遗漏的细微 authz/business-logic 漏洞，并对 每个发现进行**对抗性验证**（保守验证 —— 不确定的高严重性漏洞会标记为 `needs-human`，绝不自动消除）。 它存在的意义：执行跨文件 taint 追踪的确定性引擎（CodeQL global flow, Semgrep Pro, Joern）很精准，但将其置于付费墙之后，且会遗漏 business-logic 缺陷；纯 LLM scanners 会幻觉，且仅限于 diff 范围。 `ultrasec` 占据了中间地带 —— 一个**显式的跨文件 link-graph** 加上**对抗性 AI 验证** —— 并保持全代码库覆盖和防幻觉 （每个发现都必须引用可解析的 `[file:line]` 跳转）。 ## 安装 **作为 agent skill**（Claude Code, Cursor, … 通过 [skills.sh](https://skills.sh)）： ``` npx skills add maxgfr/ultrasec ``` 这会将 `SKILL.md` + `references/` + 已提交的 `scripts/ultrasec.mjs` bundle 放入您 agent 的 skills 目录中。然后，您的 agent 会在 “audit this repo for security”、“find vulnerabilities” 等指令下触发它。 **独立运行**（仅 CLI —— 无需 agent）： ``` git clone https://github.com/maxgfr/ultrasec && cd ultrasec node scripts/ultrasec.mjs --help # the committed bundle runs as-is (zero deps, Node >= 18) ``` **从 release tarball 安装：** 从 [最新发布](https://github.com/maxgfr/ultrasec/releases) 获取 `ultrasec-.tgz`，执行 `tar xf` 解压，并 运行 `node package/scripts/ultrasec.mjs`。 无需 `npm install`，无需 API keys —— 该引擎是一个单一的无依赖 bundle。 外部 scanners 是可选的，并且会被自动检测（参见下方的 [Docker](#analysis-tools-via-docker)）。 ## 快速开始 ``` node scripts/ultrasec.mjs tools # installed scanners + how to get the rest node scripts/ultrasec.mjs scan --repo . --out .ultrasec # graph + cross-file taint + tools → dossier node scripts/ultrasec.mjs paths --run .ultrasec # the candidate source→sink chains node scripts/ultrasec.mjs dossier --run .ultrasec # one finding's real code + path (adjudicate) node scripts/ultrasec.mjs verify --run .ultrasec # adversarial worklist → write verdicts.json node scripts/ultrasec.mjs verify --apply verdicts.json --run .ultrasec node scripts/ultrasec.mjs check --run .ultrasec --semantic # exit gate: grounded + adjudicated node scripts/ultrasec.mjs render --run .ultrasec # SUMMARY/REPORT/FULL.md + index.html ``` 无需任何外部工具 —— link-graph 和 taint 推理是 常开的核心。已安装的 scanners（Trivy, OpenGrep/Semgrep, gitleaks, osv-scanner, cargo-audit, govulncheck, …）是自动的额外奖励，它们会被标准化整合到一个 发现模型中。 有关完整的运行流程，请参阅 [`assets/example-audit/`](assets/example-audit/)，有关 agent 工作流程（包含 [深度审计指南](references/deep-audit-playbook.md)），请参阅 [`SKILL.md`](SKILL.md) + [`references/`](references/)。 ## 通过 Docker 使用分析工具 ultrasec 编排了顶级的开源 OSS scanners，并将它们的输出标准化为一个统一的 发现模型。您无需安装任何工具 —— 这里提供两条 Docker 路径： **1. `--docker`（零安装）。** ultrasec 会按需从其官方的、 锁定版本的镜像中运行每个 scanner，并将您的代码库 bind-mounted 到 `/work`： ``` node scripts/ultrasec.mjs scan --repo . --out .ultrasec --docker # 通过 docker 运行：trivy, gitleaks, osv-scanner, semgrep — 只要是有 image 的都可以 node scripts/ultrasec.mjs scan --repo . --docker --tools trivy,gitleaks # pick a subset ``` 仅需要 Docker。报告的路径会自动从 `/work` 重写回 代码库的相对路径。锁定的镜像包括：`ghcr.io/aquasecurity/trivy:0.71.1`, `ghcr.io/gitleaks/gitleaks:v8.30.1`, `ghcr.io/google/osv-scanner:v2.3.8`, `semgrep/semgrep:1.166.0`。 **2. 工具箱镜像（内置所有工具）。** 构建一个包含引擎和所有 捆绑 scanners 的镜像，并在其中运行整个审计过程： ``` docker compose build TARGET=/path/to/repo docker compose run --rm ultrasec scan --repo /work --out /work/.ultrasec TARGET=/path/to/repo docker compose run --rm ultrasec tools # all show ✓ installed ``` 有关完整的 scanner 矩阵和 建议添加的工具（trufflehog, checkov, syft, bandit, brakeman），请参阅 [`references/tools.md`](references/tools.md)。 ## 在真实项目中测试 已在真实的、故意带有漏洞的代码库中**端到端验证了 Docker 工具箱** （包含引擎 + trivy + osv-scanner + semgrep + gitleaks，共四款 scanners）： | 代码库 | 语言 | 发现 (taint + tools) | 亮点 | |------|------|--------------------------|------------| | [OWASP/NodeGoat](https://github.com/OWASP/NodeGoat) | JS | **275** — 13 taint · 262 tool (trivy 67, osv 163, semgrep 29, gitleaks 3) | 标志性的服务端 **`eval()` SSJI** (`eval(req.body.…)`, CWE-94)、**命令注入**、**开放重定向**、反射型 **XSS** —— 外加依赖项 CVE、硬编码的 secrets（包含一个私钥），以及 SAST 发现 | | [we45/Vulnerable-Flask-App](https://github.com/we45/Vulnerable-Flask-App) | Python | **206** — 6 taint · 200 tool (trivy 69, osv 110, semgrep 21) | **SQLi**、**不安全的反序列化**、**路径遍历**、**SSTI**、**弱加密** (CWE-89/502/22/79/327) —— 外加 Python 依赖项 CVE 和 SAST | 每个发现的路径都是相对于代码库的，并且基础校验门（`check`）在 所有路径上均通过；随后，每一项都会由 AI 进行裁定，确认无误后才算作已证实。 重现： ``` TARGET=/path/to/repo docker compose run --rm ultrasec scan --repo /work --out /work/.ultrasec ``` ## 工作原理 | 阶段 | 负责者 | 内容 | |-------|-----|------| | scan | engine | 遍历代码库 → 跨文件/函数 link-graph（约 15 种语言）→ 枚举候选 source→sink taint paths → 运行已安装的 scanners → evidence packets | | adjudicate | **AI** | 沿着每条路径阅读真实代码；确认可达性 + 可利用性；发现工具遗漏的 authz/business-logic 漏洞 | | verify | **AI** + engine | 对抗性工作清单，保守的校验门（不确定的高严重性漏洞 → `needs-human`，绝不自动丢弃） | | report | engine | 有事实依据的、带引用的、分层的 Markdown + 独立 HTML | ## 开发 ``` pnpm install pnpm typecheck && pnpm test && pnpm run check:build # the CI gate ``` 发布过程是自动化的：`main` 上的 Conventional Commits 驱动 semantic-release （GitHub release + tarball）。 ## License MIT

标签：C2, GNU通用公共许可证, MITM代理, Node.js, 对称加密, 自动化审计, 自动化攻击, 请求拦截, 静态应用安全测试