Skip to content

Added KeychainsItems Support for MacOS - #88

Open
Gear-I wants to merge 1 commit into
abrignoni:mainfrom
Gear-I:Keychains
Open

Added KeychainsItems Support for MacOS#88
Gear-I wants to merge 1 commit into
abrignoni:mainfrom
Gear-I:Keychains

Conversation

@Gear-I

@Gear-I Gear-I commented Aug 23, 2026

Copy link
Copy Markdown

Summary

  • Adds `scripts/artifacts/keychains.py`, three new artifacts under category "Keychains (macOS)": Generic Passwords and Internet Passwords (classic `*.keychain-db` format), and Local Items (`keychain-2.db`, the modern per-user SQLite-backed keychain).

What it recovers

  • Item metadata only: creation/modification time, label, account, service/server, protocol/port/path, access group, comment. The password/secret itself is never decrypted -- flagged present/size instead, since decrypting the classic format needs the user's login password and the local items format is Secure Enclave-protected.
  • A hand-written parser for Apple's undocumented 'kych' binary format, since `keychain-db` isn't SQLite. Checked byte-for-byte against a real macOS Big Sur test image (Josh Hickman / thisisdfir, acquired 2021-02-20) using chainbreaker as an independent reference parser -- every field matched exactly across all 16 real generic password records recovered.
  • A validated SHA-1 dictionary match for keychain-2.db's hashed acct/svce/labl columns: candidates are pulled only from other evidence already present in the same extraction (access-group names, plaintext values recovered from the classic keychain files), so every resolved value is traceable back to real evidence in the case rather than an external wordlist. Resolved 128 of 327 local-items rows on the validation image, including confirming the account's real Apple ID on several iCloud-related items.

Code was Co-Authored by Claude Sonnet 5

@abrignoni

Copy link
Copy Markdown
Owner

Thanks for the contribution!

This PR changes artifact modules without test data for them. A small fixture with each artifact change lets reviewers run the module against real data, and the committed case keeps guarding the module after merge.

  • Keychains.py: please include a fixture with this PR.

Adding a fixture

Generate it from your extraction with the helper (details in create_module_test_cases.md):

python admin/test/scripts/make_case_data.py <module> --case <case_number> --input <extraction.zip>

It writes admin/test/cases/testdata.<module>.json and one zip per artifact under admin/test/cases/data/<module>/.

Size rules:

  • Under 10 MB per zip: commit the files in this PR.
  • 10 to 25 MB: commit the case JSON in the PR and attach the zip to a comment here.
  • Over 25 MB: say so here and a maintainer will arrange a handoff.

If your extraction cannot be shared:

  • If the app appears on a public research image, generate the fixture from that instead. public_corpus_images.md lists the images and where to download them.
  • Or sanitize the real file in place: keep the file the app wrote and overwrite only the personal values, which keeps the format honest.
  • Or script a known session: install the app on a test device with a throwaway account, perform documented actions, and extract that.

If none of those fit, say so here and we will work it out. The PR can still be reviewed and merged with the gap recorded in the artifact's notes.

This is a request, not a gate. Nothing here blocks review.

@abrignoni abrignoni added the needs-test-data Artifact PR without test data for the changed modules label Aug 25, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

needs-test-data Artifact PR without test data for the changed modules

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants