Skip to content

Artifact Module API

Jump to bottom Edit New page
James Habben edited this page Sep 19, 2025 · 8 revisions

This page documents the official API functions available to artifact module developers in iLEAPP. Use these functions for file access, data parsing, error handling, and common conversions to ensure robust and consistent module behavior.

Table of Contents

Some key functions are included in the list below, but there are more available in each of the sections.

Media Management

Work with media files types such as images, videos, audio to include in the various artifact output formats.

Important Note: When a column in data_headers is designated for media (e.g., ('Image', 'media')), the corresponding value in your data_list must be the reference ID returned from either the check_in_media() or check_in_embedded_media() function. Directly inserting file paths or other data into a media column will result in errors during the report generation process. These functions handle the necessary file copying and database entries to ensure media is correctly processed and displayed.

check_in_media(...)

Processes a media file that exists as a standalone file in the extraction. This function finds the file, copies it to the report's media folder, creates the necessary database entries for LAVA, and returns a unique reference ID to be included in your artifact's data row.

Parameters

  • file_path: (string) The path of the media file you want to process (e.g., '/Media/PhotoData/Thumbnails/abc/123.jpg').
  • name: (string) An optional friendly name or description for the media (e.g., "User Profile Picture").

When to use:

Use this function when your artifact discovers a path to a media file (image, video, audio) that exists as a separate file within the extraction.

Example:

from scripts.ilapfuncs import check_in_media

# Be sure to use the 'media' type in the column header for the media object
data_headers = ('Message', ('Image', 'media'))

# Assume 'db_row' is a record from a database
media_path_from_db = db_row['path_to_attachment'] # e.g., '/Attachments/123/image.jpg'
media_name = db_row['attachment_filename'] # e.g., 'image.jpg'

# process_media will return a media item for your data row
media_item = check_in_media(
    media_path_from_db,
    name=media_name
)

# Now add media_ref_id to your data list
data_list.append((message, media_ref_id))

Usage:

check_in_embedded_media(...)

Processes media content that is embedded within another file (e.g., a database BLOB). This function saves the raw media data to a file in the report's media folder, creates the necessary database entries for LAVA, and returns a unique reference ID to be included in your artifact's data row.

Parameters

  • source_file: (string) The path of the file where the embedded media was found (e.g., a database file path).
  • data: (bytes) The raw byte content of the media file.
  • name: (string) An optional friendly name or description for the media.

When to use:

Use this function when your artifact discovers media content stored directly inside another file (like a database BLOB), rather than as a standalone file in the extraction.

Example:

from scripts.ilapfuncs import check_in_embedded_media, get_file_path

# Be sure to use the 'media' type in the column header for the media object
data_headers = ('Message', ('Attachment', 'media'))

# Assume 'db_row' is a record from a database with a BLOB column
media_data = db_row['attachment_blob'] # e.g., b'\xff\xd8\xff\xe0...'
media_name = db_row['attachment_filename'] # e.g., 'photo.jpg'
db_path = get_file_path(files_found, 'database.sqlite')

# check_in_embedded_media will return a media item for your data row
media_item = check_in_embedded_media(
    db_path,
    media_data,
    name=media_name
)

# Now add media_item to your data list
data_list.append((message, media_item))

Usage:

File and Path Utilities

sanitize_file_path(filename, replacement_char='')

Removes illegal characters from file paths (for Windows compatibility).

sanitize_file_name(filename, replacement_char='')

Removes illegal characters from file names (for Windows compatibility).

get_next_unused_name(path)

Returns a new file path if the given one already exists, appending -01, -02, etc.

get_file_path(files_found, filename, skip=False)

Finds and returns a file path from a list of found files, optionally skipping files containing a substring.

Text and Plist File Reading

get_txt_file_content(file_path)

Reads a text file and returns its content as a list of lines, handling common errors for you.

This function is safer than using Python’s built-in open() directly, because it will not crash your module if the file is missing or unreadable—it just returns an empty list and logs the error for you.

Parameter

  • file_path: (string) path to the local file on disk you wish to read

When to use:

  • Use this function for all times you need to read a plain text file (such as logs, CSVs, or configuration files) in your artifact module.

Example:

from scripts.ilapfuncs import get_txt_file_content

lines = get_txt_file_content('/path/to/somefile.txt')
for line in lines:
    print(line)

Usage:

get_plist_content(data)

Parses property list (plist) data from a bytes object, handling both standard and NSKeyedArchiver plists.
This function is safer than using plistlib.loads() directly, because it will not crash your module if the data is invalid or malformed—it just returns an empty dictionary and logs the error for you.

Parameter

  • data: (bytes) the raw plist data you want to parse (for example, data extracted from a SQLite database BLOB field or another binary source)

When to use:

-Use this function when you have plist data that is not stored as a standalone file, but instead is embedded inside another file or database (such as a BLOB column in SQLite, or a binary field in another format).
-If you have a path to a standalone plist file on disk, use get_plist_file_content(file_path) instead.

Example:

from scripts.ilapfuncs import get_plist_content

# Suppose you have extracted a BLOB from a SQLite database:
blob_data = some_sqlite_row['blob_column']
plist_data = get_plist_content(blob_data)
for key, val in plist_data.items():
    print(f'key: {key}; value: {val}')

Usage:

  • iCloudDriveSharedFiles in filesApp.py around like 343

get_plist_file_content(file_path)

Reads and parses a property list (plist) file from the local filesystem, handling both standard and NSKeyedArchiver plists.
This function is safer than using Python’s built-in open() and plistlib directly, because it will not crash your module if the file is missing, unreadable, or malformed—it just returns an empty dictionary and logs the error for you.

Parameter

  • file_path: (string) path to the local plist file on disk you wish to read

When to use:

  • Use this function whenever you need to read and parse a standalone plist file that exists on disk (for example, files ending in .plist found in iOS backups or app directories).
  • If you have plist data stored as a binary blob inside a database or another file (not as a standalone file), use get_plist_content(data) instead.

Example:

from scripts.ilapfuncs import get_plist_file_content

plist_data = get_plist_file_content('/path/to/somefile.plist')
for key, val in plist_data.items():
    print(f'key: {key}; value: {val}')

Usage:

SQLite Database Utilities

get_sqlite_db_path(path)

Returns a platform-correct SQLite DB path (handles Windows long paths).

open_sqlite_db_readonly(path)

Opens a SQLite DB in read-only mode, preserving original files.

attach_sqlite_db_readonly(path, db_name)

Returns an ATTACH statement for a SQLite DB in read-only mode.

get_sqlite_db_records(path, query, attach_query=None)

Executes a query and returns records from a SQLite DB.

get_sqlite_multiple_db_records(path_list, query, data_headers)

Executes a query across multiple SQLite DBs and aggregates results.

does_column_exist_in_db(path, table_name, col_name)

Checks if a column exists in a SQLite table.

does_table_exist_in_db(path, table_name)

Checks if a table exists in a SQLite DB.

does_view_exist_in_db(path, table_name)

Checks if a view exists in a SQLite DB.

Timestamp and Date Conversion

convert_unix_ts_in_seconds(ts)

Normalizes Unix timestamps to seconds.

convert_unix_ts_to_utc(ts)

Converts a Unix timestamp to UTC datetime.

convert_unix_ts_to_str(ts)

Converts a Unix timestamp to a formatted string.

convert_human_ts_to_utc(ts)

Converts a human-readable timestamp to UTC datetime.

convert_cocoa_core_data_ts_to_utc(cocoa_core_data_ts)

Converts Cocoa Core Data timestamps to UTC.

convert_log_ts_to_utc(str_dt)

Converts log-formatted timestamps to UTC.

convert_local_to_utc(local_timestamp_str)

Converts a local timestamp string with offset to UTC.

convert_time_obj_to_utc(ts)

Sets a datetime object to UTC.

convert_utc_human_to_timezone(utc_time, time_offset)

Converts a UTC datetime to a specified timezone.

convert_ts_int_to_timezone(time, time_offset)

Converts an integer timestamp to a specified timezone.

webkit_timestampsconv(webkittime)

Converts WebKit timestamps to UTC.

convert_ts_human_to_utc(ts)

Converts a human-readable timestamp to UTC.

convert_ts_int_to_utc(ts)

Converts an integer timestamp to UTC.

convert_unix_ts_to_timezone(ts, timezone_offset)

Converts a Unix timestamp to a specified timezone.

convert_ts_human_to_timezone_offset(ts, timezone_offset)

Converts a human-readable timestamp to a specified timezone.

convert_plist_date_to_timezone_offset(plist_date, timezone_offset)

Converts a plist date to a specified timezone.

convert_plist_date_to_utc(plist_date)

Converts a plist date to UTC.

get_birthdate(date)

Converts a Cocoa epoch date to a human-readable string.

Data Formatting and Conversion

convert_bytes_to_unit(size)

Converts a byte size to a human-readable string (e.g., KB, MB).

strings_raw(data)

Returns a string of printable characters from bytes, replacing non-printables with ..

strings(data)

Returns printable strings from bytes, similar to the Linux strings command.

generate_hexdump(data, char_per_row = 5)

Returns an HTML table of a hexdump of the data.

Miscellaneous Utilities

logfunc(message="")

Log messages to the HTML report and optionally to the GUI.

generate_thumbnail(imDirectory, imFilename, seeker, report_folder)

Generates or finds a thumbnail for an image and returns an HTML tag.

get_resolution_for_model_id(model_id: str)

Returns screen resolution info for a given iOS model ID.

Usage Notes

  • Always use these API functions for file access, data parsing, and conversions in your artifact modules.
  • This ensures consistent error handling and future compatibility as the iLEAPP core evolves.
  • If you need a utility not listed here, consider submitting a feature request or PR to extend the API.
Add a custom footer

iLEAPP Guide

Usage

Artifacts

Developers

Clone this wiki locally