A .NET 8, 9 and 10 library to help mitigate Server Side Request Forgery (SSRF) vulnerabilities in .NET applications that use HttpClient or ClientWebSocket.
Add the idunno.Security.Ssrf package to your project, then, when you create an HttpClient
pass an create a handler with SsrfSocketsHttpHandlerFactory.Create() and pass it in as
the handler parameter of the HttpClient constructor.
using (var httpClient = new HttpClient(
SsrfSocketsHttpHandlerFactory.Create(connectTimeout: new TimeSpan(0, 0, 5))))
{
_ = await httpClient.GetAsync(new Uri("bad.ssl.fail")).ConfigureAwait(false);
}If you want to protect a ClientWebSocket create an HttpClient with a handler created by SsrfSocketsHttpHandlerFactory.Create(),
and pass it in as the invoker parameter of the
ConnectAsync();.
using (var clientWebSocket = new ClientWebSocket())
using (var invoker = new HttpClient(
SsrfSocketsHttpHandlerFactory.Create()))
{
await clientWebSocket.ConnectAsync(
uri: new Uri("wss://echo.websocket.org"),
invoker: invoker);
}If the SSRF handler encounters anything unsafe it will throw an SsrfException.
You can read the full documentation at https://ssrf.idunno.dev/
- Mitigates Common SSRF vulnerabilities in .NET applications that use
HttpClientorClientWebSocket. - Supports both IPv4 and IPv6 addresses.
- Allows for extra IP ranges and individual addresses to be added to the default block list.
If you want to perform both checks you can use the IsUnsafe method, which will check both the URI and the resolved IP addresses.
When an application and an attacker love each other very much ...
A ServerSide Request Forgery (SSRF) vulnerability occurs when an application takes a user-supplied URL and makes a request to that URL without properly, and continuously validating it.
Imagine an application that takes a user-supplied URL as input and fetches data from it. Everything works fine when the user supplies a URL like https://example.com/data,
but what if the user supplies a URL like http://localhost/admin? If the application is running on a server that has an admin interface accessible at http://localhost/admin,
then the application could potentially access sensitive information and share it with an attacker or allow them
to perform actions on the server that they shouldn't be able to.
It gets worse. If the user supplies a URL like https://notanattacksite.com and the URL is validated during
data entry by resolving the IP addresses for the domain and checking against a block list, and marked as safe.
Then later on the DNS entry for notanattacksite.com is changed to point to 127.0.0.1 and your application
starts making internal requests. This is called a Time of Check / Time of Use (TOCTOU) vulnerability,
and is a common pitfall when trying to mitigate SSRF vulnerabilities.
In addition the default lists of known bad IP networks and IP addresses are probably longer than you think.
If you are accepting user input that is used to make outgoing HTTP requests, or WebSocket connections, then you should be mitigating SSRF vulnerabilities in your application, and this library can help you do that.
If you want to manually check URIs supplied by untrusted you can use the idunno.Security.Ssrf class.
if (Ssrf.IsUnsafeUri(new Uri("https://bad.ssl.fail")))
{
// Disallow entry of this URI into the system,
// or log an alert, or whatever you want to do with it.
}If you want to manually check an IP address you can use the idunno.Security.Ssrf class.
if (Ssrf.IsUnsafeIpAddress(IPAddress.Parse("127.0.0.1")))
{
// Disallow this IP address from being used in the system,
// or log an alert, or whatever you want to do with it.
}
idunno.Security.Ssrf is available under the MIT license, see the LICENSE file for more information.
If you find this library useful please consider donating to
- a local food bank,
- a local animal rescue or shelter, or
- a national Multiple Sclerosis charity in your country
- US: National Multiple Sclerosis Society
- UK: MS Society UK
- Canada: MS Canada
If you want to give me the warm fuzzies, you can tag me on Bluesky at @blowdart.me to let me know.
The releases page provides details of each release and what was added, changed or removed. The changelog also contains this information, as well as information on upcoming releases.
The project uses an Authenticode certificate to sign assemblies and to author sign the nupkg packages. nuget validates the signatures during its publication process.
To validate these signatures use
dotnet nuget verify [<package-path(s)>]
The subject name of the signing certificate should be
Subject Name: CN=Barry Dorrans, O=Barry Dorrans, L=Bothell, S=Washington, C=US
In addition, GitHub artifacts are attested during build, and are also signed with minisign with the following public key.
RWTsT4BHHChe/Rj/GBAuZHg3RaZFnfBDqaZ7KzLvr44a7mO6fLCxSAFc
To validate a file using an artifact signature from a release
download the .nupkg from nuget and the appropriate the .minisig from the release page, then use the following command,
replacing <package-path> with the file name you wish to verify.
minisign -Vm <package-path> -P RWTsT4BHHChe/Rj/GBAuZHg3RaZFnfBDqaZ7KzLvr44a7mO6fLCxSAFc
If you want to test pre-releases you can find them in the myget feed.
You can add this as a Package Source in Visual Studio
or through the command line, or by using the sample nuget.config file shown below:
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<packageSources>
<clear />
<add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
<add key="blowdart.myget.org" value="https://www.myget.org/F/blowdart/api/v3/index.json" />
</packageSources>
<packageSourceMapping>
<packageSource key="blowdart.myget.org">
<package pattern="idunno.Security.Ssrf" />
</packageSource>
<packageSource key="nuget.org">
<package pattern="*" />
</packageSource>
</packageSourceMapping>
</configuration>The package source URI is https://www.myget.org/F/blowdart/api/v3/index.json
Please note that nightly builds are signed with Azure Artifact Signing, the signing certificate chain will not match the signing chain of a release build. The subject name remains the same.
- DotNetAnalyzers.DocumentationAnalyzers - used to validate XML docs on public types.
- CommentSense - used to validate XML docs on public types.
- Microsoft.CodeAnalysis.PublicApiAnalyzers - used to track public API changes.
- SonarAnalyzer.CSharp - used for common code smell detection.
- DotNet.ReproducibleBuilds - used to easily set .NET reproducible build settings.
- Coverlet.Collector - used to produce code coverage files
- JunitXml.TestLogger - used in CI builds to produce test results in a format understood by the test-summary GitHub action.
- NerdBank.GitVersioning - used for version stamping assemblies and packages.
- ReportGenerator - used to produce code coverage reports.
- sign - used to code sign assemblies and nuget packages.
- xunit - used for unit tests.