{"id":16489474,"url":"https://github.com/j0k3r/httplug-ssrf-plugin","last_synced_at":"2025-03-23T12:34:32.340Z","repository":{"id":56995270,"uuid":"108416823","full_name":"j0k3r/httplug-ssrf-plugin","owner":"j0k3r","description":"Server-Side Request Forgery (SSRF) protection plugin for HTTPlug","archived":false,"fork":false,"pushed_at":"2025-01-06T09:13:27.000Z","size":110,"stargazers_count":4,"open_issues_count":2,"forks_count":5,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-16T01:17:21.892Z","etag":null,"topics":["httplug","php","plugin","server-side-request-forgery","ssrf"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/j0k3r.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"j0k3r"}},"created_at":"2017-10-26T13:41:34.000Z","updated_at":"2025-01-06T09:13:12.000Z","dependencies_parsed_at":"2024-06-18T22:47:25.645Z","dependency_job_id":"36f8c2f7-a8f4-4715-b054-3f107167b250","html_url":"https://github.com/j0k3r/httplug-ssrf-plugin","commit_stats":{"total_commits":36,"total_committers":3,"mean_commits":12.0,"dds":0.5,"last_synced_commit":"b60e8068054bdb15fdf1e62cd314d941c62a3b72"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/j0k3r%2Fhttplug-ssrf-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/j0k3r%2Fhttplug-ssrf-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/j0k3r%2Fhttplug-ssrf-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/j0k3r%2Fhttplug-ssrf-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/j0k3r","download_url":"https://codeload.github.com/j0k3r/httplug-ssrf-plugin/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245104460,"owners_count":20561377,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["httplug","php","plugin","server-side-request-forgery","ssrf"],"created_at":"2024-10-11T13:44:15.510Z","updated_at":"2025-03-23T12:34:32.313Z","avatar_url":"https://github.com/j0k3r.png","language":"PHP","funding_links":["https://github.com/sponsors/j0k3r"],"categories":[],"sub_categories":[],"readme":"# Server-Side Request Forgery (SSRF) protection plugin for HTTPlug\n\n![CI](https://github.com/j0k3r/httplug-ssrf-plugin/workflows/CI/badge.svg)\n[![Coverage Status](https://coveralls.io/repos/j0k3r/httplug-ssrf-plugin/badge.svg?branch=master\u0026service=github)](https://coveralls.io/github/j0k3r/httplug-ssrf-plugin?branch=master)\n\nInspired from [SafeCurl](https://github.com/j0k3r/safecurl), it intends to validate each part of the URL against a white or black list, to help protect against _Server-Side Request Forgery_ attacks when using [HTTPlug](https://docs.php-http.org/en/latest/).\n\nEach 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.\n\n## Installation\n\nIt can be included in any PHP project using [Composer](https://getcomposer.org).\n\n```\ncomposer require j0k3r/httplug-ssrf-plugin\n```\n\n## Usage\n\n```php\nuse Graby\\HttpClient\\Plugin\\ServerSideRequestForgeryProtection\\ServerSideRequestForgeryProtectionPlugin;\nuse Http\\Client\\Common\\PluginClient;\nuse Http\\Discovery\\Psr18ClientDiscovery;\n\n$ssrfPlugin = new ServerSideRequestForgeryProtectionPlugin();\n\n$pluginClient = new PluginClient(\n    Psr18ClientDiscovery::find(),\n    [$ssrfPlugin]\n);\n```\n\nThe plugin throws a `Graby\\HttpClient\\Plugin\\ServerSideRequestForgeryProtection\\Exception\\InvalidURLException` if the url is not valid.\n\n#### Options\n\nThe default options are to not allow access to any [private IP addresses](https://en.wikipedia.org/wiki/Private_network), and to only allow HTTP(S) connections.\n\nIf you wish to add your own options (such as to blacklist any requests to domains your control), simply get a new `Graby\\HttpClient\\Plugin\\ServerSideRequestForgeryProtection\\Options` object, add to the white or black lists, and pass it along with the method calls.\n\nDomains 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)).\n\n```php\nuse Graby\\HttpClient\\Plugin\\ServerSideRequestForgeryProtection\\Options;\nuse Graby\\HttpClient\\Plugin\\ServerSideRequestForgeryProtection\\ServerSideRequestForgeryProtectionPlugin;\nuse Http\\Discovery\\Psr17FactoryDiscovery;\nuse Http\\Discovery\\Psr18ClientDiscovery;\nuse Http\\Client\\Common\\PluginClient;\n\n$options = new Options();\n$options-\u003eaddToList(Options::LIST_BLACKLIST, Options::TYPE_DOMAIN, '(.*)\\.example\\.com');\n\n$pluginClient = new PluginClient(\n    Psr18ClientDiscovery::find(),\n    [new ServerSideRequestForgeryProtectionPlugin($options)]\n);\n\n// This will throw an Graby\\HttpClient\\Plugin\\ServerSideRequestForgeryProtection\\Exception\\InvalidURLException\\InvalidDomainException\n$request = Psr17FactoryDiscovery::findRequestFactory()-\u003ecreateRequest('GET', 'https://www.example.com');\n$response = $pluginClient-\u003esendRequest($request);\n\n$options = new Options();\n$options-\u003esetList(Options::LIST_WHITELIST, [Options::TYPE_SCHEME =\u003e ['https']]);\n\n$pluginClient = new PluginClient(\n    Psr18ClientDiscovery::find(),\n    [new ServerSideRequestForgeryProtectionPlugin($options)]\n);\n\n// This will be allowed, and return the response\n$request = Psr17FactoryDiscovery::findRequestFactory()-\u003ecreateRequest('GET', 'https://www.example.com');\n$response = $pluginClient-\u003esendRequest($request);\n\n// This will throw an Graby\\HttpClient\\Plugin\\ServerSideRequestForgeryProtection\\Exception\\InvalidURLException\\InvalidDomainException\n$request = Psr17FactoryDiscovery::findRequestFactory()-\u003ecreateRequest('GET', 'https://www.example.com');\n$response = $pluginClient-\u003esendRequest($request);\n```\n\n#### Optional Protections\n\nIn addition to the standard checks, two more are available.\n\nThe 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.\n\n```php\n$options = new Options();\n$options-\u003eenablePinDns();\n```\n\nThe 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.\n\n```php\nuse Graby\\HttpClient\\Plugin\\ServerSideRequestForgeryProtection\\Options;\nuse Graby\\HttpClient\\Plugin\\ServerSideRequestForgeryProtection\\ServerSideRequestForgeryProtectionPlugin;\nuse Http\\Discovery\\Psr17FactoryDiscovery;\nuse Http\\Discovery\\Psr18ClientDiscovery;\nuse Http\\Client\\Common\\PluginClient;\n\n$options = new Options();\n$options-\u003edisableSendCredentials();\n\n//This will throw an Http\\Client\\Exception\\RequestException\n$pluginClient = new PluginClient(\n    Psr18ClientDiscovery::find(),\n    [new ServerSideRequestForgeryProtectionPlugin($options)]\n);\n$request = Psr17FactoryDiscovery::findRequestFactory()-\u003ecreateRequest('GET', 'https://user:pass@google.com');\n$response = $pluginClient-\u003esendRequest($request);\n```\n\n#### Caveats\n\nSince the libray uses [`gethostbynamel`](https://php.net/manual/en/function.gethostbynamel.php) to resolve domain names, which isn't IPv6 compatible, the class will only work with IPv4 at the moment.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fj0k3r%2Fhttplug-ssrf-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fj0k3r%2Fhttplug-ssrf-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fj0k3r%2Fhttplug-ssrf-plugin/lists"}