driftguard-audit 0.1.0__tar.gz

driftguard_audit-0.1.0/LICENSE

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

driftguard_audit-0.1.0/PKG-INFO

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: driftguard-audit
+Version: 0.1.0
+Summary: Offline security capability diffing for Python package releases
+Author: Adnan Omar
+License: MIT
+Project-URL: Homepage, https://github.com/adnanomar77/driftguard-audit
+Project-URL: Repository, https://github.com/adnanomar77/driftguard-audit
+Project-URL: Issues, https://github.com/adnanomar77/driftguard-audit/issues
+Keywords: security,supply-chain,python,static-analysis,dependency-audit
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# DriftGuard Audit
+
+Offline security-capability diffing for Python package releases.
+
+DriftGuard Audit compares two local Python package directories or ZIP/wheel/sdist archives without importing or executing package code. It reports newly observed capabilities such as process spawning, network access, environment reads, dynamic code, native loading, and filesystem access.
+
+> This is static analysis, not proof of safety. Dynamic dispatch, obfuscation, native extensions, and behavior outside the analyzed Python source can be missed.
+
+## Install
+
+```bash
+python -m pip install driftguard-audit
+```
+
+## CLI
+
+```bash
+driftguard analyze old.whl --json
+driftguard diff old.whl new.whl --json
+```
+
+The `diff` command exits with status `2` when new capabilities are observed, `0` when no capability drift is observed, and a nonzero error status for invalid input.
+
+## Python API
+
+```python
+from driftguard import compare_packages
+
+report = compare_packages("old.whl", "new.whl")
+if report.added:
+    print(report.to_json())
+```
+
+## Scope and safety
+
+The package is offline and has no runtime dependencies. It reads local directories and ZIP-compatible archives, extracts archives with path-boundary checks into a temporary directory, never imports the target package, and never executes package code. It does not query CVE databases, verify intent, scan native binaries, or replace sandboxing, EDR, SCA, or package-signature verification.
+
+## License
+
+MIT

driftguard_audit-0.1.0/README.md

@@ -0,0 +1,40 @@
+# DriftGuard Audit
+
+Offline security-capability diffing for Python package releases.
+
+DriftGuard Audit compares two local Python package directories or ZIP/wheel/sdist archives without importing or executing package code. It reports newly observed capabilities such as process spawning, network access, environment reads, dynamic code, native loading, and filesystem access.
+
+> This is static analysis, not proof of safety. Dynamic dispatch, obfuscation, native extensions, and behavior outside the analyzed Python source can be missed.
+
+## Install
+
+```bash
+python -m pip install driftguard-audit
+```
+
+## CLI
+
+```bash
+driftguard analyze old.whl --json
+driftguard diff old.whl new.whl --json
+```
+
+The `diff` command exits with status `2` when new capabilities are observed, `0` when no capability drift is observed, and a nonzero error status for invalid input.
+
+## Python API
+
+```python
+from driftguard import compare_packages
+
+report = compare_packages("old.whl", "new.whl")
+if report.added:
+    print(report.to_json())
+```
+
+## Scope and safety
+
+The package is offline and has no runtime dependencies. It reads local directories and ZIP-compatible archives, extracts archives with path-boundary checks into a temporary directory, never imports the target package, and never executes package code. It does not query CVE databases, verify intent, scan native binaries, or replace sandboxing, EDR, SCA, or package-signature verification.
+
+## License
+
+MIT

driftguard_audit-0.1.0/driftguard/__init__.py

@@ -0,0 +1,5 @@
+"""DriftGuard: offline security capability diffing for Python packages."""
+from .analyzer import Capability, Report, analyze_package, compare_packages
+
+__all__ = ["Capability", "Report", "analyze_package", "compare_packages"]
+__version__ = "0.1.0"

driftguard_audit-0.1.0/driftguard/analyzer.py

@@ -0,0 +1,143 @@
+from __future__ import annotations
+
+import ast
+import json
+import tempfile
+import zipfile
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+
+
+@dataclass(frozen=True, order=True)
+class Capability:
+    kind: str
+    evidence: str
+    file: str
+    line: int
+    severity: str
+
+
+@dataclass
+class Report:
+    old: str
+    new: str
+    added: list[Capability] = field(default_factory=list)
+    removed: list[Capability] = field(default_factory=list)
+    unchanged: list[Capability] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+
+    @property
+    def decision(self) -> str:
+        return "REVIEW" if self.added else "UNCHANGED"
+
+    def to_dict(self) -> dict:
+        return {"old": self.old, "new": self.new, "decision": self.decision,
+                "added_capabilities": [asdict(x) for x in self.added],
+                "removed_capabilities": [asdict(x) for x in self.removed],
+                "unchanged_capabilities": [asdict(x) for x in self.unchanged],
+                "warnings": self.warnings}
+
+    def to_json(self) -> str:
+        return json.dumps(self.to_dict(), indent=2, sort_keys=True)
+
+
+_RULES = (
+    ("process_spawn", "subprocess", "high"), ("process_spawn", "os.system", "high"),
+    ("process_spawn", "os.popen", "high"), ("network_access", "socket", "high"),
+    ("network_access", "requests", "medium"), ("network_access", "urllib", "medium"),
+    ("network_access", "httpx", "medium"), ("dynamic_code", "eval", "high"),
+    ("dynamic_code", "exec", "high"), ("dynamic_import", "importlib", "medium"),
+    ("environment_read", "os.environ", "medium"), ("filesystem_access", "open", "low"),
+    ("filesystem_access", "pathlib", "low"), ("native_code", "ctypes", "high"),
+)
+
+
+def _safe_extract(archive: zipfile.ZipFile, destination: Path) -> None:
+    destination = destination.resolve()
+    for member in archive.infolist():
+        name = member.filename.replace("\\", "/")
+        target = (destination / name).resolve()
+        if target != destination and destination not in target.parents:
+            raise ValueError(f"archive member escapes extraction directory: {member.filename}")
+        if member.is_dir():
+            target.mkdir(parents=True, exist_ok=True)
+        else:
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_bytes(archive.read(member))
+
+
+def _archive_root(source: str | Path):
+    path = Path(source)
+    if path.is_dir():
+        yield path, None
+        return
+    if not path.is_file():
+        raise FileNotFoundError(source)
+    tmp = tempfile.TemporaryDirectory(prefix="driftguard-")
+    try:
+        with zipfile.ZipFile(path) as archive:
+            _safe_extract(archive, Path(tmp.name))
+        yield Path(tmp.name), tmp
+    except (zipfile.BadZipFile, ValueError) as exc:
+        tmp.cleanup()
+        if isinstance(exc, ValueError):
+            raise
+        raise ValueError(f"Expected a directory or ZIP/wheel/sdist archive: {source}") from exc
+
+
+def _node_text(node: ast.AST) -> str:
+    if isinstance(node, (ast.Call, ast.Attribute, ast.Name)):
+        return ast.unparse(node)
+    if isinstance(node, ast.Import):
+        return " ".join(alias.name for alias in node.names)
+    if isinstance(node, ast.ImportFrom):
+        return node.module or ""
+    return ""
+
+
+def _capabilities(root: Path) -> list[Capability]:
+    found: dict[tuple[str, str, int], Capability] = {}
+    for source in sorted(root.rglob("*.py")):
+        if any(part in {"__pycache__", ".git", ".tox", ".venv"} for part in source.parts):
+            continue
+        relative = source.relative_to(root).as_posix()
+        try:
+            tree = ast.parse(source.read_text(encoding="utf-8"), filename=relative)
+        except (UnicodeDecodeError, SyntaxError):
+            continue
+        for node in ast.walk(tree):
+            text = _node_text(node)
+            for kind, token, severity in _RULES:
+                if token in text:
+                    key = (kind, relative, node.lineno)
+                    candidate = Capability(kind, text[:160], relative, node.lineno, severity)
+                    current = found.get(key)
+                    if current is None or len(candidate.evidence) < len(current.evidence):
+                        found[key] = candidate
+    return sorted(found.values())
+
+
+def analyze_package(source: str | Path) -> list[Capability]:
+    """Analyze a local directory or ZIP-compatible archive without executing it."""
+    root, holder = next(_archive_root(source))
+    try:
+        return _capabilities(root)
+    finally:
+        if holder is not None:
+            holder.cleanup()
+
+
+def _key(item: Capability) -> tuple[str, str, str, int]:
+    return item.kind, item.evidence, item.file, item.line
+
+
+def compare_packages(old: str | Path, new: str | Path) -> Report:
+    """Compare two local package directories or ZIP-compatible archives."""
+    old_caps, new_caps = analyze_package(old), analyze_package(new)
+    old_map, new_map = {_key(x): x for x in old_caps}, {_key(x): x for x in new_caps}
+    return Report(str(old), str(new),
+                  [new_map[k] for k in sorted(new_map.keys() - old_map.keys())],
+                  [old_map[k] for k in sorted(old_map.keys() - new_map.keys())],
+                  [new_map[k] for k in sorted(new_map.keys() & old_map.keys())],
+                  ["Static analysis cannot prove runtime behavior; dynamic dispatch and native binaries may be missed.",
+                   "Package code is never executed; archives are extracted only to a private temporary directory."])

driftguard_audit-0.1.0/driftguard/cli.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from .analyzer import analyze_package, compare_packages
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="driftguard", description="Offline security capability diff for Python packages")
+    sub = parser.add_subparsers(dest="command", required=True)
+    analyze = sub.add_parser("analyze", help="Analyze one local package without executing it")
+    analyze.add_argument("package", type=Path)
+    analyze.add_argument("--json", action="store_true")
+    diff = sub.add_parser("diff", help="Compare security capabilities between two local releases")
+    diff.add_argument("old", type=Path)
+    diff.add_argument("new", type=Path)
+    diff.add_argument("--json", action="store_true")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+    if args.command == "analyze":
+        result = [c.__dict__ for c in analyze_package(args.package)]
+        if args.json:
+            print(json.dumps(result, indent=2, sort_keys=True))
+        else:
+            for item in result:
+                print(f"{item['severity'].upper():6} {item['kind']:18} {item['file']}:{item['line']}  {item['evidence']}")
+        return 0
+    report = compare_packages(args.old, args.new)
+    if args.json:
+        print(report.to_json())
+    else:
+        print(f"Decision: {report.decision}")
+        for capability in report.added:
+            print(f"+ {capability.severity.upper():6} {capability.kind:18} {capability.file}:{capability.line}  {capability.evidence}")
+        for capability in report.removed:
+            print(f"- {capability.kind:18} {capability.file}:{capability.line}  {capability.evidence}")
+        for warning in report.warnings:
+            print(f"Warning: {warning}", file=sys.stderr)
+    return 2 if report.added else 0

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

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: driftguard-audit
+Version: 0.1.0
+Summary: Offline security capability diffing for Python package releases
+Author: Adnan Omar
+License: MIT
+Project-URL: Homepage, https://github.com/adnanomar77/driftguard-audit
+Project-URL: Repository, https://github.com/adnanomar77/driftguard-audit
+Project-URL: Issues, https://github.com/adnanomar77/driftguard-audit/issues
+Keywords: security,supply-chain,python,static-analysis,dependency-audit
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# DriftGuard Audit
+
+Offline security-capability diffing for Python package releases.
+
+DriftGuard Audit compares two local Python package directories or ZIP/wheel/sdist archives without importing or executing package code. It reports newly observed capabilities such as process spawning, network access, environment reads, dynamic code, native loading, and filesystem access.
+
+> This is static analysis, not proof of safety. Dynamic dispatch, obfuscation, native extensions, and behavior outside the analyzed Python source can be missed.
+
+## Install
+
+```bash
+python -m pip install driftguard-audit
+```
+
+## CLI
+
+```bash
+driftguard analyze old.whl --json
+driftguard diff old.whl new.whl --json
+```
+
+The `diff` command exits with status `2` when new capabilities are observed, `0` when no capability drift is observed, and a nonzero error status for invalid input.
+
+## Python API
+
+```python
+from driftguard import compare_packages
+
+report = compare_packages("old.whl", "new.whl")
+if report.added:
+    print(report.to_json())
+```
+
+## Scope and safety
+
+The package is offline and has no runtime dependencies. It reads local directories and ZIP-compatible archives, extracts archives with path-boundary checks into a temporary directory, never imports the target package, and never executes package code. It does not query CVE databases, verify intent, scan native binaries, or replace sandboxing, EDR, SCA, or package-signature verification.
+
+## License
+
+MIT

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

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+driftguard/__init__.py
+driftguard/analyzer.py
+driftguard/cli.py
+driftguard/py.typed
+driftguard_audit.egg-info/PKG-INFO
+driftguard_audit.egg-info/SOURCES.txt
+driftguard_audit.egg-info/dependency_links.txt
+driftguard_audit.egg-info/entry_points.txt
+driftguard_audit.egg-info/requires.txt
+driftguard_audit.egg-info/top_level.txt
+tests/test_analyzer.py

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

@@ -0,0 +1 @@
+

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

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

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

@@ -0,0 +1,3 @@
+
+[test]
+pytest>=7

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

@@ -0,0 +1 @@
+driftguard

driftguard_audit-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "driftguard-audit"
+version = "0.1.0"
+description = "Offline security capability diffing for Python package releases"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Adnan Omar" }]
+keywords = ["security", "supply-chain", "python", "static-analysis", "dependency-audit"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Security",
+]
+dependencies = []
+
+[project.scripts]
+driftguard = "driftguard.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/adnanomar77/driftguard-audit"
+Repository = "https://github.com/adnanomar77/driftguard-audit"
+Issues = "https://github.com/adnanomar77/driftguard-audit/issues"
+
+[project.optional-dependencies]
+test = ["pytest>=7"]
+
+[tool.setuptools.packages.find]
+include = ["driftguard*"]
+
+[tool.setuptools.package-data]
+driftguard = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+filterwarnings = ["error"]
+markers = ["security: security-focused tests"]

driftguard_audit-0.1.0/setup.cfg

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

driftguard_audit-0.1.0/tests/test_analyzer.py

@@ -0,0 +1,49 @@
+from pathlib import Path
+from zipfile import ZipFile
+
+import pytest
+
+from driftguard import analyze_package, compare_packages
+
+
+def write_pkg(root: Path, body: str) -> Path:
+    root.mkdir()
+    (root / "pkg.py").write_text(body, encoding="utf-8")
+    return root
+
+
+def test_detects_new_network_and_process(tmp_path):
+    old = write_pkg(tmp_path / "old", "def run():\n    return 1\n")
+    new = write_pkg(tmp_path / "new", "import socket\nimport subprocess\ndef run():\n    socket.socket()\n    subprocess.run(['x'])\n")
+    report = compare_packages(old, new)
+    assert report.decision == "REVIEW"
+    assert {x.kind for x in report.added} == {"network_access", "process_spawn"}
+
+
+def test_same_capabilities_are_unchanged(tmp_path):
+    old = write_pkg(tmp_path / "old", "import os\nprint(os.environ.get('X'))\n")
+    new = write_pkg(tmp_path / "new", "import os\nprint(os.environ.get('X'))\n")
+    report = compare_packages(old, new)
+    assert report.decision == "UNCHANGED"
+    assert len(report.unchanged) >= 1
+
+
+def test_zip_is_supported_without_execution(tmp_path):
+    archive = tmp_path / "pkg.whl"
+    with ZipFile(archive, "w") as zf:
+        zf.writestr("pkg/__init__.py", "import ctypes\n")
+    found = analyze_package(archive)
+    assert any(item.kind == "native_code" for item in found)
+
+
+def test_zip_path_escape_is_rejected(tmp_path):
+    archive = tmp_path / "evil.zip"
+    with ZipFile(archive, "w") as zf:
+        zf.writestr("../../outside.py", "import socket\n")
+    with pytest.raises(ValueError, match="escapes"):
+        analyze_package(archive)
+
+
+def test_missing_input_is_rejected(tmp_path):
+    with pytest.raises(FileNotFoundError):
+        analyze_package(tmp_path / "missing.whl")