百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
A

apple_cloud_notes_parser

> 编程语言
开源

解析器,用于在 Apple 手持设备上显示的云端存储的 Apple 笔记数据

537 stars0 点赞4 次浏览
访问官网GitHub

工具介绍

解析器,用于在 Apple 手持设备上显示的云端存储的 Apple 笔记数据

Apple Cloud Notes Parser

By: Jon Baumann, Ciofeca Forensics

About

This program is a parser for the current version of Apple Notes data syncable with iCloud as seen on Apple handsets in iOS 9 and later. This program is needed because Apple Notes data is stored in a series of protobufs and tables in the database and it is not always easy to piece them back together by hand. This program intends to make it easy for Apple users to backup Apple Notes of their own and to expose as much of the Apple Notes information as possible for forensic examiners.

This program was implemented in Ruby and currently requires Ruby 3.0 or newer.

Features

This program will:

  1. Parse legacy (pre-iOS9) Notes files (but those are already plaintext, so not much to be gained)
  2. Parse iOS 9-26 Cloud Notes files
  3. ... decrypting notes if the password is known and the device passcode is not used
  4. ... generating CSV roll-ups of each account, folder, note, and embedded object within them
  5. ... rebuilding the notes as an HTML file to browse and see as they would be displayed on the phone
  6. ... amending the NoteStore.sqlite database to include plaintext and decompressed objects to interact with in other tools
  7. ... from iTunes logical backups, physical backups, single files, and directly from Mac versions
  8. ... displaying tables as actual tables and ripping the embedded images from the backup and putting them into a folder with the other output files for review
  9. ... identifying the CloudKit participants involved in any shared items.
  10. ... producing well-structured JSON for automated backups
  11. ... actually run tests against its output after 5 years of YOLO.

Usage

Base

This program is run by Ruby on a command line, using either rake or ruby. The easiest use is to drop your exported NoteStore.sqlite into the same directory as this program and then run rake:

…

If you are more comfortable with the command line, you can point the program anywhere you would like on your computer and specify the type of backup you are looking at, see the Options section below for specifics.
The benefit of pointing at full backups is this program can pull embedded files out of the notes, such as drawings and pictures.

Options

The options that are currently supported are:

Short Switch Long Switch Purpose
-i --itunes-dir DIRECTORY Root directory of an iTunes backup folder (i.e. where Manifest.db is). These normally have hashed filenames.
-f --file FILE Single NoteStore.sqlite file.
-g --one-output-folder Always write to the same output folder.
-p --physical DIRECTORY Root directory of a physical backup (i.e. right above /private).
-m --mac DIRECTORY Root directory of a Mac application (i.e. /Users/{username}/Library/Group Containers/group.com.apple.notes).
-o --output-dir DIRECTORY Change the output directory from the default ./output
-w --password-file FILE File with plaintext passwords, one per line.
-r --retain-display-order Retain the display order for folders and notes, not the database's order.
--manual-password Enter a password from the command prompt, without having to use a file on disk.
--show-password-successes Toggle the display of password success ON.
--range-start DATE Set the start date of the date range to extract. Must use YYYY-MM-DD format, defaults to 1970-01-01.
--range-end DATE Set the end date of the date range to extract. Must use YYYY-MM-DD format, defaults to 2024-08-09.
--individual-files Output individual HTML files for each note, organized in folders mirroring the Notes folder structure.
--uuid Use UUIDs in HTML output rather than local database IDs.
-h --help Print help information

Docker

Thanks to @jareware, if you have Docker installed already you can run this program as a docker container. This is a great way to ensure you will not run into any dependancy issues or have to have Ruby installed. Shell scripts have been provided in the docker_scripts folder to cover the most common use cases. Each of these uses the present working directory to create the output folder.

Script Purpose
linux_run_file.sh This script will run the program on a NoteStore.sqlite file found in the present working directory (as if you ran --file NoteStore.sqlite).
mac_run_file.sh This script will run the program on a NoteStore.sqlite file found in the present working directory (as if you ran --file NoteStore.sqlite).
mac_run_itunes.sh This script will run the program on the local user's Mobile Backups(as if you used --itunes ~/Library/Application\ Support/MobileSync/Backup/[your backup]).
mac_run_notes.sh This script will run the program on the local user's Apple Notes directory (as if you used --mac ~/Library/Group\ Containers/group.com.apple.notes).

If you are more experienced with Docker, you can use the base image with any of the below options the same as if you ran the program with Ruby. The basic command to use would be:

bash
docker run --rm \
  -v [path to your data folder or file]:/data:ro \
  -v $(pwd)/output:/app/output \
  ghcr.io/threeplanetssoftware/apple_cloud_notes_parser \
  [your command line options]

As an example, to run a NoteStore.sqlite file that is in your current directory you would type:

bash
docker run --rm \
  -v "$(pwd)":/data:ro \
  -v "$(pwd)"/output:/app/output \
  ghcr.io/threeplanetssoftware/apple_cloud_notes_parser \
  --file /data/NoteStore.sqlite --one-output-folder

Important Caveats:

  • While Docker can make things easier in some respects, it does so at the cost of additional complexity. It is harder to troubleshoot and adds more memory overhead. It is my hope that the Docker image helps some use this program, but the first troubleshooting step that will be recommended is to use Ruby directly to see if that fixes the issue.
  • The base image that is used for the Docker container is published by Ruby. It relies on a Debian base layer and as of today has multiple "vulnerabilities" identified on Docker (i.e. packages that are out of date). Use the Docker container at your own risk and if you are uncomfortable with it, feel free to clone this repository and use Ruby to run it, instead.
  • MacOS permissions lead to read errors trying to mount the Notes and iTunes backups from elsewhere in the user's home folder. As a result, the shell scripts create a temporary folder in the present working directory and copy the relevant files into it. This is an ugly hack which will chew up extra disk space and time to perform the copy. If you dislike this tradeoff, feel free to clone this repository and use Ruby to run it, instead.

How It Works

iTunes backup (-i option)

For backups created with iTunes MobileSync, that include a wide range of hashed files inside of folders named after the filename, this program expects to be given the root folder of that backup. With that, it will compute the path to the NoteStore.sqlite file. If it exists, that file will be copied to the output directory and the copy, not the original, will be opened.

For example, if you had an iTunes backup located in /home/user/phone_rips/iphone/[deviceid]/ (Which means the Manifest.db is located at /home/whatever/phone_rips/iphone/[deviceid]/Manifest.db) you would run

bash
ruby notes_cloud_ripper.rb -i /home/user/phone_rips/iphone/[deviceid]/

Physical backup (-p option)

For backups created with a full file system (or at least the /private directory) from your tool of choice. This program expects to be given the root folder of that backup. With that, it will compute the path to the NoteStore.sqlite file. If it exists, that file will be copied to the output directory and the copy, not the original, will be opened.

For example, if you had a physical backup located in /home/user/phone_rips/iphone/physical/ (Which means the phone's /private directory is located at /home/whatever/phone_rips/iphone/physical/private/) you would run:

bash
ruby notes_cloud_ripper.rb -p /home/user/phone_rips/iphone/physical

Single File (-f option)

For single file "backups", this program expects to be given the path of the NoteStore.sqlite file directly, although filename does not matter. If it exists, that file will be copied to the output directory and the copy, not the original, will be opened.

For example, if you had a NoteStore.sqlite file located in /home/user/phone_rips/iphone/files/NoteStore.sqlite you would run:

bash
ruby notes_cloud_ripper.rb -f /home/user/phone_rips/iphone/files/NoteStore.sqlite

Mac backup (-m option)

For backups created from the Notes app as installed on a Mac. This program expects to be given the group.com.apple.notes folder of that Mac. With that, it will compute the path to the NoteStore.sqlite file. If it exists, that file will be copied to the output directory and the copy, not the original, will be opened.

For example, if you were running this on data from a Mac used by 'Logitech' and had the full file system available, you would run:

bash
ruby notes_cloud_ripper.rb -m /Users/Logitech/Library/Group Containers/group.com.apple.notes/

Password (-w | --password-file FILE option)

For backups that may have encrypted notes within them, this option tells the program where to find its password list. This list should have one password per row and any passwords that correctly decrypt an encrypted note will be tried before the rest for future encrypted notes.

For example, if you were running this on data from a Mac used by 'Logitech,' had the full file system available, and wanted to use a file called "passwords.txt" you would run:

bash
ruby notes_cloud_ripper.rb -m /Users/Logitech/Library/Group Containers/group.com.apple.notes/ -w passwords.txt

Note: As of March 2021, all logging of passwords to the local debug_log.txt file and HTML output has been removed. If you need to see which passwords generated decrypted notes, use the --show-password-successes switch and read the console output after the run.

Note: As of iOS 16, users can use their device passcode instead of a spearate password within Notes. This program does not yet handle that case, it will simply fail to decrypt.

Date Range Extraction

Note: This feature is not intended to be robust. It does not smartly handle differences in timezones, nor convert to UTC. It is purely intended to help those with large Notes databases to better whittle down how much is processed.

The --range-start and --range-end switches allow the user to specify starting and ending dates for which notes to extract. By default, these will cover "all time" (i.e. 1970 through to tomorrow) so all notes should match, assuming system time hasn't been messed with. Officially these switches request the date format in "YYYY-MM-DD" format, but technically as long as Time.parse() can understand the format, it should work.

These selections are made on the ZICCLOUDSYNCINGOBJECT.ZMODIFIEDDATE1 field, which will capture any notes that have a modified date in that range. For example, if you wanted all notes modified after December 1, 2022, or all the notes modified in the month of June 2022, you could run:

bash
# All notes modified after December 1, 2022
ruby notes_cloud_ripper.rb -f NoteStore.sqlite --range-start "2022-12-01"

# All notes modified in the month of June 2022
ruby notes_cloud_ripper.rb -f NoteStore.sqlite --range-start "2022-06-01" --range-end "2022-07-01"

If you ever need to know what dates were used for a given backup, you can check the debug_log.txt file by looking for the line that has "Rip Notes" in it. For e

Issues· 0 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

Ruby

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月17日
分类编程语言
定价开源

> 相关工具

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言