ntparse

A lightweight Python package for parsing syscalls from ntdll.dll on Windows systems.

Features

• Easy syscall extraction from ntdll.dll using capstone disassembly
• Multiple output formats: JSON, CSV, Assembly, Python dict
• Command line interface for quick usage
• Clean Python API for integration into your projects
• Automatic path detection for default ntdll.dll location
• Validation of PE files and syscall detection

Installation

pip install ntparse

Development Installation

git clone https://github.com/micREsoft/ntparse/ntparse.git
cd ntparse
pip install -e .

Quick Start

Command Line Usage

Parse with specific output format:

ntparse --format json --output syscalls.json
ntparse --format csv --output syscalls.csv
ntparse --format asm --output syscalls.asm
ntparse --format python --output syscalls.py

Parse from a custom ntdll.dll:

ntparse --input C:\path\to\ntdll.dll --format json
ntparse --input C:\path\to\ntdll.dll --format json --output done.json

Python API Usage

from ntparse import parse_ntdll, to_json, to_csv

# parse syscalls from default ntdll.dll
syscalls = parse_ntdll()

# parse from custom path
syscalls = parse_ntdll("C:\\Windows\\System32\\ntdll.dll")

# convert to different formats
json_output = to_json(syscalls)
csv_output = to_csv(syscalls)

print(f"Found {len(syscalls)} syscalls")

API Reference

Core Functions

parse_ntdll(path=None, arch="x64")

Parse syscalls from ntdll.dll.

Parameters:

• path (str, optional): Path to ntdll.dll. If None, uses default Windows location
• arch (str): Target architecture ("x64" or "x86"). Currently only x64 is supported

Returns:

• dict: Dictionary mapping function names to syscall numbers

Example:

syscalls = parse_ntdll()
# returns: {"NtClose": 0x0C, "NtOpenProcess": 0x26, ...}

get_syscalls(dll_path)

Extract syscall numbers from a specific DLL file.

Parameters:

• dll_path (str): Path to the ntdll.dll file

Returns:

• dict: Dictionary mapping function names to syscall numbers

Formatter Functions

to_json(syscalls, output_file=None)

Convert syscalls to JSON format.

to_csv(syscalls, output_file=None)

Convert syscalls to CSV format.

to_asm(syscalls, output_file=None)

Convert syscalls to x64 assembly format.

to_python_dict(syscalls, output_file=None)

Convert syscalls to Python dictionary format.

Output Formats

JSON Format

{
  "syscalls": {
    "NtClose": "0x0C",
    "NtOpenProcess": "0x26",
    "NtCreateFile": "0x55"
  },
  "count": 3,
  "metadata": {
    "format": "json",
    "version": "1.0"
  }
}

CSV Format

Function Name, Syscall ID, Offset (hex)
NtClose, 12, 0x0C
NtOpenProcess, 38, 0x26
NtCreateFile, 85, 0x55

Assembly Format

.code

; Generated by ntparse
; Syscall stubs for x64

NtClose PROC
    mov r10, rcx
    mov eax. 0Fh
    syscall
    ret
NtClose ENDP

NtOpenProcess PROC
    mov r10, rcx
    mov eax, 026h
    syscall
    ret
NtOpenProcess ENDP

end

Command Line Options

usage: ntparse [-h] [--input INPUT] [--format {json,csv,asm,python}]
               [--output OUTPUT] [--arch {x64,x86}] [--validate]

Parse syscalls from ntdll.dll

options:
  -h, --help            show this help message and exit
  --input INPUT, -i INPUT
                        Path to ntdll.dll (default: C:\Windows\System32\ntdll.dll)
  --format {json,csv,asm,python}, -f {json,csv,asm,python}
                        Output format (default: json)
  --output OUTPUT, -o OUTPUT
                        Output file path (default: stdout)
  --arch {x64,x86}      Target architecture (default: x64)
  --validate            Validate ntdll.dll before parsing

Requirements

• Python 3.7+
• Windows OS (for ntdll.dll access)
• pefile
• capstone

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

Acknowledgments

• Built with pefile for PE parsing
• Uses capstone for disassembly
• Inspired by Windows syscall research and development tools