mac_apt: a plugin framework for macOS and iOS forensic artifacts

A framework with plugins, not a case tool

mac_apt is a DFIR tool, a Digital Forensics and Incident Response tool, to process Mac computer full disk images or live machines and extract data and metadata useful for forensic investigation. It is a Python based framework which has plugins to process individual artifacts, such as Safari internet history, network interfaces and recently accessed files and volumes.

That word, framework, is the one that describes the architecture. The tool is a set of plugins, each of which knows how to find and parse one artifact family, and the framework deals with the image, the file system, the outputs and the reporting. The plugin count is the measure of the coverage, and it runs to several dozen.

The project also includes ios_apt, for processing iOS images, so the same framework covers the two Apple platforms rather than the macOS one only.

The homepage is swiftforensics.com, the tool is MIT licensed, the primary language is Python, the default branch is `master`, and the last push was on 2026-10-10. The recent releases are v1.36.2 from 2026-10-10, v1.33.2 from 2026-07-19 and v1.29.0 from 2026-02-11, so the numbering is a slow-moving line rather than a rapid one, which suits a tool that has to keep up with the operating system's own formats.

The repository layout follows the design. There is `mac_apt.py` as the main entry point, `ios_apt.py` for the mobile side, `mac_apt_artifact_only.py` and `mac_apt_mounted_sys_data.py` for the two narrower modes, `plugin.py` and a `plugins/` directory for the artefacts themselves, `extract_apfs_fs.py` for the file system layer, `version.py`, and then the packaging directories: `pyinstaller/`, `macos_installer/` and `other_dependencies/`.

The image formats, and the awkward ones

The feature list of supported inputs is where the difficulty of this kind of tool actually shows.

It works on E01, VMDK, AFF4, DD, split-DD, DMG with no compression, SPARSEIMAGE, UAC collections, Velociraptor collected files and mounted images. And in the latest section there are the awkward cases, each with a note about where it comes from.

A Velociraptor targeted collection zip, when created through the MacOS.Search.FileFinder artifact, and an Axiom created targeted collection zip. Sparse images created by RECON, FUJI and ASLA. UAC collections as ZIP, TAR and TAR.GZ. macOS Big Sur sealed volumes, which are 11.0. And encrypted APFS images, which can now be processed using a password or a recovery key.

Two of those deserve a note. The sealed volume support is the Big Sur change, where the system volume is cryptographically sealed and the layout differs, and the recovery key path is what makes an encrypted image processable at all rather than only decryptable with somebody present.

The other is the separately mounted SYSTEM and DATA volumes on macOS Catalina, 10.15 and later, which the README lists as supported. That is the split-volume layout, and a parser that reads only one of the two volumes misses half the disk, so a tool that handles both is doing more than it looks.

The last item in that list is the format people expect to be hardest, and the tool covers it. AFF4 images, including those created by Macquisition and DigitalCollector, are supported, which is what makes the tool usable with the acquisition tools that a case team is most likely to already have.

The plugin list is the product

The table of available plugins is long, and it is the most informative page in the repository, so it is worth sampling rather than reading exhaustively.

The browser and communication artefacts are the obvious ones: SAFARI for internet history, downloaded file information, cookies and more from the Safari caches, CHROMIUM for Edge, Chrome, Opera and the rest with history, top sites, downloads and extension information, FIREFOX for Mozilla history, IMESSAGE for chats, and COOKIES for the binary cookie files and the HSTS plist. CFURLCACHE reads the URL cache to URLs, requests and responses.

The system and user artefacts are where the forensic value usually is. USERS gives local and domain user information, name, UID, UUID, GID, account creation and password set dates, password hints, home directory and Darwin paths. KEYCHAINS reads the system keychain and decrypts stored passwords, which is a capability rather than a feature. TCC reads the Transparency, Consent and Control database, which is where the permissions a user granted live. XPROTECT reads the XProtect diagnostic files and the XProtect Behavior Service database, so the tool covers both the platform's own security telemetry and its logs.

The activity artefacts are the third group: ASL for the Apple System Log from asl.log, asl.db and the .asl files, FSEVENTS for the file system event logs, SPOTLIGHT and SPOTLIGHTSHORTCUTS for the index databases and for what the user typed in the Spotlight bar, SCREENTIME for the ScreenTime database, RECENTITEMS for recently accessed servers, documents, hosts, volumes and applications, and TRASH for deleted file and folder metadata out of the .DS_Store files.

And there are the small, telling ones. AUTOSTART retrieves the programs, daemons and services set to start at boot or login, which is how a persistence mechanism is found. TERMINALSTATE reads the Terminal saved state files, which include the full text content of terminal windows, and TERMSESSIONS reads the bash and zsh history and sessions for every user. SUDOLASTRUN gets the last time sudo was used. INSTALLHISTORY is the software installation history, and CALCULATOR reads the calculator history.

Outputs, and the boundary between parsing and analysis

The tool produces XLSX, CSV, TSV, JSONL and SQLite outputs, and the analysed files and artefacts are exported for later review.

That last clause is the important one. The output of mac_apt is a set of extracted records and the files themselves, and the analysis is somebody else's job. A plugin that reads the keychain hands you decrypted passwords; deciding whether the presence of a keychain entry is evidence of anything is the analyst's work, and the design keeps the two apart.

The SQLite output is the one that changes how the tool is used. A case with a hundred plugins produces a hundred tables of extracted records, and a relational output means they can be joined with SQL rather than with a spreadsheet per artefact, which is what turns a pile of extractions into a timeline.

Two more capabilities are worth naming. The compressed file support covers zlib, lzvn and lzfse, which matters because on a modern volume a large share of the interesting files are inside compression containers. And there is a native HFS and APFS parser rather than a dependency on the host operating system to mount the volume, which is what makes the tool cross platform.

The Spotlights database is read directly as well, and the tool is described as having no dependency on pyobjc, which is a deliberate portability decision: pyobjc would tie the tool to macOS and to a specific interpreter build, and the tool is tested on Windows and macOS on both ARM and x64, up to Python 3.14.

The FAST mode is the other thing a user will notice, since it trades completeness for speed on a large image.

How it is put together, and the dependency wall

The requirements file is the place where the real engineering of this project is visible, because the list is a list of file system parsers and format libraries rather than of convenience packages.

construct==2.10.70
libewf-python
libvmdk-python
pytsk3==20230125
pyliblzfse
pycryptodome
cryptography
kaitaistruct
biplist
plistutils

`libewf-python` and `libvmdk-python` are the E01 and VMDK readers, `pytsk3` is the file system forensics library, `pyliblzfse` handles the Apple compression format, `pycryptodome` and `cryptography` do the cryptography, `kaitaistruct` and `construct` are the binary parsing libraries, and `biplist` and `plistutils` read the plists that so much of macOS stores its state in. The last line is a local build, a zip of a patched AFF4 library, which tells you that the public package did not do what the tool needed and a fork was vendored in.

That vendored dependency is the pattern the `Dockerfile` follows as well. It starts from `python:3.9`, installs a pinned list of packages with versions that are older than the ones in the requirements file, then builds libewf from a source tarball and installs the same patched AFF4 zip from a URL.

So the container and the requirements file disagree about versions, and the container is older. That is a maintenance smell, and it is the kind of thing to raise with the maintainer, because a container that lags the documented Python requirement is a container that behaves differently from a local install.

The packaging side is handled by three directories: `pyinstaller/` for the standalone binaries, `macos_installer/` for the macOS package, and `other_dependencies/` for the vendored libraries.

One plugin removed, and the reason is the whole point

One entry in the plugin table is struck through, and its note is the most useful thing in the list.

The unified logs plugin, which read the macOS unified logging logs from .tracev3 files, is removed, because better options are available. The note says that processing unified logs in Python is slow and takes a very long time, and that a much faster Rust-based alternative exists, so please use that instead.

A tool that removes a feature is making a statement about scope, and here the statement is about implementation language rather than about capability. The unified log is a valuable forensic source and it is not going away, but the tool that reads it now has to be written in Rust to be usable at scale, and the author would rather point at that tool than maintain a slow Python version of it.

The plugin that replaces the role is still there in a different form, as UNIFIEDLOGEXPORT, which exports the unified logs and associated files for external processing. So the capability is preserved by moving the processing out of the framework, which is a different design decision from dropping the feature.

It is worth reading that note as a statement about the project. The tool keeps growing its coverage, and it prunes the parts where its implementation language is the wrong tool, and it says so in the table rather than in a changelog.

Where mac_apt is the wrong tool

The limits are the ones that come from choosing a parsing framework over a case platform, and they are worth being precise about.

The first is that mac_apt does not analyse. It extracts records, and the SQLite output is a set of tables that a human or a script has to query. There is no timeline reconstruction, no artefact correlation, no link chart and no narrative. For an analyst who wants the extractions, that is exactly right, and for a team that wants a case tool it is a large gap.

The second is coverage versus specialism. The plugins cover the artefacts that a general macOS case involves, and a specialist source of truth for one artefact, say the keychain or the unified log, will do that artefact better. The tool is a breadth tool, and the README is honest about the cost of that in the removed plugin.

The third is that this is a tool for reading other people's images, and it carries the obligations that implies. The keychain plugin decrypts stored passwords, the imessage plugin reads chats, and the tool is therefore something that has to be kept out of reach of people who should not see the data it extracts, which is a property of how you deploy it rather than of the code.

The alternative, for a team that needs the whole case workflow, is a commercial forensics suite with timeline and reporting built in, and the difference in approach is that mac_apt is a set of parsers you can read, patch and script against, while a suite is a product you configure. For a team that already knows exactly which artefacts it needs and wants them extracted quickly and reproducibly, the open framework is often the better tool, and for a team that needs a case file at the end of the week it usually is not.

Editorial conclusion

mac_apt fits a forensic analyst who has an image and a list of artifacts to read, who wants the parsing written once and applied consistently across a case, and who is comfortable with Python. It is the wrong tool for a team that needs a full case management and timeline product, because the framework parses and exports and leaves the analysis and the narrative to the analyst, and it is the wrong tool for a workflow built on the unified log, since the author removed that plugin in favour of a faster Rust implementation. Before relying on it, check the pinned versions in `requirements.txt` against the images you have to read, and treat the output as evidence to be verified rather than as a finding, since a parser that reads a field correctly is not the same as a conclusion about what the field means.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. ydkhatri/mac_apt on GitHub