How cclgroupltd/ccl_chromium_reader works
Project type and purpose
• This is an open-source Python library and toolkit (“ccl_chromium_reader”) for forensic extraction of data from Chromium/Chrome profile folders.
• It provides modular readers (cache, history, IndexedDB, LocalStorage, etc.), serialization/deserialization of on-disk formats, a high-level Facade (ChromiumProfileFolder), and several CLI/utility scripts.
File structure
• Top-level package: ccl_chromium_reader/
• Modules for each data store:
– ccl_chromium_cache.py (Cache API)
– ccl_chromium_filesystem.py (FileSystem API)
– ccl_chromium_history.py (History)
– ccl_chromium_indexeddb.py (IndexedDB)
– ccl_chromium_localstorage.py (Local Storage)
– ccl_chromium_sessionstorage.py (Session Storage)
– ccl_chromium_notifications.py, ccl_chromium_snss2.py, downloads, common utilities
• Subpackage serialization_formats/ handles object deserialization (Pickle, Protobuf, V8, Blink).
• Subpackage storage_formats/ wraps on-disk databases (LevelDB).
• profile_folder_protocols.py and ccl_chromium_profile_folder.py implement the Facade and common protocols.
• tools_and_utilities/ folder: CLI scripts that invoke the library (dumpers and the audit tool).
• Project config: pyproject.toml, requirements.txt.
Extract insights from README
• Core façade: ChromiumProfileFolder lazily loads each data store.
• Two APIs per module: raw and wrapper API.
• CLI tools reuse modules for automated data dumps and audits.
• Dependencies are minimal (Python 3.10, optional Brotli).
a. Main Components
• External: Chromium Profile Folder (file system containing SQLite, LevelDB, cache, blobs)
• Data-Access Layer
– FileSystem API
– LevelDB wrapper (storage_formats)
– Shared-Proto-DB reads (downloads)
• Serialization Layer (serialization_formats)
– Protobuf, Pickle, V8, Blink deserializers
• Core Domain
– Individual store readers (cache, history, Local/Session Storage, notifications, SNSS)
– Common utilities (common.py, download_common.py)
• Facade Layer
– ChromiumProfileFolder (unified API, KeySearch)
• CLI/Tools Layer (tools_and_utilities)
– Scripts (dumpers, ccl_chrome_audit.py, benchmark)
b. Relationships and Data Flow
1. CLI script invokes Facade or individual store reader.
2. Facade calls the appropriate store reader module.
3. Store reader uses Data-Access Layer to read raw files/LevelDB stubs.
4. Serialization Layer decodes raw bytes into Python objects.
5. Data objects are wrapped in domain classes and returned to CLI or user code.
6. CLI writes output (console, CSV, files).
c. Architectural patterns and principles
• Layered architecture (Data-Access → Serialization → Domain → Facade → Presentation)
• Facade pattern (ChromiumProfileFolder unifies multiple modules)
• Adapter pattern (wrapping LevelDB, block-file cache)
• Separation of concerns: each module handles one store or one format.
d. Key technologies
• Python 3.10
• LevelDB (via direct file parsing)
• Protocol Buffers
• Chrome’s Pickle, V8, Blink serialization formats
• Standard library + optional Brotli
Details
• Clear labels on every component (package or script name).
• Chromium Profile Folder at the bottom as the physical data source.
• Facade methods (e.g., iter_local_storage(), iterate_history_records()).