Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix various typos, dead links and style #23

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Fix various typos, dead links and style #23

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
83 changes: 62 additions & 21 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,18 +1,26 @@
# SafeCurl

SafeCurl intends to be a drop-in replacement for the [curl_exec](http://php.net/manual/en/function.curl-exec.php) function in PHP. SafeCurl validates each part of the URL against a white or black list, to help protect against Server-Side Request Forgery attacks.
SafeCurl intends to be a drop-in replacement for the
[curl_exec](http://php.net/manual/en/function.curl-exec.php) function in PHP.
SafeCurl validates each part of the URL against a white or black list, to help
protect against Server-Side Request Forgery attacks.

For more infomation about the project see the blog post ['SafeCurl: SSRF Protection, and a "Capture the Bitcoins"'](http://blog.fin1te.net/post/86235998757/safecurl-ssrf-protection-and-a-capture-the-bitcoins).
For more infomation about the project see the blog post
['SafeCurl: SSRF Protection, and a "Capture the Bitcoins"'](https://whitton.io/articles/safecurl-ssrf-protection-and-a-capture-the-bitcoins/).

## Protections

Each part of the URL is broken down and validated against a white or black list. This includes resolve a domain name to it's IP addresses.
Each part of the URL is broken down and validated against a white or black
list. This includes resolving a domain name to its IP addresses.

If you chose to enable "FOLLOWLOCATION", then any redirects are caught, and re-validated.
If you chose to enable "FOLLOWLOCATION", then any redirects are caught, and
re-validated.

## Installation

SafeCurl can be included in any PHP project using [Composer](https://getcomposer.org). Include the following in your `composer.json` file under `require`.
SafeCurl can be included in any PHP project using
[Composer](https://getcomposer.org). Include the following in your
`composer.json` file under `require`.

```
"require": {
Expand All @@ -28,7 +36,8 @@ composer update

## Usage

It's as easy as replacing `curl_exec` with `SafeCurl::execute`, and wrapping it in a `try {} catch {}` block.
It's as easy as replacing `curl_exec` with `SafeCurl::execute`, and wrapping it
in a `try {} catch {}` block.

```php
use fin1te\SafeCurl\SafeCurl;
Expand All @@ -47,13 +56,20 @@ try {
//URL wasn't safe
}
```

#### Options

The default options are to not allow access to any [private IP addresses](http://en.wikipedia.org/wiki/Private_network), and to only allow HTTP(S) connections.
The default options are to not allow access to any
[private IP addresses](http://en.wikipedia.org/wiki/Private_network), and to
only allow HTTP(S) connections.

If you wish to add your own options (such as to blacklist any requests to domains your control), simply get a new SimpleCurl\Options object, add to the white or black lists, and pass it along with the method calls.
If you wish to add your own options (such as to blacklist any requests to
domains your control), simply get a new SimpleCurl\Options object, add to the
white or black lists, and pass it along with the method calls.

Domains are express using regex syntax, whilst IPs, scheme and ports are standard strings (IPs can be specified in [CIDR notation](https://en.wikipedia.org/wiki/Cidr)).
Domains are express using regex syntax, whilst IPs, scheme and ports are
standard strings (IPs can be specified in
[CIDR notation](https://en.wikipedia.org/wiki/Cidr)).

```php
use fin1te\SafeCurl\Options;
Expand All @@ -69,7 +85,11 @@ $response = SafeCurl::execute('http://safecurl.fin1te.net', $curlHandle, $option
$response = SafeCurl::execute('ftp://fin1te.net', $curlHandle, $options);
```

Since we can't get access to any already set cURL options (see Caveats section), to enable `CURL_FOLLOWREDIRECTS` you must call the `enableFollowRedirects()` method. If you wish to specify a redirect limit, you will need to call `setMaxRedirects()`. Passing in `0` will allow infinite redirects.
Since we can't get access to any already set cURL options (see Caveats
section), to enable `CURL_FOLLOWREDIRECTS` you must call the
`enableFollowRedirects()` method. If you wish to specify a redirect limit, you
will need to call `setMaxRedirects()`. Passing in `0` will allow infinite
redirects.

```php
$options = new Options();
Expand All @@ -80,7 +100,9 @@ $options->setFollowLocationLimit(10);

#### URL Checking

The URL checking methods are also public, meaning that you can validate a URL before using it elsewhere in your application, although you'd want to try and catch any redirects.
The URL checking methods are also public, meaning that you can validate a URL
before using it elsewhere in your application, although you'd want to try and
catch any redirects.

```php
use fin1te\SafeCurl\Url;
Expand All @@ -94,20 +116,23 @@ try {
// URL wasn't safe
}
```


#### Optional Protections

In addition to the standard checks, two more are available.

The first is to prevent [DNS Rebinding](https://en.wikipedia.org/wiki/DNS_rebinding) attacks. This can be enabled by calling the `enablePinDns` method on an `Options` object. There is one major issue with this - the SSL certificate **can't** be validated. This is due to the real hostname being sent in the `Host` header, and the URL using the IP address.
The first is to prevent [DNS Rebinding](https://en.wikipedia.org/wiki/DNS_rebinding)
attacks. This can be enabled by calling the `enablePinDns` method on an
`Options` object. There is one major issue with this - the SSL certificate
**can't** be validated. This is due to the real hostname being sent in the
`Host` header, and the URL using the IP address.

```php
$options = new Options();
$options->enablePinDns();
```

The second disables the use of credentials in a URL, since PHP's `parse_url` returns values which differ from ones cURL uses. This is a temporary fix.
The second disables the use of credentials in a URL, since PHP's `parse_url`
returns values which differ from ones cURL uses. This is a temporary fix.

```php
$options = new Options();
Expand All @@ -117,17 +142,33 @@ $options->disableSendCredentials();
$response = SafeCurl::execute('http://user:pass@google.com', $curlHandle, $options);
```

#### Cavets
Since SafeCurl uses `getaddrbyhostl` to resolve domain names, which isn't IPv6 compatible, the class will only work with IPv4 at the moment. See [Issue #1](https://github.com/fin1te/safecurl/issues/1).
#### Caveats

As mentioned above, we can't fetch the value of any cURL options set against the provided cURL handle. Because SafeCurl handles redirects itself, it will turn off `CURLOPT_FOLLOWLOCATION` and use the value from the `Options` object. This is also true of `CURLOPT_MAXREDIRECTS`.
Since SafeCurl uses `getaddrbyhostl` to resolve domain names, which isn't IPv6
compatible, the class will only work with IPv4 at the moment. See
[Issue #1](https://github.com/fin1te/safecurl/issues/1).

As mentioned above, we can't fetch the value of any cURL options set against
the provided cURL handle. Because SafeCurl handles redirects itself, it will
turn off `CURLOPT_FOLLOWLOCATION` and use the value from the `Options` object.
This is also true of `CURLOPT_MAXREDIRECTS`.

## Demo

A live demo is available at [http://safecurl.fin1te.net/#demo](http://safecurl.fin1te.net/#demo). For the site source code (if you're curious), it's hosted at [fin1te/safecurl.fin1te.net](https://github.com/fin1te/safecurl.fin1te.net).
A live demo was available at
[http://safecurl.fin1te.net/#demo](http://safecurl.fin1te.net/#demo). For the
site source code (if you're curious), it's hosted at
[fin1te/safecurl.fin1te.net](https://github.com/fin1te/safecurl.fin1te.net).

## Bounty

In order to help make SafeCurl secure and ready for production use, [a Bitcoin bounty](http://safecurl.fin1te.net/#bounty) has been setup.
In order to help make SafeCurl secure and ready for production use,
[a Bitcoin bounty](http://safecurl.fin1te.net/#bounty) was run.

Inside the document root was a [Bitcoin wallet](http://safecurl.fin1te.net/btc.txt),
which could only be accessed by 127.0.0.1. If you could bypass the protections
and grab the file, you were free to take the Bitcoins.

Inside the document root is a [Bitcoin wallet](http://safecurl.fin1te.net/btc.txt), which is only accessible by 127.0.0.1. If you can bypass the protections and grab the file, you're free to take the Bitcoins.
The Bitcoin bounty has since concluded. For more information on the Bitcoin
bounty, see the blog post
['SafeCurl "Capture the Bitcoins" Post-Mortem'](https://whitton.io/articles/safecurl-capture-the-bitcoins-post-mortem/).