andrewpopov/url-guard
GitHub: andrewpopov/url-guard
Node.js 服务端 SSRF 防护库，在发起用户提供的 URL 请求前，对协议、主机名和 DNS 解析地址进行预检拦截，阻止请求触达内网与保留地址段。
Stars: 0 | Forks: 0
# @andrewpopov/url-guard
一个用于服务端获取用户提供的 URL 的 **SSRF guard**。它是四个手动编写的副本（cairn, bewks, savoro, smarthome）的超集 —— 这样每个使用者都能获得最强大的版本，而不是他们碰巧自己写的那个版本。
拦截：
- 非 `http(s)` 协议、嵌入凭据以及（可选的）不允许的端口；
- 在进行任何 DNS 查询之前，拦截 `localhost` 和内部后缀主机（`.local`、`.internal`、`.home.arpa`、…）；
- IP 字面量主机，以及 **DNS 解析** 为私有 / 回环 / 链路本地 / CGNAT / 元数据 / 多播 / 保留 / TEST-NET 范围的主机名 —— 包括 IPv4 **和** IPv6，包括简单的字符串匹配 guard 会遗漏的十六进制 IPv4 映射形式（`::ffff:7f00:1`）。
零运行时依赖 —— 仅使用 Node `dns` + `net`（Node ≥ 20）。
## 安装
```
npm install github:andrewpopov/url-guard#v0.1.4
```
## 使用
```
import { assertSafeUrl, UrlNotAllowedError } from '@andrewpopov/url-guard';
try {
const url = await assertSafeUrl(userUrl, { label: 'Webhook URL' });
// This is a validated preflight result, not a pinned connection.
} catch (err) {
if (err instanceof UrlNotAllowedError) {
// err.reason: 'protocol' | 'credentials' | 'blocked_host' | 'blocked_address' | ...
throw new BadRequest(err.message);
}
throw err;
}
```
它可以直接作为注入的 guard 插入 `@andrewpopov/webhook-kit`：
```
await deliverWebhooks(targets, body, {
assertSafeUrl: (url) => assertSafeUrl(url, { label: 'Webhook URL' }),
});
```
## 选项
| 选项 | 默认值 | 用途 |
|---|---|---|
| `label` | `"URL"` | 在错误消息中命名该 URL。 |
| `allowedProtocols` | `['http:','https:']` | 允许的协议。 |
| `allowedPorts` | any | 如果设置，则必须列出非默认端口（例如 `['80','443']`）。 |
| `requireHttps` | `false` | 拒绝 `http:`（要求 TLS）。 |
| `lookup` | `dns.lookup(host,{all,verbatim})` | 用于测试的可注入解析器。 |
## 导出
`assertSafeUrl`、`UrlNotAllowedError` 以及基础构建块 `isBlockedIp`、
`isBlockedIPv4`、`isBlockedIPv6`、`ipv6ToBytes`、`isBlockedHostname`、
`BLOCKED_HOSTNAMES`、`BLOCKED_HOSTNAME_SUFFIXES`。
## 安全边界：仅限预检
`assertSafeUrl` 仅在 **其运行时** 验证 URL 及其 DNS 响应。
它无法保证后续的普通 `fetch(url)` 是安全的：该 fetch 会再次解析
主机名，因此 DNS rebinding 可能会在验证后更改目标。
对于不受信任的 URL，请使用连接到已审查 IP 的传输方式，同时
保留原始的 Host/SNI 身份，并拒绝重定向，或者
验证并锁定每一个重定向跃点。在使用前重新检查并设置
`redirect: 'manual'` 可以降低风险，但并不能将此预检辅助工具
转变为完整的 SSRF 边界。请勿将其作为控制元数据、
回环或内部网络访问的唯一手段。
## 本地验证
```
npm ci
npm run verify
npm audit --omit=dev --audit-level=high
```
## 标准
请参阅 [`STANDARDS.md`](./STANDARDS.md)（从 `agent_brain/knowledge/shared-package-standards.md` 同步）。
## 项目政策
请参阅[贡献指南](./CONTRIBUTING.md)、[支持](./SUPPORT.md)和
[安全政策](./SECURITY.md)。本软件包根据 [MIT](./LICENSE) 授权。
标签：API密钥检测, GNU通用公共许可证, MITM代理, Node.js, SSRF防护, URL校验, Web安全, 暗色界面, 网络访问控制, 自动化攻击, 蓝队分析, 输入验证