lockstep-evidence 0.1.0__tar.gz

lockstep_evidence-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ritish Saini
+
+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.

lockstep_evidence-0.1.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: lockstep-evidence
+Version: 0.1.0
+Summary: Does what's actually installed match the lockfile? Runtime dependency drift, not just a commit-time CVE scan.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/MaXiMo000/lockstep
+Project-URL: Source, https://github.com/MaXiMo000/lockstep
+Project-URL: Issues, https://github.com/MaXiMo000/lockstep/issues
+Project-URL: Changelog, https://github.com/MaXiMo000/lockstep/releases
+Keywords: dependencies,drift,supply-chain,evidence,reliability,pip
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# lockstep
+
+[![ci](https://github.com/MaXiMo000/lockstep/actions/workflows/ci.yml/badge.svg)](https://github.com/MaXiMo000/lockstep/actions/workflows/ci.yml)
+
+**Does what's actually installed match the lockfile? Runtime dependency
+drift, not a commit-time CVE scan.**
+
+[`carabiner`](https://github.com/MaXiMo000/carabiner)'s `deps` engine
+answers "does the lockfile *committed to this repo* have a known CVE" --
+a question about the source tree, checked in CI. `lockstep` answers a
+different one: does the environment actually *running right now* --
+the container, the server, the venv someone SSHed into and patched by
+hand -- still match what that lockfile says should be there. A CVE scan
+at commit time can't see drift that happens after deploy; this is built
+specifically to.
+
+```
+$ lockstep check requirements.lock
+[!=] 'click' is pinned to 8.0.0 but 8.1.3 is installed
+[--] 'requests' is pinned to 2.31.0 but is not installed
+[++] 'pip' 24.0 is installed but not declared anywhere in the lockfile
+
+0/3 matched, 3 drifted
+```
+
+(Real output, from a real venv.)
+
+## Install
+
+```
+pip install lockstep-evidence   # the command it installs is `lockstep`
+```
+
+(`lockstep` was already taken on PyPI -- same story as every sibling in
+this portfolio.)
+
+## Use
+
+Run it **inside** the environment you want to verify -- the container at
+runtime, the deployed server, the venv itself -- against a lockfile:
+
+```
+lockstep check requirements.lock
+```
+
+It reads the *running interpreter's own* installed-package metadata
+(`importlib.metadata`, stdlib, no subprocess) and compares it against the
+lockfile. `--json` prints the full machine-readable report; `--quiet-matched`
+hides packages that already match, showing only drift.
+
+## Three kinds of drift, not one
+
+| Status | Meaning |
+|---|---|
+| `matched` | Installed version equals the locked version. |
+| `version_mismatch` | Installed, but a different version than declared. |
+| `missing` | Declared in the lockfile, not installed at all. |
+| `extra` | Installed, but the lockfile says nothing about it. |
+
+`extra` is the headline case: the hotfix someone `pip install`ed directly
+on a live server that never made it back into the lockfile, silently
+outliving the deploy that was supposed to make it official. A commit-time
+scan of the lockfile alone can never see this -- by the time it exists,
+the running environment and the committed lockfile have already diverged.
+
+Exit code is `1` if anything drifted, `0` if every declared package
+matches exactly.
+
+## What this assumes
+
+**A fully-pinned lockfile** -- the output of `pip freeze`, `pip-compile`,
+or `poetry export`, every direct *and transitive* dependency pinned to an
+exact version. Not a hand-written `requirements.txt` listing only your
+own top-level packages. If you point this at a partial file, every
+transitive dependency pip installed on its own behalf (which never
+appears in a partial file) reports as `extra` -- correct, technically, but
+noise that drowns the real signal. That's a lockfile-completeness problem
+this tool surfaces, not a bug in it.
+
+## Not the same question as `pip check`
+
+`pip check` already ships with pip, and answers the obvious first
+question: are the packages *currently installed* internally consistent
+with each other's own declared requirements (nothing needs `foo>=2.0`
+while `foo 1.0` is what's actually there)? It never reads a lockfile at
+all -- it can't tell you whether reality matches what you *intended* to
+have installed, only whether what's installed is self-consistent right
+now. An environment can pass `pip check` cleanly while still being three
+versions behind its own lockfile, or running a hotfixed package the
+lockfile has never heard of -- exactly lockstep's `extra` case, above.
+
+The two are complementary, not competing: `pip check` catches a broken
+dependency graph; `lockstep check` catches drift from your own declared
+source of truth. Worth running both -- neither substitutes for the
+other, and `pip check` costs nothing extra since it's already there.
+
+## What this does NOT do
+
+- **Python only, via `pip`/PyPI metadata.** `carabiner`'s own `deps.py`
+  docstring makes the same call for the same reason: "the plan called for
+  pip-audit, npm audit and osv-scanner... it gets one" -- one ecosystem
+  done correctly beats three done shallowly. npm/Cargo/etc. runtime drift
+  is the same idea, applied to a different package manager; not built here.
+- **No CVE data, no severity, no vulnerability database.** That's
+  `carabiner`'s `deps` engine's job already, at commit time. This only
+  asks "does reality match the declaration," not "is the declared version
+  itself safe" -- genuinely different questions, and conflating them would
+  duplicate an engine that already exists and does that one well.
+- **Doesn't distinguish a top-level `extra` from a transitive one.** Real
+  dependency-tree resolution (which package pulled in which) is
+  `pip-compile`-level complexity; out of scope for what's meant to be a
+  small, fast check.
+
+## Tests
+
+```
+pip install -e .
+python tests/test_names.py       # PEP 503 name normalization
+python tests/test_parse.py       # lockfile parsing -- extras, ===, hashes, markers
+python tests/test_installed.py   # reads THIS interpreter's real installed packages
+python tests/test_check.py       # matched/version_mismatch/missing/extra classification
+python tests/test_cli.py         # the real CLI, against this real environment
+```
+
+35 tests. Several exist because testing against real `pip-compile` output
+shapes (not synthetic `"package==1.2.3"` lines) caught real parsing bugs
+during development: PEP 440's `===` arbitrary-equality operator being
+mangled by a regex that matched `==` first and left a stray `=` on the
+version, and `package[extra]==1.2.3` syntax needing to be handled
+explicitly rather than assumed away.
+
+MIT licensed.

lockstep_evidence-0.1.0/README.md

@@ -0,0 +1,132 @@
+# lockstep
+
+[![ci](https://github.com/MaXiMo000/lockstep/actions/workflows/ci.yml/badge.svg)](https://github.com/MaXiMo000/lockstep/actions/workflows/ci.yml)
+
+**Does what's actually installed match the lockfile? Runtime dependency
+drift, not a commit-time CVE scan.**
+
+[`carabiner`](https://github.com/MaXiMo000/carabiner)'s `deps` engine
+answers "does the lockfile *committed to this repo* have a known CVE" --
+a question about the source tree, checked in CI. `lockstep` answers a
+different one: does the environment actually *running right now* --
+the container, the server, the venv someone SSHed into and patched by
+hand -- still match what that lockfile says should be there. A CVE scan
+at commit time can't see drift that happens after deploy; this is built
+specifically to.
+
+```
+$ lockstep check requirements.lock
+[!=] 'click' is pinned to 8.0.0 but 8.1.3 is installed
+[--] 'requests' is pinned to 2.31.0 but is not installed
+[++] 'pip' 24.0 is installed but not declared anywhere in the lockfile
+
+0/3 matched, 3 drifted
+```
+
+(Real output, from a real venv.)
+
+## Install
+
+```
+pip install lockstep-evidence   # the command it installs is `lockstep`
+```
+
+(`lockstep` was already taken on PyPI -- same story as every sibling in
+this portfolio.)
+
+## Use
+
+Run it **inside** the environment you want to verify -- the container at
+runtime, the deployed server, the venv itself -- against a lockfile:
+
+```
+lockstep check requirements.lock
+```
+
+It reads the *running interpreter's own* installed-package metadata
+(`importlib.metadata`, stdlib, no subprocess) and compares it against the
+lockfile. `--json` prints the full machine-readable report; `--quiet-matched`
+hides packages that already match, showing only drift.
+
+## Three kinds of drift, not one
+
+| Status | Meaning |
+|---|---|
+| `matched` | Installed version equals the locked version. |
+| `version_mismatch` | Installed, but a different version than declared. |
+| `missing` | Declared in the lockfile, not installed at all. |
+| `extra` | Installed, but the lockfile says nothing about it. |
+
+`extra` is the headline case: the hotfix someone `pip install`ed directly
+on a live server that never made it back into the lockfile, silently
+outliving the deploy that was supposed to make it official. A commit-time
+scan of the lockfile alone can never see this -- by the time it exists,
+the running environment and the committed lockfile have already diverged.
+
+Exit code is `1` if anything drifted, `0` if every declared package
+matches exactly.
+
+## What this assumes
+
+**A fully-pinned lockfile** -- the output of `pip freeze`, `pip-compile`,
+or `poetry export`, every direct *and transitive* dependency pinned to an
+exact version. Not a hand-written `requirements.txt` listing only your
+own top-level packages. If you point this at a partial file, every
+transitive dependency pip installed on its own behalf (which never
+appears in a partial file) reports as `extra` -- correct, technically, but
+noise that drowns the real signal. That's a lockfile-completeness problem
+this tool surfaces, not a bug in it.
+
+## Not the same question as `pip check`
+
+`pip check` already ships with pip, and answers the obvious first
+question: are the packages *currently installed* internally consistent
+with each other's own declared requirements (nothing needs `foo>=2.0`
+while `foo 1.0` is what's actually there)? It never reads a lockfile at
+all -- it can't tell you whether reality matches what you *intended* to
+have installed, only whether what's installed is self-consistent right
+now. An environment can pass `pip check` cleanly while still being three
+versions behind its own lockfile, or running a hotfixed package the
+lockfile has never heard of -- exactly lockstep's `extra` case, above.
+
+The two are complementary, not competing: `pip check` catches a broken
+dependency graph; `lockstep check` catches drift from your own declared
+source of truth. Worth running both -- neither substitutes for the
+other, and `pip check` costs nothing extra since it's already there.
+
+## What this does NOT do
+
+- **Python only, via `pip`/PyPI metadata.** `carabiner`'s own `deps.py`
+  docstring makes the same call for the same reason: "the plan called for
+  pip-audit, npm audit and osv-scanner... it gets one" -- one ecosystem
+  done correctly beats three done shallowly. npm/Cargo/etc. runtime drift
+  is the same idea, applied to a different package manager; not built here.
+- **No CVE data, no severity, no vulnerability database.** That's
+  `carabiner`'s `deps` engine's job already, at commit time. This only
+  asks "does reality match the declaration," not "is the declared version
+  itself safe" -- genuinely different questions, and conflating them would
+  duplicate an engine that already exists and does that one well.
+- **Doesn't distinguish a top-level `extra` from a transitive one.** Real
+  dependency-tree resolution (which package pulled in which) is
+  `pip-compile`-level complexity; out of scope for what's meant to be a
+  small, fast check.
+
+## Tests
+
+```
+pip install -e .
+python tests/test_names.py       # PEP 503 name normalization
+python tests/test_parse.py       # lockfile parsing -- extras, ===, hashes, markers
+python tests/test_installed.py   # reads THIS interpreter's real installed packages
+python tests/test_check.py       # matched/version_mismatch/missing/extra classification
+python tests/test_cli.py         # the real CLI, against this real environment
+```
+
+35 tests. Several exist because testing against real `pip-compile` output
+shapes (not synthetic `"package==1.2.3"` lines) caught real parsing bugs
+during development: PEP 440's `===` arbitrary-equality operator being
+mangled by a regex that matched `==` first and left a stray `=` on the
+version, and `package[extra]==1.2.3` syntax needing to be handled
+explicitly rather than assumed away.
+
+MIT licensed.

lockstep_evidence-0.1.0/lockstep/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

lockstep_evidence-0.1.0/lockstep/check.py

@@ -0,0 +1,52 @@
+"""Compare a lockfile's pinned versions against what's actually installed.
+
+Three distinct kinds of drift, not one blended "different" bucket, because
+each implies a different fix: a version_mismatch means re-pin or
+reinstall; missing means something never got installed; extra means an
+undeclared package is present -- the case this tool exists for, the patch
+someone installed by hand on a live server that never made it back into
+the lockfile.
+"""
+from __future__ import annotations
+
+MATCHED, VERSION_MISMATCH, MISSING, EXTRA = "matched", "version_mismatch", "missing", "extra"
+
+
+def check_drift(lockfile: dict, installed: dict[str, str]) -> list[dict]:
+    pinned = lockfile["pinned"]
+    results = []
+
+    for name in sorted(pinned):
+        locked_version = pinned[name]
+        actual_version = installed.get(name)
+        if actual_version is None:
+            results.append({
+                "name": name, "status": MISSING,
+                "locked_version": locked_version, "installed_version": None,
+                "detail": f"'{name}' is pinned to {locked_version} but is not installed",
+            })
+        elif actual_version != locked_version:
+            results.append({
+                "name": name, "status": VERSION_MISMATCH,
+                "locked_version": locked_version, "installed_version": actual_version,
+                "detail": (f"'{name}' is pinned to {locked_version} but "
+                           f"{actual_version} is installed"),
+            })
+        else:
+            results.append({
+                "name": name, "status": MATCHED,
+                "locked_version": locked_version, "installed_version": actual_version,
+                "detail": f"'{name}' matches its locked version {locked_version}",
+            })
+
+    declared = set(pinned) | set(lockfile.get("unpinned", ()))
+    for name in sorted(installed):
+        if name not in declared:
+            results.append({
+                "name": name, "status": EXTRA,
+                "locked_version": None, "installed_version": installed[name],
+                "detail": (f"'{name}' {installed[name]} is installed but not declared "
+                           "anywhere in the lockfile"),
+            })
+
+    return results

lockstep_evidence-0.1.0/lockstep/cli.py

@@ -0,0 +1,54 @@
+"""lockstep check <lockfile> [--json] [--quiet-matched]"""
+from __future__ import annotations
+
+import argparse
+import json
+import pathlib
+import sys
+
+from .check import EXTRA, MATCHED, MISSING, VERSION_MISMATCH, check_drift
+from .installed import installed_packages
+from .parse import parse_lockfile
+
+_TAG = {MATCHED: "OK", VERSION_MISMATCH: "!=", MISSING: "--", EXTRA: "++"}
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="lockstep")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    check_p = sub.add_parser(
+        "check", help="compare this environment's installed packages against a pinned lockfile")
+    check_p.add_argument("lockfile", help="a fully-pinned lockfile -- see README's \"What this assumes\"")
+    check_p.add_argument("--json", action="store_true", help="print the full report as JSON")
+    check_p.add_argument("--quiet-matched", action="store_true",
+                          help="only print drift, not every package that already matches")
+
+    args = parser.parse_args(argv)
+
+    try:
+        text = pathlib.Path(args.lockfile).read_text(encoding="utf-8")
+    except OSError as exc:
+        sys.exit(f"lockstep: {exc}")
+
+    lockfile = parse_lockfile(text)
+    results = check_drift(lockfile, installed_packages())
+
+    if args.json:
+        print(json.dumps(results, indent=2))
+    else:
+        for r in results:
+            if args.quiet_matched and r["status"] == MATCHED:
+                continue
+            print(f"[{_TAG[r['status']]}] {r['detail']}")
+        n_drift = sum(1 for r in results if r["status"] != MATCHED)
+        summary = f"{len(results) - n_drift}/{len(results)} matched"
+        if n_drift:
+            summary += f", {n_drift} drifted"
+        print(f"\n{summary}")
+
+    return 1 if any(r["status"] != MATCHED for r in results) else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

lockstep_evidence-0.1.0/lockstep/installed.py

@@ -0,0 +1,23 @@
+"""What's actually installed in the running Python environment, right now.
+
+Not a second parse of anything -- `importlib.metadata` is the interpreter's
+own view of itself, stdlib, no subprocess needed. Run `lockstep check`
+*inside* the environment you want to verify (the container, the venv, the
+deployed server) so this reflects that environment, not the one lockstep
+itself happens to be installed in.
+"""
+from __future__ import annotations
+
+from importlib import metadata
+
+from .names import normalize
+
+
+def installed_packages() -> dict[str, str]:
+    result: dict[str, str] = {}
+    for dist in metadata.distributions():
+        name = dist.metadata.get("Name")
+        if not name:
+            continue  # a distribution with no name in its own metadata -- skip, not a crash
+        result[normalize(name)] = dist.version
+    return result

lockstep_evidence-0.1.0/lockstep/names.py

@@ -0,0 +1,16 @@
+"""PEP 503 name normalization: pip, PyPI, and importlib.metadata all agree
+that "Flask-Login", "flask_login", and "FLASK.LOGIN" name the same
+distribution. Comparing a lockfile's spelling against the installed
+environment's spelling without this would report real matches as drift
+purely from formatting, which is worse than missing a real one -- it
+teaches whoever runs this to stop trusting the output.
+"""
+from __future__ import annotations
+
+import re
+
+_SEPARATORS = re.compile(r"[-_.]+")
+
+
+def normalize(name: str) -> str:
+    return _SEPARATORS.sub("-", name).strip().lower()

lockstep_evidence-0.1.0/lockstep/parse.py

@@ -0,0 +1,67 @@
+"""Parse a pinned requirements.txt-style lockfile into
+{"pinned": {name: version}, "unpinned": [name, ...]}.
+
+Only an exact pin (`package==1.2.3`) declares a single version runtime
+could drift from -- a range (`package>=1.0`) or a bare name doesn't, so
+those are recorded separately as "unpinned" rather than silently ignored
+(which would make them read as untracked "extra" packages later) or
+treated as a false pinned match.
+
+lockstep assumes a **fully-pinned** lockfile -- the output of `pip freeze`,
+`pip-compile`, or `poetry export`, every direct and transitive dependency
+pinned -- not a hand-written requirements.txt listing only top-level
+packages. See README's "What this assumes" for why: pip installs
+transitive dependencies that never appear in a partial file, and every one
+of them would otherwise report as "extra" for no reason but the lockfile
+being incomplete.
+"""
+from __future__ import annotations
+
+import re
+
+from .names import normalize
+
+# Extras (`requests[security]`) and environment markers (`; python_version
+# >= "3.8"`) are both real, common syntax in a real requirements file --
+# found by testing this against actual pip-compile output, not synthetic
+# "package==1.2.3" lines alone.
+_PIN = re.compile(
+    r'^([A-Za-z0-9][A-Za-z0-9._-]*)'   # name
+    r'(?:\[[^\]]*\])?'                  # optional extras, e.g. [security]
+    r'\s*(?:===|==)\s*'                  # PEP 440 arbitrary-equality (===) tried
+    r'([^\s;#]+)'                       # first, or == would eat two of its three '='
+)
+_RANGE_OP = re.compile(
+    r'^([A-Za-z0-9][A-Za-z0-9._-]*)(?:\[[^\]]*\])?\s*(?:>=|<=|!=|~=|>|<)'
+)
+_BARE_NAME = re.compile(r'^([A-Za-z0-9][A-Za-z0-9._-]*)(?:\[[^\]]*\])?\s*$')
+
+
+def parse_lockfile(text: str) -> dict:
+    pinned: dict[str, str] = {}
+    unpinned: list[str] = []
+
+    for raw_line in text.splitlines():
+        # Environment markers and inline comments both trail after the
+        # version; strip the comment first so a marker doesn't hide behind
+        # it, then let each pattern's own [^\s;#]+ stop at a marker.
+        line = raw_line.split("#", 1)[0].strip()
+        if not line or line.startswith("-"):
+            continue  # blank, or a pip option line (-r other.txt, --index-url ...)
+
+        m = _PIN.match(line)
+        if m:
+            name, version = m.groups()
+            pinned[normalize(name)] = version
+            continue
+
+        m = _RANGE_OP.match(line)
+        if m:
+            unpinned.append(normalize(m.group(1)))
+            continue
+
+        m = _BARE_NAME.match(line)
+        if m:
+            unpinned.append(normalize(m.group(1)))
+
+    return {"pinned": pinned, "unpinned": unpinned}

lockstep_evidence-0.1.0/lockstep_evidence.egg-info/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: lockstep-evidence
+Version: 0.1.0
+Summary: Does what's actually installed match the lockfile? Runtime dependency drift, not just a commit-time CVE scan.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/MaXiMo000/lockstep
+Project-URL: Source, https://github.com/MaXiMo000/lockstep
+Project-URL: Issues, https://github.com/MaXiMo000/lockstep/issues
+Project-URL: Changelog, https://github.com/MaXiMo000/lockstep/releases
+Keywords: dependencies,drift,supply-chain,evidence,reliability,pip
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# lockstep
+
+[![ci](https://github.com/MaXiMo000/lockstep/actions/workflows/ci.yml/badge.svg)](https://github.com/MaXiMo000/lockstep/actions/workflows/ci.yml)
+
+**Does what's actually installed match the lockfile? Runtime dependency
+drift, not a commit-time CVE scan.**
+
+[`carabiner`](https://github.com/MaXiMo000/carabiner)'s `deps` engine
+answers "does the lockfile *committed to this repo* have a known CVE" --
+a question about the source tree, checked in CI. `lockstep` answers a
+different one: does the environment actually *running right now* --
+the container, the server, the venv someone SSHed into and patched by
+hand -- still match what that lockfile says should be there. A CVE scan
+at commit time can't see drift that happens after deploy; this is built
+specifically to.
+
+```
+$ lockstep check requirements.lock
+[!=] 'click' is pinned to 8.0.0 but 8.1.3 is installed
+[--] 'requests' is pinned to 2.31.0 but is not installed
+[++] 'pip' 24.0 is installed but not declared anywhere in the lockfile
+
+0/3 matched, 3 drifted
+```
+
+(Real output, from a real venv.)
+
+## Install
+
+```
+pip install lockstep-evidence   # the command it installs is `lockstep`
+```
+
+(`lockstep` was already taken on PyPI -- same story as every sibling in
+this portfolio.)
+
+## Use
+
+Run it **inside** the environment you want to verify -- the container at
+runtime, the deployed server, the venv itself -- against a lockfile:
+
+```
+lockstep check requirements.lock
+```
+
+It reads the *running interpreter's own* installed-package metadata
+(`importlib.metadata`, stdlib, no subprocess) and compares it against the
+lockfile. `--json` prints the full machine-readable report; `--quiet-matched`
+hides packages that already match, showing only drift.
+
+## Three kinds of drift, not one
+
+| Status | Meaning |
+|---|---|
+| `matched` | Installed version equals the locked version. |
+| `version_mismatch` | Installed, but a different version than declared. |
+| `missing` | Declared in the lockfile, not installed at all. |
+| `extra` | Installed, but the lockfile says nothing about it. |
+
+`extra` is the headline case: the hotfix someone `pip install`ed directly
+on a live server that never made it back into the lockfile, silently
+outliving the deploy that was supposed to make it official. A commit-time
+scan of the lockfile alone can never see this -- by the time it exists,
+the running environment and the committed lockfile have already diverged.
+
+Exit code is `1` if anything drifted, `0` if every declared package
+matches exactly.
+
+## What this assumes
+
+**A fully-pinned lockfile** -- the output of `pip freeze`, `pip-compile`,
+or `poetry export`, every direct *and transitive* dependency pinned to an
+exact version. Not a hand-written `requirements.txt` listing only your
+own top-level packages. If you point this at a partial file, every
+transitive dependency pip installed on its own behalf (which never
+appears in a partial file) reports as `extra` -- correct, technically, but
+noise that drowns the real signal. That's a lockfile-completeness problem
+this tool surfaces, not a bug in it.
+
+## Not the same question as `pip check`
+
+`pip check` already ships with pip, and answers the obvious first
+question: are the packages *currently installed* internally consistent
+with each other's own declared requirements (nothing needs `foo>=2.0`
+while `foo 1.0` is what's actually there)? It never reads a lockfile at
+all -- it can't tell you whether reality matches what you *intended* to
+have installed, only whether what's installed is self-consistent right
+now. An environment can pass `pip check` cleanly while still being three
+versions behind its own lockfile, or running a hotfixed package the
+lockfile has never heard of -- exactly lockstep's `extra` case, above.
+
+The two are complementary, not competing: `pip check` catches a broken
+dependency graph; `lockstep check` catches drift from your own declared
+source of truth. Worth running both -- neither substitutes for the
+other, and `pip check` costs nothing extra since it's already there.
+
+## What this does NOT do
+
+- **Python only, via `pip`/PyPI metadata.** `carabiner`'s own `deps.py`
+  docstring makes the same call for the same reason: "the plan called for
+  pip-audit, npm audit and osv-scanner... it gets one" -- one ecosystem
+  done correctly beats three done shallowly. npm/Cargo/etc. runtime drift
+  is the same idea, applied to a different package manager; not built here.
+- **No CVE data, no severity, no vulnerability database.** That's
+  `carabiner`'s `deps` engine's job already, at commit time. This only
+  asks "does reality match the declaration," not "is the declared version
+  itself safe" -- genuinely different questions, and conflating them would
+  duplicate an engine that already exists and does that one well.
+- **Doesn't distinguish a top-level `extra` from a transitive one.** Real
+  dependency-tree resolution (which package pulled in which) is
+  `pip-compile`-level complexity; out of scope for what's meant to be a
+  small, fast check.
+
+## Tests
+
+```
+pip install -e .
+python tests/test_names.py       # PEP 503 name normalization
+python tests/test_parse.py       # lockfile parsing -- extras, ===, hashes, markers
+python tests/test_installed.py   # reads THIS interpreter's real installed packages
+python tests/test_check.py       # matched/version_mismatch/missing/extra classification
+python tests/test_cli.py         # the real CLI, against this real environment
+```
+
+35 tests. Several exist because testing against real `pip-compile` output
+shapes (not synthetic `"package==1.2.3"` lines) caught real parsing bugs
+during development: PEP 440's `===` arbitrary-equality operator being
+mangled by a regex that matched `==` first and left a stray `=` on the
+version, and `package[extra]==1.2.3` syntax needing to be handled
+explicitly rather than assumed away.
+
+MIT licensed.

lockstep_evidence-0.1.0/lockstep_evidence.egg-info/SOURCES.txt

@@ -0,0 +1,19 @@
+LICENSE
+README.md
+pyproject.toml
+lockstep/__init__.py
+lockstep/check.py
+lockstep/cli.py
+lockstep/installed.py
+lockstep/names.py
+lockstep/parse.py
+lockstep_evidence.egg-info/PKG-INFO
+lockstep_evidence.egg-info/SOURCES.txt
+lockstep_evidence.egg-info/dependency_links.txt
+lockstep_evidence.egg-info/entry_points.txt
+lockstep_evidence.egg-info/top_level.txt
+tests/test_check.py
+tests/test_cli.py
+tests/test_installed.py
+tests/test_names.py
+tests/test_parse.py

lockstep_evidence-0.1.0/lockstep_evidence.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

lockstep_evidence-0.1.0/lockstep_evidence.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+lockstep = lockstep.cli:main

lockstep_evidence-0.1.0/lockstep_evidence.egg-info/top_level.txt

@@ -0,0 +1 @@
+lockstep

lockstep_evidence-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+# "lockstep" was already taken on PyPI, same story as every sibling in
+# this portfolio. The installed command stays the short name --
+# python-dateutil installs `dateutil`, this installs `lockstep`.
+name = "lockstep-evidence"
+version = "0.1.0"
+description = "Does what's actually installed match the lockfile? Runtime dependency drift, not just a commit-time CVE scan."
+requires-python = ">=3.10"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["dependencies", "drift", "supply-chain", "evidence", "reliability", "pip"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: System Administrators",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: System :: Systems Administration",
+]
+# Stdlib only -- importlib.metadata reads the running interpreter's own
+# installed-package data directly, no subprocess or extra parser needed.
+dependencies = []
+
+urls.Homepage = "https://github.com/MaXiMo000/lockstep"
+urls.Source = "https://github.com/MaXiMo000/lockstep"
+urls.Issues = "https://github.com/MaXiMo000/lockstep/issues"
+urls.Changelog = "https://github.com/MaXiMo000/lockstep/releases"
+
+[project.scripts]
+lockstep = "lockstep.cli:main"
+
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["lockstep*"]

lockstep_evidence-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

lockstep_evidence-0.1.0/tests/test_check.py

@@ -0,0 +1,84 @@
+"""Run: python tests/test_check.py"""
+from __future__ import annotations
+
+import pathlib
+import sys
+import unittest
+
+sys.path.insert(0, str(pathlib.Path(__file__).parent.parent))
+
+from lockstep.check import EXTRA, MATCHED, MISSING, VERSION_MISMATCH, check_drift
+
+
+class TestCheckDrift(unittest.TestCase):
+    def test_exact_match(self):
+        lockfile = {"pinned": {"requests": "2.31.0"}, "unpinned": []}
+        installed = {"requests": "2.31.0"}
+        results = check_drift(lockfile, installed)
+        self.assertEqual(results, [{
+            "name": "requests", "status": MATCHED,
+            "locked_version": "2.31.0", "installed_version": "2.31.0",
+            "detail": "'requests' matches its locked version 2.31.0",
+        }])
+
+    def test_version_mismatch(self):
+        lockfile = {"pinned": {"requests": "2.31.0"}, "unpinned": []}
+        installed = {"requests": "2.28.0"}
+        results = check_drift(lockfile, installed)
+        self.assertEqual(results[0]["status"], VERSION_MISMATCH)
+        self.assertEqual(results[0]["installed_version"], "2.28.0")
+
+    def test_pinned_but_not_installed_is_missing(self):
+        lockfile = {"pinned": {"requests": "2.31.0"}, "unpinned": []}
+        results = check_drift(lockfile, installed={})
+        self.assertEqual(results[0]["status"], MISSING)
+        self.assertIsNone(results[0]["installed_version"])
+
+    def test_installed_but_undeclared_is_extra(self):
+        """The headline case this tool exists for: a package present on
+        disk that the lockfile says nothing about at all."""
+        lockfile = {"pinned": {}, "unpinned": []}
+        installed = {"some-hotfix-package": "0.0.1"}
+        results = check_drift(lockfile, installed)
+        self.assertEqual(results[0]["status"], EXTRA)
+        self.assertEqual(results[0]["installed_version"], "0.0.1")
+
+    def test_unpinned_declared_package_is_not_reported_as_extra(self):
+        """A range/bare-name entry in the lockfile still counts as
+        'declared' for the extra check, even though it has no version to
+        compare against for drift."""
+        lockfile = {"pinned": {}, "unpinned": ["click"]}
+        installed = {"click": "8.1.3"}
+        results = check_drift(lockfile, installed)
+        self.assertEqual(results, [])
+
+    def test_names_normalized_on_both_sides_still_match(self):
+        lockfile = {"pinned": {"flask-login": "0.6.2"}, "unpinned": []}
+        installed = {"flask-login": "0.6.2"}  # already normalized, as installed_packages() gives it
+        results = check_drift(lockfile, installed)
+        self.assertEqual(results[0]["status"], MATCHED)
+
+    def test_results_are_sorted_by_name_deterministically(self):
+        lockfile = {"pinned": {"zeta": "1.0", "alpha": "1.0"}, "unpinned": []}
+        installed = {"zeta": "1.0", "alpha": "1.0"}
+        results = check_drift(lockfile, installed)
+        self.assertEqual([r["name"] for r in results], ["alpha", "zeta"])
+
+    def test_mixed_real_scenario(self):
+        lockfile = {"pinned": {"requests": "2.31.0", "click": "8.1.3"}, "unpinned": ["numpy"]}
+        installed = {
+            "requests": "2.31.0",       # matched
+            "click": "8.0.0",           # version_mismatch
+            "numpy": "1.24.0",          # declared unpinned, no drift possible
+            "sneaky-hotfix": "0.1.0",   # extra
+            # "flask" (if it were pinned) would be missing -- not in this scenario
+        }
+        results = check_drift(lockfile, installed)
+        by_name = {r["name"]: r["status"] for r in results}
+        self.assertEqual(by_name, {
+            "requests": MATCHED, "click": VERSION_MISMATCH, "sneaky-hotfix": EXTRA,
+        })
+
+
+if __name__ == "__main__":
+    unittest.main()

lockstep_evidence-0.1.0/tests/test_cli.py

@@ -0,0 +1,92 @@
+"""Run: python tests/test_cli.py
+
+Exercises the real CLI entry point against the real, currently-running
+Python environment -- not mocked installed-package data -- so this proves
+the whole pipeline (read file -> parse -> introspect this interpreter ->
+diff -> report) actually works end to end.
+"""
+from __future__ import annotations
+
+import contextlib
+import io
+import json
+import pathlib
+import sys
+import tempfile
+import unittest
+
+sys.path.insert(0, str(pathlib.Path(__file__).parent.parent))
+
+from lockstep.cli import main
+from lockstep.installed import installed_packages
+
+
+class TestCli(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.lockfile = pathlib.Path(self.tmp.name) / "requirements.lock"
+
+    def tearDown(self):
+        self.tmp.cleanup()
+
+    def test_correctly_pinned_real_package_matches(self):
+        """pip is installed in this real environment -- pin it to its
+        actual real version and lockstep should say it matches. Checked via
+        --json against pip's specific entry, not the overall exit code:
+        this test runs in a real, un-isolated dev environment with many
+        other installed packages a one-line lockfile never declares, which
+        correctly makes the *overall* result drift (see "What this
+        assumes" in README) -- that's real, intended behavior, not
+        something to work around by asserting a global pass here."""
+        pip_version = installed_packages()["pip"]
+        self.lockfile.write_text(f"pip=={pip_version}\n")
+        buf = io.StringIO()
+        with contextlib.redirect_stdout(buf):
+            main(["check", str(self.lockfile), "--json"])
+        report = json.loads(buf.getvalue())
+        pip_entry = next(r for r in report if r["name"] == "pip")
+        self.assertEqual(pip_entry["status"], "matched")
+
+    def test_wrong_pinned_version_of_a_real_package_is_drift(self):
+        self.lockfile.write_text("pip==0.0.1\n")  # almost certainly not what's really installed
+        buf = io.StringIO()
+        with contextlib.redirect_stdout(buf):
+            code = main(["check", str(self.lockfile)])
+        self.assertEqual(code, 1)
+        self.assertIn("[!=]", buf.getvalue())
+
+    def test_a_package_that_cannot_exist_is_missing(self):
+        self.lockfile.write_text("this-package-definitely-does-not-exist-xyz==1.0.0\n")
+        buf = io.StringIO()
+        with contextlib.redirect_stdout(buf):
+            code = main(["check", str(self.lockfile)])
+        self.assertEqual(code, 1)
+        self.assertIn("[--]", buf.getvalue())
+
+    def test_quiet_matched_hides_ok_rows_but_keeps_drift(self):
+        pip_version = installed_packages()["pip"]
+        self.lockfile.write_text(f"pip=={pip_version}\nthis-does-not-exist-xyz==1.0\n")
+        buf = io.StringIO()
+        with contextlib.redirect_stdout(buf):
+            main(["check", str(self.lockfile), "--quiet-matched"])
+        self.assertNotIn("[OK]", buf.getvalue())
+        self.assertIn("[--]", buf.getvalue())
+
+    def test_missing_lockfile_is_a_clean_error_not_a_traceback(self):
+        with self.assertRaises(SystemExit) as ctx:
+            main(["check", str(self.lockfile)])  # never written
+        self.assertIn("lockstep:", str(ctx.exception))
+
+    def test_json_flag_prints_the_full_report(self):
+        pip_version = installed_packages()["pip"]
+        self.lockfile.write_text(f"pip=={pip_version}\n")
+        buf = io.StringIO()
+        with contextlib.redirect_stdout(buf):
+            main(["check", str(self.lockfile), "--json"])
+        report = json.loads(buf.getvalue())
+        self.assertEqual(report[0]["name"], "pip")
+        self.assertEqual(report[0]["status"], "matched")
+
+
+if __name__ == "__main__":
+    unittest.main()

lockstep_evidence-0.1.0/tests/test_installed.py

@@ -0,0 +1,42 @@
+"""Run: python tests/test_installed.py
+
+Exercises the real importlib.metadata of the interpreter running this
+test -- not a mock -- so this proves installed_packages() actually reads
+real package metadata correctly, not just that it calls the right stdlib
+function.
+"""
+from __future__ import annotations
+
+import pathlib
+import sys
+import unittest
+
+sys.path.insert(0, str(pathlib.Path(__file__).parent.parent))
+
+from lockstep.installed import installed_packages
+
+
+class TestInstalledPackages(unittest.TestCase):
+    def test_pip_itself_is_found(self):
+        """pip is installed in essentially every real Python environment
+        this tool will ever run in -- a safe, real package to assert on
+        rather than a hypothetical one."""
+        packages = installed_packages()
+        self.assertIn("pip", packages)
+        self.assertTrue(packages["pip"])  # a non-empty version string
+
+    def test_all_keys_are_normalized(self):
+        packages = installed_packages()
+        for name in packages:
+            self.assertEqual(name, name.lower())
+            self.assertNotIn("_", name)
+
+    def test_returns_a_real_nonempty_mapping(self):
+        packages = installed_packages()
+        self.assertGreater(len(packages), 0)
+        for version in packages.values():
+            self.assertIsInstance(version, str)
+
+
+if __name__ == "__main__":
+    unittest.main()

lockstep_evidence-0.1.0/tests/test_names.py

@@ -0,0 +1,29 @@
+"""Run: python tests/test_names.py"""
+from __future__ import annotations
+
+import pathlib
+import sys
+import unittest
+
+sys.path.insert(0, str(pathlib.Path(__file__).parent.parent))
+
+from lockstep.names import normalize
+
+
+class TestNormalize(unittest.TestCase):
+    def test_dashes_underscores_dots_are_equivalent(self):
+        self.assertEqual(normalize("Flask-Login"), normalize("flask_login"))
+        self.assertEqual(normalize("flask_login"), normalize("flask.login"))
+
+    def test_case_insensitive(self):
+        self.assertEqual(normalize("Requests"), normalize("REQUESTS"))
+
+    def test_repeated_separators_collapse(self):
+        self.assertEqual(normalize("foo__bar"), normalize("foo-bar"))
+
+    def test_all_together(self):
+        self.assertEqual(normalize("Foo_Bar.Baz"), "foo-bar-baz")
+
+
+if __name__ == "__main__":
+    unittest.main()

lockstep_evidence-0.1.0/tests/test_parse.py

@@ -0,0 +1,102 @@
+"""Run: python tests/test_parse.py
+
+Tested against real pip-compile/pip-freeze output shapes, not just
+synthetic "package==1.2.3" lines -- two real bugs (the === operator, and
+extras syntax) were found exactly this way while building this module.
+"""
+from __future__ import annotations
+
+import pathlib
+import sys
+import unittest
+
+sys.path.insert(0, str(pathlib.Path(__file__).parent.parent))
+
+from lockstep.parse import parse_lockfile
+
+
+class TestParseLockfile(unittest.TestCase):
+    def test_simple_pin(self):
+        result = parse_lockfile("requests==2.31.0\n")
+        self.assertEqual(result["pinned"], {"requests": "2.31.0"})
+        self.assertEqual(result["unpinned"], [])
+
+    def test_names_are_normalized(self):
+        result = parse_lockfile("Flask-Login==0.6.2\n")
+        self.assertEqual(result["pinned"], {"flask-login": "0.6.2"})
+
+    def test_blank_lines_and_comments_are_skipped(self):
+        result = parse_lockfile("\n# a comment\n\nrequests==2.31.0\n")
+        self.assertEqual(result["pinned"], {"requests": "2.31.0"})
+
+    def test_inline_comment_after_a_pin(self):
+        result = parse_lockfile("requests==2.31.0  # via -r requirements.in\n")
+        self.assertEqual(result["pinned"], {"requests": "2.31.0"})
+
+    def test_pip_option_lines_are_skipped(self):
+        text = "-r base.txt\n--index-url https://pypi.org/simple\nrequests==2.31.0\n"
+        result = parse_lockfile(text)
+        self.assertEqual(result["pinned"], {"requests": "2.31.0"})
+
+    def test_hash_pinned_continuation_lines_are_skipped(self):
+        text = "requests==2.31.0 \\\n    --hash=sha256:abc123\n    --hash=sha256:def456\nclick==8.1.3\n"
+        result = parse_lockfile(text)
+        self.assertEqual(result["pinned"], {"requests": "2.31.0", "click": "8.1.3"})
+
+    def test_environment_marker_is_stripped_from_the_version(self):
+        result = parse_lockfile('urllib3==2.0.4 ; python_version >= "3.8"\n')
+        self.assertEqual(result["pinned"], {"urllib3": "2.0.4"})
+
+    def test_extras_syntax_does_not_break_the_pin(self):
+        """requests[security]==2.31.0 -- extras are real, common syntax in
+        a real pip-compile lockfile."""
+        result = parse_lockfile("requests[security]==2.31.0\n")
+        self.assertEqual(result["pinned"], {"requests": "2.31.0"})
+
+    def test_arbitrary_equality_operator_is_not_mangled(self):
+        """attrs===23.1.0 -- PEP 440's arbitrary-equality operator. A regex
+        matching a bare '==' first would eat two of its three '=' and
+        leave a leading '=' stuck on the front of the captured version --
+        a real bug caught by testing this exact operator, not assumed
+        equivalent to '=='."""
+        result = parse_lockfile("attrs===23.1.0\n")
+        self.assertEqual(result["pinned"], {"attrs": "23.1.0"})
+
+    def test_range_specifiers_are_unpinned_not_ignored(self):
+        result = parse_lockfile("click>=8.0\n")
+        self.assertEqual(result["pinned"], {})
+        self.assertEqual(result["unpinned"], ["click"])
+
+    def test_bare_name_with_no_operator_is_unpinned(self):
+        result = parse_lockfile("numpy\n")
+        self.assertEqual(result["unpinned"], ["numpy"])
+
+    def test_compatible_release_operator_is_unpinned(self):
+        result = parse_lockfile("django~=4.2\n")
+        self.assertEqual(result["unpinned"], ["django"])
+
+    def test_empty_file_is_nothing_not_an_error(self):
+        result = parse_lockfile("")
+        self.assertEqual(result, {"pinned": {}, "unpinned": []})
+
+    def test_a_realistic_mixed_file(self):
+        text = (
+            "# autogenerated by pip-compile\n"
+            "--index-url https://pypi.org/simple\n"
+            "\n"
+            "requests==2.31.0\n"
+            "    # via -r requirements.in\n"
+            'urllib3==2.0.4 ; python_version >= "3.8"\n'
+            "attrs===23.1.0\n"
+            "click>=8.0\n"
+            "numpy\n"
+        )
+        result = parse_lockfile(text)
+        self.assertEqual(result["pinned"], {
+            "requests": "2.31.0", "urllib3": "2.0.4", "attrs": "23.1.0",
+        })
+        self.assertEqual(sorted(result["unpinned"]), ["click", "numpy"])
+
+
+if __name__ == "__main__":
+    unittest.main()