browsermem 0.1.0__py3-none-win_amd64.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,258 @@
1
+ """Offline / volatile-memory forensics.
2
+
3
+ A :class:`MemoryImage` is a set of ``(base_address, bytes)`` regions. Build one
4
+ from a live process, a Windows minidump, or any acquisition you can turn into
5
+ regions, then list the URLs in it or resolve the URL that belongs to a tab
6
+ title -- no running browser needed::
7
+
8
+ from browsermem.forensics import MemoryImage, write_minidump
9
+
10
+ write_minidump(pid, "chrome.dmp") # acquire
11
+ with MemoryImage.from_minidump("chrome.dmp") as image:
12
+ image.urls()[:20] # most frequent URLs
13
+ image.resolve("Inbox - Gmail").url # URL for a known tab title
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ import contextlib
19
+ import ctypes
20
+ import mmap
21
+ import os
22
+ import struct
23
+ from ctypes import POINTER, byref, c_uint32, c_uint64, c_void_p, wintypes
24
+ from typing import Iterable, Iterator, List, Optional, Tuple, Union
25
+
26
+ from ._native import bm_tab, bm_url_entry, lib
27
+ from .api import _url_list
28
+ from .errors import AccessDeniedError, BrowserMemError, check
29
+ from .models import Browser, Tab, UrlCount, _tab_from_native
30
+
31
+ PathLike = Union[str, "os.PathLike[str]"]
32
+
33
+ __all__ = ["MemoryImage", "read_minidump_regions", "write_minidump"]
34
+
35
+
36
+ class MemoryImage:
37
+ """A captured or reconstructed process memory image."""
38
+
39
+ def __init__(self) -> None:
40
+ """Create an empty image; add memory with :meth:`add_region`."""
41
+ self._handle = c_void_p()
42
+ check(lib.bm_image_create(byref(self._handle)))
43
+
44
+ # -- construction -----------------------------------------------------------
45
+
46
+ @classmethod
47
+ def capture(cls, pid: int = 0) -> MemoryImage:
48
+ """Copy the private read/write memory of a running process.
49
+
50
+ ``pid=0`` picks the most recently active browser.
51
+ """
52
+ image = cls.__new__(cls)
53
+ image._handle = c_void_p()
54
+ check(lib.bm_image_capture(pid, byref(image._handle)))
55
+ return image
56
+
57
+ @classmethod
58
+ def from_regions(cls, regions: Iterable[Tuple[int, bytes]]) -> MemoryImage:
59
+ """Build an image from ``(base_address, data)`` pairs."""
60
+ image = cls()
61
+ for base, data in regions:
62
+ image.add_region(base, data)
63
+ return image
64
+
65
+ @classmethod
66
+ def from_minidump(cls, path: PathLike, *, private_only: bool = True) -> MemoryImage:
67
+ """Load a Windows minidump (.dmp), e.g. from Task Manager → *Create dump file*,
68
+ ProcDump, or :func:`write_minidump`. Needs a full-memory dump.
69
+
70
+ With ``private_only`` (default) only private, writable memory is loaded when
71
+ the dump records region types -- the same memory a live capture reads.
72
+ """
73
+ return cls.from_regions(read_minidump_regions(path, private_only=private_only))
74
+
75
+ def add_region(self, base: int, data: Union[bytes, bytearray, memoryview]) -> None:
76
+ """Add one memory region (copied). Regions must not overlap."""
77
+ self._require_open()
78
+ buf = (ctypes.c_char * len(data)).from_buffer_copy(data) if len(data) else None
79
+ check(lib.bm_image_add_region(self._handle, base, buf, len(data)))
80
+
81
+ # -- analysis ---------------------------------------------------------------
82
+
83
+ @property
84
+ def total_bytes(self) -> int:
85
+ total, _ = self._info()
86
+ return total
87
+
88
+ @property
89
+ def region_count(self) -> int:
90
+ _, regions = self._info()
91
+ return regions
92
+
93
+ def urls(self) -> List[UrlCount]:
94
+ """Every URL string in the image, most frequent first."""
95
+ self._require_open()
96
+ arr = POINTER(bm_url_entry)()
97
+ count = c_uint32()
98
+ check(lib.bm_image_urls(self._handle, byref(arr), byref(count)))
99
+ return _url_list(arr, count.value)
100
+
101
+ def resolve(self, title: str, browser: Optional[Union[Browser, str]] = None) -> Tab:
102
+ """URL of the tab whose title is ``title``.
103
+
104
+ If ``browser`` is given, ``title`` may also be a full window caption
105
+ (``"Inbox - Gmail - Google Chrome"``). Check ``tab.resolved``.
106
+ """
107
+ self._require_open()
108
+ b = int(Browser.parse(browser)) if browser is not None else 0
109
+ ptr = POINTER(bm_tab)()
110
+ check(lib.bm_image_resolve(self._handle, title.encode("utf-8"), b, byref(ptr)))
111
+ try:
112
+ return _tab_from_native(ptr.contents)
113
+ finally:
114
+ lib.bm_tab_free(ptr)
115
+
116
+ # -- lifecycle --------------------------------------------------------------
117
+
118
+ def close(self) -> None:
119
+ if self._handle:
120
+ lib.bm_image_free(self._handle)
121
+ self._handle = c_void_p()
122
+
123
+ def __enter__(self) -> MemoryImage:
124
+ return self
125
+
126
+ def __exit__(self, *exc: object) -> None:
127
+ self.close()
128
+
129
+ def __del__(self) -> None:
130
+ with contextlib.suppress(Exception):
131
+ self.close()
132
+
133
+ def __repr__(self) -> str:
134
+ if not self._handle:
135
+ return "<MemoryImage closed>"
136
+ total, regions = self._info()
137
+ return f"<MemoryImage {regions} regions, {total / 1048576:.1f} MiB>"
138
+
139
+ def _info(self) -> Tuple[int, int]:
140
+ self._require_open()
141
+ total, regions = c_uint64(), c_uint32()
142
+ check(lib.bm_image_info(self._handle, byref(total), byref(regions)))
143
+ return total.value, regions.value
144
+
145
+ def _require_open(self) -> None:
146
+ if not self._handle:
147
+ raise BrowserMemError("MemoryImage is closed")
148
+
149
+
150
+ # ---- minidump reading -------------------------------------------------------------
151
+
152
+ _MEMORY_LIST = 5
153
+ _MEMORY64_LIST = 9
154
+ _MEMORY_INFO_LIST = 16
155
+ _MEM_COMMIT = 0x1000
156
+ _MEM_PRIVATE = 0x20000
157
+ _WRITABLE = 0x04 | 0x08 | 0x40 | 0x80 # RW, WRITECOPY, EXECUTE_RW, EXECUTE_WRITECOPY
158
+ _GUARD_OR_NOACCESS = 0x100 | 0x01
159
+
160
+
161
+ def read_minidump_regions(path: PathLike, *, private_only: bool = True) -> Iterator[
162
+ Tuple[int, bytes]
163
+ ]:
164
+ """Yield ``(base_address, data)`` for the memory ranges stored in a minidump."""
165
+ with open(path, "rb") as f, mmap.mmap(f.fileno(), 0, access=mmap.ACCESS_READ) as m:
166
+ if m[:4] != b"MDMP":
167
+ raise BrowserMemError(f"{os.fspath(path)!r} is not a minidump")
168
+ n_streams, dir_rva = struct.unpack_from("<II", m, 8)
169
+ streams = {}
170
+ for i in range(n_streams):
171
+ stype, size, rva = struct.unpack_from("<III", m, dir_rva + 12 * i)
172
+ streams[stype] = (rva, size)
173
+
174
+ allowed = _private_writable_ranges(m, streams) if private_only else None
175
+
176
+ def keep(base: int, size: int) -> bool:
177
+ if allowed is None:
178
+ return True
179
+ return any(lo <= base < hi for lo, hi in allowed)
180
+
181
+ if _MEMORY64_LIST in streams:
182
+ rva, _ = streams[_MEMORY64_LIST]
183
+ count, data_rva = struct.unpack_from("<QQ", m, rva)
184
+ offset = data_rva
185
+ for i in range(count):
186
+ base, size = struct.unpack_from("<QQ", m, rva + 16 + 16 * i)
187
+ if keep(base, size):
188
+ yield base, m[offset:offset + size]
189
+ offset += size
190
+ elif _MEMORY_LIST in streams:
191
+ rva, _ = streams[_MEMORY_LIST]
192
+ (count,) = struct.unpack_from("<I", m, rva)
193
+ for i in range(count):
194
+ base, size, data_rva = struct.unpack_from("<QII", m, rva + 4 + 16 * i)
195
+ if keep(base, size):
196
+ yield base, m[data_rva:data_rva + size]
197
+ else:
198
+ raise BrowserMemError("minidump contains no memory (create a full-memory dump)")
199
+
200
+
201
+ def _private_writable_ranges(m: mmap.mmap, streams: dict) -> Optional[List[Tuple[int, int]]]:
202
+ if _MEMORY_INFO_LIST not in streams:
203
+ return None # region types unknown: keep everything
204
+ rva, _ = streams[_MEMORY_INFO_LIST]
205
+ header_size, entry_size, count = struct.unpack_from("<IIQ", m, rva)
206
+ ranges = []
207
+ for i in range(count):
208
+ base, _alloc, _aprot, _pad, size, state, protect, mtype = struct.unpack_from(
209
+ "<QQIIQIII", m, rva + header_size + entry_size * i
210
+ )
211
+ if (state == _MEM_COMMIT and mtype == _MEM_PRIVATE and protect & _WRITABLE
212
+ and not protect & _GUARD_OR_NOACCESS):
213
+ ranges.append((base, base + size))
214
+ ranges.sort()
215
+ return ranges
216
+
217
+
218
+ # ---- minidump writing -------------------------------------------------------------
219
+
220
+ _PROCESS_QUERY_INFORMATION = 0x0400
221
+ _PROCESS_VM_READ = 0x0010
222
+ _MiniDumpWithFullMemory = 0x00000002
223
+ _MiniDumpWithFullMemoryInfo = 0x00000800
224
+
225
+
226
+ def write_minidump(pid: int, path: PathLike) -> None:
227
+ """Write a full-memory minidump of a running process (like Task Manager's
228
+ *Create dump file*), for later analysis with :meth:`MemoryImage.from_minidump`."""
229
+ import msvcrt
230
+
231
+ kernel32 = ctypes.WinDLL("kernel32", use_last_error=True)
232
+ dbghelp = ctypes.WinDLL("dbghelp", use_last_error=True)
233
+ kernel32.OpenProcess.restype = wintypes.HANDLE
234
+ kernel32.OpenProcess.argtypes = [wintypes.DWORD, wintypes.BOOL, wintypes.DWORD]
235
+ kernel32.CloseHandle.argtypes = [wintypes.HANDLE]
236
+ dbghelp.MiniDumpWriteDump.restype = wintypes.BOOL
237
+ dbghelp.MiniDumpWriteDump.argtypes = [wintypes.HANDLE, wintypes.DWORD, wintypes.HANDLE,
238
+ wintypes.DWORD, c_void_p, c_void_p, c_void_p]
239
+
240
+ process = kernel32.OpenProcess(_PROCESS_QUERY_INFORMATION | _PROCESS_VM_READ, False, pid)
241
+ if not process:
242
+ raise AccessDeniedError(f"OpenProcess({pid}) failed, Win32 error {ctypes.get_last_error()}")
243
+ try:
244
+ with open(path, "wb") as f:
245
+ ok = dbghelp.MiniDumpWriteDump(
246
+ process, pid, msvcrt.get_osfhandle(f.fileno()),
247
+ _MiniDumpWithFullMemory | _MiniDumpWithFullMemoryInfo, None, None, None,
248
+ )
249
+ if not ok:
250
+ raise AccessDeniedError(
251
+ f"MiniDumpWriteDump failed, Win32 error {ctypes.get_last_error()}"
252
+ )
253
+ except BaseException:
254
+ with contextlib.suppress(OSError):
255
+ os.remove(path)
256
+ raise
257
+ finally:
258
+ kernel32.CloseHandle(process)
browsermem/history.py ADDED
@@ -0,0 +1,122 @@
1
+ """Browsing timeline built from live tab events."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import threading
6
+ from collections import defaultdict
7
+ from dataclasses import dataclass
8
+ from datetime import datetime, timedelta
9
+ from typing import Any, Dict, List, Optional
10
+
11
+ from .models import EventKind, Tab
12
+ from .monitor import TabMonitor
13
+
14
+
15
+ @dataclass
16
+ class Visit:
17
+ """A stretch of time during which one URL was the active tab of a window."""
18
+
19
+ tab: Tab
20
+ started: datetime
21
+ ended: Optional[datetime] = None
22
+
23
+ @property
24
+ def url(self) -> Optional[str]:
25
+ return self.tab.url
26
+
27
+ @property
28
+ def duration(self) -> timedelta:
29
+ """Time on the page so far (or in total, once the visit has ended)."""
30
+ return (self.ended or datetime.now()) - self.started
31
+
32
+ def to_dict(self) -> Dict[str, Any]:
33
+ return {
34
+ "url": self.url,
35
+ "title": self.tab.title,
36
+ "domain": self.tab.domain,
37
+ "browser": self.tab.browser.name.lower(),
38
+ "started": self.started.isoformat(timespec="seconds"),
39
+ "ended": self.ended.isoformat(timespec="seconds") if self.ended else None,
40
+ "seconds": round(self.duration.total_seconds(), 1),
41
+ }
42
+
43
+
44
+ class TabHistory:
45
+ """Records which URL was active, when, and for how long::
46
+
47
+ monitor = TabMonitor()
48
+ history = TabHistory(monitor)
49
+ monitor.start()
50
+ ...
51
+ for domain, spent in history.time_by_domain().items():
52
+ print(domain, spent)
53
+
54
+ A new visit starts whenever the active URL changes (tab switch, navigation,
55
+ switching to another browser window). Time spent outside the browser is
56
+ counted towards the last visit until the browser reports a new event, so
57
+ durations are an upper bound.
58
+ """
59
+
60
+ def __init__(self, monitor: Optional[TabMonitor] = None, *, max_visits: int = 10_000):
61
+ self._lock = threading.Lock()
62
+ self._visits: List[Visit] = []
63
+ self._max = max_visits
64
+ if monitor is not None:
65
+ self.attach(monitor)
66
+
67
+ def attach(self, monitor: TabMonitor) -> None:
68
+ """Start recording events from ``monitor``."""
69
+ monitor.add_handler(self.record)
70
+
71
+ def record(self, tab: Tab) -> None:
72
+ """Feed one event (called automatically when attached to a monitor)."""
73
+ with self._lock:
74
+ current = self._visits[-1] if self._visits else None
75
+ if tab.event == EventKind.WINDOW_CLOSED:
76
+ if current and current.ended is None and current.tab.hwnd == tab.hwnd:
77
+ current.ended = tab.timestamp
78
+ return
79
+ if not tab.resolved:
80
+ return
81
+ if (current and current.ended is None and current.url == tab.url
82
+ and current.tab.hwnd == tab.hwnd):
83
+ return # same page, e.g. returning to the window
84
+ if current and current.ended is None:
85
+ current.ended = tab.timestamp
86
+ self._visits.append(Visit(tab, tab.timestamp))
87
+ if len(self._visits) > self._max:
88
+ del self._visits[: len(self._visits) - self._max]
89
+
90
+ # -- queries --------------------------------------------------------------
91
+
92
+ @property
93
+ def visits(self) -> List[Visit]:
94
+ """All recorded visits, oldest first (a copy)."""
95
+ with self._lock:
96
+ return list(self._visits)
97
+
98
+ @property
99
+ def current(self) -> Optional[Visit]:
100
+ """The visit in progress, if any."""
101
+ with self._lock:
102
+ last = self._visits[-1] if self._visits else None
103
+ return last if last and last.ended is None else None
104
+
105
+ def time_by_domain(self) -> Dict[str, timedelta]:
106
+ """Total time per domain, longest first."""
107
+ totals: Dict[str, timedelta] = defaultdict(timedelta)
108
+ for visit in self.visits:
109
+ totals[visit.tab.domain or visit.tab.scheme or "unknown"] += visit.duration
110
+ return dict(sorted(totals.items(), key=lambda kv: kv[1], reverse=True))
111
+
112
+ def to_list(self) -> List[Dict[str, Any]]:
113
+ """JSON-friendly list of visits."""
114
+ return [v.to_dict() for v in self.visits]
115
+
116
+ def clear(self) -> None:
117
+ with self._lock:
118
+ self._visits.clear()
119
+
120
+ def __len__(self) -> int:
121
+ with self._lock:
122
+ return len(self._visits)
browsermem/models.py ADDED
@@ -0,0 +1,190 @@
1
+ """Public data types."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from dataclasses import dataclass, field
6
+ from datetime import datetime
7
+ from enum import IntEnum
8
+ from typing import Any, Iterable, NamedTuple, Optional, Tuple, Union
9
+ from urllib.parse import urlsplit
10
+
11
+ from ._native import bm_tab
12
+
13
+
14
+ class Browser(IntEnum):
15
+ """Supported browsers (values match ``BM_BROWSER_*``)."""
16
+
17
+ UNKNOWN = 0
18
+ CHROME = 1
19
+ EDGE = 2
20
+ BRAVE = 3
21
+ OPERA = 4
22
+ VIVALDI = 5
23
+ YANDEX = 6
24
+ FIREFOX = 7 #: experimental
25
+
26
+ @classmethod
27
+ def parse(cls, value: Union[str, int, Browser]) -> Browser:
28
+ """``Browser.parse("edge")`` -> ``Browser.EDGE``."""
29
+ if isinstance(value, str):
30
+ return cls[value.strip().upper()]
31
+ return cls(value)
32
+
33
+
34
+ class EventKind(IntEnum):
35
+ """Why a :class:`Tab` was produced (values match ``BM_EVENT_*``)."""
36
+
37
+ SNAPSHOT = 0 #: one-shot query, or a monitor's initial state
38
+ TAB_CHANGED = 1 #: tab switch, new tab, or navigation that changed the title
39
+ WINDOW_ACTIVATED = 2 #: user switched to a browser window
40
+ URL_CHANGED = 3 #: periodic rescan found a new URL with the same title
41
+ WINDOW_CLOSED = 4 #: browser window closed; fields hold the last known tab
42
+
43
+
44
+ BrowserFilter = Union[Browser, str, Iterable[Union[Browser, str]], None]
45
+
46
+
47
+ def browser_mask(browsers: BrowserFilter) -> int:
48
+ """Convert a browser filter to the native bit mask (``None`` = all browsers)."""
49
+ if browsers is None:
50
+ return 0xFFFFFFFF
51
+ if isinstance(browsers, (Browser, str, int)):
52
+ browsers = [browsers] # type: ignore[list-item]
53
+ mask = 0
54
+ for b in browsers: # type: ignore[union-attr]
55
+ mask |= 1 << int(Browser.parse(b))
56
+ return mask
57
+
58
+
59
+ class UrlCount(NamedTuple):
60
+ """A URL found in memory and how many copies of it exist."""
61
+
62
+ url: str
63
+ count: int
64
+
65
+
66
+ @dataclass(frozen=True)
67
+ class Tab:
68
+ """The active tab of a browser window, as recovered from memory."""
69
+
70
+ event: EventKind
71
+ browser: Browser
72
+ browser_name: str
73
+ pid: int
74
+ hwnd: int
75
+ title: str
76
+ caption: str
77
+ url: Optional[str]
78
+ confidence: float
79
+ timestamp: datetime
80
+ scan_ms: int
81
+ candidates: Tuple[Tuple[str, float], ...] = field(default=(), repr=False)
82
+
83
+ @property
84
+ def resolved(self) -> bool:
85
+ """True if a URL was found."""
86
+ return self.url is not None
87
+
88
+ @property
89
+ def scheme(self) -> Optional[str]:
90
+ """``"https"``, ``"chrome"``, ``"file"``, ... (``None`` if unresolved)."""
91
+ return urlsplit(self.url).scheme or None if self.url else None
92
+
93
+ @property
94
+ def host(self) -> Optional[str]:
95
+ """Lower-cased host name, e.g. ``"www.github.com"``."""
96
+ return urlsplit(self.url).hostname if self.url else None
97
+
98
+ @property
99
+ def domain(self) -> Optional[str]:
100
+ """Host name without a leading ``www.``, e.g. ``"github.com"``."""
101
+ host = self.host
102
+ return host[4:] if host and host.startswith("www.") else host
103
+
104
+ @property
105
+ def is_web(self) -> bool:
106
+ """True for ``http``/``https`` pages (False for ``chrome://newtab``, files, ...)."""
107
+ return self.scheme in ("http", "https")
108
+
109
+ def matches_domain(self, *domains: str) -> bool:
110
+ """True if the tab is on one of ``domains`` or a subdomain of one."""
111
+ host = self.host
112
+ if not host:
113
+ return False
114
+ return any(host == d.lower() or host.endswith("." + d.lower()) for d in domains)
115
+
116
+ def to_dict(self) -> dict[str, Any]:
117
+ """JSON-friendly representation."""
118
+ return {
119
+ "domain": self.domain,
120
+ "event": self.event.name.lower(),
121
+ "browser": self.browser.name.lower(),
122
+ "browser_name": self.browser_name,
123
+ "pid": self.pid,
124
+ "hwnd": self.hwnd,
125
+ "title": self.title,
126
+ "caption": self.caption,
127
+ "url": self.url,
128
+ "confidence": round(self.confidence, 4),
129
+ "timestamp": self.timestamp.isoformat(timespec="milliseconds"),
130
+ "scan_ms": self.scan_ms,
131
+ "candidates": [{"url": u, "score": round(s, 4)} for u, s in self.candidates],
132
+ }
133
+
134
+
135
+ @dataclass(frozen=True)
136
+ class BrowserWindow:
137
+ """A top-level browser window (found without reading memory)."""
138
+
139
+ hwnd: int
140
+ pid: int
141
+ browser: Browser
142
+ browser_name: str
143
+ caption: str
144
+ title: str
145
+ is_foreground: bool
146
+
147
+ def to_dict(self) -> dict[str, Any]:
148
+ return {
149
+ "hwnd": self.hwnd,
150
+ "pid": self.pid,
151
+ "browser": self.browser.name.lower(),
152
+ "browser_name": self.browser_name,
153
+ "caption": self.caption,
154
+ "title": self.title,
155
+ "is_foreground": self.is_foreground,
156
+ }
157
+
158
+
159
+ # ---- conversions from native structs (internal) -------------------------------
160
+
161
+
162
+ def _s(raw: Optional[bytes]) -> str:
163
+ return raw.decode("utf-8", "replace") if raw else ""
164
+
165
+
166
+ def _browser(value: int) -> Browser:
167
+ try:
168
+ return Browser(value)
169
+ except ValueError:
170
+ return Browser.UNKNOWN
171
+
172
+
173
+ def _tab_from_native(t: bm_tab) -> Tab:
174
+ candidates = tuple(
175
+ (_s(t.candidates[i].url), float(t.candidates[i].score)) for i in range(t.candidate_count)
176
+ )
177
+ return Tab(
178
+ event=EventKind(t.event),
179
+ browser=_browser(t.browser),
180
+ browser_name=_s(t.browser_name),
181
+ pid=t.pid,
182
+ hwnd=t.hwnd,
183
+ title=_s(t.title),
184
+ caption=_s(t.caption),
185
+ url=_s(t.url) or None,
186
+ confidence=float(t.confidence),
187
+ timestamp=datetime.fromtimestamp(t.timestamp_ms / 1000),
188
+ scan_ms=t.scan_ms,
189
+ candidates=candidates,
190
+ )