NSudo 共享库 NSudoCreateProcess 接口全解析:从 C/C++ 到 C 的系统级进程创建实战指南

原创2026-10-14 18:22:481,414 阅读
文章标签:认证鉴权身份认证CLI桌面应用系统底层与硬件开发工具

NSudo 共享库 NSudoCreateProcess 接口全解析:从 C/C++ 到 C# 的系统级进程创建实战指南

本文以 Website/ru-ru/docs/SharedLibrary.md 为核心,系统讲解 NSudo 共享库对外暴露的核心 API NSudoCreateProcess:包括 C/C++ 函数原型、五个枚举参数与四个基础参数的完整语义、底层 Token 接管实现原理,以及通过 M2.NSudo 托管封装在 C#/.NET 项目中调用该能力的完整方案。读完本文,你将能够把 NSudo 共享库的进程创建能力无缝接入自己的原生或 .NET 工具,实现以 TrustedInstaller、SYSTEM 等身份启动进程并精细控制其权限、完整性级别与优先级。

一、NSudo 共享库是什么

NSudo 共享库(Shared Library)是 NSudo 项目中独立编译、对外提供系统管理能力的一组原生导出函数。它由 Source/Native/NSudoSDK/NSudoAPI.h 定义接口,Source/Native/NSudoSDK/NSudoAPI.cpp 完成实现,并通过 Source/Native/NSudoSDK/NSudoAPI.def 声明导出符号。从导出表(EXPORTS)可以看出,共享库目前对外提供三个函数:

  • NSudoReadLog —— 读取 NSudo 内部日志基础设施的文本内容;
  • NSudoWriteLog —— 向 NSudo 日志基础设施写入一条带发送者、时间戳、进程/线程 ID 的记录;
  • NSudoCreateProcess —— 以指定的用户模式、特权模式、完整性标签、优先级与窗口模式创建新进程,即本文主角。

在仓库中,该共享库同时被 GUI 版(NSudoLauncherGUI)与命令行版(NSudoLauncherCUI)启动器直接链接使用,也可以被第三方程序集成。共享库工程本身还包含 NSudoSDK.vcxproj 静态库与 NSudoAPI.vcxproj 动态库两套构建形态,NSudoSDK.props 与 NSudoAPI.props 则分别为两类使用者提供了「自动携带头文件路径 + 自动链接对应 .lib」的便捷属性集。

二、NSudoCreateProcess 函数与 C/C++ 原型

NSudoCreateProcess 的职责是创建一个新进程及其主线程,并把 NSudo 的用户切换、权限提升、完整性级别设置、优先级设置等能力一次性应用到该进程上。其 C/C++ 原型如下(与头文件 NSudoAPI.h 完全一致):

EXTERN_C HRESULT WINAPI NSudoCreateProcess(
    _In_ NSUDO_USER_MODE_TYPE UserModeType,
    _In_ NSUDO_PRIVILEGES_MODE_TYPE PrivilegesModeType,
    _In_ NSUDO_MANDATORY_LABEL_TYPE MandatoryLabelType,
    _In_ NSUDO_PROCESS_PRIORITY_CLASS_TYPE ProcessPriorityClassType,
    _In_ NSUDO_SHOW_WINDOW_MODE_TYPE ShowWindowModeType,
    _In_ DWORD WaitInterval,
    _In_ BOOL CreateNewConsole,
    _In_ LPCWSTR CommandLine,
    _In_opt_ LPCWSTR CurrentDirectory);

前五个参数分别对应五个枚举类型,决定"以谁的身份、带哪些特权、以什么完整性级别、什么优先级、什么窗口方式"创建进程;后四个参数控制等待时间、控制台、命令行与工作目录等进程创建细节。返回值为 HRESULT,成功时返回 S_OK(即 0)。注意,实现中对非法的枚举值会返回 E_INVALIDARG,并在日志中写入 Invalid Parameter: <参数名>,这一点可以在 NSudoAPI.cpp 的三个 switch 分支中直接看到。

三、五个枚举参数详解

3.1 UserModeType —— 用户模式

该参数决定新进程以哪个用户/进程令牌运行,对应枚举定义:

typedef enum class _NSUDO_USER_MODE_TYPE
{
    DEFAULT,
    TRUSTED_INSTALLER,
    SYSTEM,
    CURRENT_USER,
    CURRENT_PROCESS,
    CURRENT_PROCESS_DROP_RIGHT
} NSUDO_USER_MODE_TYPE, *PNSUDO_USER_MODE_TYPE;

各取值的实际含义可结合 NSudoAPI.cpp 的令牌获取分支理解:

枚举值 底层实现(源码路径) 效果
DEFAULT 不匹配任何分支,直接返回 E_INVALIDARG 默认占位值,不可直接使用
TRUSTED_INSTALLER Mile::OpenServiceProcessToken(L"TrustedInstaller", ...) 打开 Windows 的 TrustedInstaller 服务进程令牌,获得系统级服务权限,是 NSudo 的招牌能力
SYSTEM Mile::CreateSystemToken(...) 创建 SYSTEM 账号访问令牌
CURRENT_USER Mile::CreateSessionToken(SessionID, ...) 创建当前交互会话(active session)的用户令牌
CURRENT_PROCESS ::OpenProcessToken(::GetCurrentProcess(), ...) 直接使用当前调用进程自身的令牌
CURRENT_PROCESS_DROP_RIGHT Mile::CreateLUAToken(hCurrentProcessToken, ...) 基于当前进程令牌创建 LUA(降权)令牌,即模拟去掉管理员权限后的受限令牌

值得一提的补充事实:当前头文件版本中还包含自 NSudo 8.1.0 起新增的 CURRENT_USER_ELEVATED(获取当前会话用户的高完整性提升令牌,见 NSudoAPI.h),命令行启动器的 -U:E 选项即映射到该值(见下文第六节)。

3.2 PrivilegesModeType —— 特权模式

该参数决定新进程令牌中所有特权的启停状态:

typedef enum class _NSUDO_PRIVILEGES_MODE_TYPE
{
    DEFAULT,
    ENABLE_ALL_PRIVILEGES,
    DISABLE_ALL_PRIVILEGES
} NSUDO_PRIVILEGES_MODE_TYPE, *PNSUDO_PRIVILEGES_MODE_TYPE;

实现中(NSudoAPI.cpp):ENABLE_ALL_PRIVILEGES 调用 Mile::AdjustTokenAllPrivileges(hToken, SE_PRIVILEGE_ENABLED) 把令牌内的全部特权(如 SeDebugPrivilege、SeTakeOwnershipPrivilege 等)置为启用;DISABLE_ALL_PRIVILEGES 则以 0 属性值调用同一函数,全部禁用;DEFAULT 保持令牌原有特权不变。

3.3 MandatoryLabelType —— 完整性标签(Integrity Level)

该参数控制新进程的强制完整性标签(Windows 的 Mandatory Integrity Control):

typedef enum class _NSUDO_MANDATORY_LABEL_TYPE
{
    UNTRUSTED,
    LOW,
    MEDIUM,
    MEDIUM_PLUS,
    HIGH,
    SYSTEM,
    PROTECTED_PROCESS,
} NSUDO_MANDATORY_LABEL_TYPE, *PNSUDO_MANDATORY_LABEL_TYPE;

实现将其映射为 Windows 安全描述符中的 RID 常量(NSudoAPI.cpp):

枚举值 映射的 RID 常量 含义
UNTRUSTED SECURITY_MANDATORY_UNTRUSTED_RID 不可信级别,且实现中跳过标签设置逻辑(见 NSudoAPI.cpp 的 UNTRUSTED != MandatoryLabelType 判断)
LOW SECURITY_MANDATORY_LOW_RID 低完整性
MEDIUM SECURITY_MANDATORY_MEDIUM_RID 中完整性
MEDIUM_PLUS SECURITY_MANDATORY_MEDIUM_PLUS_RID 中加完整性
HIGH SECURITY_MANDATORY_HIGH_RID 高完整性
SYSTEM SECURITY_MANDATORY_SYSTEM_RID 系统完整性
PROTECTED_PROCESS SECURITY_MANDATORY_PROTECTED_PROCESS_RID 受保护进程级别

3.4 ProcessPriorityClassType —— 进程优先级

对应 Windows 的进程优先级类(Process Priority Class):

typedef enum class _NSUDO_PROCESS_PRIORITY_CLASS_TYPE
{
    IDLE,
    BELOW_NORMAL,
    NORMAL,
    ABOVE_NORMAL,
    HIGH,
    REALTIME,
} NSUDO_PROCESS_PRIORITY_CLASS_TYPE, *PNSUDO_PROCESS_PRIORITY_CLASS_TYPE;

映射为 Win32 优先级类常量(NSudoAPI.cpp):IDLE → IDLE_PRIORITY_CLASS、BELOW_NORMAL → BELOW_NORMAL_PRIORITY_CLASS、NORMAL → NORMAL_PRIORITY_CLASS、ABOVE_NORMAL → ABOVE_NORMAL_PRIORITY_CLASS、HIGH → HIGH_PRIORITY_CLASS、REALTIME → REALTIME_PRIORITY_CLASS。进程创建成功后,实现通过 ::SetPriorityClass(ProcessInfo.hProcess, ProcessPriority) 应用该优先级(NSudoAPI.cpp)。

3.5 ShowWindowModeType —— 窗口显示模式

typedef enum class _NSUDO_SHOW_WINDOW_MODE_TYPE
{
    DEFAULT,
    SHOW,
    HIDE,
    MAXIMIZE,
    MINIMIZE,
} NSUDO_SHOW_WINDOW_MODE_TYPE, *PNSUDO_SHOW_WINDOW_MODE_TYPE;

映射为 ShowWindow 命令(NSudoAPI.cpp):DEFAULT → SW_SHOWDEFAULT、SHOW → SW_SHOW、HIDE → SW_HIDE、MAXIMIZE → SW_MAXIMIZE、MINIMIZE → SW_MINIMIZE。该值通过 STARTUPINFOW.wShowWindow 与 STARTF_USESHOWWINDOW 标志传递给创建过程(NSudoAPI.cpp)。

四、四个基础参数详解

4.1 WaitInterval —— 等待超时

类型为 DWORD,单位是毫秒,表示创建进程后等待该进程结束(或超时)的时间。实现中通过 ::WaitForSingleObjectEx(ProcessInfo.hProcess, WaitInterval, FALSE) 等待(NSudoAPI.cpp)。传 0 表示立即返回不等待;命令行版 NSudo 的 -Wait 参数会将此值设为 INFINITE(见第六节)。

4.2 CreateNewConsole —— 新控制台

类型为 BOOL。为 TRUE 时新进程拥有独立的新控制台窗口;为 FALSE(默认)时继承父进程的控制台。实现中在创建标志 dwCreationFlags 基础上按需追加 CREATE_NEW_CONSOLE(NSudoAPI.cpp)。

4.3 CommandLine —— 命令行

要执行的命令行字符串(LPCWSTR)。有两条硬性长度限制:

  • 整个命令行最大 32K(32768)字符;
  • 命令行中的模块名部分受 MAX_PATH(260 字符)限制。

实现中还会先用 Mile::ExpandEnvironmentStringsW 对命令行做环境变量展开(如 %windir%),再交给 ::CreateProcessAsUserW 执行(NSudoAPI.cpp)。

4.4 CurrentDirectory —— 当前目录

新进程的当前工作目录,必须使用完整路径,也支持 UNC 路径。传 nullptr 时,新进程将使用调用进程当前的驱动器和目录——文档特别说明该特性主要为"需要启动应用并指定其初始驱动器与工作目录的 Shell"而设计。

4.5 返回值

HRESULT 类型:成功返回 S_OK;非法枚举参数返回 E_INVALIDARG;任何 Win32 调用失败时,实现通过 Mile::HResultFromLastError 转换为对应 HRESULT 返回,并将详细失败原因写入共享库日志(便于后续用 NSudoReadLog 排查)。

五、源码级原理:NSudoCreateProcess 是如何"变身"的

理解了参数,再来看 NSudoAPI.cpp 中完整的执行链路,这对理解 API 的边界与前提非常重要:

  1. 写日志:先调用 NSudoWriteLog 记录本次调用的全部参数(见 NSudoAPI.cpp)。
  2. 参数校验与映射:依次把 MandatoryLabel、Priority、ShowWindow 三个枚举映射为 Win32 常量,非法值直接 E_INVALIDARG。
  3. 准备上下文令牌:OpenProcessToken 打开当前进程令牌并复制一份,为其启用 SeDebugPrivilege,再通过 SetThreadToken 将该令牌设为线程上下文,为后续打开 SYSTEM / TrustedInstaller 令牌铺路(NSudoAPI.cpp)。
  4. 获取活动会话:Mile::GetActiveSessionID 得到当前活动会话 ID,之后会写回目标令牌,保证进程创建在正确的会话中(NSudoAPI.cpp)。
  5. 获取目标用户令牌:按 UserModeType 打开/创建对应的"原始令牌"(TrustedInstaller 服务令牌 / SYSTEM 令牌 / 会话令牌 / 当前进程令牌 / LUA 令牌,逻辑见第三节表格)。
  6. 令牌整形:将原始令牌复制为主令牌 hToken,用 SetTokenInformation(TokenSessionId) 写入会话 ID;再按 PrivilegesModeType 启用/禁用全部特权,按 MandatoryLabelType 通过 Mile::SetTokenMandatoryLabel 写入完整性标签(NSudoAPI.cpp)。
  7. 创建进程:以 CREATE_SUSPENDED | CREATE_UNICODE_ENVIRONMENT(必要时追加 CREATE_NEW_CONSOLE)为创建标志,用 CreateEnvironmentBlock 按令牌生成环境块,然后调用 ::CreateProcessAsUserW 真正启动进程(NSudoAPI.cpp)。
  8. 善后:设置优先级类 → ResumeThread 恢复主线程 → WaitForSingleObjectEx 按 WaitInterval 等待 → 关闭句柄、销毁环境块、通过 Mile::ScopeExitTaskHandler 统一回收所有令牌句柄并清除线程令牌(NSudoAPI.cpp)。

需要强调的是:因为依赖打开 TrustedInstaller / SYSTEM 令牌的权限,NSudoCreateProcess 本质上要求调用进程具备管理员权限(且能获得 SeDebugPrivilege),这也是整个 NSudo 工具链的固有前提。

六、命令行启动器如何消费该 API

共享库不仅是独立组件,也是 NSudo 启动器的直接后端。以命令行版 NSudoLauncherCUI.cpp 为例,它将命令行选项解析为枚举后,在 第 679 行 统一调用 NSudoCreateProcess:

if (NSudoCreateProcess(
    UserModeType,
    PrivilegesModeType,
    MandatoryLabelType,
    ProcessPriorityClassType,
    ShowWindowModeType,
    WaitInterval,
    CreateNewConsole,
    UnresolvedCommandLine.c_str(),
    CurrentDirectory.c_str()) != S_OK)
{
    return NSUDO_MESSAGE::CREATE_PROCESS_FAILED;
}

对照 Website/en-us/docs/Readme.md 的命令行帮助,可以清晰看到选项与枚举的映射关系,这也是理解各枚举语义的绝佳旁证:

启动器选项 映射枚举
-U:T / -U:S / -U:C / -U:E / -U:P / -U:D TRUSTED_INSTALLER / SYSTEM / CURRENT_USER / CURRENT_USER_ELEVATED / CURRENT_PROCESS / CURRENT_PROCESS_DROP_RIGHT
-P:E / -P:D(缺省即 DEFAULT) ENABLE_ALL_PRIVILEGES / DISABLE_ALL_PRIVILEGES
-M:S / -M:H / -M:M / -M:L SYSTEM / HIGH / MEDIUM / LOW
-Priority:Idle ... -Priority:RealTime 六档优先级枚举
-ShowWindowMode:Show/Hide/Maximize/Minimize 对应窗口模式枚举
-Wait WaitInterval = INFINITE
-UseCurrentConsole CreateNewConsole = FALSE
-CurrentDirectory:[路径] CurrentDirectory

七、C# 接口:M2.NSudo 托管封装

对 .NET 开发者,NSudo 共享库提供了现成的托管包装程序集 M2.NSudo(工程文件见 M2.NSudo.csproj,目标框架为 netstandard2.0,可被现代 .NET 与 .NET Framework 项目同时引用)。核心类是 NSudoInstance.cs 中的 NSudoInstance。

7.1 加载机制

NSudoInstance 不是简单的 P/Invoke 静态绑定,而是运行时动态加载原生 DLL:

  • 默认构造时,会根据 RuntimeInformation.ProcessArchitecture 在应用目录下寻找 Win32\NSudoAPI.dll、x64\NSudoAPI.dll 或 ARM64\NSudoAPI.dll(即按位数自动选择架构匹配的二进制,见 NSudoInstance.cs);
  • 也支持通过 NSudoInstance(IDictionary<Architecture, string> BinaryPaths) 构造函数自定义各架构下的 DLL 路径;
  • 加载流程为 LoadLibrary → GetProcAddress → Marshal.GetDelegateForFunctionPointer,三个导出函数分别绑定到内部委托(NSudoInstance.cs),析构时自动 FreeLibrary。

五个枚举在托管侧也有对应定义(NSUDO_USER_MODE_TYPE.cs、NSUDO_PRIVILEGES_MODE_TYPE.cs、NSUDO_MANDATORY_LABEL_TYPE.cs、NSUDO_PROCESS_PRIORITY_CLASS_TYPE.cs、NSUDO_SHOW_WINDOW_MODE_TYPE.cs,均位于 Source/MSIL/M2.NSudo 目录),取值与 C/C++ 侧一一对应。

7.2 CreateProcess 方法与异常约定

托管方法 NSudoInstance.CreateProcess(...) 的签名与原生函数完全对齐(参数顺序一致),并做了两层转换:WaitInterval 使用 uint;CreateNewConsole 以 <a href="https://link.gitcode.com/i/bde2316d0e9ea537cdcf79457ccd5edd" target="_blank">MarshalAs(UnmanagedType.Bool)] 映射为 C# bool([NSudoInstance.cs)。调用结束后,若底层返回的 HRESULT 不等于 0(即非 S_OK),封装会抛出 ExternalException("-", hr),hr 即原生的 HRESULT 值。

7.3 官方示例:以 TrustedInstaller 身份启动 cmd

关联文档给出的 C# 示例与仓库内 M2.NSudo.Demo/Program.cs 完全对应,是最经典的用法——以 TrustedInstaller 身份、启用全部特权、SYSTEM 完整性级别、正常优先级、新控制台启动 cmd:

using System;

namespace M2.NSudo.Demo
{
    class Program
    {
        static void Main(string[] args)
        {
            NSudoInstance instance = new NSudoInstance();

            instance.CreateProcess(
                NSUDO_USER_MODE_TYPE.TRUSTED_INSTALLER,
                NSUDO_PRIVILEGES_MODE_TYPE.ENABLE_ALL_PRIVILEGES,
                NSUDO_MANDATORY_LABEL_TYPE.SYSTEM,
                NSUDO_PROCESS_PRIORITY_CLASS_TYPE.NORMAL,
                NSUDO_SHOW_WINDOW_MODE_TYPE.DEFAULT,
                0,
                true,
                "cmd",
                null);

            Console.ReadKey();
        }
    }
}

各实参含义:TRUSTED_INSTALLER 以 TrustedInstaller 服务令牌运行;ENABLE_ALL_PRIVILEGES 启用令牌全部特权;SYSTEM 完整性级别;NORMAL 优先级;DEFAULT 窗口模式;等待时间 0(不等待);true 新建独立控制台;命令行 "cmd";工作目录 null(继承调用进程目录)。

7.4 更完整的演示与日志读取

仓库中的演示工程还额外示范了 WriteLog / ReadLog 的用法(Program.cs):在创建进程前后分别写入 "Start" / "End" 日志,最后通过 instance.ReadLog() 一次性读出共享库内部记录的完整日志(包括本次调用各参数与所有失败原因),并在 catch 块中打印 ex.HResult。这套日志机制在排查"为什么进程创建失败"时非常实用:

instance.WriteLog("M2.NSudo.Demo", "Start");
try
{
    instance.CreateProcess(/* ... */);
}
catch (Exception ex)
{
    Console.WriteLine("CreateProcess Failed, return {0}", ex.HResult);
}
instance.WriteLog("M2.NSudo.Demo", "End");
Console.WriteLine(instance.ReadLog());

八、如何把共享库接入自己的项目

8.1 原生 C/C++ 工程

在 Visual Studio 中通过 Import 引入属性集即可自动获得头文件路径与链接库:

<Import Project="$(NSudoRepo)\Source\Native\NSudoSDK\NSudoAPI.props" />

该属性集(见 NSudoAPI.props)会做两件事:把 NSudoSDK 目录加入 IncludePath,并把 $(OutDir)NSudoAPI.lib 追加到链接依赖。随后只需 #include <NSudoAPI.h> 并按本文第二节的原型调用即可。注意头文件开头有一行强制约定:#error "<a href="https://link.gitcode.com/i/41dcdf6369c99d511921116a5cf412f0" target="_blank">NSudoAPI] You should use a C++ compiler.",即该接口面向 C++ 编译器([NSudoAPI.h)。

8.2 .NET 工程

引用 M2.NSudo 程序集(netstandard2.0),并按运行时位数把对应架构的 NSudoAPI.dll 放置在应用输出目录的 Win32 / x64 / ARM64 子文件夹中(这是默认加载路径,见 7.1 节),即可直接使用 NSudoInstance。

九、使用前提与注意事项

  1. 管理员权限是硬前提:无论是 TrustedInstaller、SYSTEM 还是会话令牌的获取,都依赖 SeDebugPrivilege 与管理员上下文(见第五节第 3 步),普通权限进程调用会直接失败并写入日志。
  2. 枚举值不可混用:五个枚举均有严格的取值约束,非法值(如 DEFAULT 直接作为 UserModeType)会返回 E_INVALIDARG。
  3. 命令行长度限制:整体不超过 32K 字符,模块名部分不超过 MAX_PATH(260)字符;可通过环境变量展开(%windir% 等)增强可移植性。
  4. 等待语义:WaitInterval = 0 表示不等待、立即返回;需要阻塞等待进程退出时,命令行版使用 INFINITE,库调用方同样可以传入 INFINITE。
  5. 失败排查:优先调用 NSudoReadLog() 读取共享库内部日志,其中记录了每一步 Win32 调用的失败 HRESULT 与具体原因,比只看返回值信息量更大。

十、结语

NSudo 共享库通过 NSudoCreateProcess 这一个入口,把"以 TrustedInstaller / SYSTEM / 当前用户 / 降权用户身份创建进程"这一复杂操作封装成了参数化、可复用的 API:原生侧有清晰的枚举语义与 NSudoAPI.cpp 的完整实现可供研读,托管侧有 M2.NSudo 封装与 M2.NSudo.Demo 开箱即用的示例。开发者既可以将其作为 NSudo 工具链的组成模块理解,也可以直接集成到自己的系统管理工具中,快速获得与 NSudo 一致的进程创建能力。

登录后查看全文
NSudo