tsc-security/py-url-security

# py-url-security 严格且防 SSRF 的 URL 验证及 Python 出站 HTTP 辅助库。 `py-url-security` 在发起请求前会对 URL 进行验证和解析，阻止非公有网络访问，将连接锚定到预验证的 IP，并强制执行响应大小限制。 ## 功能特性 - 仅允许 `http` 和 `https`。 - 仅允许端口 `80` 和 `443`。 - 拒绝嵌入凭据、片段、路径参数和控制字符。 - 拒绝私有/内部/回环/链路本地/多播/保留 IP 目标。 - 先进行 DNS 解析，验证每个解析地址，然后连接到锚定 IP。 - 支持可配置限制的安全重定向处理。 - 设置响应体大小上限以避免无限内存增长。 ## 环境要求 - Python `3.11+` - Poetry `1.8+` - Make ## 安装 ``` poetry install ``` ## 快速开始 ``` from url_security import UrlSecurity, UnsafeUrlError url = "https://example.com" if UrlSecurity.is_safe(url): response = UrlSecurity.fetch(url) print(response.status, response.final_url, response.remote_ip) else: print("Unsafe URL") try: target = UrlSecurity.resolve("https://example.com/path?q=1") print(target.hostname, target.addresses) except UnsafeUrlError as exc: print(f"Rejected: {exc}") ``` ## API ### `UrlSecurity.is_safe(url: str) -> bool` 当 URL 通过策略验证和 DNS/IP 检查时返回 `True`。 这仅是一个预检验证器。请使用 `fetch(...)` 在同一个流程中执行包含 DNS/IP 验证和锚定连接的实际请求。 ### `UrlSecurity.resolve(url: str) -> ResolvedTarget` 解析并验证 URL，然后返回规范的 `ResolvedTarget`： - `url` - `scheme` - `hostname` - `port` - `path_and_query` - `addresses`（已验证的公有 IP） ### `UrlSecurity.fetch(...) -> SafeHttpResponse` 使用锚定地址和感知策略的重定向执行安全请求。 主要参数： - `method`：HTTP 方法（默认：`GET`） - `headers`：可选的请求头 - `body`：可选的原始请求体 - `timeout`：单次请求超时时间（秒） - `max_redirects`：重定向限制 - `max_response_bytes`：响应大小上限 - `allow_redirects`：启用/禁用跟随重定向 返回一个 `SafeHttpResponse`： - `status` - `reason` - `headers` - `body` - `final_url` - `remote_ip` - `redirect_count` 响应头通过不区分大小写的映射暴露，键为小写的 header 名称，将重复项保留为元组： `Mapping[str, tuple[str, ...]]`。 ## 异常 - `SafeHttpError`：基础请求/传输失败。 - `UnsafeUrlError`：URL/DNS/IP 策略违规。 - `RedirectPolicyError`：无效或过多的重定向。 - `ResponseTooLargeError`：body 超出配置限制。 ## 开发 使用 `Makefile` 作为主要接口： ``` make ``` ### 显示可用目标 ``` make help ``` ### 运行测试 ``` make test ``` ### 仅运行单元测试 ``` make test-unit ``` ### 运行集成测试（真实公有主机） ``` make test-integration ``` 集成测试是可选的，并依赖于外部网络/DNS。它们针对安全的公有主机，例如 `google.com`、`apple.com` 和 `microsoft.com`。 `make test-integration` 目标以跨平台的方式（Linux/macOS/Windows）启用集成模式。 ### 运行覆盖率报告 ``` make coverage ``` `make coverage` 强制执行至少 `90%` 的覆盖率，低于该阈值将失败。 ### Lint 和格式化 ``` make lint make lint-fix make format make format-check ``` ### 推荐的本地质量门禁 ``` make quality ``` ## 本项目的 Ruff 策略 Ruff 在 `pyproject.toml` 中配置了： - 通过 `ruff format` 进行格式化 - 针对正确性、风格、导入、简化和 docstrings 的 Lint 家族 - Pydocstyle 规范与 PEP 257 对齐 - 为了提高测试可读性，有意放宽了测试 docstring 检查

标签：API密钥检测, CISA项目, DNS重绑定防护, IP绑定, Python 3, SSRF防护, URL验证, XML 请求, 安全开发, 安全编码, 开源安全工具, 漏洞缓解, 白名单, 网络安全, 请求过滤, 输入验证, 逆向工具, 逆向工程平台, 隐私保护