appbinary-inspector 0.1.0__tar.gz

appbinary_inspector-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,28 @@
+name: Publish to PyPI
+
+on:
+  workflow_dispatch:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/appbinary-inspector
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build package
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build
+      - name: Publish package
+        uses: pypa/gh-action-pypi-publish@release/v1

appbinary_inspector-0.1.0/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 William Laurento
+
+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.

appbinary_inspector-0.1.0/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.5
+Name: appbinary-inspector
+Version: 0.1.0
+Summary: Safe static inspection and embedded-file extraction for application binaries.
+Author: William Laurento
+License: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# appbinary-inspector
+
+Static inspection of application binaries without executing them.
+
+## Features
+
+- Detects PE, ELF, Mach-O, ZIP, 7z, and RAR headers
+- Calculates SHA-256 and SHA-1 hashes
+- Extracts readable strings and entropy
+- Reads basic PE header metadata
+- Extracts embedded ZIP archives and carves recognizable binary signatures
+
+## Install
+
+```bash
+pip install appbinary-inspector
+```
+
+## Use
+
+```bash
+appbin inspect program.exe
+appbin extract program.exe --output extracted
+```
+
+## Safety
+
+Targets are read as bytes only and never executed. The package does not defeat encryption, DRM, licensing controls, passwords, or code protections. It can analyze plaintext and extract recognizable embedded content from files you are authorized to inspect.

appbinary_inspector-0.1.0/README.md

@@ -0,0 +1,28 @@
+# appbinary-inspector
+
+Static inspection of application binaries without executing them.
+
+## Features
+
+- Detects PE, ELF, Mach-O, ZIP, 7z, and RAR headers
+- Calculates SHA-256 and SHA-1 hashes
+- Extracts readable strings and entropy
+- Reads basic PE header metadata
+- Extracts embedded ZIP archives and carves recognizable binary signatures
+
+## Install
+
+```bash
+pip install appbinary-inspector
+```
+
+## Use
+
+```bash
+appbin inspect program.exe
+appbin extract program.exe --output extracted
+```
+
+## Safety
+
+Targets are read as bytes only and never executed. The package does not defeat encryption, DRM, licensing controls, passwords, or code protections. It can analyze plaintext and extract recognizable embedded content from files you are authorized to inspect.

appbinary_inspector-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "appbinary-inspector"
+version = "0.1.0"
+description = "Safe static inspection and embedded-file extraction for application binaries."
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [{name = "William Laurento"}]
+classifiers = ["Programming Language :: Python :: 3", "License :: OSI Approved :: MIT License", "Operating System :: OS Independent"]
+dependencies = []
+
+[project.scripts]
+appbin = "appbinary_inspector.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/appbinary_inspector"]

appbinary_inspector-0.1.0/src/appbinary_inspector/__init__.py

@@ -0,0 +1,7 @@
+"""Static binary inspection without executing the analyzed file."""
+
+from .analyzer import inspect_file
+from .extract import extract_embedded
+
+__all__ = ["inspect_file", "extract_embedded"]
+__version__ = "0.1.0"

appbinary_inspector-0.1.0/src/appbinary_inspector/analyzer.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+import hashlib
+import math
+import re
+import struct
+from pathlib import Path
+
+from .formats import detect_format
+
+PRINTABLE = re.compile(rb"[\x20-\x7e]{4,}")
+
+def _entropy(data: bytes) -> float:
+    if not data:
+        return 0.0
+    counts = [0] * 256
+    for value in data:
+        counts[value] += 1
+    return -sum((n / len(data)) * math.log2(n / len(data)) for n in counts if n)
+
+def _pe_metadata(data: bytes) -> dict:
+    if not data.startswith(b"MZ") or len(data) < 0x40:
+        return {}
+    offset = struct.unpack_from("<I", data, 0x3C)[0]
+    if offset + 24 > len(data) or data[offset:offset + 4] != b"PE\0\0":
+        return {"valid": False}
+    machine, sections, timestamp, _, _, opt_size, characteristics = struct.unpack_from("<HHIIIHH", data, offset + 4)
+    machine_names = {0x14C: "x86", 0x8664: "x86-64", 0xAA64: "ARM64"}
+    return {"valid": True, "architecture": machine_names.get(machine, hex(machine)), "section_count": sections, "timestamp_utc": timestamp, "optional_header_size": opt_size, "characteristics": hex(characteristics)}
+
+def inspect_file(path: str | Path, string_limit: int = 200) -> dict:
+    """Return static metadata. The target file is never executed."""
+    target = Path(path)
+    data = target.read_bytes()
+    report = {"path": str(target), "size_bytes": len(data), "format": detect_format(target), "sha256": hashlib.sha256(data).hexdigest(), "sha1": hashlib.sha1(data).hexdigest(), "entropy": round(_entropy(data), 4), "strings": [s.decode("utf-8", "replace") for s in PRINTABLE.findall(data)[:string_limit]]}
+    if data.startswith(b"MZ"):
+        report["pe"] = _pe_metadata(data)
+    return report

appbinary_inspector-0.1.0/src/appbinary_inspector/cli.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+import argparse
+import json
+
+from .analyzer import inspect_file
+from .extract import extract_embedded
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Static application-binary inspector. Never executes targets.")
+    commands = parser.add_subparsers(dest="command", required=True)
+    inspect_cmd = commands.add_parser("inspect", help="inspect a binary")
+    inspect_cmd.add_argument("file")
+    inspect_cmd.add_argument("--strings", type=int, default=200)
+    extract_cmd = commands.add_parser("extract", help="extract recognizable embedded files")
+    extract_cmd.add_argument("file")
+    extract_cmd.add_argument("--output", required=True)
+    args = parser.parse_args()
+    result = inspect_file(args.file, args.strings) if args.command == "inspect" else extract_embedded(args.file, args.output)
+    print(json.dumps(result, indent=2))
+
+if __name__ == "__main__":
+    main()

appbinary_inspector-0.1.0/src/appbinary_inspector/extract.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import io
+import zipfile
+from pathlib import Path
+
+from .formats import EMBEDDED_SIGNATURES
+
+def extract_embedded(path: str | Path, output_dir: str | Path, min_offset: int = 1) -> list[dict]:
+    """Carve recognizable embedded files without executing or decrypting content."""
+    source = Path(path)
+    destination = Path(output_dir)
+    destination.mkdir(parents=True, exist_ok=True)
+    data = source.read_bytes()
+    found: list[dict] = []
+    seen: set[tuple[int, str]] = set()
+    for signature, (kind, extension) in EMBEDDED_SIGNATURES.items():
+        start = 0
+        while True:
+            index = data.find(signature, start)
+            if index < 0:
+                break
+            start = index + 1
+            if index < min_offset or (index, kind) in seen:
+                continue
+            seen.add((index, kind))
+            stem = f"{source.stem}_offset_{index:08x}"
+            if kind == "zip":
+                try:
+                    with zipfile.ZipFile(io.BytesIO(data[index:])) as archive:
+                        member_dir = destination / stem
+                        member_dir.mkdir(exist_ok=True)
+                        archive.extractall(member_dir)
+                        found.append({"offset": index, "type": kind, "path": str(member_dir), "members": archive.namelist()})
+                except (zipfile.BadZipFile, OSError):
+                    pass
+            else:
+                carved = destination / f"{stem}{extension}"
+                carved.write_bytes(data[index:])
+                found.append({"offset": index, "type": kind, "path": str(carved), "note": "carved from signature through EOF"})
+    return found

appbinary_inspector-0.1.0/src/appbinary_inspector/formats.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+MAGIC = {
+    b"MZ": "PE executable (Windows)",
+    b"\x7fELF": "ELF executable (Linux/Unix)",
+    b"\xcf\xfa\xed\xfe": "Mach-O executable (macOS, 64-bit)",
+    b"\xfe\xed\xfa\xcf": "Mach-O executable (macOS, 64-bit, swapped)",
+    b"PK\x03\x04": "ZIP archive",
+    b"7z\xbc\xaf'\x1c": "7z archive",
+    b"Rar!\x1a\x07": "RAR archive",
+}
+
+EMBEDDED_SIGNATURES = {
+    b"PK\x03\x04": ("zip", ".zip"),
+    b"\x1f\x8b\x08": ("gzip", ".gz"),
+    b"7z\xbc\xaf'\x1c": ("7z", ".7z"),
+    b"MZ": ("pe", ".exe"),
+    b"\x7fELF": ("elf", ".elf"),
+    b"%PDF-": ("pdf", ".pdf"),
+    b"\x89PNG\r\n\x1a\n": ("png", ".png"),
+}
+
+def detect_format(path: Path) -> str:
+    header = path.read_bytes()[:16]
+    for signature, name in MAGIC.items():
+        if header.startswith(signature):
+            return name
+    return "Unknown binary/data"