Impacket esentutl.py
Back to the category index / Back to the command index
Overview
Section titled “Overview”Reads catalog information, pages, and table rows from a local ESE/ESENT database.
| Item | Details |
|---|---|
| Implementation | examples/esentutl.py |
| Category | Secrets / DPAPI / registry / file analysis |
| Size | 111 lines |
| Distribution | Installed as a script through scripts=examples/*.py in setup.py |
CLI and input
Section titled “CLI and input”Run python examples/esentutl.py -h for the current option definitions.
Subcommands: dump, info, export
| Argument | Description |
|---|---|
databaseFile | ESE database to open |
-debug | Enable debug output |
-ts | Add a timestamp to each log message |
-page | Page to open |
-table | Table to dump; required |
Detailed processing flow
Section titled “Detailed processing flow”The tool opens a database file with ESENT_DB. info displays the catalog, dump displays the specified page as a structure, and export reads and displays rows from the specified table through a cursor. It performs no remote I/O or authentication.
How it works
Section titled “How it works”An ESE database consists of fixed-size pages, B-trees, and catalog metadata.
ESENT_DB reads page size and version from the header, then traverses the catalog
table to build schemas for tables, columns, and indexes. The info command displays
this catalog, a higher-level structure than a raw page dump.
dump calculates a file offset from the page number and displays the page header,
tags, and records as structures. export resolves a table through the catalog,
walks records with a cursor, and decodes fixed, variable, and tagged data
according to column types. Deleted records, NULLs, and long values cannot be
handled like ordinary scalars.
The CLI is a thin front end to the parser, so page layout and B-tree traversal
changes belong in impacket.ese. As a tool that accepts damaged databases,
it should validate page numbers, tag offsets, and record lengths against the
file size so a malformed record cannot cause a read from another page.
Key implementation elements
Section titled “Key implementation elements”| Symbol | Location | Where to trace its responsibility |
|---|---|---|
dumpPage() | 31 | Module function |
exportTable() | 35 | Module function |
main() | 59 | Module function |
Dependencies
Section titled “Dependencies”Within Impacket
Section titled “Within Impacket”| Module | Main names used |
|---|---|
impacket.examples | logger |
impacket | version |
impacket.ese | ESENT_DB |
Output, side effects, and required privileges
Section titled “Output, side effects, and required privileges”- The main operation parses local files. Treat input as untrusted: validate offsets, lengths, and format identifiers before accessing data.
- Options may create or update local files. Check how existing files are handled and the permissions on output containing secrets.
Failure paths and cleanup
Section titled “Failure paths and cleanup”- Distinguish a missing input file, a damaged file, an incomplete read, and an unsupported format.
When changing the implementation
Section titled “When changing the implementation”The code relies almost entirely on impacket.ese.ESENT_DB. dumpPage() and exportTable() form a thin display layer. Change page or table parsing in impacket/ese.py and tests/misc/test_ese.py rather than in the CLI.
Verification
Section titled “Verification”- Syntax:
python -m py_compile examples/esentutl.py - CLI:
python examples/esentutl.py -h - Related test:
tests/misc/test_ese.py