browsermem 0.1.0__tar.gz

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.
Files changed (56) hide show
  1. browsermem-0.1.0/.gitattributes +4 -0
  2. browsermem-0.1.0/.gitignore +27 -0
  3. browsermem-0.1.0/CHANGELOG.md +25 -0
  4. browsermem-0.1.0/CMakeLists.txt +45 -0
  5. browsermem-0.1.0/CONTRIBUTING.md +63 -0
  6. browsermem-0.1.0/LICENSE +21 -0
  7. browsermem-0.1.0/PKG-INFO +219 -0
  8. browsermem-0.1.0/README.md +174 -0
  9. browsermem-0.1.0/SECURITY.md +28 -0
  10. browsermem-0.1.0/docs/activity.md +51 -0
  11. browsermem-0.1.0/docs/api.md +63 -0
  12. browsermem-0.1.0/docs/changelog.md +1 -0
  13. browsermem-0.1.0/docs/cli.md +45 -0
  14. browsermem-0.1.0/docs/events.md +112 -0
  15. browsermem-0.1.0/docs/forensics.md +59 -0
  16. browsermem-0.1.0/docs/getting-started.md +80 -0
  17. browsermem-0.1.0/docs/how-it-works.md +76 -0
  18. browsermem-0.1.0/docs/index.md +39 -0
  19. browsermem-0.1.0/examples/active_tab.py +12 -0
  20. browsermem-0.1.0/examples/async_watch.py +16 -0
  21. browsermem-0.1.0/examples/forensics_minidump.py +29 -0
  22. browsermem-0.1.0/examples/watch_tabs.py +23 -0
  23. browsermem-0.1.0/mkdocs.yml +57 -0
  24. browsermem-0.1.0/native/include/browsermem.h +173 -0
  25. browsermem-0.1.0/native/src/browsers.cpp +184 -0
  26. browsermem-0.1.0/native/src/browsers.hpp +63 -0
  27. browsermem-0.1.0/native/src/c_api.cpp +417 -0
  28. browsermem-0.1.0/native/src/common.cpp +39 -0
  29. browsermem-0.1.0/native/src/common.hpp +42 -0
  30. browsermem-0.1.0/native/src/memory.cpp +85 -0
  31. browsermem-0.1.0/native/src/memory.hpp +38 -0
  32. browsermem-0.1.0/native/src/monitor.cpp +332 -0
  33. browsermem-0.1.0/native/src/monitor.hpp +124 -0
  34. browsermem-0.1.0/native/src/resolver.cpp +156 -0
  35. browsermem-0.1.0/native/src/resolver.hpp +42 -0
  36. browsermem-0.1.0/native/src/url_index.cpp +97 -0
  37. browsermem-0.1.0/native/src/url_index.hpp +48 -0
  38. browsermem-0.1.0/pyproject.toml +87 -0
  39. browsermem-0.1.0/src/browsermem/__init__.py +66 -0
  40. browsermem-0.1.0/src/browsermem/__main__.py +5 -0
  41. browsermem-0.1.0/src/browsermem/_native.py +139 -0
  42. browsermem-0.1.0/src/browsermem/api.py +117 -0
  43. browsermem-0.1.0/src/browsermem/cli.py +182 -0
  44. browsermem-0.1.0/src/browsermem/errors.py +44 -0
  45. browsermem-0.1.0/src/browsermem/forensics.py +258 -0
  46. browsermem-0.1.0/src/browsermem/history.py +122 -0
  47. browsermem-0.1.0/src/browsermem/models.py +190 -0
  48. browsermem-0.1.0/src/browsermem/monitor.py +335 -0
  49. browsermem-0.1.0/src/browsermem/py.typed +0 -0
  50. browsermem-0.1.0/tests/__init__.py +0 -0
  51. browsermem-0.1.0/tests/_planted_child.py +27 -0
  52. browsermem-0.1.0/tests/conftest.py +118 -0
  53. browsermem-0.1.0/tests/test_api.py +138 -0
  54. browsermem-0.1.0/tests/test_browser.py +105 -0
  55. browsermem-0.1.0/tests/test_forensics.py +120 -0
  56. browsermem-0.1.0/tests/test_realtime_helpers.py +114 -0
@@ -0,0 +1,4 @@
1
+ * text=auto eol=lf
2
+ *.bat text eol=crlf
3
+ *.dll binary
4
+ *.dmp binary
@@ -0,0 +1,27 @@
1
+ # Python
2
+ __pycache__/
3
+ *.py[cod]
4
+ *.egg-info/
5
+ .venv/
6
+ venv/
7
+ .pytest_cache/
8
+ .ruff_cache/
9
+ .mypy_cache/
10
+
11
+ # Build outputs
12
+ build/
13
+ dist/
14
+ site/
15
+ _skbuild/
16
+ src/browsermem/*.dll
17
+ *.obj
18
+ *.lib
19
+ *.exp
20
+ *.pdb
21
+
22
+ # Memory dumps can contain sensitive data
23
+ *.dmp
24
+
25
+ # IDEs
26
+ .idea/
27
+ .vscode/
@@ -0,0 +1,25 @@
1
+ # Changelog
2
+
3
+ All notable changes are documented here. The format follows
4
+ [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses
5
+ [Semantic Versioning](https://semver.org/).
6
+
7
+ ## [Unreleased]
8
+
9
+ ## [0.1.0] - 2026-11-19
10
+
11
+ First public release.
12
+
13
+ ### Added
14
+ - `current_url()`, `get_active_tab()`, `get_tab()`, `get_all_tabs()`, `list_windows()`.
15
+ - `TabMonitor` live events: `SNAPSHOT`, `TAB_CHANGED`, `WINDOW_ACTIVATED`, `URL_CHANGED`,
16
+ `WINDOW_CLOSED`. Callbacks, decorators, iterator and asyncio interfaces.
17
+ - Handler filters `on_domain()` and `on_url()`, and `wait_for()`.
18
+ - `TabHistory` / `Visit`: visits and time spent per domain.
19
+ - `Tab` helpers: `domain`, `host`, `scheme`, `is_web`, `matches_domain()`, `to_dict()`.
20
+ - `browsermem` command-line tool with JSON output.
21
+ - Forensics: `MemoryImage` (live capture, minidump, custom regions), `write_minidump()`.
22
+ - Support for Chrome, Edge, Brave, Opera, Vivaldi and Yandex; experimental Firefox.
23
+
24
+ [Unreleased]: https://github.com/BinaryBreaker/browsermem/compare/v0.1.0...HEAD
25
+ [0.1.0]: https://github.com/BinaryBreaker/browsermem/releases/tag/v0.1.0
@@ -0,0 +1,45 @@
1
+ cmake_minimum_required(VERSION 3.20)
2
+
3
+ # The version lives in pyproject.toml; scikit-build-core passes it in.
4
+ if(DEFINED SKBUILD_PROJECT_VERSION)
5
+ set(BM_VERSION "${SKBUILD_PROJECT_VERSION}")
6
+ else()
7
+ set(BM_VERSION "0.0.0")
8
+ endif()
9
+
10
+ project(browsermem VERSION ${BM_VERSION} LANGUAGES CXX)
11
+
12
+ if(NOT WIN32)
13
+ message(FATAL_ERROR "browsermem currently supports Windows only")
14
+ endif()
15
+
16
+ set(CMAKE_CXX_STANDARD 17)
17
+ set(CMAKE_CXX_STANDARD_REQUIRED ON)
18
+ set(CMAKE_CXX_EXTENSIONS OFF)
19
+ # Link the C runtime statically so the DLL has no redistributable dependency.
20
+ set(CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>")
21
+
22
+ add_library(browsermem SHARED
23
+ native/src/browsers.cpp
24
+ native/src/c_api.cpp
25
+ native/src/common.cpp
26
+ native/src/memory.cpp
27
+ native/src/monitor.cpp
28
+ native/src/resolver.cpp
29
+ native/src/url_index.cpp)
30
+ target_include_directories(browsermem
31
+ PUBLIC $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/native/include> $<INSTALL_INTERFACE:include>
32
+ PRIVATE native/src)
33
+ target_compile_definitions(browsermem PRIVATE BM_BUILD_DLL BM_VERSION="${BM_VERSION}"
34
+ UNICODE _UNICODE)
35
+ target_compile_options(browsermem PRIVATE /W4 /WX /utf-8 /permissive- /EHsc)
36
+ target_link_libraries(browsermem PRIVATE user32)
37
+
38
+ if(SKBUILD)
39
+ # Python wheel: the DLL sits next to the package's Python files.
40
+ install(TARGETS browsermem RUNTIME DESTINATION browsermem)
41
+ else()
42
+ # Plain C/C++ consumers: cmake --install build --prefix <dir>
43
+ install(TARGETS browsermem RUNTIME DESTINATION bin ARCHIVE DESTINATION lib)
44
+ install(FILES native/include/browsermem.h DESTINATION include)
45
+ endif()
@@ -0,0 +1,63 @@
1
+ # Contributing to browsermem
2
+
3
+ Thanks for helping! Bug reports, browser-compatibility reports and pull requests are all
4
+ welcome.
5
+
6
+ ## Development setup
7
+
8
+ You need Windows 10/11 x64, Python 3.9+, and **Visual Studio 2022 or newer with the
9
+ "Desktop development with C++" workload**. CMake and Ninja are installed automatically by
10
+ the build.
11
+
12
+ ```bash
13
+ git clone https://github.com/BinaryBreaker/browsermem
14
+ cd browsermem
15
+ python -m venv .venv
16
+ .venv\Scripts\activate
17
+ pip install -e ".[dev]" # builds the DLL and installs in editable mode
18
+ pytest
19
+ ```
20
+
21
+ After changing C++ code, run `pip install -e .` again to rebuild the DLL.
22
+
23
+ ## Tests
24
+
25
+ | Command | What runs |
26
+ |---|---|
27
+ | `pytest` | unit, forensics and live-capture tests (no browser needed) |
28
+ | `set BROWSERMEM_TEST_BROWSER=1 && pytest -m browser` | end-to-end tests with a real Chrome or Edge (opens browser windows) |
29
+
30
+ The forensics tests build synthetic memory, and they also start a helper process that
31
+ keeps a browser-like "tab object" in memory, so the matching engine can be tested
32
+ deterministically.
33
+
34
+ ## Code style
35
+
36
+ - Python: `ruff check .` (configuration in `pyproject.toml`).
37
+ - C++: C++17, `/W4 /WX` must stay warning-free. Follow the existing style (Google-like,
38
+ 100 columns).
39
+ - Public Python API changes need docstrings, a docs update in `docs/`, and a
40
+ `CHANGELOG.md` entry under *Unreleased*.
41
+ - Keep `native/include/browsermem.h` and `src/browsermem/_native.py` in sync; a test checks
42
+ that the enum values match.
43
+
44
+ ## Adding a browser
45
+
46
+ Most Chromium-based browsers only need a new entry in `AllProfiles()` in
47
+ `native/src/browsers.cpp` (executable name, window class, caption suffix), a value in the
48
+ `Browser` enum in both the header and `models.py`, and a line in the README table.
49
+
50
+ ## Pull requests
51
+
52
+ 1. Fork the repository and create a branch from `main`.
53
+ 2. Add tests for your change.
54
+ 3. Make sure `pytest` and `ruff check .` pass.
55
+ 4. Open a PR describing what changed and why.
56
+
57
+ ## Releasing (maintainers)
58
+
59
+ 1. Update `version` in `pyproject.toml` and move the *Unreleased* changelog entries under
60
+ the new version.
61
+ 2. Commit, then tag: `git tag v0.2.0 && git push --tags`.
62
+ 3. The *Release* workflow builds the wheel and sdist, tests them, publishes to PyPI with
63
+ Trusted Publishing, and creates a GitHub release.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 BinaryBreaker
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,219 @@
1
+ Metadata-Version: 2.4
2
+ Name: browsermem
3
+ Version: 0.1.0
4
+ Summary: Real-time browser tab URLs and titles for Python on Windows: get the active tab, react to tab changes, track browsing activity. Chrome, Edge, Brave, Opera, Vivaldi.
5
+ Keywords: browser,url,active-tab,current-url,tab,chrome,edge,brave,real-time,monitoring,activity-tracking,windows,automation,forensics
6
+ Author: BinaryBreaker
7
+ Maintainer: BinaryBreaker
8
+ License-Expression: MIT
9
+ License-File: LICENSE
10
+ Classifier: Development Status :: 4 - Beta
11
+ Classifier: Intended Audience :: Developers
12
+ Classifier: Intended Audience :: Information Technology
13
+ Classifier: Intended Audience :: Science/Research
14
+ Classifier: Operating System :: Microsoft :: Windows
15
+ Classifier: Programming Language :: C++
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3 :: Only
18
+ Classifier: Programming Language :: Python :: 3.9
19
+ Classifier: Programming Language :: Python :: 3.10
20
+ Classifier: Programming Language :: Python :: 3.11
21
+ Classifier: Programming Language :: Python :: 3.12
22
+ Classifier: Programming Language :: Python :: 3.13
23
+ Classifier: Programming Language :: Python :: 3.14
24
+ Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
25
+ Classifier: Topic :: System :: Monitoring
26
+ Classifier: Topic :: Utilities
27
+ Classifier: Topic :: Security
28
+ Classifier: Typing :: Typed
29
+ Project-URL: Homepage, https://github.com/BinaryBreaker/browsermem
30
+ Project-URL: Documentation, https://binarybreaker.github.io/browsermem/
31
+ Project-URL: Issues, https://github.com/BinaryBreaker/browsermem/issues
32
+ Project-URL: Changelog, https://github.com/BinaryBreaker/browsermem/blob/main/CHANGELOG.md
33
+ Requires-Python: >=3.9
34
+ Provides-Extra: test
35
+ Requires-Dist: pytest>=7; extra == "test"
36
+ Requires-Dist: pytest-timeout>=2; extra == "test"
37
+ Provides-Extra: docs
38
+ Requires-Dist: mkdocs-material>=9.5; extra == "docs"
39
+ Requires-Dist: mkdocstrings[python]>=0.26; extra == "docs"
40
+ Provides-Extra: dev
41
+ Requires-Dist: browsermem[docs,test]; extra == "dev"
42
+ Requires-Dist: ruff>=0.6; extra == "dev"
43
+ Requires-Dist: build>=1; extra == "dev"
44
+ Description-Content-Type: text/markdown
45
+
46
+ <div align="center">
47
+
48
+ # browsermem
49
+
50
+ **Get the real-time URL of the active browser tab from Python. No extension, no WebDriver, no setup.**
51
+
52
+ [![PyPI](https://img.shields.io/pypi/v/browsermem.svg)](https://pypi.org/project/browsermem/)
53
+ [![Python](https://img.shields.io/pypi/pyversions/browsermem.svg)](https://pypi.org/project/browsermem/)
54
+ [![CI](https://github.com/BinaryBreaker/browsermem/actions/workflows/ci.yml/badge.svg)](https://github.com/BinaryBreaker/browsermem/actions/workflows/ci.yml)
55
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
56
+ [![Docs](https://img.shields.io/badge/docs-binarybreaker.github.io-informational)](https://binarybreaker.github.io/browsermem/)
57
+
58
+ </div>
59
+
60
+ ```python
61
+ import browsermem
62
+
63
+ browsermem.current_url()
64
+ # 'https://github.com/BinaryBreaker/browsermem'
65
+ ```
66
+
67
+ `browsermem` reads the active tab's URL and title straight from the browser's memory, and
68
+ sends an event every time you switch tabs, open a tab or navigate. It works with the
69
+ browser you already use: the user doesn't need to install anything or restart the browser
70
+ with special flags.
71
+
72
+ ## Features
73
+
74
+ - **Active tab:** `current_url()`, `get_active_tab()`, or the active tab of every open window.
75
+ - **Live events:** tab switched, new tab, navigation, browser window focused or closed.
76
+ - **Several ways to handle events:** callbacks, decorators, iterators or `async for`.
77
+ - **Filters:** `@monitor.on_domain("youtube.com")`, `@monitor.on_url(r"/checkout")`, and
78
+ `monitor.wait_for(...)` to block until a matching page opens.
79
+ - **Activity tracking:** `TabHistory` records visits and time spent per domain.
80
+ - **Browsers:** Chrome, Edge, Brave, Opera and Vivaldi (any Chromium-based browser).
81
+ Firefox is experimental.
82
+ - **Fast:** event-driven (no polling loop in Python); about 0.1–0.5 s per lookup, with caching.
83
+ - **Command line:** `browsermem active`, `browsermem watch --json` and more.
84
+ - **Typed and dependency-free:** one wheel covers Python 3.9–3.14. Nothing to compile.
85
+ - **Bonus: memory forensics.** Analyse minidumps of a browser offline.
86
+
87
+ ## Install
88
+
89
+ ```bash
90
+ pip install browsermem
91
+ ```
92
+
93
+ Requires Windows 10/11 (x64) and Python 3.9+.
94
+
95
+ ## Quick start
96
+
97
+ ### The active tab
98
+
99
+ ```python
100
+ import browsermem
101
+
102
+ tab = browsermem.get_active_tab()
103
+ print(tab.browser_name) # Google Chrome
104
+ print(tab.title) # BinaryBreaker/browsermem
105
+ print(tab.url) # https://github.com/BinaryBreaker/browsermem
106
+ print(tab.domain) # github.com
107
+ ```
108
+
109
+ ### React to tab changes
110
+
111
+ ```python
112
+ from browsermem import TabMonitor, EventKind
113
+
114
+ monitor = TabMonitor()
115
+
116
+ @monitor.on(EventKind.TAB_CHANGED, EventKind.WINDOW_ACTIVATED)
117
+ def changed(tab):
118
+ print(f"{tab.browser_name}: {tab.title} -> {tab.url}")
119
+
120
+ @monitor.on_domain("youtube.com")
121
+ def youtube(tab):
122
+ print("Watching:", tab.title)
123
+
124
+ monitor.run_forever() # Ctrl+C to stop
125
+ ```
126
+
127
+ ### Iterate, or use asyncio
128
+
129
+ ```python
130
+ with TabMonitor() as monitor:
131
+ for tab in monitor.events():
132
+ print(tab.url)
133
+
134
+ async with TabMonitor() as monitor:
135
+ async for tab in monitor.aevents():
136
+ print(tab.url)
137
+ ```
138
+
139
+ ### Wait for a page
140
+
141
+ ```python
142
+ with TabMonitor() as monitor:
143
+ tab = monitor.wait_for(r"/payment/success", timeout=300)
144
+ print("Done!" if tab else "Timed out")
145
+ ```
146
+
147
+ ### Track browsing time
148
+
149
+ ```python
150
+ from browsermem import TabMonitor, TabHistory
151
+
152
+ monitor = TabMonitor()
153
+ history = TabHistory(monitor)
154
+ monitor.start()
155
+ # ... later
156
+ for domain, spent in history.time_by_domain().items():
157
+ print(f"{domain:30} {spent}")
158
+ ```
159
+
160
+ ### Command line
161
+
162
+ ```bash
163
+ browsermem active # URL of the active tab
164
+ browsermem windows # all browser windows
165
+ browsermem watch # live tab events
166
+ browsermem watch --json # JSON lines, ready to pipe
167
+ ```
168
+
169
+ ## Events
170
+
171
+ | `EventKind` | When |
172
+ |---|---|
173
+ | `SNAPSHOT` | Current state when the monitor starts (also returned by one-shot queries) |
174
+ | `TAB_CHANGED` | Tab switch, new tab, or a navigation that changed the page title |
175
+ | `WINDOW_ACTIVATED` | You switched to a browser window from another app or window |
176
+ | `URL_CHANGED` | Same title, different URL (single-page apps). Needs `rescan_ms` |
177
+ | `WINDOW_CLOSED` | A browser window closed; the event holds its last tab |
178
+
179
+ ## How it works
180
+
181
+ 1. Windows notifies browsermem when a browser window gains focus or its title changes,
182
+ which happens on every tab switch and navigation.
183
+ 2. browsermem takes a snapshot of the browser process's own memory (read-only, the same
184
+ access Task Manager uses).
185
+ 3. It finds the tab's title in that memory, follows the pointers that refer to it, and
186
+ picks the URL stored inside the same browser objects.
187
+
188
+ See [How it works](https://binarybreaker.github.io/browsermem/how-it-works/) for details.
189
+
190
+ ## Supported browsers
191
+
192
+ | Browser | Status |
193
+ |---|---|
194
+ | Google Chrome | ✅ tested |
195
+ | Microsoft Edge | ✅ tested |
196
+ | Brave, Opera, Vivaldi, Yandex | ✅ supported (same Chromium engine) |
197
+ | Firefox | 🧪 experimental |
198
+
199
+ ## Limitations
200
+
201
+ - Windows x64 only for now.
202
+ - A navigation that keeps the same page title is only detected with `TabMonitor(rescan_ms=...)`.
203
+ - Two tabs with exactly the same title can be confused.
204
+ - browsermem only reads processes your user account can open (no elevation needed for
205
+ your own browser).
206
+
207
+ ## Responsible use
208
+
209
+ browsermem reads memory of processes that belong to **your** user account. Use it for your
210
+ own productivity tools, automation, research and authorised investigations. Monitoring
211
+ other people's browsing without their knowledge and consent may be illegal where you live.
212
+
213
+ ## Contributing
214
+
215
+ Bug reports and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
216
+
217
+ ## License
218
+
219
+ [MIT](LICENSE) © BinaryBreaker
@@ -0,0 +1,174 @@
1
+ <div align="center">
2
+
3
+ # browsermem
4
+
5
+ **Get the real-time URL of the active browser tab from Python. No extension, no WebDriver, no setup.**
6
+
7
+ [![PyPI](https://img.shields.io/pypi/v/browsermem.svg)](https://pypi.org/project/browsermem/)
8
+ [![Python](https://img.shields.io/pypi/pyversions/browsermem.svg)](https://pypi.org/project/browsermem/)
9
+ [![CI](https://github.com/BinaryBreaker/browsermem/actions/workflows/ci.yml/badge.svg)](https://github.com/BinaryBreaker/browsermem/actions/workflows/ci.yml)
10
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
11
+ [![Docs](https://img.shields.io/badge/docs-binarybreaker.github.io-informational)](https://binarybreaker.github.io/browsermem/)
12
+
13
+ </div>
14
+
15
+ ```python
16
+ import browsermem
17
+
18
+ browsermem.current_url()
19
+ # 'https://github.com/BinaryBreaker/browsermem'
20
+ ```
21
+
22
+ `browsermem` reads the active tab's URL and title straight from the browser's memory, and
23
+ sends an event every time you switch tabs, open a tab or navigate. It works with the
24
+ browser you already use: the user doesn't need to install anything or restart the browser
25
+ with special flags.
26
+
27
+ ## Features
28
+
29
+ - **Active tab:** `current_url()`, `get_active_tab()`, or the active tab of every open window.
30
+ - **Live events:** tab switched, new tab, navigation, browser window focused or closed.
31
+ - **Several ways to handle events:** callbacks, decorators, iterators or `async for`.
32
+ - **Filters:** `@monitor.on_domain("youtube.com")`, `@monitor.on_url(r"/checkout")`, and
33
+ `monitor.wait_for(...)` to block until a matching page opens.
34
+ - **Activity tracking:** `TabHistory` records visits and time spent per domain.
35
+ - **Browsers:** Chrome, Edge, Brave, Opera and Vivaldi (any Chromium-based browser).
36
+ Firefox is experimental.
37
+ - **Fast:** event-driven (no polling loop in Python); about 0.1–0.5 s per lookup, with caching.
38
+ - **Command line:** `browsermem active`, `browsermem watch --json` and more.
39
+ - **Typed and dependency-free:** one wheel covers Python 3.9–3.14. Nothing to compile.
40
+ - **Bonus: memory forensics.** Analyse minidumps of a browser offline.
41
+
42
+ ## Install
43
+
44
+ ```bash
45
+ pip install browsermem
46
+ ```
47
+
48
+ Requires Windows 10/11 (x64) and Python 3.9+.
49
+
50
+ ## Quick start
51
+
52
+ ### The active tab
53
+
54
+ ```python
55
+ import browsermem
56
+
57
+ tab = browsermem.get_active_tab()
58
+ print(tab.browser_name) # Google Chrome
59
+ print(tab.title) # BinaryBreaker/browsermem
60
+ print(tab.url) # https://github.com/BinaryBreaker/browsermem
61
+ print(tab.domain) # github.com
62
+ ```
63
+
64
+ ### React to tab changes
65
+
66
+ ```python
67
+ from browsermem import TabMonitor, EventKind
68
+
69
+ monitor = TabMonitor()
70
+
71
+ @monitor.on(EventKind.TAB_CHANGED, EventKind.WINDOW_ACTIVATED)
72
+ def changed(tab):
73
+ print(f"{tab.browser_name}: {tab.title} -> {tab.url}")
74
+
75
+ @monitor.on_domain("youtube.com")
76
+ def youtube(tab):
77
+ print("Watching:", tab.title)
78
+
79
+ monitor.run_forever() # Ctrl+C to stop
80
+ ```
81
+
82
+ ### Iterate, or use asyncio
83
+
84
+ ```python
85
+ with TabMonitor() as monitor:
86
+ for tab in monitor.events():
87
+ print(tab.url)
88
+
89
+ async with TabMonitor() as monitor:
90
+ async for tab in monitor.aevents():
91
+ print(tab.url)
92
+ ```
93
+
94
+ ### Wait for a page
95
+
96
+ ```python
97
+ with TabMonitor() as monitor:
98
+ tab = monitor.wait_for(r"/payment/success", timeout=300)
99
+ print("Done!" if tab else "Timed out")
100
+ ```
101
+
102
+ ### Track browsing time
103
+
104
+ ```python
105
+ from browsermem import TabMonitor, TabHistory
106
+
107
+ monitor = TabMonitor()
108
+ history = TabHistory(monitor)
109
+ monitor.start()
110
+ # ... later
111
+ for domain, spent in history.time_by_domain().items():
112
+ print(f"{domain:30} {spent}")
113
+ ```
114
+
115
+ ### Command line
116
+
117
+ ```bash
118
+ browsermem active # URL of the active tab
119
+ browsermem windows # all browser windows
120
+ browsermem watch # live tab events
121
+ browsermem watch --json # JSON lines, ready to pipe
122
+ ```
123
+
124
+ ## Events
125
+
126
+ | `EventKind` | When |
127
+ |---|---|
128
+ | `SNAPSHOT` | Current state when the monitor starts (also returned by one-shot queries) |
129
+ | `TAB_CHANGED` | Tab switch, new tab, or a navigation that changed the page title |
130
+ | `WINDOW_ACTIVATED` | You switched to a browser window from another app or window |
131
+ | `URL_CHANGED` | Same title, different URL (single-page apps). Needs `rescan_ms` |
132
+ | `WINDOW_CLOSED` | A browser window closed; the event holds its last tab |
133
+
134
+ ## How it works
135
+
136
+ 1. Windows notifies browsermem when a browser window gains focus or its title changes,
137
+ which happens on every tab switch and navigation.
138
+ 2. browsermem takes a snapshot of the browser process's own memory (read-only, the same
139
+ access Task Manager uses).
140
+ 3. It finds the tab's title in that memory, follows the pointers that refer to it, and
141
+ picks the URL stored inside the same browser objects.
142
+
143
+ See [How it works](https://binarybreaker.github.io/browsermem/how-it-works/) for details.
144
+
145
+ ## Supported browsers
146
+
147
+ | Browser | Status |
148
+ |---|---|
149
+ | Google Chrome | ✅ tested |
150
+ | Microsoft Edge | ✅ tested |
151
+ | Brave, Opera, Vivaldi, Yandex | ✅ supported (same Chromium engine) |
152
+ | Firefox | 🧪 experimental |
153
+
154
+ ## Limitations
155
+
156
+ - Windows x64 only for now.
157
+ - A navigation that keeps the same page title is only detected with `TabMonitor(rescan_ms=...)`.
158
+ - Two tabs with exactly the same title can be confused.
159
+ - browsermem only reads processes your user account can open (no elevation needed for
160
+ your own browser).
161
+
162
+ ## Responsible use
163
+
164
+ browsermem reads memory of processes that belong to **your** user account. Use it for your
165
+ own productivity tools, automation, research and authorised investigations. Monitoring
166
+ other people's browsing without their knowledge and consent may be illegal where you live.
167
+
168
+ ## Contributing
169
+
170
+ Bug reports and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
171
+
172
+ ## License
173
+
174
+ [MIT](LICENSE) © BinaryBreaker
@@ -0,0 +1,28 @@
1
+ # Security policy
2
+
3
+ ## Supported versions
4
+
5
+ Security fixes are made for the latest released version.
6
+
7
+ ## Reporting a vulnerability
8
+
9
+ Please **don't** open a public issue for security problems. Report them privately through
10
+ [GitHub Security Advisories](https://github.com/BinaryBreaker/browsermem/security/advisories/new).
11
+ You should get a response within a few days.
12
+
13
+ ## Scope and design
14
+
15
+ browsermem only **reads** memory, and only of processes the current user is allowed to
16
+ open (`PROCESS_VM_READ | PROCESS_QUERY_INFORMATION`). It never writes to or injects into
17
+ another process, never escalates privileges, and never sends data anywhere. Everything it
18
+ reads stays inside your Python process.
19
+
20
+ Note that a URL can contain sensitive data, such as session tokens in query strings. If
21
+ your application stores or transmits URLs from browsermem, treat them as you would any
22
+ browsing history.
23
+
24
+ ## Responsible use
25
+
26
+ Use browsermem on machines and accounts you own or administer, or with the informed
27
+ consent of the people being monitored. Covertly monitoring someone else's browsing may be
28
+ illegal in your jurisdiction.
@@ -0,0 +1,51 @@
1
+ # Activity tracking
2
+
3
+ `TabHistory` turns live events into a timeline of visits: which URL was active, when, and
4
+ for how long.
5
+
6
+ ```python
7
+ import time
8
+ from browsermem import TabMonitor, TabHistory
9
+
10
+ monitor = TabMonitor()
11
+ history = TabHistory(monitor) # attaches itself as a handler
12
+ monitor.start()
13
+
14
+ time.sleep(600) # browse for a while
15
+
16
+ for domain, spent in history.time_by_domain().items():
17
+ print(f"{domain:30} {spent}")
18
+
19
+ for visit in history.visits:
20
+ print(visit.started, visit.duration, visit.url)
21
+
22
+ monitor.stop()
23
+ ```
24
+
25
+ ## Rules
26
+
27
+ - A new **visit** starts when the active URL changes (a tab switch, a navigation, or a
28
+ switch to another browser window) and ends when the next one starts.
29
+ - Returning to the same page in the same window continues the current visit.
30
+ - Events whose URL couldn't be resolved are skipped.
31
+ - `WINDOW_CLOSED` ends the visit of that window.
32
+
33
+ !!! note
34
+ Windows only reports events *in* the browser. Time spent in another application is
35
+ counted towards the last browser visit until the browser sends a new event, so
36
+ durations are an upper bound. If you need exact focus time, combine this with your
37
+ own foreground-window tracking.
38
+
39
+ ## Export
40
+
41
+ ```python
42
+ import json
43
+ json.dump(history.to_list(), open("activity.json", "w"), indent=2)
44
+ ```
45
+
46
+ Each entry contains `url`, `title`, `domain`, `browser`, `started`, `ended` and `seconds`.
47
+
48
+ ## Without a monitor
49
+
50
+ `TabHistory.record(tab)` accepts any `Tab`, so you can feed it events from your own
51
+ pipeline or replay a saved log.