memlapse 0.1.1__tar.gz

memlapse-0.1.1/CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+Notable changes to memlapse. Versions follow [semantic
+versioning](https://semver.org/spec/v2.0.0.html): while the major version is 0
+the interface may still change, and any such change is called out here under
+**Changed** rather than assumed to be obvious from the version number.
+
+What is versioned is the application: its command line, its window, and the
+recordings it writes. The `memlapse` package is importable, but it is a
+program rather than a library, and the names inside it may move without that
+being a breaking change. A recording is the part with the longest life, so a
+release after which an older recording no longer opens, or opens and scores
+differently, says so here.
+
+## [0.1.1] - 2026-09-11
+
+First release, and the first as a package: until now memlapse ran only from a
+checkout with `python main.py`. It installs with `pip install memlapse` and
+starts with `memlapse`, or `memlapse --elevate` to relaunch through UAC.
+Windows only, Python 3.14.
+
+The name is written in lower case throughout, in the window, the docs and the
+repository, as it already was on PyPI. 0.1.0 below was tagged and never
+published, which is why the first release is numbered 0.1.1.
+
+### Added
+
+- A live process table, sortable and filterable, complete whether or not the
+  app is elevated.
+- A memory map for the selected process, read with `VirtualQueryEx` and
+  refreshed once a second while it is on screen, with a hex preview of a
+  region's first bytes and a bounded save of a region's contents for a
+  disassembler or a YARA rule.
+- Recording of a process's memory map over time to SQLite, and playback of a
+  recording on a timeline that can be scrubbed or played.
+- A 0 to 100 injection score for each executable region, from unbacked
+  private or mapped executable memory, RWX protection, a PE header, a NOP
+  sled, high entropy, a thread starting in memory no image backs, and code
+  rewritten in place or unpacked from packed to code-like. Scores fall into
+  bands of low, review and likely injection, and the top band needs a signal
+  the memory map alone cannot give, so a private RWX page of the kind a JIT
+  compiler leaves stops at review.
+- In playback, each region's rewrite history across the whole recording,
+  shown in its tooltip and as ticks on the timeline to scrub to. It is kept
+  beside the score rather than in it.
+- A dashboard of system memory gauges, a scrolling usage timeline, a ranked
+  list of the processes using the most memory, and CSV and JSON export.
+
+## [0.1.0] - 2026-09-11
+
+Tagged, never published. PyPI refused the upload because the repository was
+then named `Memlapse` and the trusted publisher waiting for it named
+`memlapse`, and a trusted publisher matches the repository name exactly. No
+release was made anywhere, and the tag is left where it is so that the version
+number is never used for anything else. 0.1.1 is the same program under the
+lower case name.
+
+[0.1.1]: https://github.com/mjaksn/memlapse/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/mjaksn/memlapse/tree/v0.1.0

memlapse-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mjaksn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

memlapse-0.1.1/MANIFEST.in

@@ -0,0 +1,7 @@
+# What the sdist carries beyond the package. Left to itself setuptools takes
+# tests/test_*.py and nothing else from tests/, so the source distribution
+# would hold a suite without its conftest.py, and without the files
+# test_version.py reads, that could not run. With these it can test itself.
+graft tests
+include CHANGELOG.md requirements.txt requirements-dev.txt
+global-exclude *.py[cod]

memlapse-0.1.1/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: memlapse
+Version: 0.1.1
+Summary: A Windows memory forensics tool that records a process's memory map over time, replays it, and scores each region for signs of code injection
+Author: mjaksn
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/mjaksn/memlapse
+Project-URL: Source, https://github.com/mjaksn/memlapse
+Project-URL: Issues, https://github.com/mjaksn/memlapse/issues
+Project-URL: Changelog, https://github.com/mjaksn/memlapse/blob/main/CHANGELOG.md
+Keywords: memory-forensics,dfir,process-injection,malware-detection,windows,virtualqueryex,process-explorer,pyside6
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Win32 (MS Windows)
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PySide6<6.12,>=6.11.2
+Requires-Dist: psutil<7.3,>=7.2.2
+Requires-Dist: pyqtgraph<0.15,>=0.14.0
+Dynamic: license-file
+
+# memlapse
+
+[![CI](https://github.com/mjaksn/memlapse/actions/workflows/ci.yml/badge.svg)](https://github.com/mjaksn/memlapse/actions/workflows/ci.yml)
+[![Release](https://github.com/mjaksn/memlapse/actions/workflows/release.yml/badge.svg)](https://github.com/mjaksn/memlapse/actions/workflows/release.yml)
+[![PyPI](https://img.shields.io/pypi/v/memlapse)](https://pypi.org/project/memlapse/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/mjaksn/memlapse/blob/main/LICENSE)
+
+A Windows memory forensics tool, Process Explorer / System Informer-style
+monitoring, that records a process's memory map over time and replays it.
+Recording and playback of the memory activity of specific threads is the
+planned next phase (Phase 5). See
+[docs/ARCHITECTURE.md](https://github.com/mjaksn/memlapse/blob/main/docs/ARCHITECTURE.md)
+for the design and
+[docs/RESEARCH_NOTES.md](https://github.com/mjaksn/memlapse/blob/main/docs/RESEARCH_NOTES.md)
+for the reference material behind the detection heuristics and the ideas
+queued for later phases.
+
+Antivirus checks are made mostly when a process starts, which leaves code
+written into a process that is already running unscanned. Sampling a live
+process on a timer covers exactly that gap, and recording the samples lets an
+analyst scrub back to the moment the memory changed.
+
+## Status
+
+- **Phase 1**, live process monitor (sortable, filterable table).
+- **Phase 2**, memory-map view: select a process to see its VirtualQueryEx
+  region map, refreshed every second while on screen; click a region for a
+  hex preview of its bytes.
+- **Phase 3**, record a process's memory map over time to SQLite.
+- **Phase 4**, playback: scrub the recording with the timeline to replay how
+  its regions and footprint evolved.
+- **Phase 6**, injection heuristics: each executable region gets a 0 to 100
+  score (unbacked private or mapped executable memory, RWX, PE header, NOP
+  sled, high entropy, and a thread whose start address lands in memory no
+  image backs) shown as a Score column with a heat tint and a reason tooltip
+  in the region view, banded low, review or likely injection. The top band
+  needs a signal the memory map alone cannot give, so a page that is merely
+  private and RWX, which is what a JIT compiler leaves behind, stops at
+  review. A fourth band, allowlisted, exists for a region whose every scoring
+  rule an entry has excused, but nothing in the app creates an entry yet, so
+  no run of it shows that band. The score also rises for a region whose code
+  was rewritten in place, and again if its entropy fell from packed to
+  code-like, the traces an injector leaves when it overwrites executable
+  memory that already exists and when a payload decrypts itself there. Both
+  work in playback, between consecutive samples, and in live mode, between
+  one refresh and the next. A replay then says more than a live watch can:
+  every score is still the answer for the sample being shown, but a region's
+  tooltip also says how many times the whole recording saw it rewritten and
+  when that last happened, and the timeline carries a tick at each of those
+  samples to scrub to. A region rewritten once, minutes ago, scores nothing
+  now and would otherwise pass for quiet.
+
+- **Dashboard**, a vivid, near-live overview tab: system RAM/swap gauges, a
+  scrolling usage timeline, a heat-ranked top-process list (click to drill into
+  the monitor), leak/anomaly interpretation, and CSV/JSON export of the window.
+
+Next: per-thread memory activity via ETW (Phase 5).
+
+## Use
+
+1. Open the **Forensic Monitor** tab (the app starts on the Dashboard; clicking
+   a process bar there also jumps to the monitor), then select a process (left)
+   to inspect its live memory map (right).
+2. Click **● Record** to sample it over time; **■ Stop** when done. Right-click
+   a region to save its bytes for a disassembler or a YARA rule.
+3. **Open Recording ▾** → pick a recording to enter playback, then drag the
+   timeline (or press ▶) to replay it. A tick on the timeline is a sample
+   where a region's executable bytes changed, which is where to scrub.
+   **Live** returns to real-time mode.
+
+## Install
+
+Windows only, Python 3.14.
+
+```powershell
+pip install memlapse
+
+memlapse            # live monitor
+memlapse --elevate  # relaunch elevated to read system and other users' processes
+```
+
+`python -m memlapse` runs the same thing. Running elevated enables
+`SeDebugPrivilege`, required to read most system and other-user processes.
+The status bar reports the privilege state when the window opens.
+
+The package accepts a range of versions of its three dependencies. For the
+exact versions it is tested with, each checked against the hashes PyPI
+publishes, install from a checkout instead:
+
+## Run from a checkout
+
+```powershell
+python -m venv .venv
+.venv\Scripts\Activate.ps1
+pip install --require-hashes -r requirements.txt
+
+python main.py            # live monitor
+python main.py --elevate  # relaunch elevated
+```
+
+VS Code and PyCharm each have a plain and an elevated launcher checked in, in
+`.vscode/launch.json` and `.idea/runConfigurations/`. The elevated one takes
+the same `--elevate` path as the command line above: Windows starts a separate
+elevated process through UAC and the one the editor started exits immediately,
+so nothing is left for a debugger to attach to. To debug with privileges,
+start the editor elevated and use the plain launcher, which inherits them.
+
+## Test
+
+```powershell
+pip install -r requirements-dev.txt
+python -m pytest
+```
+
+Dependencies are pinned by version and hash. The requirements files name every
+package with an exact version, and `scripts/lock_hashes.py` writes the hashes
+under each pin from the digests PyPI reports; the top of `requirements.txt`
+says how to move a version.
+
+## Licence
+
+MIT. See [LICENSE](https://github.com/mjaksn/memlapse/blob/main/LICENSE).
+
+Changes are listed in
+[CHANGELOG.md](https://github.com/mjaksn/memlapse/blob/main/CHANGELOG.md).

memlapse-0.1.1/README.md

@@ -0,0 +1,125 @@
+# memlapse
+
+[![CI](https://github.com/mjaksn/memlapse/actions/workflows/ci.yml/badge.svg)](https://github.com/mjaksn/memlapse/actions/workflows/ci.yml)
+[![Release](https://github.com/mjaksn/memlapse/actions/workflows/release.yml/badge.svg)](https://github.com/mjaksn/memlapse/actions/workflows/release.yml)
+[![PyPI](https://img.shields.io/pypi/v/memlapse)](https://pypi.org/project/memlapse/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/mjaksn/memlapse/blob/main/LICENSE)
+
+A Windows memory forensics tool, Process Explorer / System Informer-style
+monitoring, that records a process's memory map over time and replays it.
+Recording and playback of the memory activity of specific threads is the
+planned next phase (Phase 5). See
+[docs/ARCHITECTURE.md](https://github.com/mjaksn/memlapse/blob/main/docs/ARCHITECTURE.md)
+for the design and
+[docs/RESEARCH_NOTES.md](https://github.com/mjaksn/memlapse/blob/main/docs/RESEARCH_NOTES.md)
+for the reference material behind the detection heuristics and the ideas
+queued for later phases.
+
+Antivirus checks are made mostly when a process starts, which leaves code
+written into a process that is already running unscanned. Sampling a live
+process on a timer covers exactly that gap, and recording the samples lets an
+analyst scrub back to the moment the memory changed.
+
+## Status
+
+- **Phase 1**, live process monitor (sortable, filterable table).
+- **Phase 2**, memory-map view: select a process to see its VirtualQueryEx
+  region map, refreshed every second while on screen; click a region for a
+  hex preview of its bytes.
+- **Phase 3**, record a process's memory map over time to SQLite.
+- **Phase 4**, playback: scrub the recording with the timeline to replay how
+  its regions and footprint evolved.
+- **Phase 6**, injection heuristics: each executable region gets a 0 to 100
+  score (unbacked private or mapped executable memory, RWX, PE header, NOP
+  sled, high entropy, and a thread whose start address lands in memory no
+  image backs) shown as a Score column with a heat tint and a reason tooltip
+  in the region view, banded low, review or likely injection. The top band
+  needs a signal the memory map alone cannot give, so a page that is merely
+  private and RWX, which is what a JIT compiler leaves behind, stops at
+  review. A fourth band, allowlisted, exists for a region whose every scoring
+  rule an entry has excused, but nothing in the app creates an entry yet, so
+  no run of it shows that band. The score also rises for a region whose code
+  was rewritten in place, and again if its entropy fell from packed to
+  code-like, the traces an injector leaves when it overwrites executable
+  memory that already exists and when a payload decrypts itself there. Both
+  work in playback, between consecutive samples, and in live mode, between
+  one refresh and the next. A replay then says more than a live watch can:
+  every score is still the answer for the sample being shown, but a region's
+  tooltip also says how many times the whole recording saw it rewritten and
+  when that last happened, and the timeline carries a tick at each of those
+  samples to scrub to. A region rewritten once, minutes ago, scores nothing
+  now and would otherwise pass for quiet.
+
+- **Dashboard**, a vivid, near-live overview tab: system RAM/swap gauges, a
+  scrolling usage timeline, a heat-ranked top-process list (click to drill into
+  the monitor), leak/anomaly interpretation, and CSV/JSON export of the window.
+
+Next: per-thread memory activity via ETW (Phase 5).
+
+## Use
+
+1. Open the **Forensic Monitor** tab (the app starts on the Dashboard; clicking
+   a process bar there also jumps to the monitor), then select a process (left)
+   to inspect its live memory map (right).
+2. Click **● Record** to sample it over time; **■ Stop** when done. Right-click
+   a region to save its bytes for a disassembler or a YARA rule.
+3. **Open Recording ▾** → pick a recording to enter playback, then drag the
+   timeline (or press ▶) to replay it. A tick on the timeline is a sample
+   where a region's executable bytes changed, which is where to scrub.
+   **Live** returns to real-time mode.
+
+## Install
+
+Windows only, Python 3.14.
+
+```powershell
+pip install memlapse
+
+memlapse            # live monitor
+memlapse --elevate  # relaunch elevated to read system and other users' processes
+```
+
+`python -m memlapse` runs the same thing. Running elevated enables
+`SeDebugPrivilege`, required to read most system and other-user processes.
+The status bar reports the privilege state when the window opens.
+
+The package accepts a range of versions of its three dependencies. For the
+exact versions it is tested with, each checked against the hashes PyPI
+publishes, install from a checkout instead:
+
+## Run from a checkout
+
+```powershell
+python -m venv .venv
+.venv\Scripts\Activate.ps1
+pip install --require-hashes -r requirements.txt
+
+python main.py            # live monitor
+python main.py --elevate  # relaunch elevated
+```
+
+VS Code and PyCharm each have a plain and an elevated launcher checked in, in
+`.vscode/launch.json` and `.idea/runConfigurations/`. The elevated one takes
+the same `--elevate` path as the command line above: Windows starts a separate
+elevated process through UAC and the one the editor started exits immediately,
+so nothing is left for a debugger to attach to. To debug with privileges,
+start the editor elevated and use the plain launcher, which inherits them.
+
+## Test
+
+```powershell
+pip install -r requirements-dev.txt
+python -m pytest
+```
+
+Dependencies are pinned by version and hash. The requirements files name every
+package with an exact version, and `scripts/lock_hashes.py` writes the hashes
+under each pin from the digests PyPI reports; the top of `requirements.txt`
+says how to move a version.
+
+## Licence
+
+MIT. See [LICENSE](https://github.com/mjaksn/memlapse/blob/main/LICENSE).
+
+Changes are listed in
+[CHANGELOG.md](https://github.com/mjaksn/memlapse/blob/main/CHANGELOG.md).

memlapse-0.1.1/memlapse/__init__.py

@@ -0,0 +1,8 @@
+"""memlapse, a Windows memory forensics tool.
+
+Process Explorer / System Informer-style monitoring with recording and
+playback of a process's memory map over time, and a per-region injection
+score. Per-thread attribution via ETW is planned (see docs/ARCHITECTURE.md).
+"""
+
+__version__ = "0.1.1"

memlapse-0.1.1/memlapse/__main__.py

@@ -0,0 +1,8 @@
+"""Run memlapse with ``python -m memlapse`` (add --elevate for admin)."""
+
+from __future__ import annotations
+
+from .app import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())