NSudo 共享库 NSudoCreateProcess 接口全解析:从 C/C++ 到 C 的系统级进程创建实战指南
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 的边界与前提非常重要:
- 写日志:先调用
NSudoWriteLog记录本次调用的全部参数(见 NSudoAPI.cpp)。 - 参数校验与映射:依次把 MandatoryLabel、Priority、ShowWindow 三个枚举映射为 Win32 常量,非法值直接
E_INVALIDARG。 - 准备上下文令牌:
OpenProcessToken打开当前进程令牌并复制一份,为其启用SeDebugPrivilege,再通过SetThreadToken将该令牌设为线程上下文,为后续打开 SYSTEM / TrustedInstaller 令牌铺路(NSudoAPI.cpp)。 - 获取活动会话:
Mile::GetActiveSessionID得到当前活动会话 ID,之后会写回目标令牌,保证进程创建在正确的会话中(NSudoAPI.cpp)。 - 获取目标用户令牌:按
UserModeType打开/创建对应的"原始令牌"(TrustedInstaller 服务令牌 / SYSTEM 令牌 / 会话令牌 / 当前进程令牌 / LUA 令牌,逻辑见第三节表格)。 - 令牌整形:将原始令牌复制为主令牌
hToken,用SetTokenInformation(TokenSessionId)写入会话 ID;再按PrivilegesModeType启用/禁用全部特权,按MandatoryLabelType通过Mile::SetTokenMandatoryLabel写入完整性标签(NSudoAPI.cpp)。 - 创建进程:以
CREATE_SUSPENDED | CREATE_UNICODE_ENVIRONMENT(必要时追加CREATE_NEW_CONSOLE)为创建标志,用CreateEnvironmentBlock按令牌生成环境块,然后调用::CreateProcessAsUserW真正启动进程(NSudoAPI.cpp)。 - 善后:设置优先级类 →
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。
九、使用前提与注意事项
- 管理员权限是硬前提:无论是 TrustedInstaller、SYSTEM 还是会话令牌的获取,都依赖
SeDebugPrivilege与管理员上下文(见第五节第 3 步),普通权限进程调用会直接失败并写入日志。 - 枚举值不可混用:五个枚举均有严格的取值约束,非法值(如
DEFAULT直接作为 UserModeType)会返回E_INVALIDARG。 - 命令行长度限制:整体不超过 32K 字符,模块名部分不超过
MAX_PATH(260)字符;可通过环境变量展开(%windir%等)增强可移植性。 - 等待语义:
WaitInterval = 0表示不等待、立即返回;需要阻塞等待进程退出时,命令行版使用INFINITE,库调用方同样可以传入INFINITE。 - 失败排查:优先调用
NSudoReadLog()读取共享库内部日志,其中记录了每一步 Win32 调用的失败 HRESULT 与具体原因,比只看返回值信息量更大。
十、结语
NSudo 共享库通过 NSudoCreateProcess 这一个入口,把"以 TrustedInstaller / SYSTEM / 当前用户 / 降权用户身份创建进程"这一复杂操作封装成了参数化、可复用的 API:原生侧有清晰的枚举语义与 NSudoAPI.cpp 的完整实现可供研读,托管侧有 M2.NSudo 封装与 M2.NSudo.Demo 开箱即用的示例。开发者既可以将其作为 NSudo 工具链的组成模块理解,也可以直接集成到自己的系统管理工具中,快速获得与 NSudo 一致的进程创建能力。