drift-evidence 0.1.0__tar.gz

drift_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.

drift_evidence-0.1.0/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: drift-evidence
+Version: 0.1.0
+Summary: Does a device's real network traffic match what it's declared to be allowed to contact? Checked against a real packet capture.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/MaXiMo000/drift
+Project-URL: Source, https://github.com/MaXiMo000/drift
+Project-URL: Issues, https://github.com/MaXiMo000/drift/issues
+Project-URL: Changelog, https://github.com/MaXiMo000/drift/releases
+Keywords: iot,privacy,network,pcap,evidence,provenance
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: scapy>=2.5
+Requires-Dist: PyYAML>=6.0
+Dynamic: license-file
+
+# drift
+
+[![ci](https://github.com/MaXiMo000/drift/actions/workflows/ci.yml/badge.svg)](https://github.com/MaXiMo000/drift/actions/workflows/ci.yml)
+
+**Does a device's real network traffic match what it's declared to be
+allowed to contact? Checked against a real packet capture.**
+
+[`witness`](https://github.com/MaXiMo000/witness) checks a website's own
+traffic against its declared privacy claims, from inside a browser.
+`drift` is the same idea pushed past that ceiling: a device on your own
+network — anything, not just something with a browser in it — checked
+against a declared allow-list by reading what it actually sent, from a
+packet capture.
+
+```
+$ drift check http.cap claims.yaml
+[XX] 145.254.160.237: 'test workstation' contacted domain(s) outside its declared allow-list: pagead2.googlesyndication.com
+
+0/1 pass, 1 fail
+```
+
+(Real output — see "Tested against real traffic" below for what capture
+this is and why.)
+
+## Read this before anything else: what's actually verified here
+
+The idea this comes from (see the portfolio audit) is a **Raspberry Pi
+acting as a live network tap on a real home network**, checking a real
+smart-home device's real traffic in real time. **That deployment is not
+built or tested here** — this session has no access to a Raspberry Pi, a
+real IoT device, or a real home network to verify any of it against, and
+building software nobody can verify would be the one thing this whole
+portfolio has consistently refused to do.
+
+What genuinely is built and tested: the actual analysis core — reading a
+`.pcap`/`.pcapng` file, extracting which domains each device contacted
+(via DNS queries and HTTP `Host:` headers), and checking that against a
+declared allow-list. That core doesn't care whether the capture came from
+a live Pi tap, a router's own packet-capture feature, or a file someone
+handed you — a `.pcap` file is a `.pcap` file. **Wiring this to an actual
+live tap on real hardware is real, unstarted future work**, stated
+plainly rather than implied by silence.
+
+## Scope
+
+Same discipline as `witness`: this is for checking traffic *you* captured
+on a network *you* own, against claims *you* declared. It has no notion
+of any real device manufacturer's actual claims and ships with no data
+about any real product.
+
+## Install
+
+```
+pip install drift-evidence   # the command it installs is `drift`
+```
+
+(`drift` was already taken on PyPI — same story as most siblings in this
+portfolio.)
+
+## Use
+
+Declare which domains each device (identified by its IP in the capture)
+is allowed to contact, in `claims.yaml`:
+
+```yaml
+devices:
+  - id: "192.168.1.42"
+    name: "smart bulb"
+    allowed_domains:
+      - vendor.example.com
+```
+
+Then check a real capture against it:
+
+```
+drift check capture.pcap claims.yaml
+```
+
+A device with no entry in `claims.yaml` reads `unverified`, never a
+silent pass — same three-status discipline as every claim-checking tool
+in this portfolio. `--json` prints the full report.
+
+## How domains are actually extracted
+
+Two signals, both read in the clear regardless of what runs on top of
+them:
+
+- **DNS query names** — the device asking "where is X" is visible even
+  when the connection to X itself is fully encrypted. This is the signal
+  that matters for a real modern device, whose actual traffic is mostly
+  HTTPS.
+- **HTTP `Host:` headers** — cleartext HTTP only, a strictly narrower
+  signal, kept because it names a domain a request actually *reached*,
+  not just one that was looked up.
+
+## What this does NOT do
+
+- **Can't read a domain out of an HTTPS/TLS connection.** That needs
+  either the TLS ClientHello's SNI field (sent in the clear even over an
+  otherwise-encrypted connection, and not read here) or a decryption key.
+  Real, addable scope — not attempted in this version.
+- **No live capture of anything.** `drift` reads a `.pcap` file that
+  already exists; it has no code that touches a network interface. Making
+  one (a Raspberry Pi tap, a router's mirror port, `tcpdump` itself) is
+  the caller's job.
+- **Doesn't distinguish which device asked from which device the traffic
+  is actually *about*** beyond source IP. On a network with NAT or DHCP
+  churn, the same IP can mean a different physical device over time — a
+  real limitation of IP-based identification, not solved here.
+
+## Privacy
+
+Everything stays on the machine `drift` runs on. It makes no network
+calls of its own -- `rdpcap` reads the `.pcap` file from disk, and the
+report goes to stdout or a `--json` file you name; nothing is uploaded
+or phoned home anywhere.
+
+The thing to actually be careful of is upstream of drift, not in it: a
+`.pcap` captured on a shared network (a router's mirror port, a home
+Wi-Fi capture) records *every* device's traffic that happened to be on
+the wire, not just the one you're checking. `extract_domains` (in
+`pcap.py`) buckets by every source IP it sees, and `check_pcap` reports
+on every one of them -- a device with no entry in `claims.yaml` still
+comes back `unverified`, **with its full list of observed domains
+included in the report**, exactly the same as a declared device's would
+be. Point drift at a capture that includes a housemate's phone or a
+guest's laptop, and their browsing domains end up in your output, not
+just your smart bulb's.
+
+That's not a bug to fix -- filtering out "devices you didn't mean to
+capture" isn't something drift can know how to do, since it has no way
+to tell an incidental bystander's IP from a device you meant to declare
+later. It's a fact about what a shared-network capture *is*, and worth
+knowing before you paste a report somewhere or hand it to someone else:
+capture only what you mean to, and treat the report as covering
+everyone who was on the network at the time, not just the device named
+in your claims file.
+
+## Tested against real traffic, not synthetic fixtures
+
+`tests/fixtures/http.cap` is a real capture downloaded from
+[Wireshark's own official sample-captures page](https://wiki.wireshark.org/SampleCaptures)
+(see `tests/fixtures/PROVENANCE.md`) — 2004-era traffic of a client
+requesting a page from `www.ethereal.com` (Wireshark's former name)
+whose response pulled in a Google AdSense ad from
+`pagead2.googlesyndication.com`. That's a real DNS query *and* a real
+HTTP request to an undeclared third party, sitting in a 20-year-old
+capture nobody built for this purpose — exactly the shape `drift` exists
+to catch, found in genuine traffic rather than constructed to prove a
+point.
+
+## Tests
+
+```
+pip install -e .
+python tests/test_pcap.py     # domain extraction, against the real fixture above
+python tests/test_claims.py   # claims.yaml validation
+python tests/test_check.py    # pass/fail/unverified classification
+python tests/test_cli.py      # the real CLI entry point, against the real fixture
+```
+
+29 tests.
+
+MIT licensed.

drift_evidence-0.1.0/README.md

@@ -0,0 +1,164 @@
+# drift
+
+[![ci](https://github.com/MaXiMo000/drift/actions/workflows/ci.yml/badge.svg)](https://github.com/MaXiMo000/drift/actions/workflows/ci.yml)
+
+**Does a device's real network traffic match what it's declared to be
+allowed to contact? Checked against a real packet capture.**
+
+[`witness`](https://github.com/MaXiMo000/witness) checks a website's own
+traffic against its declared privacy claims, from inside a browser.
+`drift` is the same idea pushed past that ceiling: a device on your own
+network — anything, not just something with a browser in it — checked
+against a declared allow-list by reading what it actually sent, from a
+packet capture.
+
+```
+$ drift check http.cap claims.yaml
+[XX] 145.254.160.237: 'test workstation' contacted domain(s) outside its declared allow-list: pagead2.googlesyndication.com
+
+0/1 pass, 1 fail
+```
+
+(Real output — see "Tested against real traffic" below for what capture
+this is and why.)
+
+## Read this before anything else: what's actually verified here
+
+The idea this comes from (see the portfolio audit) is a **Raspberry Pi
+acting as a live network tap on a real home network**, checking a real
+smart-home device's real traffic in real time. **That deployment is not
+built or tested here** — this session has no access to a Raspberry Pi, a
+real IoT device, or a real home network to verify any of it against, and
+building software nobody can verify would be the one thing this whole
+portfolio has consistently refused to do.
+
+What genuinely is built and tested: the actual analysis core — reading a
+`.pcap`/`.pcapng` file, extracting which domains each device contacted
+(via DNS queries and HTTP `Host:` headers), and checking that against a
+declared allow-list. That core doesn't care whether the capture came from
+a live Pi tap, a router's own packet-capture feature, or a file someone
+handed you — a `.pcap` file is a `.pcap` file. **Wiring this to an actual
+live tap on real hardware is real, unstarted future work**, stated
+plainly rather than implied by silence.
+
+## Scope
+
+Same discipline as `witness`: this is for checking traffic *you* captured
+on a network *you* own, against claims *you* declared. It has no notion
+of any real device manufacturer's actual claims and ships with no data
+about any real product.
+
+## Install
+
+```
+pip install drift-evidence   # the command it installs is `drift`
+```
+
+(`drift` was already taken on PyPI — same story as most siblings in this
+portfolio.)
+
+## Use
+
+Declare which domains each device (identified by its IP in the capture)
+is allowed to contact, in `claims.yaml`:
+
+```yaml
+devices:
+  - id: "192.168.1.42"
+    name: "smart bulb"
+    allowed_domains:
+      - vendor.example.com
+```
+
+Then check a real capture against it:
+
+```
+drift check capture.pcap claims.yaml
+```
+
+A device with no entry in `claims.yaml` reads `unverified`, never a
+silent pass — same three-status discipline as every claim-checking tool
+in this portfolio. `--json` prints the full report.
+
+## How domains are actually extracted
+
+Two signals, both read in the clear regardless of what runs on top of
+them:
+
+- **DNS query names** — the device asking "where is X" is visible even
+  when the connection to X itself is fully encrypted. This is the signal
+  that matters for a real modern device, whose actual traffic is mostly
+  HTTPS.
+- **HTTP `Host:` headers** — cleartext HTTP only, a strictly narrower
+  signal, kept because it names a domain a request actually *reached*,
+  not just one that was looked up.
+
+## What this does NOT do
+
+- **Can't read a domain out of an HTTPS/TLS connection.** That needs
+  either the TLS ClientHello's SNI field (sent in the clear even over an
+  otherwise-encrypted connection, and not read here) or a decryption key.
+  Real, addable scope — not attempted in this version.
+- **No live capture of anything.** `drift` reads a `.pcap` file that
+  already exists; it has no code that touches a network interface. Making
+  one (a Raspberry Pi tap, a router's mirror port, `tcpdump` itself) is
+  the caller's job.
+- **Doesn't distinguish which device asked from which device the traffic
+  is actually *about*** beyond source IP. On a network with NAT or DHCP
+  churn, the same IP can mean a different physical device over time — a
+  real limitation of IP-based identification, not solved here.
+
+## Privacy
+
+Everything stays on the machine `drift` runs on. It makes no network
+calls of its own -- `rdpcap` reads the `.pcap` file from disk, and the
+report goes to stdout or a `--json` file you name; nothing is uploaded
+or phoned home anywhere.
+
+The thing to actually be careful of is upstream of drift, not in it: a
+`.pcap` captured on a shared network (a router's mirror port, a home
+Wi-Fi capture) records *every* device's traffic that happened to be on
+the wire, not just the one you're checking. `extract_domains` (in
+`pcap.py`) buckets by every source IP it sees, and `check_pcap` reports
+on every one of them -- a device with no entry in `claims.yaml` still
+comes back `unverified`, **with its full list of observed domains
+included in the report**, exactly the same as a declared device's would
+be. Point drift at a capture that includes a housemate's phone or a
+guest's laptop, and their browsing domains end up in your output, not
+just your smart bulb's.
+
+That's not a bug to fix -- filtering out "devices you didn't mean to
+capture" isn't something drift can know how to do, since it has no way
+to tell an incidental bystander's IP from a device you meant to declare
+later. It's a fact about what a shared-network capture *is*, and worth
+knowing before you paste a report somewhere or hand it to someone else:
+capture only what you mean to, and treat the report as covering
+everyone who was on the network at the time, not just the device named
+in your claims file.
+
+## Tested against real traffic, not synthetic fixtures
+
+`tests/fixtures/http.cap` is a real capture downloaded from
+[Wireshark's own official sample-captures page](https://wiki.wireshark.org/SampleCaptures)
+(see `tests/fixtures/PROVENANCE.md`) — 2004-era traffic of a client
+requesting a page from `www.ethereal.com` (Wireshark's former name)
+whose response pulled in a Google AdSense ad from
+`pagead2.googlesyndication.com`. That's a real DNS query *and* a real
+HTTP request to an undeclared third party, sitting in a 20-year-old
+capture nobody built for this purpose — exactly the shape `drift` exists
+to catch, found in genuine traffic rather than constructed to prove a
+point.
+
+## Tests
+
+```
+pip install -e .
+python tests/test_pcap.py     # domain extraction, against the real fixture above
+python tests/test_claims.py   # claims.yaml validation
+python tests/test_check.py    # pass/fail/unverified classification
+python tests/test_cli.py      # the real CLI entry point, against the real fixture
+```
+
+29 tests.
+
+MIT licensed.

drift_evidence-0.1.0/drift/__init__.py

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

drift_evidence-0.1.0/drift/check.py

@@ -0,0 +1,49 @@
+"""Compare what a device actually contacted (extracted from a real packet
+capture) against what it's declared to be allowed to contact. Same
+three-status discipline as witness's own diff.js: no claim recorded for a
+device is `unverified`, never a silent pass; a domain outside the
+declared allow-list is `fail`, named explicitly, not folded into a vague
+"suspicious" bucket.
+"""
+from __future__ import annotations
+
+PASS, FAIL, UNVERIFIED = "pass", "fail", "unverified"
+
+
+def _norm(domain: str) -> str:
+    return domain.strip().lower().rstrip(".")
+
+
+def check_device(device_id: str, observed: dict, claims: dict | None) -> dict:
+    all_observed = sorted(set(observed.get("dns", [])) | set(observed.get("http", [])))
+
+    if claims is None:
+        return {
+            "device_id": device_id, "status": UNVERIFIED,
+            "detail": (f"no claims recorded for device '{device_id}' -- observed "
+                       f"{len(all_observed)} domain(s), nothing to check them against"),
+            "observed_domains": all_observed, "unexpected_domains": [],
+        }
+
+    allowed = {_norm(d) for d in claims["allowed_domains"]}
+    unexpected = [d for d in all_observed if _norm(d) not in allowed]
+
+    if unexpected:
+        return {
+            "device_id": device_id, "status": FAIL,
+            "detail": (f"'{claims['name']}' contacted domain(s) outside its declared "
+                       f"allow-list: {', '.join(unexpected)}"),
+            "observed_domains": all_observed, "unexpected_domains": unexpected,
+        }
+    return {
+        "device_id": device_id, "status": PASS,
+        "detail": f"'{claims['name']}' only contacted declared domains",
+        "observed_domains": all_observed, "unexpected_domains": [],
+    }
+
+
+def check_pcap(observed_by_device: dict[str, dict], claims: dict[str, dict]) -> list[dict]:
+    return [
+        check_device(dev_id, obs, claims.get(dev_id))
+        for dev_id, obs in sorted(observed_by_device.items())
+    ]

drift_evidence-0.1.0/drift/claims.py

@@ -0,0 +1,52 @@
+"""Load a drift claims file: which domains each device is declared to be
+allowed to contact. Same discipline as witness's own claims schema (this
+portfolio's browser-side equivalent): the allow-list is the actual gate,
+and a device with no entry here reads as unverified, never a silent pass.
+"""
+from __future__ import annotations
+
+import yaml
+
+
+class ClaimsError(ValueError):
+    pass
+
+
+def _norm(domain: str) -> str:
+    return domain.strip().lower().rstrip(".")
+
+
+def load_claims(path: str) -> dict[str, dict]:
+    try:
+        with open(path, encoding="utf-8") as f:
+            raw = yaml.safe_load(f)
+    except yaml.YAMLError as exc:
+        raise ClaimsError(f"{path}: not valid YAML ({exc})") from exc
+    except OSError as exc:
+        raise ClaimsError(f"{path}: {exc}") from exc
+
+    if not isinstance(raw, dict) or "devices" not in raw:
+        raise ClaimsError(f"{path}: must be a mapping with a top-level 'devices' list")
+    devices = raw["devices"]
+    if not isinstance(devices, list) or not devices:
+        raise ClaimsError(f"{path}: 'devices' must be a non-empty list")
+
+    result: dict[str, dict] = {}
+    for i, dev in enumerate(devices):
+        if not isinstance(dev, dict):
+            raise ClaimsError(f"{path}: devices[{i}] must be a mapping")
+        dev_id = dev.get("id")
+        if not dev_id or not isinstance(dev_id, str):
+            raise ClaimsError(f"{path}: devices[{i}] is missing a string 'id'")
+        if dev_id in result:
+            raise ClaimsError(f"{path}: duplicate device id '{dev_id}'")
+
+        allowed = dev.get("allowed_domains", [])
+        if not isinstance(allowed, list):
+            raise ClaimsError(f"{path}: device '{dev_id}': 'allowed_domains' must be a list")
+
+        result[dev_id] = {
+            "name": dev.get("name", dev_id),
+            "allowed_domains": [_norm(d) for d in allowed],
+        }
+    return result

drift_evidence-0.1.0/drift/cli.py

@@ -0,0 +1,60 @@
+"""drift check <pcap> <claims.yaml> [--json]"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from .check import FAIL, PASS, UNVERIFIED, check_pcap
+from .claims import ClaimsError, load_claims
+from .pcap import extract_domains
+
+_TAG = {PASS: "OK", FAIL: "XX", UNVERIFIED: "??"}
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="drift")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    check_p = sub.add_parser(
+        "check", help="check devices in a packet capture against their declared allowed domains")
+    check_p.add_argument("pcap", help="a packet capture file (.pcap/.pcapng)")
+    check_p.add_argument("claims", help="drift-claims.yaml")
+    check_p.add_argument("--json", action="store_true", help="print the full report as JSON")
+
+    args = parser.parse_args(argv)
+
+    try:
+        claims = load_claims(args.claims)
+    except ClaimsError as exc:
+        sys.exit(f"drift: {exc}")
+
+    try:
+        observed = extract_domains(args.pcap)
+    except OSError as exc:
+        sys.exit(f"drift: could not read {args.pcap}: {exc}")
+    except Exception as exc:  # noqa: BLE001 -- scapy's own parse errors vary by malformation
+        sys.exit(f"drift: could not parse {args.pcap} as a packet capture ({exc})")
+
+    results = check_pcap(observed, claims)
+
+    if args.json:
+        print(json.dumps(results, indent=2))
+    else:
+        for r in results:
+            print(f"[{_TAG[r['status']]}] {r['device_id']}: {r['detail']}")
+        n_fail = sum(1 for r in results if r["status"] == FAIL)
+        n_unverified = sum(1 for r in results if r["status"] == UNVERIFIED)
+        n_pass = len(results) - n_fail - n_unverified
+        summary = f"{n_pass}/{len(results)} pass"
+        if n_fail:
+            summary += f", {n_fail} fail"
+        if n_unverified:
+            summary += f", {n_unverified} unverified"
+        print(f"\n{summary}")
+
+    return 1 if any(r["status"] == FAIL for r in results) else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

drift_evidence-0.1.0/drift/pcap.py

@@ -0,0 +1,69 @@
+"""Extract which domains each device (identified by its source IP)
+actually contacted in a packet capture.
+
+Two signals, both cleartext regardless of what runs on top of them:
+
+- DNS query names -- the device asking "where is X" is visible even when
+  the connection to X itself is fully encrypted, which is why this is the
+  signal that actually matters for a modern device whose traffic is
+  mostly HTTPS.
+- HTTP `Host:` headers -- a strictly narrower signal (cleartext HTTP
+  only), kept because it's free once a capture has any plain HTTP in it
+  at all, and it names the domain a request actually reached, not just
+  one it resolved.
+
+What this does NOT do: read a domain out of an HTTPS/TLS connection.
+That needs either the TLS ClientHello's SNI field (sent in the clear even
+over an otherwise-encrypted connection, and not read here -- real,
+addable scope) or a decryption key. Stated as a real gap, not silently
+worked around.
+"""
+from __future__ import annotations
+
+
+def _parse_host_header(data: bytes) -> str | None:
+    for line in data.split(b"\r\n"):
+        if line.lower().startswith(b"host:"):
+            return line.split(b":", 1)[1].strip().decode("ascii", errors="replace")
+    return None
+
+
+def extract_domains(pcap_path: str) -> dict[str, dict]:
+    """Returns {source_ip: {"dns": [names...], "http": [hosts...]}},
+    both lists sorted for deterministic output."""
+    from scapy.all import rdpcap  # imported here, not at module load, so
+    from scapy.layers.dns import DNS  # importing drift.claims/drift.check
+    from scapy.layers.inet import IP, TCP  # never requires scapy at all
+    from scapy.packet import Raw
+
+    packets = rdpcap(pcap_path)
+    result: dict[str, dict] = {}
+
+    def bucket(ip: str) -> dict:
+        return result.setdefault(ip, {"dns": set(), "http": set()})
+
+    for pkt in packets:
+        if IP not in pkt:
+            continue
+        src = pkt[IP].src
+
+        # qr == 0 is a query, not a response -- the querier is the device
+        # actually asking, which is who this attributes the lookup to.
+        # qd is a PacketListField (scapy's newer versions warn on treating
+        # it as a single record) -- indexed explicitly, not accessed as if
+        # it were one object, so this doesn't silently break when a future
+        # scapy release removes the deprecated single-object shim.
+        if DNS in pkt and pkt[DNS].qd and pkt[DNS].qr == 0:
+            qname = pkt[DNS].qd[0].qname
+            if isinstance(qname, bytes):
+                qname = qname.decode("ascii", errors="replace")
+            bucket(src)["dns"].add(qname.rstrip("."))
+
+        if TCP in pkt and Raw in pkt:
+            data = bytes(pkt[Raw])
+            if data.startswith((b"GET ", b"POST ", b"HEAD ", b"PUT ", b"DELETE ")):
+                host = _parse_host_header(data)
+                if host:
+                    bucket(src)["http"].add(host)
+
+    return {ip: {"dns": sorted(v["dns"]), "http": sorted(v["http"])} for ip, v in result.items()}

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

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: drift-evidence
+Version: 0.1.0
+Summary: Does a device's real network traffic match what it's declared to be allowed to contact? Checked against a real packet capture.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/MaXiMo000/drift
+Project-URL: Source, https://github.com/MaXiMo000/drift
+Project-URL: Issues, https://github.com/MaXiMo000/drift/issues
+Project-URL: Changelog, https://github.com/MaXiMo000/drift/releases
+Keywords: iot,privacy,network,pcap,evidence,provenance
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: scapy>=2.5
+Requires-Dist: PyYAML>=6.0
+Dynamic: license-file
+
+# drift
+
+[![ci](https://github.com/MaXiMo000/drift/actions/workflows/ci.yml/badge.svg)](https://github.com/MaXiMo000/drift/actions/workflows/ci.yml)
+
+**Does a device's real network traffic match what it's declared to be
+allowed to contact? Checked against a real packet capture.**
+
+[`witness`](https://github.com/MaXiMo000/witness) checks a website's own
+traffic against its declared privacy claims, from inside a browser.
+`drift` is the same idea pushed past that ceiling: a device on your own
+network — anything, not just something with a browser in it — checked
+against a declared allow-list by reading what it actually sent, from a
+packet capture.
+
+```
+$ drift check http.cap claims.yaml
+[XX] 145.254.160.237: 'test workstation' contacted domain(s) outside its declared allow-list: pagead2.googlesyndication.com
+
+0/1 pass, 1 fail
+```
+
+(Real output — see "Tested against real traffic" below for what capture
+this is and why.)
+
+## Read this before anything else: what's actually verified here
+
+The idea this comes from (see the portfolio audit) is a **Raspberry Pi
+acting as a live network tap on a real home network**, checking a real
+smart-home device's real traffic in real time. **That deployment is not
+built or tested here** — this session has no access to a Raspberry Pi, a
+real IoT device, or a real home network to verify any of it against, and
+building software nobody can verify would be the one thing this whole
+portfolio has consistently refused to do.
+
+What genuinely is built and tested: the actual analysis core — reading a
+`.pcap`/`.pcapng` file, extracting which domains each device contacted
+(via DNS queries and HTTP `Host:` headers), and checking that against a
+declared allow-list. That core doesn't care whether the capture came from
+a live Pi tap, a router's own packet-capture feature, or a file someone
+handed you — a `.pcap` file is a `.pcap` file. **Wiring this to an actual
+live tap on real hardware is real, unstarted future work**, stated
+plainly rather than implied by silence.
+
+## Scope
+
+Same discipline as `witness`: this is for checking traffic *you* captured
+on a network *you* own, against claims *you* declared. It has no notion
+of any real device manufacturer's actual claims and ships with no data
+about any real product.
+
+## Install
+
+```
+pip install drift-evidence   # the command it installs is `drift`
+```
+
+(`drift` was already taken on PyPI — same story as most siblings in this
+portfolio.)
+
+## Use
+
+Declare which domains each device (identified by its IP in the capture)
+is allowed to contact, in `claims.yaml`:
+
+```yaml
+devices:
+  - id: "192.168.1.42"
+    name: "smart bulb"
+    allowed_domains:
+      - vendor.example.com
+```
+
+Then check a real capture against it:
+
+```
+drift check capture.pcap claims.yaml
+```
+
+A device with no entry in `claims.yaml` reads `unverified`, never a
+silent pass — same three-status discipline as every claim-checking tool
+in this portfolio. `--json` prints the full report.
+
+## How domains are actually extracted
+
+Two signals, both read in the clear regardless of what runs on top of
+them:
+
+- **DNS query names** — the device asking "where is X" is visible even
+  when the connection to X itself is fully encrypted. This is the signal
+  that matters for a real modern device, whose actual traffic is mostly
+  HTTPS.
+- **HTTP `Host:` headers** — cleartext HTTP only, a strictly narrower
+  signal, kept because it names a domain a request actually *reached*,
+  not just one that was looked up.
+
+## What this does NOT do
+
+- **Can't read a domain out of an HTTPS/TLS connection.** That needs
+  either the TLS ClientHello's SNI field (sent in the clear even over an
+  otherwise-encrypted connection, and not read here) or a decryption key.
+  Real, addable scope — not attempted in this version.
+- **No live capture of anything.** `drift` reads a `.pcap` file that
+  already exists; it has no code that touches a network interface. Making
+  one (a Raspberry Pi tap, a router's mirror port, `tcpdump` itself) is
+  the caller's job.
+- **Doesn't distinguish which device asked from which device the traffic
+  is actually *about*** beyond source IP. On a network with NAT or DHCP
+  churn, the same IP can mean a different physical device over time — a
+  real limitation of IP-based identification, not solved here.
+
+## Privacy
+
+Everything stays on the machine `drift` runs on. It makes no network
+calls of its own -- `rdpcap` reads the `.pcap` file from disk, and the
+report goes to stdout or a `--json` file you name; nothing is uploaded
+or phoned home anywhere.
+
+The thing to actually be careful of is upstream of drift, not in it: a
+`.pcap` captured on a shared network (a router's mirror port, a home
+Wi-Fi capture) records *every* device's traffic that happened to be on
+the wire, not just the one you're checking. `extract_domains` (in
+`pcap.py`) buckets by every source IP it sees, and `check_pcap` reports
+on every one of them -- a device with no entry in `claims.yaml` still
+comes back `unverified`, **with its full list of observed domains
+included in the report**, exactly the same as a declared device's would
+be. Point drift at a capture that includes a housemate's phone or a
+guest's laptop, and their browsing domains end up in your output, not
+just your smart bulb's.
+
+That's not a bug to fix -- filtering out "devices you didn't mean to
+capture" isn't something drift can know how to do, since it has no way
+to tell an incidental bystander's IP from a device you meant to declare
+later. It's a fact about what a shared-network capture *is*, and worth
+knowing before you paste a report somewhere or hand it to someone else:
+capture only what you mean to, and treat the report as covering
+everyone who was on the network at the time, not just the device named
+in your claims file.
+
+## Tested against real traffic, not synthetic fixtures
+
+`tests/fixtures/http.cap` is a real capture downloaded from
+[Wireshark's own official sample-captures page](https://wiki.wireshark.org/SampleCaptures)
+(see `tests/fixtures/PROVENANCE.md`) — 2004-era traffic of a client
+requesting a page from `www.ethereal.com` (Wireshark's former name)
+whose response pulled in a Google AdSense ad from
+`pagead2.googlesyndication.com`. That's a real DNS query *and* a real
+HTTP request to an undeclared third party, sitting in a 20-year-old
+capture nobody built for this purpose — exactly the shape `drift` exists
+to catch, found in genuine traffic rather than constructed to prove a
+point.
+
+## Tests
+
+```
+pip install -e .
+python tests/test_pcap.py     # domain extraction, against the real fixture above
+python tests/test_claims.py   # claims.yaml validation
+python tests/test_check.py    # pass/fail/unverified classification
+python tests/test_cli.py      # the real CLI entry point, against the real fixture
+```
+
+29 tests.
+
+MIT licensed.

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

@@ -0,0 +1,18 @@
+LICENSE
+README.md
+pyproject.toml
+drift/__init__.py
+drift/check.py
+drift/claims.py
+drift/cli.py
+drift/pcap.py
+drift_evidence.egg-info/PKG-INFO
+drift_evidence.egg-info/SOURCES.txt
+drift_evidence.egg-info/dependency_links.txt
+drift_evidence.egg-info/entry_points.txt
+drift_evidence.egg-info/requires.txt
+drift_evidence.egg-info/top_level.txt
+tests/test_check.py
+tests/test_claims.py
+tests/test_cli.py
+tests/test_pcap.py

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

@@ -0,0 +1 @@
+

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

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

drift_evidence-0.1.0/drift_evidence.egg-info/requires.txt

@@ -0,0 +1,2 @@
+scapy>=2.5
+PyYAML>=6.0

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

@@ -0,0 +1 @@
+drift

drift_evidence-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+# "drift" was already taken on PyPI, same story as most siblings in this
+# portfolio. The installed command stays the short name -- python-dateutil
+# installs `dateutil`, this installs `drift`.
+name = "drift-evidence"
+version = "0.1.0"
+description = "Does a device's real network traffic match what it's declared to be allowed to contact? Checked against a real packet capture."
+requires-python = ">=3.10"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["iot", "privacy", "network", "pcap", "evidence", "provenance"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Security",
+]
+# scapy for reading the pcap format itself -- there's no lighter way to
+# parse real packet captures correctly. PyYAML for claims.yaml, same real
+# dependency invariant/escrow/portable already use for their own config
+# files, not a new convention introduced here.
+dependencies = ["scapy>=2.5", "PyYAML>=6.0"]
+
+urls.Homepage = "https://github.com/MaXiMo000/drift"
+urls.Source = "https://github.com/MaXiMo000/drift"
+urls.Issues = "https://github.com/MaXiMo000/drift/issues"
+urls.Changelog = "https://github.com/MaXiMo000/drift/releases"
+
+[project.scripts]
+drift = "drift.cli:main"
+
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+include = ["drift*"]

drift_evidence-0.1.0/setup.cfg

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

drift_evidence-0.1.0/tests/test_check.py

@@ -0,0 +1,69 @@
+"""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 drift.check import FAIL, PASS, UNVERIFIED, check_device, check_pcap
+
+
+class TestCheckDevice(unittest.TestCase):
+    def test_no_claims_is_unverified_never_a_silent_pass(self):
+        r = check_device("10.0.0.5", {"dns": ["vendor.com"], "http": []}, claims=None)
+        self.assertEqual(r["status"], UNVERIFIED)
+
+    def test_an_undeclared_devices_observed_domains_still_appear_in_the_report(self):
+        """Privacy-relevant, documented in README: a device with no claims
+        entry (a housemate's phone caught in a shared-network capture, not
+        just an undeclared IoT device) still gets its full domain list
+        included in the output -- 'unverified' doesn't mean 'omitted'."""
+        r = check_device("10.0.0.9", {"dns": ["some-random-site.example"], "http": []}, claims=None)
+        self.assertEqual(r["observed_domains"], ["some-random-site.example"])
+
+    def test_only_declared_domains_is_pass(self):
+        claims = {"name": "bulb", "allowed_domains": ["vendor.com"]}
+        r = check_device("10.0.0.5", {"dns": ["vendor.com"], "http": []}, claims)
+        self.assertEqual(r["status"], PASS)
+
+    def test_an_undeclared_domain_is_fail_and_named(self):
+        claims = {"name": "bulb", "allowed_domains": ["vendor.com"]}
+        r = check_device("10.0.0.5", {"dns": ["vendor.com", "ads.example.com"], "http": []}, claims)
+        self.assertEqual(r["status"], FAIL)
+        self.assertIn("ads.example.com", r["unexpected_domains"])
+        self.assertIn("ads.example.com", r["detail"])
+
+    def test_dns_and_http_observations_are_merged_and_deduplicated(self):
+        claims = {"name": "bulb", "allowed_domains": ["vendor.com"]}
+        r = check_device("10.0.0.5", {"dns": ["vendor.com"], "http": ["vendor.com"]}, claims)
+        self.assertEqual(r["observed_domains"], ["vendor.com"])
+
+    def test_case_and_trailing_dot_do_not_cause_a_false_mismatch(self):
+        claims = {"name": "bulb", "allowed_domains": ["vendor.com"]}
+        r = check_device("10.0.0.5", {"dns": ["Vendor.com."], "http": []}, claims)
+        self.assertEqual(r["status"], PASS)
+
+    def test_no_observations_at_all_with_claims_is_a_clean_pass(self):
+        claims = {"name": "bulb", "allowed_domains": ["vendor.com"]}
+        r = check_device("10.0.0.5", {"dns": [], "http": []}, claims)
+        self.assertEqual(r["status"], PASS)
+        self.assertEqual(r["observed_domains"], [])
+
+
+class TestCheckPcap(unittest.TestCase):
+    def test_multiple_devices_evaluated_independently_and_sorted(self):
+        observed = {
+            "10.0.0.2": {"dns": ["ads.example.com"], "http": []},
+            "10.0.0.1": {"dns": ["vendor.com"], "http": []},
+        }
+        claims = {"10.0.0.1": {"name": "a", "allowed_domains": ["vendor.com"]}}
+        results = check_pcap(observed, claims)
+        self.assertEqual([r["device_id"] for r in results], ["10.0.0.1", "10.0.0.2"])
+        self.assertEqual(results[0]["status"], PASS)
+        self.assertEqual(results[1]["status"], UNVERIFIED)  # 10.0.0.2 has no claims entry
+
+
+if __name__ == "__main__":
+    unittest.main()

drift_evidence-0.1.0/tests/test_claims.py

@@ -0,0 +1,76 @@
+"""Run: python tests/test_claims.py"""
+from __future__ import annotations
+
+import pathlib
+import sys
+import tempfile
+import unittest
+
+sys.path.insert(0, str(pathlib.Path(__file__).parent.parent))
+
+from drift.claims import ClaimsError, load_claims
+
+
+class TestLoadClaims(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.path = pathlib.Path(self.tmp.name) / "claims.yaml"
+
+    def tearDown(self):
+        self.tmp.cleanup()
+
+    def _write(self, text: str) -> str:
+        self.path.write_text(text, encoding="utf-8")
+        return str(self.path)
+
+    def test_valid_claims(self):
+        p = self._write(
+            "devices:\n  - id: '10.0.0.5'\n    name: bulb\n    allowed_domains: [Vendor.com]\n"
+        )
+        claims = load_claims(p)
+        self.assertEqual(claims, {"10.0.0.5": {"name": "bulb", "allowed_domains": ["vendor.com"]}})
+
+    def test_domain_normalization_lowercases_and_strips_trailing_dot(self):
+        p = self._write("devices:\n  - id: x\n    allowed_domains: ['Example.COM.']\n")
+        claims = load_claims(p)
+        self.assertEqual(claims["x"]["allowed_domains"], ["example.com"])
+
+    def test_name_defaults_to_id_when_absent(self):
+        p = self._write("devices:\n  - id: x\n    allowed_domains: []\n")
+        claims = load_claims(p)
+        self.assertEqual(claims["x"]["name"], "x")
+
+    def test_missing_file_is_a_claims_error_not_a_crash(self):
+        with self.assertRaises(ClaimsError):
+            load_claims(str(self.path))
+
+    def test_not_yaml_is_a_claims_error(self):
+        p = self._write("not: valid: yaml: at: all:::")
+        with self.assertRaises(ClaimsError):
+            load_claims(p)
+
+    def test_missing_devices_key_is_rejected(self):
+        p = self._write("something_else: true\n")
+        with self.assertRaises(ClaimsError) as ctx:
+            load_claims(p)
+        self.assertIn("devices", str(ctx.exception))
+
+    def test_device_missing_id_is_rejected(self):
+        p = self._write("devices:\n  - name: x\n")
+        with self.assertRaises(ClaimsError) as ctx:
+            load_claims(p)
+        self.assertIn("id", str(ctx.exception))
+
+    def test_duplicate_device_ids_are_rejected(self):
+        p = self._write("devices:\n  - id: x\n  - id: x\n")
+        with self.assertRaises(ClaimsError):
+            load_claims(p)
+
+    def test_allowed_domains_defaults_to_empty_list(self):
+        p = self._write("devices:\n  - id: x\n")
+        claims = load_claims(p)
+        self.assertEqual(claims["x"]["allowed_domains"], [])
+
+
+if __name__ == "__main__":
+    unittest.main()

drift_evidence-0.1.0/tests/test_cli.py

@@ -0,0 +1,98 @@
+"""Run: python tests/test_cli.py
+
+Exercises the real CLI entry point against the real pcap fixture (see
+test_pcap.py's docstring for its provenance) -- not a mocked
+extract_domains().
+"""
+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 drift.cli import main
+
+FIXTURE = str(pathlib.Path(__file__).parent / "fixtures" / "http.cap")
+
+
+class TestCli(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.claims_path = pathlib.Path(self.tmp.name) / "claims.yaml"
+
+    def tearDown(self):
+        self.tmp.cleanup()
+
+    def test_real_pcap_with_an_undeclared_domain_fails(self):
+        self.claims_path.write_text(
+            "devices:\n"
+            "  - id: '145.254.160.237'\n"
+            "    name: test workstation\n"
+            "    allowed_domains: [www.ethereal.com]\n"
+        )
+        buf = io.StringIO()
+        with contextlib.redirect_stdout(buf):
+            code = main(["check", FIXTURE, str(self.claims_path)])
+        self.assertEqual(code, 1)
+        self.assertIn("pagead2.googlesyndication.com", buf.getvalue())
+        self.assertIn("[XX]", buf.getvalue())
+
+    def test_real_pcap_with_both_domains_declared_passes(self):
+        self.claims_path.write_text(
+            "devices:\n"
+            "  - id: '145.254.160.237'\n"
+            "    allowed_domains: [www.ethereal.com, pagead2.googlesyndication.com]\n"
+        )
+        buf = io.StringIO()
+        with contextlib.redirect_stdout(buf):
+            code = main(["check", FIXTURE, str(self.claims_path)])
+        self.assertEqual(code, 0)
+        self.assertIn("1/1 pass", buf.getvalue())
+
+    def test_unknown_device_in_the_capture_is_unverified_not_a_fail(self):
+        self.claims_path.write_text("devices:\n  - id: '10.0.0.99'\n    allowed_domains: []\n")
+        buf = io.StringIO()
+        with contextlib.redirect_stdout(buf):
+            code = main(["check", FIXTURE, str(self.claims_path)])
+        self.assertEqual(code, 0)
+        self.assertIn("[??]", buf.getvalue())
+
+    def test_missing_pcap_is_a_clean_error_not_a_traceback(self):
+        self.claims_path.write_text("devices:\n  - id: x\n    allowed_domains: []\n")
+        with self.assertRaises(SystemExit) as ctx:
+            main(["check", "/no/such/file.pcap", str(self.claims_path)])
+        self.assertIn("drift:", str(ctx.exception))
+
+    def test_bad_claims_file_is_a_clean_error_not_a_traceback(self):
+        self.claims_path.write_text("not: a valid claims file\n")
+        with self.assertRaises(SystemExit) as ctx:
+            main(["check", FIXTURE, str(self.claims_path)])
+        self.assertIn("drift:", str(ctx.exception))
+
+    def test_not_actually_a_pcap_file_is_a_clean_error(self):
+        bad_pcap = pathlib.Path(self.tmp.name) / "not_a_pcap.pcap"
+        bad_pcap.write_text("this is definitely not packet capture data")
+        self.claims_path.write_text("devices:\n  - id: x\n    allowed_domains: []\n")
+        with self.assertRaises(SystemExit) as ctx:
+            main(["check", str(bad_pcap), str(self.claims_path)])
+        self.assertIn("drift:", str(ctx.exception))
+
+    def test_json_flag_prints_the_full_report(self):
+        self.claims_path.write_text(
+            "devices:\n  - id: '145.254.160.237'\n    allowed_domains: [www.ethereal.com]\n"
+        )
+        buf = io.StringIO()
+        with contextlib.redirect_stdout(buf):
+            main(["check", FIXTURE, str(self.claims_path), "--json"])
+        report = json.loads(buf.getvalue())
+        self.assertEqual(report[0]["status"], "fail")
+
+
+if __name__ == "__main__":
+    unittest.main()

drift_evidence-0.1.0/tests/test_pcap.py

@@ -0,0 +1,51 @@
+"""Run: python tests/test_pcap.py
+
+Against a real packet capture (tests/fixtures/http.cap, downloaded from
+Wireshark's own official SampleCaptures wiki -- see
+tests/fixtures/PROVENANCE.md), not a synthetic one. Real traffic from
+2004: a client hitting www.ethereal.com that also pulled in a Google
+AdSense ad from pagead2.googlesyndication.com, both via a real DNS query
+and a real HTTP request -- exactly the "declared one thing, actually did
+another" shape this whole tool exists to catch, found in genuine traffic,
+not constructed to make a point.
+"""
+from __future__ import annotations
+
+import pathlib
+import sys
+import unittest
+
+sys.path.insert(0, str(pathlib.Path(__file__).parent.parent))
+
+from drift.pcap import extract_domains
+
+FIXTURE = str(pathlib.Path(__file__).parent / "fixtures" / "http.cap")
+
+
+class TestExtractDomains(unittest.TestCase):
+    def test_the_one_real_device_in_the_capture_is_found(self):
+        result = extract_domains(FIXTURE)
+        self.assertIn("145.254.160.237", result)
+
+    def test_the_real_dns_query_is_extracted(self):
+        result = extract_domains(FIXTURE)
+        self.assertIn("pagead2.googlesyndication.com", result["145.254.160.237"]["dns"])
+
+    def test_the_real_http_host_headers_are_extracted(self):
+        result = extract_domains(FIXTURE)
+        http_hosts = result["145.254.160.237"]["http"]
+        self.assertIn("www.ethereal.com", http_hosts)
+        self.assertIn("pagead2.googlesyndication.com", http_hosts)
+
+    def test_results_are_sorted_and_deduplicated(self):
+        result = extract_domains(FIXTURE)
+        http_hosts = result["145.254.160.237"]["http"]
+        self.assertEqual(http_hosts, sorted(set(http_hosts)))
+
+    def test_a_nonexistent_pcap_path_raises_an_os_error(self):
+        with self.assertRaises(OSError):
+            extract_domains("/no/such/file.pcap")
+
+
+if __name__ == "__main__":
+    unittest.main()