1
- SafeURL
2
- =======
1
+ # SafeURL
3
2
4
3
[ ![ Build Status] [ badge-github ]] [ github-build ]
5
4
[ ![ Version] [ badge-version ]] [ hexpm ]
6
5
[ ![ Downloads] [ badge-downloads ]] [ hexpm ]
7
6
[ ![ License] [ badge-license ]] [ github-license ]
8
7
9
-
10
8
> SSRF Protection in Elixir 🛡️
11
9
12
-
13
10
SafeURL is a library that aids developers in protecting against a class of vulnerabilities
14
11
known as Server Side Request Forgery. It does this by validating a URL against a configurable
15
- allow or block list before making an HTTP request. SafeURL is open-source and licensed under
16
- MIT.
17
-
18
- This library was originally created by Nick Fox at [ Include Security] [ includesecurity ] ,
19
- with substantial improvements contributed by the [ Slab] [ slab ] team. As of January 2022, this
20
- library is now officially maintained by Slab.
12
+ allow or block list before making an HTTP request.
21
13
22
14
See the [ Documentation] [ docs ] on HexDocs.
23
15
24
16
<br >
25
17
26
-
27
-
28
-
29
18
## Installation
30
19
31
20
To get started, add ` safeurl ` to your project dependencies in ` mix.exs ` . Optionally, you may
@@ -45,9 +34,6 @@ To use SafeURL with your favorite HTTP Client, see the [HTTP Clients][readme-htt
45
34
46
35
<br >
47
36
48
-
49
-
50
-
51
37
## Usage
52
38
53
39
` SafeURL ` blocks private/reserved IP addresses are by default, and users can add additional
@@ -58,7 +44,6 @@ You can use `allowed?/2` or `validate/2` to check if a URL is safe to call. If y
58
44
[ ` HTTPoison ` ] [ lib-httpoison ] application available, you can also call ` get/4 ` which will
59
45
validate the host automatically before making a web request, and return an error otherwise.
60
46
61
-
62
47
``` elixir
63
48
iex> SafeURL .allowed? (" https://includesecurity.com" )
64
49
true
@@ -83,26 +68,23 @@ iex> SafeURL.get("https://google.com/")
83
68
84
69
<br >
85
70
86
-
87
-
88
-
89
71
## Configuration
90
72
91
73
` SafeURL ` can be configured to customize and override validation behaviour by passing the
92
74
following options:
93
75
94
- * ` :block_reserved ` - Block reserved/private IP ranges. Defaults to ` true ` .
76
+ - ` :block_reserved ` - Block reserved/private IP ranges. Defaults to ` true ` .
95
77
96
- * ` :blocklist ` - List of CIDR ranges to block. This is additive with ` :block_reserved ` .
97
- Defaults to ` [] ` .
78
+ - ` :blocklist ` - List of CIDR ranges to block. This is additive with ` :block_reserved ` .
79
+ Defaults to ` [] ` .
98
80
99
- * ` :allowlist ` - List of CIDR ranges to allow. If specified, blocklist will be ignored.
100
- Defaults to ` [] ` .
81
+ - ` :allowlist ` - List of CIDR ranges to allow. If specified, blocklist will be ignored.
82
+ Defaults to ` [] ` .
101
83
102
- * ` :schemes ` - List of allowed URL schemes. Defaults to ` ["http, "https"] ` .
84
+ - ` :schemes ` - List of allowed URL schemes. Defaults to ` ["http, "https"] ` .
103
85
104
- * ` :dns_module ` - Any module that implements the ` SafeURL.DNSResolver ` behaviour.
105
- Defaults to ` DNS ` from the [ ` :dns ` ] [ lib-dns ] package.
86
+ - ` :dns_module ` - Any module that implements the ` SafeURL.DNSResolver ` behaviour.
87
+ Defaults to ` DNS ` from the [ ` :dns ` ] [ lib-dns ] package.
106
88
107
89
These options can be passed to the function directly or set globally in your ` config.exs `
108
90
file:
@@ -119,16 +101,12 @@ Find detailed documentation on [HexDocs][docs].
119
101
120
102
<br >
121
103
122
-
123
-
124
-
125
104
## HTTP Clients
126
105
127
106
While SafeURL already provides a convenient [ ` get/4 ` ] [ docs-get ] method to validate hosts
128
107
before making GET HTTP requests, you can also write your own wrappers, helpers or
129
108
middleware to work with the HTTP Client of your choice.
130
109
131
-
132
110
### HTTPoison
133
111
134
112
For [ HTTPoison] [ lib-httpoison ] , you can create a wrapper module that validates hosts
@@ -157,7 +135,6 @@ iex> CustomClient.get("http://230.10.10.10/data.json", [], safeurl: [block_reser
157
135
{:ok , %HTTPoison .Response {.. .}}
158
136
```
159
137
160
-
161
138
### Tesla
162
139
163
140
For [ Tesla] [ lib-tesla ] , you can write a custom middleware to halt requests that are not
192
169
193
170
<br >
194
171
195
-
196
-
197
-
198
172
## Custom DNS Resolver
199
173
200
174
In some cases you might want to use a custom strategy for DNS resolution. You can do so by
@@ -203,13 +177,12 @@ config.
203
177
204
178
Example use-cases of this are:
205
179
206
- - Using a specific DNS server
207
- - Avoiding network access in specific environments
208
- - Mocking DNS resolution in tests
180
+ - Using a specific DNS server
181
+ - Avoiding network access in specific environments
182
+ - Mocking DNS resolution in tests
209
183
210
184
You can do so by implementing ` DNSResolver ` :
211
185
212
-
213
186
``` elixir
214
187
defmodule TestDNSResolver do
215
188
@behaviour SafeURL .DNSResolver
@@ -229,47 +202,36 @@ For more examples, see [`SafeURL.DNSResolver`][docs-dns] docs.
229
202
230
203
<br >
231
204
232
-
233
-
234
-
235
205
## Contributing
236
206
237
- - [ Fork] [ github-fork ] , Enhance, Send PR
238
- - Lock issues with any bugs or feature requests
239
- - Implement something from Roadmap
240
- - Spread the word :heart :
207
+ - [ Fork] [ github-fork ] , Enhance, Send PR
208
+ - Lock issues with any bugs or feature requests
209
+ - Implement something from Roadmap
210
+ - Spread the word :heart :
241
211
242
212
<br >
243
213
214
+ ## About
244
215
245
-
246
-
247
- ## License
248
-
249
- This package is available as open source under the terms of the [ MIT License] [ github-license ] .
216
+ SafeURL is officially maintained by the team at [ Slab] [ slab ] . It was originally created by Nick Fox at
217
+ [ Include Security] [ includesecurity ] .
250
218
251
219
<br >
252
220
253
-
254
-
255
-
256
- [ badge-github ] : https://github.com/slab/safeurl-elixir/actions/workflows/ci.yml/badge.svg
257
- [ badge-version ] : https://img.shields.io/hexpm/v/safeurl.svg
258
- [ badge-license ] : https://img.shields.io/hexpm/l/safeurl.svg
259
- [ badge-downloads ] : https://img.shields.io/hexpm/dt/safeurl.svg
260
-
261
- [ hexpm ] : https://hex.pm/packages/safeurl
262
- [ github-build ] : https://github.com/slab/safeurl-elixir/actions/workflows/ci.yml
263
- [ github-license ] : https://github.com/slab/safeurl-elixir/blob/master/LICENSE
264
- [ github-fork ] : https://github.com/slab/safeurl-elixir/fork
265
- [ slab ] : https://slab.com/
266
- [ includesecurity ] : https://github.com/IncludeSecurity
267
- [ readme-http ] : #http-clients
268
-
269
- [ docs ] : https://hexdocs.pm/safeurl
270
- [ docs-get ] : https://hexdocs.pm/safeurl/SafeURL.html#get/4
271
- [ docs-dns ] : https://hexdocs.pm/safeurl/SafeURL.DNSResolver.html
272
-
273
- [ lib-dns ] : https://github.com/tungd/elixir-dns
274
- [ lib-tesla ] : https://github.com/elixir-tesla/tesla
275
- [ lib-httpoison ] : https://github.com/edgurgel/httpoison
221
+ [ badge-github ] : https://github.com/slab/safeurl-elixir/actions/workflows/ci.yml/badge.svg
222
+ [ badge-version ] : https://img.shields.io/hexpm/v/safeurl.svg
223
+ [ badge-license ] : https://img.shields.io/hexpm/l/safeurl.svg
224
+ [ badge-downloads ] : https://img.shields.io/hexpm/dt/safeurl.svg
225
+ [ hexpm ] : https://hex.pm/packages/safeurl
226
+ [ github-build ] : https://github.com/slab/safeurl-elixir/actions/workflows/ci.yml
227
+ [ github-license ] : https://github.com/slab/safeurl-elixir/blob/main/LICENSE
228
+ [ github-fork ] : https://github.com/slab/safeurl-elixir/fork
229
+ [ slab ] : https://slab.com/
230
+ [ includesecurity ] : https://github.com/IncludeSecurity
231
+ [ readme-http ] : #http-clients
232
+ [ docs ] : https://hexdocs.pm/safeurl
233
+ [ docs-get ] : https://hexdocs.pm/safeurl/SafeURL.html#get/4
234
+ [ docs-dns ] : https://hexdocs.pm/safeurl/SafeURL.DNSResolver.html
235
+ [ lib-dns ] : https://github.com/tungd/elixir-dns
236
+ [ lib-tesla ] : https://github.com/elixir-tesla/tesla
237
+ [ lib-httpoison ] : https://github.com/edgurgel/httpoison
0 commit comments