BinSentry 自研二进制哨兵调试引擎接口规范

[微软技术分享]

BinSentry 二进制哨兵，由 LYSHARK 独立自研，是一款运行于 Windows 平台的二进制动态调试引擎。该调试引擎从零手写开发，C++ 代码 2 万余行，实现 200 + 调试方法；原生采用 CMD 命令行 HTTP 服务器架构，专为 AI Agent 打造。配合配套 AI 智能体，能够对二进制文件、木马等恶意样本进行深层次分析，是二进制样本研究的实用工具。

哨兵可以部署到任意的虚拟机沙盒之中，并可以搭载目前流行的jev等大模型产品，AI驱动速度有质的提升，是Windows平台下AI动态调试的优质项目。

使用说明

无会话

#	接口	params(JSON)	期望
1	SystemInfo	{}	ok=true, 返回系统信息
2	ProcessList	{}	ok=true, 进程列表
3	EnumErrorCodes	{}	ok=true, 错误码表
4	EnumExceptions	{}	ok=true, 异常码表
5	EnumWindows	{"pid":4}	ok=true, 窗口枚举完成
6	IsProcessElevated	{}	ok=true, 返回是否提权
7	ClearLog	{}	ok=true, 日志已清空
8	SaveLog	{"path":"E:\LyDebugger 2.3\x86\Release\_full_log.txt"}	ok=true, 日志已保存
9	Logs	{}	ok=true, 日志查询
10	Help	{}	ok=true
11	GetJIT	{}	ok=true, JIT配置
12	SetJIT	{"path":"C:\LyDebugger\x86\LyDebugger.exe -- -p %ld -e %ld"}	ok=true
13	GetCommandLine	{}	ok=true
14	SetCommandLine	{"args":"--test-arg"}	ok=true, 下次启动生效
15	SetBPXOptions	{"option":"FASTRESUME","enable":1}	ok=true, 位掩码
16	SetExceptionBPX	{"code":"0xC0000005"}	ok=true, 异常断点已设
17	DelExceptionBPX	{"code":"0xC0000005"}	ok=true, 已删除
18	GetExceptionBPXList	{}	ok=true, 列表
19	SetDllBreakPoint	{"dll":"test.dll"}	ok=true
20	DelDllBreakPoint	{"dll":"test.dll"}	ok=true
21	GetDllBreakPoints	{}	ok=true
22	SetVar	{"name":"testvar","value":"0x1234"}	ok=true
23	DelVar	{"name":"testvar"}	ok=true
24	GetVars	{}	ok=true, 数量
25	AddArgument	{"start":"0x009015C0","end":"0x00901600","name":"func1"}	ok=true
26	DelArgument	{"start":"0x009015C0"}	ok=true
27	GetArguments	{}	ok=true
28	GetComments	{}	ok=true
29	GetLabels	{}	ok=true
30	GetBookMarks	{}	ok=true
31	Functions	{}	ok=true
32	ShowBreakPoint	{}	ok=true, 软断点数量
33	ShowHbreakPoint	{}	ok=true, 硬断点数量
34	ShowMemBreakPoint	{}	ok=true, 内存断点数量
35	ShowApiBreakPoint	{}	ok=true, API断点数量
36	LoadDatabase	{"path":"E:\LyDebugger 2.3\x86\Release\_dbg.dat"}	ok=true
37	SaveDatabase	{"path":"E:\LyDebugger 2.3\x86\Release\_dbg.dat"}	ok=true

启动会话

#	接口	params(JSON)	期望
1	Debug	{"path":"E:\LyDebugger 2.3\x86\Win32Project1.exe","args":"","cwd":"E:\LyDebugger 2.3\x86\Release"}	ok=true, 返回pid/tid
2	SetDebug	"Logs"	ok=true (params传命令字符串)
3	RunToUserCode	{}	ok=true, 设OEP断点运行到用户代码
4	Register	{}	EIP==0x009015BB

停止态-基础

#	接口	params(JSON)	期望
1	ProcessInfo	{}	ok=true
2	Threads	{}	ok=true, 取第一个threadId作TID
3	ThreadInfo	{"tid":<Threads返回的threadId>}	ok=true
4	GetActiveThread	{}	ok=true
5	SetActiveThread	{"tid":<Threads返回的threadId>}	ok=true
6	Register	{}	ok=true
7	SetRegister	{"reg":"eax","value":"0x12345678"}	ok=true, 再设回0
8	GetPageRights	{"address":"0x009015BB"}	ok=true
9	SetPageRights	{"address":"0x009015BB","protect":"RWX"}	ok=true, 改后还原protect=0x20
10	Modules	{}	ok=true
11	ModuleInfo	{"module":"Win32Project1.exe"}	ok=true
12	Sections	{"module":"Win32Project1.exe"}	ok=true
13	PEInfo	{"path":"E:\LyDebugger 2.3\x86\Win32Project1.exe"}	ok=true, ImageBase=0x400000 OEP=0x15BB
14	RichHeader	{"module":"Win32Project1.exe"}	ok=true
15	TLSCallbacks	{"module":"Win32Project1.exe"}	ok=true (无TLS返回error字段)
16	RelocationList	{"module":"Win32Project1.exe"}	ok=true
17	DebugDirectory	{"module":"Win32Project1.exe"}	ok=true
18	ImportList	{"module":"Win32Project1.exe"}	ok=true
19	ExportList	{"module":"kernel32.dll"}	ok=true
20	GetImportAddress	{"module":"Win32Project1.exe","name":"MessageBoxA"}	ok=true
21	GetExportAddress	{"module":"kernel32.dll","name":"LoadLibraryA"}	ok=true
22	AddrToModule	{"address":"0x009015BB"}	ok=true
23	GetSectionData	{"module":"Win32Project1.exe","name":".text"}	ok=true
24	GetSectionInfo	{"module":"Win32Project1.exe","name":".text"}	ok=true
25	Symbol	{"expr":"Win32Project1.exe+0x15BB"}	ok=true
26	GetSymbolInfo	{"address":"0x009015BB"}	ok=true
27	GetFunctionSize	{"address":"0x009015BB"}	ok=true
28	Heaps	{}	ok=true
29	Handles	{"max":20}	ok=true
30	SEHList	{}	ok=true
31	MemoryInfo	{"address":"0x009015BB"}	ok=true
32	Regions	{}	ok=true
33	Memory	{"address":"0x009015BB","size":16}	ok=true
34	ReadMemoryValue	{"address":"0x009015BB","size":4}	ok=true
35	WriteMemory	{"address":"0x009015BB","hex":"CC"}	ok=true, 再写回E8
36	GetString	{"address":"0x00901000","max":64,"type":"ascii"}	ok=true, JSON可解析
37	GetOpcodeSize	{"address":"0x009015BB"}	ok=true
38	DisassembleAt	{"address":"0x009015BB","count":5}	ok=true
39	Dissasembler	{"address":"0x009015BB","count":5}	ok=true
40	GetBranchTarget	{"address":"0x009015BB"}	ok=true
41	Assemble	{"instr":"mov eax, 1","cip":"0x009015C0"}	ok=true
42	AssembleAt	{"address":"0x00901050","instr":"nop"}	ok=true
43	MatchPattern	{"address":"0x009015BB","pattern":"E8","size":64}	ok=true
44	SearchMemory	{"pattern":"E8","start":"0x00901000","size":0x1000}	ok=true
45	SearchAllMemory	{"pattern":"E8","max":5}	ok=true
46	SearchStrings	{"address":"0x00901000","size":0x400}	ok=true
47	FindRef	{"address":"0x009015BB","max":5}	ok=true
48	xrefs	{"address":"0x009015BB","max":5}	ok=true
49	HashMemory	{"address":"0x009015BB","size":16,"algo":"md5"}	ok=true
50	CallStack	{"max":16}	ok=true
51	Stack	{"count":8}	ok=true
52	StackPush	{"value":"0x11223344"}	ok=true
53	StackPop	{}	ok=true
54	StackPeek	{"offset":0}	ok=true
55	SetFlag	{"flag":"ZF","value":0}	ok=true
56	Eval	{"expr":"eip+4"}	ok=true
57	AllocateMemory	{"size":0x1000}	ok=true, 记下address作MEM
58	SetMemory	{"address":MEM,"hex":"9090"}	ok=true (在分配区写, 勿写代码区)
59	FillMemory	{"address":MEM,"size":8,"value":"0x90"}	ok=true
60	Memcpy	{"src":"0x009015BB","dst":"0x"+(MEM+0x100),"size":5}	ok=true
61	FreeMemory	{"address":MEM}	ok=true
62	VaToFileOffset	{"address":"0x009015BB"}	ok=true
63	FileOffsetToVa	{"offset":"0x9BB"}	ok=true
64	minidump	{"path":"E:\LyDebugger 2.3\x86\Release\_full.dmp"}	ok=true
65	mnemonicbrief	{"address":"0x009015BB"}	ok=true
66	LastException	{}	ok=true
67	GetThreadLastError	{"tid":<Threads返回的threadId>}	ok=true
68	GetThreadPriority	{"tid":<Threads返回的threadId>}	ok=true
69	SetThreadPriority	{"tid":<Threads返回的threadId>,"priority":"NORMAL"}	ok=true
70	SetThreadName	{"tid":<Threads返回的threadId>,"name":"main-thread"}	ok=true
71	StartTraceRecord	{}	ok=true
72	GetTraceRecord	{"count":5}	ok=true
73	StopTraceRecord	{}	ok=true
74	JmpHistory	{}	ok=true
75	PatchMemory	{"address":"0x009015BB","hex":"CC"}	ok=true
76	Patches	{}	ok=true
77	RevertPatch	{"address":"0x009015BB"}	ok=true
78	DeletePatch	{"address":"0x009015BB"}	ok=true
79	ShowDebugger	{}	ok=true
80	HideDebugger	{}	ok=true
81	gpa	{"dll":"kernel32.dll","api":"LoadLibraryA"}	ok=true

断点

#	接口	params(JSON)	期望
1	SetBreakPoint	{"address":"0x009015BB"}	ok=true
2	GetBreakpointInfo	{"address":"0x009015BB"}	ok=true
3	GetBreakpointType	{"address":"0x009015BB"}	ok=true
4	SetBreakpointName	{"address":"0x009015BB","name":"OEP"}	ok=true
5	SetBreakpointSingleshoot	{"address":"0x009015BB","enable":0}	ok=true
6	SetBreakpointFastResume	{"address":"0x009015BB","enable":0}	ok=true
7	SetBreakpointSilent	{"address":"0x009015BB","enable":0}	ok=true
8	SetBreakpointLog	{"address":"0x009015BB","text":"hit OEP"}	ok=true
9	SetBreakpointLogFile	{"address":"0x009015BB","file":"E:\LyDebugger 2.3\x86\Release\_bp.log"}	ok=true
10	SetBreakpointHitCount	{"address":"0x009015BB","count":3}	ok=true
11	GetBreakpointHitCount	{"address":"0x009015BB"}	ok=true
12	ResetBreakpointHitCount	{"address":"0x009015BB"}	ok=true
13	SetCondBreakPoint	{"address":"0x009015BB","cond":"1","thread":TID}	ok=true
14	DelCondBreakPoint	{"address":"0x009015BB"}	ok=true
15	SetHbreakPoint	{"address":"0x009015C0","len":"1","flag":"e"}	ok=true (勿与软断点同址)
16	DelHbreakPoint	{"address":"0x009015C0"}	ok=true
17	SetMemBreakPoint	{"address":"0x009015C0","flag":"e"}	ok=true
18	DelMemBreakPoint	{"address":"0x009015C0"}	ok=true
19	SetApiBreakPoint	{"dll":"kernel32.dll","api":"ExitProcess"}	ok=true
20	DelApiBreakPoint	{"dll":"kernel32.dll","api":"ExitProcess"}	ok=true
21	SetPageMemory	{"address":"0x00901000","protect":"RWX"}	ok=true
22	DisableBreakpoint	{"address":"0x009015BB"}	ok=true
23	EnableBreakpoint	{"address":"0x009015BB"}	ok=true
24	BreakpointCommand	{"address":"0x009015BB","command":""}	ok=true
25	DelBreakPoint	{"address":"0x009015BB"}	ok=true, 清场后进P4

执行控制

#	接口	params(JSON)	期望
1	Run	{}	ok=true, 发送后等停止(Status.stopped)
2	StepIn	{}	ok=true, 等停止
3	StepOver	{}	ok=true, 等停止
4	StepOut	{}	ok=true, 等停止
5	EStepOver	{}	ok=true, 等停止
6	EStepInto	{}	ok=true, 等停止(注意是EStepInto非EStepIn)
7	EStepOut	{}	ok=true, 等停止
8	Skip	{"count":1}	ok=true, 保持停止
9	InstrUndo	{}	ok=true, EIP回退一条
10	ExecuteCommand	"StepOver"	ok=true (params传字符串子命令)
11	StepUser	{}	ok=true (用户代码处返回"无需运行")
12	RunToUserCode	{}	ok=true
13	TraceInto	{"count":3}	ok=true, 等停止
14	TraceOver	{"count":3}	ok=true, 等停止
15	TraceLine	{"address":"0x009015BB"}	ok=true, 等停止
16	ERun	{}	ok=true, 等停止
17	SERun	{}	ok=true, 等停止
18	DebugContinue	{"status":0}	ok=true, 等停止
19	RunTo	{"address":"0x009015BB"}	ok=true, 临时断点命中移除

运行态

#	接口	params(JSON)	期望
1	SetBreakPoint	{"address":"0x009015BB"}	ok=true
2	Run	{}	ok=true, 等停止(OEP断点命中)
3	PauseAllThreads	{}	ok=true
4	ResumeAllThreads	{}	ok=true
5	ThreadPause	{"tid":次线程threadId}	ok=true (用非活动线程)
6	ThreadResume	{"tid":次线程threadId}	ok=true
7	DelBreakPoint	{"address":"0x009015BB"}	ok=true
8	Run	{}	ok=true, 目标自由运行
9	Pause	{}	ok=true, 等停止
10	SetBreakPoint	{"address":"0x009015BB"}	ok=true
11	AnimateInto	{"count":3}	ok=true, 1.5s后
12	AnimateStop	{}	ok=true, 等停止
13	AnimateOver	{"count":3}	ok=true, 1.5s后
14	AnimateStop	{}	ok=true, 等停止
15	Run	{}	ok=true, 等停止
16	StepSystem	{}	ok=true (最后测, 会停系统代码)

会话管理

#	接口	params(JSON)	期望
1	DumpProcess	{"path":"E:\LyDebugger 2.3\x86\Release\_dump.bin","base":"0x00900000","size":0x2000}	ok=true
2	LoadConfig	{"module":"Win32Project1.exe"}	ok=true
3	SaveDatabase	{"path":"E:\LyDebugger 2.3\x86\Release\_dbg2.dat"}	ok=true
4	LoadDatabase	{"path":"E:\LyDebugger 2.3\x86\Release\_dbg2.dat"}	ok=true
5	Restart	{}	ok=true, 等2.5s
6	Stop	{}	ok=true, 会话终止
7	Debug	{"path":"E:\LyDebugger 2.3\x86\Win32Project1.exe","cwd":"E:\LyDebugger 2.3\x86\Release"}	ok=true, 重启会话等2.5s
8	Detach	{}	ok=true, 分离会话