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.
- browsermem-0.1.0/.gitattributes +4 -0
- browsermem-0.1.0/.gitignore +27 -0
- browsermem-0.1.0/CHANGELOG.md +25 -0
- browsermem-0.1.0/CMakeLists.txt +45 -0
- browsermem-0.1.0/CONTRIBUTING.md +63 -0
- browsermem-0.1.0/LICENSE +21 -0
- browsermem-0.1.0/PKG-INFO +219 -0
- browsermem-0.1.0/README.md +174 -0
- browsermem-0.1.0/SECURITY.md +28 -0
- browsermem-0.1.0/docs/activity.md +51 -0
- browsermem-0.1.0/docs/api.md +63 -0
- browsermem-0.1.0/docs/changelog.md +1 -0
- browsermem-0.1.0/docs/cli.md +45 -0
- browsermem-0.1.0/docs/events.md +112 -0
- browsermem-0.1.0/docs/forensics.md +59 -0
- browsermem-0.1.0/docs/getting-started.md +80 -0
- browsermem-0.1.0/docs/how-it-works.md +76 -0
- browsermem-0.1.0/docs/index.md +39 -0
- browsermem-0.1.0/examples/active_tab.py +12 -0
- browsermem-0.1.0/examples/async_watch.py +16 -0
- browsermem-0.1.0/examples/forensics_minidump.py +29 -0
- browsermem-0.1.0/examples/watch_tabs.py +23 -0
- browsermem-0.1.0/mkdocs.yml +57 -0
- browsermem-0.1.0/native/include/browsermem.h +173 -0
- browsermem-0.1.0/native/src/browsers.cpp +184 -0
- browsermem-0.1.0/native/src/browsers.hpp +63 -0
- browsermem-0.1.0/native/src/c_api.cpp +417 -0
- browsermem-0.1.0/native/src/common.cpp +39 -0
- browsermem-0.1.0/native/src/common.hpp +42 -0
- browsermem-0.1.0/native/src/memory.cpp +85 -0
- browsermem-0.1.0/native/src/memory.hpp +38 -0
- browsermem-0.1.0/native/src/monitor.cpp +332 -0
- browsermem-0.1.0/native/src/monitor.hpp +124 -0
- browsermem-0.1.0/native/src/resolver.cpp +156 -0
- browsermem-0.1.0/native/src/resolver.hpp +42 -0
- browsermem-0.1.0/native/src/url_index.cpp +97 -0
- browsermem-0.1.0/native/src/url_index.hpp +48 -0
- browsermem-0.1.0/pyproject.toml +87 -0
- browsermem-0.1.0/src/browsermem/__init__.py +66 -0
- browsermem-0.1.0/src/browsermem/__main__.py +5 -0
- browsermem-0.1.0/src/browsermem/_native.py +139 -0
- browsermem-0.1.0/src/browsermem/api.py +117 -0
- browsermem-0.1.0/src/browsermem/cli.py +182 -0
- browsermem-0.1.0/src/browsermem/errors.py +44 -0
- browsermem-0.1.0/src/browsermem/forensics.py +258 -0
- browsermem-0.1.0/src/browsermem/history.py +122 -0
- browsermem-0.1.0/src/browsermem/models.py +190 -0
- browsermem-0.1.0/src/browsermem/monitor.py +335 -0
- browsermem-0.1.0/src/browsermem/py.typed +0 -0
- browsermem-0.1.0/tests/__init__.py +0 -0
- browsermem-0.1.0/tests/_planted_child.py +27 -0
- browsermem-0.1.0/tests/conftest.py +118 -0
- browsermem-0.1.0/tests/test_api.py +138 -0
- browsermem-0.1.0/tests/test_browser.py +105 -0
- browsermem-0.1.0/tests/test_forensics.py +120 -0
- browsermem-0.1.0/tests/test_realtime_helpers.py +114 -0
|
@@ -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.
|
browsermem-0.1.0/LICENSE
ADDED
|
@@ -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
|
+
[](https://pypi.org/project/browsermem/)
|
|
53
|
+
[](https://pypi.org/project/browsermem/)
|
|
54
|
+
[](https://github.com/BinaryBreaker/browsermem/actions/workflows/ci.yml)
|
|
55
|
+
[](LICENSE)
|
|
56
|
+
[](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
|
+
[](https://pypi.org/project/browsermem/)
|
|
8
|
+
[](https://pypi.org/project/browsermem/)
|
|
9
|
+
[](https://github.com/BinaryBreaker/browsermem/actions/workflows/ci.yml)
|
|
10
|
+
[](LICENSE)
|
|
11
|
+
[](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.
|