ntparse 0.2.0
A lightweight Python package for parsing syscalls from ntdll.dll
License: MIT
Requires Python: >=3.7

# 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

```bash
pip install ntparse
```

### Development Installation

```bash
git clone https://github.com/micREsoft/ntparse/ntparse.git
cd ntparse
pip install -e .
```

## Quick Start

### Command Line Usage

Parse with specific output format:
```bash
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:
```bash
ntparse --input C:\path\to\ntdll.dll --format json
ntparse --input C:\path\to\ntdll.dll --format json --output done.json
```

### Python API Usage

```python
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:**
```python
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
```json
{
  "syscalls": {
    "NtClose": "0x0C",
    "NtOpenProcess": "0x26",
    "NtCreateFile": "0x55"
  },
  "count": 3,
  "metadata": {
    "format": "json",
    "version": "1.0"
  }
}
```

### CSV Format
```csv
Function Name, Syscall ID, Offset (hex)
NtClose, 12, 0x0C
NtOpenProcess, 38, 0x26
NtCreateFile, 85, 0x55
```

### Assembly Format
```asm
.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](https://github.com/erocarrera/pefile) for PE parsing
- Uses [capstone](https://github.com/capstone-engine/capstone) for disassembly
- Inspired by Windows syscall research and development tools