arkadiyt/ssrf_filter

# ssrf_filter [](https://rubygems.org/gems/ssrf_filter) [](https://static.pigsec.cn/wp-content/uploads/repos/2026/04/0eb388b6f2034905.svg) [](https://coveralls.io/github/arkadiyt/ssrf_filter?branch=main) [](https://rubygems.org/gems/ssrf_filter) [](https://github.com/arkadiyt/ssrf_filter/blob/master/LICENSE.md) ## 目录 - [用途](https://github.com/arkadiyt/ssrf_filter#whats-it-for) - [快速开始](https://github.com/arkadiyt/ssrf_filter#quick-start) - [API 参考](https://github.com/arkadiyt/ssrf_filter#api-reference) - [更新日志](https://github.com/arkadiyt/ssrf_filter#changelog) - [贡献](https://github.com/arkadiyt/ssrf_filter#contributing) ### 用途 ssrf_filter 让防御服务端请求伪造 (SSRF) 攻击变得简单。当你在服务器上接受 URL 作为用户输入并进行抓取时（例如，当用户在 Twitter/Facebook 状态更新中输入链接并生成内容预览时），就会发生 SSRF 漏洞。 用户可以传入 URL 或 IP，导致你的服务器向内部网络发起请求。例如，如果你托管在 AWS 上，他们可以请求[实例元数据端点](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html) `http://169.254.169.254/latest/meta-data/` 并获取你的 IAM 凭证。 防御此类攻击的尝试通常实施不当，例如通过阻止所有 IP 地址、未正确处理 IPv6 或 HTTP 重定向，或者存在 TOCTTOU 漏洞及其他问题。 这个 gem 提供了一种安全且简单的方式来从用户提交的 URL 抓取内容。它： - 正确处理 URI/IPv4/IPv6、重定向、DNS 等 - 具有 0 个运行时依赖 - 拥有全面的测试套件（100% 代码覆盖率） - 已针对 ruby `2.7`、`3.0`、`3.1`、`3.2`、`3.3`、`3.4`、`3.5`、`4.0` 和 `ruby-head` 进行了测试 ### 快速开始 1. 将 gem 添加到你的 Gemfile 中： ``` gem 'ssrf_filter', '~> 1.5.0' ``` 2. 在你的代码中： ``` require 'ssrf_filter' response = SsrfFilter.get(params[:url]) # throws an exception for unsafe fetches response.code => "200" response.body => "\n\n\n..." ``` ### API 参考 `Ssrf_filter.get/.put/.post/.delete/.head/.patch(url, options = {}, &block)` 分别使用 get/put/post/delete/head/patch 请求抓取指定的 URL。 参数： - `url` — 要抓取的 URL。 - `options` — 选项哈希（如下所述）。 - `block` — 一个代码块，将在发送之前接收 [HTTPRequest](https://ruby-doc.org/stdlib-2.4.1/libdoc/net/http/rdoc/Net/HTTPGenericRequest.html) 对象，如果你需要对其进行任何预处理（参见下面的示例）。 选项哈希： - `:scheme_whitelist` — 允许的协议（scheme）数组。默认为 `%w[http https]`。 - `:resolver` — 一个 proc，接收主机名字符串并返回 [IPAddr](https://ruby-doc.org/stdlib-2.4.1/libdoc/ipaddr/rdoc/IPAddr.html) 对象数组。默认使用 Ruby 的 [Resolv](https://ruby-doc.org/stdlib-2.4.1/libdoc/resolv/rdoc/Resolv.html) 进行解析。有关自定义解析器，请参见下面的示例。 - `:max_redirects` — 要跟随的最大重定向次数。默认为 10。 - `:params` — 随请求发送的参数哈希。 - `:headers` — 随请求发送的标头哈希。 - `:body` — 随请求发送的主体。 - `:http_options` – 传递给 [Net::HTTP.start](https://ruby-doc.org/stdlib-2.6.4/libdoc/net/http/rdoc/Net/HTTP.html#method-c-start) 的选项。使用此选项设置自定义超时或 SSL 选项。 - `:request_proc` - 一个 proc，接收请求对象，用于在发送请求之前进行自定义修改。 - `:allow_unfollowed_redirects` - 如果为 true 且你的请求达到了最大重定向次数，将返回最后的响应而不是抛出错误。默认为 false。 - `:sensitive_headers` — 在跟随跨域重定向（当协议、主机或端口发生变化时）时不会被转发的标头名称（不区分大小写）数组。默认为 `%w[authorization cookie]`。传递 `[]` 以禁用此保护。 - `:on_cross_origin_redirect` — 控制当跨域重定向会导致发送敏感标头时的行为。`:strip`（默认）静默移除它们并跟随重定向；`:raise` 抛出 `SsrfFilter::CredentialLeakage`。 返回： 如果 URL 被安全抓取，则返回 [HTTPResponse](https://ruby-doc.org/stdlib-2.4.1/libdoc/net/http/rdoc/Net/HTTPResponse.html) 对象；如果不安全，则抛出异常。所有异常均继承自 `SsrfFilter::Error`。 示例： ``` # GET www.example.com SsrfFilter.get('https://www.example.com') # 传递 params - 这些是等价的 SsrfFilter.get('https://www.example.com?param=value') SsrfFilter.get('https://www.example.com', params: {'param' => 'value'}) # POST，发送自定义 header，并且不跟随重定向 begin SsrfFilter.post('https://www.example.com', max_redirects: 0, headers: {'content-type' => 'application/json'}) rescue SsrfFilter::Error => e # Got an unsafe url end # 自定义 DNS 解析和请求处理 resolver = proc do |hostname| [IPAddr.new('2001:500:8f::53')] # Static resolver end # 对请求进行一些额外处理 request_proc = proc do |request| request['content-type'] = 'application/json' request.basic_auth('username', 'password') end SsrfFilter.get('https://www.example.com', resolver: resolver, request_proc: request_proc) # Stream 响应 SsrfFilter.get('https://www.example.com') do |response| response.read_body do |chunk| puts chunk end end ``` ### 更新日志 请参阅 [CHANGELOG.md](https://github.com/arkadiyt/ssrf_filter/blob/master/CHANGELOG.md)。本项目遵循[语义化版本控制](https://semver.org/)。 ### 贡献 请参阅 [CONTRIBUTING.md](https://github.com/arkadiyt/ssrf_filter/blob/master/CONTRIBUTING.md)。

标签：AWS 元数据保护, HTTP 重定向安全, IPv6 安全, IP 地址批量处理, Ruby, Ruby Gem, SSRF 防护, URL 验证, Web 安全, 开源库, 搜索引擎爬虫, 服务端请求伪造, 沙箱隔离, 漏洞防御, 知识库, 网络安全, 输入过滤, 隐私保护