Nullean.ScopedFileSystem 0.7.1

Nullean.ScopedFileSystem

A System.IO.Abstractions IFileSystem decorator that restricts file reads and writes to one or more scope root directories and rejects symbolic links, hidden files and path traversal.

Install

dotnet add package Nullean.ScopedFileSystem

Quick start

using System.IO.Abstractions;
using Nullean.ScopedFileSystem;

IFileSystem scoped = new ScopedFileSystem("/var/www/docs");

var content = scoped.File.ReadAllText("/var/www/docs/page.md");      // OK: within scope
scoped.File.WriteAllText("/var/www/docs/output.md", content);         // OK: write within scope

bool exists = scoped.File.Exists("/etc/passwd");                      // false, no exception

scoped.File.ReadAllText("/etc/passwd");                               // ScopedFileSystemException: outside scope
scoped.File.ReadAllText("/var/www/docs/../../../etc/passwd");         // ScopedFileSystemException: .. is resolved first
scoped.File.ReadAllText("/var/www/docs/.env");                        // ScopedFileSystemException: hidden file
scoped.File.ReadAllText("/var/www/docs/link-to-secret");              // ScopedFileSystemException: symbolic link

Wrap any IFileSystem, such as a MockFileSystem in tests, and allow what else you need:

using System.IO.Abstractions;
using Nullean.ScopedFileSystem;

IFileSystem inner = new FileSystem();   // or a MockFileSystem in tests

IFileSystem scoped = new ScopedFileSystem(inner, new ScopedFileSystemOptions("/var/www/docs", "/var/www/data")
{
	AllowedHiddenFolderNames = [".git"],
	AllowedHiddenFileNames = [".gitkeep"],
	AllowedSpecialFolders = AllowedSpecialFolder.Temp | AllowedSpecialFolder.ApplicationData,
});

scoped.File.WriteAllText(Path.Combine(Path.GetTempPath(), "cache.txt"), "ok");   // OK: temp is allowed

What it enforces

Any violation throws ScopedFileSystemException (extends SecurityException).

Any violation throws ScopedFileSystemException (extends SecurityException). Paths are resolved with IPath.GetFullPath before any check, so .. cannot escape, and scope membership is checked by walking up the directory tree, so /docs-extra is not inside /docs. Multiple roots must be disjoint, or the constructor throws ArgumentException.

Learn more

• Multiple roots, hidden names, special folders and the options reference: https://github.com/nullean/scoped-filesystem#multiple-roots
• Source and issues: https://github.com/nullean/scoped-filesystem