Add DirectoryService SID lookup functionality with configurable option

[Copilot]

This PR implements DirectoryService lookup functionality for unknown SID strings, addressing issue #90 by extending the parser to translate SIDs that aren't in the predefined list of well-known SIDs.

Problem

Currently, the parser only translates well-known SID aliases (e.g., DA -> Domain Admins, SY -> Local System) and predefined SID strings. When encountering unknown SIDs, it reports an error and displays them as Unknown(SID-string). This limitation prevents the parser from resolving custom domain SIDs, user accounts, or other valid but non-standard SIDs.

Solution

Added a configurable DirectoryService lookup mechanism that attempts to resolve unknown SIDs using Windows security APIs while maintaining full backward compatibility.

Key Features

• Configurable lookup: New SidResolverOptions class with EnableDirectoryServiceLookup boolean (default: false)
• DirectoryService integration: Uses SecurityIdentifier.Translate() for Windows directory lookups
• Graceful fallback: Falls back to original Unknown(SID) behavior when resolution fails
• Custom resolver support: ISidResolver interface allows dependency injection for testing and alternative implementations
• Full backward compatibility: Existing code continues to work identically without any changes

Usage Examples

// Enable DirectoryService lookup for unknown SIDs
var options = new SidResolverOptions { EnableDirectoryServiceLookup = true };

// Resolve individual SID
var sid = new Sid("S-1-5-21-1234567890-1234567890-1234567890-1001", options);
// Result: Either "DOMAIN\Username" or "Unknown(...)" if not resolvable

// Parse complete SDDL with lookup enabled
var sddl = new Sddl(sddlString, SecurableObjectType.Unknown, options);
// All SIDs in Owner, Group, and ACEs attempt DirectoryService resolution

// Custom resolver for testing
var customOptions = new SidResolverOptions 
{ 
    EnableDirectoryServiceLookup = true,
    SidResolver = new CustomSidResolver()
};

Implementation Details

• New classes:

  • ISidResolver: Interface for SID resolution abstraction
  • DirectoryServiceSidResolver: Windows DirectoryService implementation
  • SidResolverOptions: Configuration with boolean switch and custom resolver support

• Updated constructors: Added overloads to Sid, Sddl, Acl, and Ace classes accepting SidResolverOptions

• Dependencies: Added System.Security.Principal.Windows package for .NET Standard 2.0 compatibility

• Error handling: Gracefully handles invalid SID formats, network failures, and missing accounts

Testing

• Comprehensive unit tests: 11 test cases covering all scenarios including error conditions
• Backward compatibility verified: Existing SDDL parsing behavior unchanged
• Manual validation: Tested with real-world SDDL strings and custom resolvers

The functionality is disabled by default, ensuring zero impact on existing applications while providing the requested SID translation capability when explicitly enabled.

Fixes zacateras/sddl-parser#9

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.