UploadGuard 0.1.0-preview.2

UploadGuard

Secure file uploads for ASP.NET Core, from one declarative policy. UploadGuard detects the real file type from its bytes, checks it against an allow-list, and then looks inside: zip bombs, zip slip, Office macros, PDF JavaScript, SVG scripts and image polyglots. It can also scan with ClamAV, re-encode images with PixelForge, and store files under random names outside the web root.

builder.Services.AddUploadGuard(o =>
{
    o.StoragePath = "/var/app/uploads";
    o.AddPolicy("avatars", p => p.AllowImages().MaxSize(5 * 1024 * 1024).ReencodeImages()); // UploadGuard.PixelForge
    o.AddPolicy("cv", p => p.Allow(FileTypes.Pdf, FileTypes.Docx).MaxSize(10 * 1024 * 1024));
});
builder.Services.AddUploadGuardClamAV(o => o.Host = "clamav"); // UploadGuard.ClamAV, optional

app.MapPost("/avatar", async (IFormFile file, UploadPipeline uploads) =>
{
    var result = await uploads.SaveAsync(file, "avatars");
    return result.IsValid ? Results.Ok(result.StoredName) : Results.BadRequest(result.Error);
});

app.MapPost("/cv", (IFormFile file) => ...).WithUploadPolicy("cv"); // 400 ValidationProblem before the handler runs

MIT. No dependencies beyond ASP.NET Core in the core package. .NET 10 and later.

Why

Most upload code checks the extension, and sometimes the first few bytes. OWASP says about signature checks: "This should not be used on its own, as bypassing it is pretty common and easy." A JPEG header followed by <?php, a .docx with a VBA project, or a 20 KB ZIP that unpacks to 20 GB all pass a magic-byte check.

The table below runs the same files through each library, used the way apps usually use them: accept the file when the detected extension equals the file's extension. You can reproduce it with dotnet run -c Release --project benchmarks/UploadGuard.Benchmarks -- --compare. Every file is generated by Samples.cs.

Some ✅ in the other columns are right for the wrong reason: File.TypeChecker reports these ZIP files as docx, and Mime-Detective reports both Word files as zip. Both libraries are good at what they do, which is signature matching; UploadGuard is the layer around it.

Install

dotnet add package UploadGuard --prerelease
dotnet add package UploadGuard.ClamAV --prerelease       # optional: virus scanning with clamd
dotnet add package UploadGuard.PixelForge --prerelease   # optional: image re-encoding

Policies

A policy is an allow-list plus limits. Everything else is rejected.

builder.Services.AddUploadGuard(o =>
{
    o.AddPolicy("avatars", p => p
        .AllowImages()                     // JPEG, PNG, GIF, WebP
        .MaxSize(5 * 1024 * 1024));        // default 10 MB

    o.AddPolicy("imports", p => p
        .Allow(FileTypes.Csv, FileTypes.Xlsx)
        .LimitArchives(maxEntries: 1_000, maxUncompressedSize: 50 * 1024 * 1024, maxCompressionRatio: 50));
});

Policies are built at startup: a policy without types, a duplicate name, or WithUploadPolicy("typo") fails when the app starts, not on the first upload.

Raise ASP.NET Core's own limits too when you allow large files (KestrelServerLimits.MaxRequestBodySize, FormOptions.MultipartBodyLengthLimit). They run before UploadGuard and reject oversized requests cheaply.

What runs, in order

The first failing check decides the result. UploadResult.Error.Code tells you which one.

Detected types

Text is valid UTF-8 (or UTF-16 with a byte order mark) without control characters. CSV and plain text have the same content, so the extension picks one. 7z, RAR and TAR are detected but their contents are not inspected: prefer ZIP if you accept archives.

Minimal APIs

WithUploadPolicy validates every file in the form before the handler runs. Invalid files get a 400 validation problem with one error per form field:

app.MapPost("/import", (IFormFile file) => Import(file)).WithUploadPolicy("imports");

{
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": { "file": ["The file has the extension '.csv', but the content was detected as HTML document."] }
}

It works on route groups too: app.MapGroup("/uploads").WithUploadPolicy("documents").

MVC

[HttpPost("avatar")]
[UploadPolicy("avatars")]
public IActionResult Upload(IFormFile file) => ...;

Errors are added to ModelState and returned as a ValidationProblemDetails.

Validating, saving and any stream

Inject UploadPipeline when you need the result:

UploadResult result = await uploads.ValidateAsync(file, "cv");   // checks only
UploadResult saved = await uploads.SaveAsync(file, "avatars");   // checks, transforms, stores

result.FileType is the detected type, result.Error is null when valid, and saved.StoredName is the generated name. Error messages never contain internal details, so you can return them to the client.

Both methods also take a Stream, a file name and a Content-Type, for uploads that do not come from IFormFile. The stream must be seekable because it is read more than once; IFormFile streams already are.

Antivirus with ClamAV

builder.Services.AddUploadGuardClamAV(o => builder.Configuration.GetSection("ClamAV").Bind(o)); // Host, Port, Timeout
builder.Services.AddHealthChecks().AddClamAV();

Every file that passes the built-in checks is streamed to clamd with INSTREAM. Infected files are rejected with Malware and the signature name is logged, not returned to the client. If clamd is down or slower than Timeout (30 s by default), the upload is rejected with ScanFailed: UploadGuard fails closed. Set clamd's StreamMaxLength to at least your largest MaxSize; clamd refuses longer streams, which also ends in ScanFailed.

Run clamd locally:

docker run -d -p 3310:3310 clamav/clamav:stable

Or in an Aspire AppHost:

var clamav = builder.AddContainer("clamav", "clamav/clamav", "stable")
    .WithEndpoint(targetPort: 3310, name: "tcp");

builder.AddProject<Projects.Api>("api")
    .WithEnvironment(context =>
    {
        var endpoint = clamav.GetEndpoint("tcp");
        context.EnvironmentVariables["ClamAV__Host"] = endpoint.Property(EndpointProperty.Host);
        context.EnvironmentVariables["ClamAV__Port"] = endpoint.Property(EndpointProperty.Port);
    });

ClamAVClient can also be used on its own: PingAsync, GetVersionAsync and ScanAsync(stream). It replaces nClam for new code: async, cancellable, with timeouts and dependency injection.

UploadGuard.ClamAV is not affiliated with Cisco or the ClamAV project.

Re-encoding images with PixelForge

o.AddPolicy("avatars", p => p.AllowImages().ReencodeImages(maxPixels: 25_000_000, quality: 90));

SaveAsync decodes each image and encodes it again (content disarm and reconstruction). The stored file contains only pixels: EXIF and GPS data, comments, appended bytes and polyglot payloads are gone. The image is rotated upright first, because the orientation tag is dropped too. The pixel limit is checked from the header before any memory is allocated, which stops decompression bombs.

JPEG and WebP keep their format (lossless WebP stays lossless). PNG, GIF and BMP become PNG; a GIF keeps only its first frame. Other image types are rejected under this policy, and non-image types in the same policy are stored unchanged.

Storing and serving files

With StoragePath set, SaveAsync stores files with FileSystemUploadStorage:

• Names are 128 random bits plus the detected type's extension (3f9c…e1.jpg). The client's file name is never used as a path.
• The app refuses to start if StoragePath is inside the web root.
• OpenReadAsync and DeleteAsync accept only names it generated, so a name from a URL cannot traverse.

Register your own IUploadStorage for blob storage. When you serve files back, send them so a browser never runs them:

app.MapGet("/files/{name}", async (string name, IUploadStorage storage, HttpContext http) =>
{
    var content = await storage.OpenReadAsync(name); // throws ArgumentException for foreign names
    http.Response.Headers.XContentTypeOptions = "nosniff";
    http.Response.Headers.ContentSecurityPolicy = "default-src 'none'; sandbox";
    return Results.File(content, "application/octet-stream", fileDownloadName: name);
});

Better still, serve user files from a separate domain. samples/UploadApi has a complete API.

Extending

• IUploadScanner: register it in dependency injection. Throw UploadRejectedException to reject; any other exception rejects with ScanFailed.
• IUploadTransformer: add it with policy.Transform(...). It runs in SaveAsync after validation.
• IUploadStorage: register it to replace the file system storage.

Observability

• Metric uploadguard.uploads (meter UploadGuard), a counter tagged with uploadguard.policy, uploadguard.result (Accepted or the error code) and uploadguard.file_type. Add it with .AddMeter("UploadGuard") in OpenTelemetry.
• Rejections are logged at Information with the policy and reason; scanner failures at Error.

Performance

Time to accept one valid file (BenchmarkDotNet ShortRun, AMD Ryzen 5 5500U, .NET 10.0.11). The other libraries only match signatures; UploadGuard runs the whole policy, including the content checks for that type, so the numbers are not like for like.

UploadGuard reads files in 64 KB chunks and never loads them whole. PDF streams are inflated to look for hidden JavaScript, which costs time in proportion to the stream size, up to LimitArchives(maxUncompressedSize).

Limits

UploadGuard lowers risk; it does not make untrusted files safe to open. Read docs/security.md for the threat model, the mapping to the OWASP File Upload Cheat Sheet, and what is not covered. In short:

• The PDF and legacy Office checks are byte scans, not parsers. Pair them with antivirus, and never render user PDFs inline on your own origin.
• Only images can be rebuilt (with UploadGuard.PixelForge). Documents and archives are stored as uploaded.
• Nested archives are not unpacked, and 7z, RAR and TAR contents are not inspected.
• Authentication, authorization, CSRF protection and rate limiting are your app's job.

License

MIT. Security issues: see SECURITY.md.