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.
- browsermem/__init__.py +66 -0
- browsermem/__main__.py +5 -0
- browsermem/_native.py +139 -0
- browsermem/api.py +117 -0
- browsermem/browsermem.dll +0 -0
- browsermem/cli.py +182 -0
- browsermem/errors.py +44 -0
- browsermem/forensics.py +258 -0
- browsermem/history.py +122 -0
- browsermem/models.py +190 -0
- browsermem/monitor.py +335 -0
- browsermem/py.typed +0 -0
- browsermem-0.1.0.dist-info/METADATA +219 -0
- browsermem-0.1.0.dist-info/RECORD +17 -0
- browsermem-0.1.0.dist-info/WHEEL +5 -0
- browsermem-0.1.0.dist-info/entry_points.txt +3 -0
- browsermem-0.1.0.dist-info/licenses/LICENSE +21 -0
browsermem/forensics.py
ADDED
|
@@ -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
|
+
)
|