kaisonox/apiscopeएक API हुकिंग फ्रेमवर्क जो विंडोज अनुप्रयोगों को इंटरसेप्ट और मॉनिटर करने के लिए है
ApiScope एक Windows x64 अनुसंधान उपकरण है जो किसी नए या चल रहे प्रक्रिया में चयनित API कॉल को ट्रेस करने के लिए है। यह Windows डिबगर API के माध्यम से DLL लोड ईवेंट का अनुसरण करता है और प्रत्येक ईवेंट से पहले डिबगी जारी रहने से पहले हुक स्थापित करता है।
शामिल हुक्स:
ntdll.dll!NtCreateFile (लक्ष्य पथ रिकॉर्ड करता है)ntdll.dll!NtOpenFile (लक्ष्य पथ रिकॉर्ड करता है)ntdll.dll!NtReadFilentdll.dll!NtWriteFilentdll.dll!NtClosentdll.dll!NtOpenKey (कुंजी पथ रिकॉर्ड करता है)ntdll.dll!NtSetValueKeyntdll.dll!NtQueryValueKeybcrypt.dll!BCryptOpenAlgorithmProvider
आवश्यकताएँ:
cmake -S . -B build -A x64
cmake --build build --config Release
ctest --test-dir build -C Release --output-on-failure
powershell -ExecutionPolicy Bypass -File .\scripts\validate-apiscope-hooks.ps1 .\build\bin\Release\apiscope-hooks.dll
powershell -ExecutionPolicy Bypass -File .\scripts\smoke.ps1 -SkipBuild
Zydis v4.1.1 एक पिन किए गए कमिट पर लाया जाता है और केवल apiscope.exe में लिंक किया जाता है। इंजेक्ट की गई apiscope-hooks.dll आयात-मुक्त रहती है।
apiscope.exe [--help | --version | --list-hooks]
apiscope.exe run -k <module!export|all> [-k <module!export>] [-f text|jsonl] [-o <path>] [-q] -- <program> [args...]
apiscope.exe attach -p <pid> -k <module!export|all> [-k <module!export>] [-f text|jsonl] [-o <path>] [-q]
हुक नाम हमेशा मॉड्यूल-योग्य होते हैं। मॉड्यूल मिलान केस-असंवेदनशील है; एक्सपोर्ट मिलान केस-संवेदनशील है।
.\apiscope.exe run `
--hook ntdll.dll!NtCreateFile `
--hook bcrypt.dll!BCryptOpenAlgorithmProvider `
-- C:\path\app.exe
.\apiscope.exe attach --pid 4242 --hook all
.\apiscope.exe run --hook all --format jsonl --output trace.jsonl --quiet -- app.exe
टर्मिनल ईवेंट पठनीय रहते हैं जबकि --output वैकल्पिक रूप से टेक्स्ट या JSONL को एक फ़ाइल में टी (tee) करता है। --quiet टर्मिनल ईवेंट मिरर को दबा देता है। --color auto|always|never टर्मिनल रंग को नियंत्रित करता है (डिफ़ॉल्ट auto: TTY के लिए चालू, पाइप या NO_COLOR के तहत बंद); रंग कभी भी --output फ़ाइलों में प्रकट नहीं होता। TTY पर ApiScope एक लाइव स्थिति फुटर (ईवेंट, ड्रॉप, दर और प्रति-हुक गणना) भी दिखाता है जो स्थान पर पुनः चित्रित होता है; इसे --status auto|always|never से नियंत्रित करें।
[*] ntdll.dll!NtWriteFile ----------
timestamp : 2026-06-07T17:44:23.3834340Z
thread_id : 3508
sequence : 3
file_handle : 0x000000000000008C
length : 16
buffer_ascii : Hello, ApiScope!
result : STATUS_SUCCESS (0x00000000)
JSONL ईवेंट में सामान्य मेटाडेटा और हुक-स्थानीय फ़ील्ड होते हैं:
{"schema_version":1,"sequence":1,"module":"bcrypt.dll","api":"BCryptOpenAlgorithmProvider","hook":"bcrypt.dll!BCryptOpenAlgorithmProvider","fields":{"flags":0,"result":"STATUS_SUCCESS (0x00000000)"}}
ईवेंट एनवेलप और प्रति-प्रकार फील्ड एनकोडिंग (पॉइंटर्स और स्टेटस 0x हेक्स स्ट्रिंग के रूप में रेंडर होते हैं) के लिए SCHEMA.md देखें।
सक्रिय हुक को पुनर्स्थापित करने, रिमोट इंस्ट्रुमेंटेशन को मुक्त करने और डिटैच करने के लिए Ctrl+C या Ctrl+Break दबाएँ। लक्ष्य चलता रहता है। प्राकृतिक निकास पर, ApiScope लक्ष्य स्थिति को दशमलव और हेक्साडेसिमल में प्रिंट करता है, उसके बाद stderr पर एक सत्र सारांश (ईवेंट, ड्रॉप और प्रति-हुक गणना) प्रिंट करता है।
NtCreateFile, NtOpenFile, और NtOpenKey OBJECT_ATTRIBUTES से लक्ष्य path को हल करते हैं और परिणामी हैंडल की रिपोर्ट करते हैं। ApiScope प्रत्येक सफल ओपन को रिकॉर्ड करता है और उसी हैंडल पर बाद के ऑपरेशन — रीड, राइट, रजिस्ट्री वैल्यू एक्सेस, और मैचिंग NtClose — को हल किए गए path के साथ एनोटेट करता है, ताकि मैन्युअल रूप से हैंडल को ट्रैक किए बिना गतिविधि पठनीय हो। NtClose हैंडल को भी हटा देता है, और सापेक्ष ओपन पहले देखे गए root_directory हैंडल के माध्यम से हल किए जाते हैं।
[*] ntdll.dll!NtCreateFile ----------
sequence : 2
path : test_file.txt
file_handle : 0x000000000000008C
result : STATUS_SUCCESS (0x00000000)
[*] ntdll.dll!NtReadFile ----------
sequence : 3
file_handle : 0x000000000000008C
buffer_ascii : Hello, ApiScope!
result : STATUS_SUCCESS (0x00000000)
path : test_file.txt
रीड और राइट ईवेंट पर path हैंडल से सहसंबद्ध होता है, कॉल पर स्वयं नहीं देखा जाता।
प्रत्येक हुक src/apiscope-hooks/hooks/ के तहत एक फ़ाइल है और अपने स्रोत मॉड्यूल, एक्सपोर्ट, हैंडलर, ट्रैम्पोलिन स्लॉट, कॉलिंग कन्वेंशन और हस्ताक्षर को एक साथ घोषित करता है:
DEFINE_API_HOOK(
BCryptOpenAlgorithmProvider,
"bcrypt.dll",
"BCryptOpenAlgorithmProvider",
NTSTATUS,
WINAPI,
PVOID* Algorithm,
const wchar_t* AlgorithmId,
const wchar_t* Implementation,
ULONG Flags) {
TraceEvent event;
InitializeTraceEvent(&event, "bcrypt.dll", "BCryptOpenAlgorithmProvider");
AddTraceUInt32(&event, "flags", Flags);
NTSTATUS result = CALL_ORIGINAL(
BCryptOpenAlgorithmProvider,
Algorithm,
AlgorithmId,
Implementation,
Flags);
AddTraceStatus(&event, "result", result);
EmitTraceEvent(&event);
return result;
}
apiscope.exe --list-hooks हुक DLL द्वारा निर्यात किए गए फिक्स्ड-लेआउट डिस्क्रिप्टर को खोजता है। किसी केंद्रीय API सूची या लॉन्चर-साइड ईवेंट स्कीमा की आवश्यकता नहीं है।
sequenceDiagram
actor User
participant ApiScope as apiscope.exe
participant Debugger as Windows debugger API
participant Target as Target process
participant Modules as Loaded DLLs
participant Hooks as apiscope-hooks.dll
participant Ring as Shared-memory ring
User->>ApiScope: run program or attach PID
alt run
ApiScope->>Debugger: CreateProcess(DEBUG_ONLY_THIS_PROCESS)
else attach
ApiScope->>Debugger: DebugActiveProcess(PID)
end
ApiScope->>Debugger: DebugSetProcessKillOnExit(FALSE)
Debugger-->>ApiScope: CREATE_PROCESS_DEBUG_EVENT
ApiScope->>Target: Map import-free hook image
ApiScope->>Ring: Create and initialize bounded ring
ApiScope->>Target: Map shared section with NtMapViewOfSection
loop CREATE_PROCESS / LOAD_DLL events
Debugger-->>ApiScope: Module base and file handle
ApiScope->>Modules: Register module name and base
alt ntdll.dll loaded
ApiScope->>Target: Build unpatched NtReadVirtualMemory bypass
end
ApiScope->>Modules: Resolve module.dll!Export and forwarders
alt export and dependencies are loaded
ApiScope->>Hooks: Resolve handler and trampoline slot
ApiScope->>Target: Allocate trampoline and patch export
else dependency is not loaded yet
ApiScope->>ApiScope: Keep hook pending
end
ApiScope->>Debugger: ContinueDebugEvent
end