Focused GetDomain Replacement

AGENTS.md

@@ -0,0 +1,42 @@
+# Repository guide for coding agents
+
+Read `coding_standards.md` and `CONTRIBUTING.md` before changing code. Treat this file as a practical map of the repository, not as a substitute for inspecting the affected component.
+
+## Repository map
+
+- `src/CommonLib/`: `SharpHoundCommonLib`, the higher-level library for LDAP resolution, caching, processors, metrics, and collection support.
+- `src/SharpHoundRPC/`: `SharpHoundRPC`, the lower-level Windows RPC, native interop, handle, and registry library. CommonLib references this project.
+- `test/unit/`: xUnit tests for CommonLib, including mocks and facades.
+- `RPCTest/`: xUnit tests for SharpHoundRPC.
+- `docfx/`: documentation project and generated coverage output.
+- `.github/workflows/build-and-test.yml`: authoritative CI build and test sequence.
+
+The two shipping projects target `net472` via `Directory.Build.props`; both test projects target `net8.0`. The root README's older prerequisite text does not override the project files. Windows is the CI platform and the code uses Windows and Active Directory APIs.
+
+## Working on a change
+
+1. Inspect the affected project, nearby implementation and tests, and any relevant public contract before editing.
+2. Keep changes scoped. Follow the existing style in each file; do not reformat unrelated code or change target frameworks, dependencies, package metadata, or generated files without a task reason.
+3. Put high-level behavior in CommonLib and native/RPC details in SharpHoundRPC. Preserve existing result, error, cancellation, and handle ownership behavior unless the task calls for changing it.
+4. Add focused tests for behavior changes using local mocks or facades. Do not require a live domain, credentials, or external hosts for routine tests.
+5. Run the relevant test project, then the CI sequence when shared behavior or build configuration changes. Report commands run, failures, and any environment limitation accurately.
+6. Update relevant README or API documentation when a consumer-facing contract changes.
+
+## Commands
+
+Run from the repository root on Windows with the .NET 8 SDK:
+
+```powershell
+dotnet restore
+dotnet build --no-restore
+dotnet test --no-build
+```
+
+For a focused check, use `dotnet test test/unit/CommonLibTest.csproj` or `dotnet test RPCTest/RPCTest.csproj`. `dotnet test` produces coverage files under `docfx/coverage/`.
+
+## Workspace care
+
+- Inspect `git status` before and after changes. Preserve user edits and untracked files.
+- Do not commit generated coverage, `bin/`, or `obj/` output.
+- Do not put secrets, credentials, or sensitive collected directory data into code, tests, logs, or documentation.
+- If the requested change needs a real AD environment or Windows-only behavior that cannot be exercised locally, use the available unit tests and state the remaining validation gap.

CODING_STANDARDS.md

@@ -0,0 +1,41 @@
+# Coding standards
+
+These standards apply to new work in SharpHoundCommon. Keep changes focused and follow the style of the file being edited; the repository does not have a single enforced formatter.
+
+## Project boundaries and compatibility
+
+- `src/CommonLib` contains higher-level LDAP, cache, processor, and collection behavior. `src/SharpHoundRPC` contains lower-level Windows RPC, native interop, handle, and registry code. Keep the dependency direction from CommonLib to RPC.
+- Both shipping libraries target **.NET Framework 4.7.2** through `Directory.Build.props`. Do not use an API or language feature in library code unless it builds for that target and its configured compiler. The `net8.0` test projects can use newer language features; their syntax is not a compatibility guide for library code.
+- Preserve public signatures, serialized output shapes, result and error meanings, and package behavior unless a change deliberately updates that contract. Add a regression test for a behavior change.
+- Keep Windows and Active Directory specifics behind the existing interfaces and wrappers so behavior can be tested without a live domain.
+
+## C# style
+
+- Use four spaces for indentation. Match the surrounding file's namespace and brace layout; both end-of-line and next-line braces exist in this repository. Avoid formatting unrelated code.
+- Use `PascalCase` for types, public members, and constants; `camelCase` for parameters and locals; and `_camelCase` for private fields. Use names that reflect the AD, LDAP, RPC, or registry concept involved.
+- Prefer small methods with explicit inputs and outcomes. Reuse existing interfaces, result types, and helpers instead of introducing a parallel abstraction for the same operation.
+- Use `async`/`await` for asynchronous I/O. Propagate cancellation where an API accepts a `CancellationToken`; do not hide cancellation as an ordinary failure.
+- Use structured `ILogger` messages with named placeholders. Do not log credentials, tokens, private keys, or raw sensitive directory data.
+- In RPC and interop code, make ownership clear. Dispose native handles, buffers, and other disposable resources on success and failure paths; keep conversions and lifetime boundaries close together.
+- Add XML documentation when a public API's purpose, parameters, error behavior, or ownership is not clear from its name. Update package READMEs for consumer-facing changes.
+
+## Tests
+
+- Add or update focused xUnit tests in `test/unit` for CommonLib changes and `RPCTest` for RPC changes. Put tests near the existing tests for the affected component.
+- Test observable behavior and important failure paths, including null or missing LDAP values, RPC status failures, cancellation, and resource cleanup when relevant. Use the existing mocks and facades for directory, network, and native boundaries.
+- Keep routine tests deterministic and independent of a live AD domain or remote host. Avoid timing-sensitive assertions and shared mutable state when practical.
+- Use a descriptive test name consistent with neighboring tests; `[Theory]` is useful for related input cases. Do not add tests that only repeat implementation details.
+
+## Validation and review
+
+CI runs on Windows with the .NET 8 SDK. From the repository root, its core sequence is:
+
+```powershell
+dotnet restore
+dotnet build --no-restore
+dotnet test --no-build
+```
+
+Run the relevant test project during development, then the full sequence for changes that affect shared code or project configuration. `dotnet test` also generates coverage under `docfx/coverage/` as described in `CONTRIBUTING.md`.
+
+Before review, check for unintended public API changes, compatibility with `net472`, resource leaks, sensitive logging, and unrelated formatting changes. Explain behavior changes and test evidence in the pull request.

src/CommonLib/ConnectionPoolManager.cs

@@ -146,17 +146,12 @@ private string ResolveIdentifier(string identifier) {
                 //we expect this to fail sometimes
             }
 
-            if (LdapUtils.GetDomain(domainName, _ldapConfig, out var domainObject))
-                try {
-                    // TODO: MC - Confirm GetDirectoryEntry is not a Blocking External Call
-                    if (domainObject.GetDirectoryEntry().ToDirectoryObject().TryGetSecurityIdentifier(out domainSid)) {
-                        Cache.AddDomainSidMapping(domainName, domainSid);
-                        return (true, domainSid);
-                    }
-                }
-                catch {
-                    //we expect this to fail sometimes (not sure why, but better safe than sorry)
-                }
+            if (LdapUtils.GetDomain(domainName, _ldapConfig, out var domainObject) &&
+                !string.IsNullOrWhiteSpace(domainObject.DomainSid)) {
+                domainSid = domainObject.DomainSid;
+                Cache.AddDomainSidMapping(domainName, domainSid);
+                return (true, domainSid);
+            }
 
             foreach (var name in _translateNames)
                 try {

src/CommonLib/Helpers.cs

@@ -213,7 +213,8 @@ public static string DistinguishedNameToDomain(string distinguishedName) {
 
             if (dcValues.Count == 0) return null;
             dcValues.Reverse();
-            return string.Join(".", dcValues).ToUpper();
+            // DNS identity must not depend on the process culture (for example, Turkish casing of i).
+            return string.Join(".", dcValues).ToUpperInvariant();
         }
 
         /// <summary>

src/CommonLib/ILdapUtils.cs

@@ -1,9 +1,10 @@
-using System;
+using System;
 using System.Collections.Generic;
 using System.Security.Principal;
 using System.Threading;
 using System.Threading.Tasks;
 using SharpHoundCommonLib.Enums;
+using SharpHoundCommonLib.Models;
 using SharpHoundCommonLib.OutputTypes;
 
 namespace SharpHoundCommonLib {
@@ -76,18 +77,18 @@ IAsyncEnumerable<Result<string>> RangedRetrieval(string distinguishedName,
         /// <returns>A tuple containing success state as well as the resolved domain sid if successful</returns>
         Task<(bool Success, string DomainSid)> GetDomainSidFromDomainName(string domainName);
         /// <summary>
-        /// Attempts to retrieve the Domain object for the specified domain
+        /// Attempts to resolve plain domain metadata using configured LDAP settings.
         /// </summary>
-        /// <param name="domainName">The domain name to retrieve the Domain object for</param>
-        /// <param name="domain">The domain object</param>
+        /// <param name="domainName">The requested domain; null selects the configured target or discovery hint.</param>
+        /// <param name="domain">The resolved metadata, or null on failure.</param>
         /// <returns>True if the domain was found, false if not</returns>
-        bool GetDomain(string domainName, out System.DirectoryServices.ActiveDirectory.Domain domain);
+        bool GetDomain(string domainName, out LdapDomainInfo domain);
         /// <summary>
-        /// Attempts to retrieve the Domain object for the user's current domain
+        /// Attempts to resolve plain domain metadata using the configured target or discovery hint.
         /// </summary>
-        /// <param name="domain">The domain object</param>
+        /// <param name="domain">The resolved metadata, or null on failure.</param>
         /// <returns>True if the domain was found, false if not</returns>
-        bool GetDomain(out System.DirectoryServices.ActiveDirectory.Domain domain);
+        bool GetDomain(out LdapDomainInfo domain);
 
         Task<(bool Success, string ForestName)> GetForest(string domain);
         /// <summary>

src/CommonLib/LdapConfig.cs

@@ -7,12 +7,25 @@ public class LdapConfig
     {
         public string Username { get; set; } = null;
         public string Password { get; set; } = null;
+        /// <summary>
+        /// The DNS or NetBIOS domain associated with the user's credentials, used as an endpoint
+        /// hint by controlled domain resolution when neither a server nor a domain argument is supplied.
+        /// Takes precedence over USERDNSDOMAIN. Does not change the authentication context or
+        /// set explicit credentials; leave Username unset to use ambient credentials under /netonly.
+        /// </summary>
+        public string UserDomain { get; set; } = null;
         public string Server { get; set; } = null;
         public int Port { get; set; } = 0;
         public int SSLPort { get; set; } = 0;
         public bool ForceSSL { get; set; } = false;
         public bool DisableSigning { get; set; } = false;
         public bool DisableCertVerification { get; set; } = false;
+        /// <summary>
+        /// Permits legacy framework domain resolution after controlled LDAP resolution fails.
+        /// Authentication rejection stops resolution without invoking this fallback.
+        /// This fallback may ignore configured LDAP settings. Disabled by default.
+        /// </summary>
+        public bool AllowUncontrolledDomainFallback { get; set; } = false;
         public AuthType AuthType { get; set; } = AuthType.Kerberos;
         public int MaxConcurrentQueries { get; set; } = 15;
 
@@ -51,9 +64,11 @@ public string GetServerTarget()
         public override string ToString() {
             var sb = new StringBuilder();
             sb.AppendLine($"Server: {Server}");
+            sb.AppendLine($"UserDomain: {UserDomain}");
             sb.AppendLine($"LdapPort: {GetPort(false)}");
             sb.AppendLine($"LdapSSLPort: {GetPort(true)}");
             sb.AppendLine($"ForceSSL: {ForceSSL}");
+            sb.AppendLine($"AllowUncontrolledDomainFallback: {AllowUncontrolledDomainFallback}");
             sb.AppendLine($"AuthType: {AuthType.ToString()}");
             sb.AppendLine($"MaxConcurrentQueries: {MaxConcurrentQueries}");
             if (!string.IsNullOrWhiteSpace(Username)) {
@@ -101,4 +116,4 @@ public string GetConfigWarnings() {
             return string.Empty;
         }
     }
-}
+}

src/CommonLib/LdapConnectionFactory.cs

@@ -0,0 +1,40 @@
+using System;
+using System.DirectoryServices.Protocols;
+using System.Net;
+
+namespace SharpHoundCommonLib {
+    internal static class LdapConnectionFactory {
+        // Creates an unbound connection. The caller owns binding, retries, and disposal.
+        internal static LdapConnection Create(LdapConfig config, string target, bool ssl,
+            bool globalCatalog = false, bool pinServer = false) {
+            var port = globalCatalog ? config.GetGCPort(ssl) : config.GetPort(ssl);
+            var identifier = new LdapDirectoryIdentifier(target, port, pinServer, false);
+            var connection = new LdapConnection(identifier);
+            try {
+                connection.Timeout = TimeSpan.FromMinutes(5);
+                connection.SessionOptions.ProtocolVersion = 3;
+                // Referral chasing does not work with paged searches.
+                connection.SessionOptions.ReferralChasing = ReferralChasingOptions.None;
+                if (pinServer) connection.SessionOptions.AutoReconnect = false;
+                if (ssl) connection.SessionOptions.SecureSocketLayer = true;
+
+                var signing = !config.DisableSigning && !ssl;
+                connection.SessionOptions.Signing = signing;
+                connection.SessionOptions.Sealing = signing;
+
+                if (config.DisableCertVerification)
+                    connection.SessionOptions.VerifyServerCertificate = (_, _) => true;
+
+                if (config.Username != null)
+                    connection.Credential = new NetworkCredential(config.Username, config.Password);
+
+                connection.AuthType = config.AuthType;
+                return connection;
+            }
+            catch {
+                connection.Dispose();
+                throw;
+            }
+        }
+    }
+}