appbinary-inspector 0.1.0__tar.gz → 0.2.0__tar.gz

appbinary_inspector-0.2.0/PKG-INFO

@@ -0,0 +1,65 @@
+Metadata-Version: 2.5
+Name: appbinary-inspector
+Version: 0.2.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
+Provides-Extra: torch
+Requires-Dist: torch>=2.1; extra == 'torch'
+Description-Content-Type: text/markdown
+
+# appbinary-inspector
+
+Static inspection of application binaries, text tokenization, and config-first PyTorch model building without executing analyzed files.
+
+## 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
+- Exports PE headers and raw binary sections for authorized analysis
+- Builds a compact tokenizer for source code, logs, or extracted text
+- Provides editable PyTorch classifier, autoencoder, and transformer templates
+
+## Install
+
+```bash
+pip install appbinary-inspector
+```
+
+## Use
+
+```bash
+appbin inspect program.exe
+appbin extract program.exe --output extracted
+appbin binary-extract program.exe --output pe_parts
+appbin tokenize source.py --vocab source-tokenizer.json
+appbin model-template classifier
+```
+
+## PyTorch models
+
+Install optional PyTorch support:
+
+```bash
+pip install "appbinary-inspector[torch]"
+```
+
+```python
+from appbinary_inspector.torch_builder import create_model, preset
+
+config = preset("classifier")
+config["layers"][0]["out_features"] = 512
+model = create_model(config)
+```
+
+## 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, export raw PE sections, and extract recognizable embedded content from files you are authorized to inspect.

appbinary_inspector-0.2.0/README.md

@@ -0,0 +1,50 @@
+# appbinary-inspector
+
+Static inspection of application binaries, text tokenization, and config-first PyTorch model building without executing analyzed files.
+
+## 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
+- Exports PE headers and raw binary sections for authorized analysis
+- Builds a compact tokenizer for source code, logs, or extracted text
+- Provides editable PyTorch classifier, autoencoder, and transformer templates
+
+## Install
+
+```bash
+pip install appbinary-inspector
+```
+
+## Use
+
+```bash
+appbin inspect program.exe
+appbin extract program.exe --output extracted
+appbin binary-extract program.exe --output pe_parts
+appbin tokenize source.py --vocab source-tokenizer.json
+appbin model-template classifier
+```
+
+## PyTorch models
+
+Install optional PyTorch support:
+
+```bash
+pip install "appbinary-inspector[torch]"
+```
+
+```python
+from appbinary_inspector.torch_builder import create_model, preset
+
+config = preset("classifier")
+config["layers"][0]["out_features"] = 512
+model = create_model(config)
+```
+
+## 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, export raw PE sections, and extract recognizable embedded content from files you are authorized to inspect.

{appbinary_inspector-0.1.0 → appbinary_inspector-0.2.0}/pyproject.toml

@@ -4,17 +4,24 @@ build-backend = "hatchling.build"
 
 [project]
 name = "appbinary-inspector"
-version = "0.1.0"
+version = "0.2.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"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+]
 dependencies = []
 
+[project.optional-dependencies]
+torch = ["torch>=2.1"]
+
 [project.scripts]
 appbin = "appbinary_inspector.cli:main"
 
 [tool.hatch.build.targets.wheel]
-packages = ["src/appbinary_inspector"]
+packages = ["src/appbinary_inspector"]

appbinary_inspector-0.2.0/src/appbinary_inspector/__init__.py

@@ -0,0 +1,8 @@
+"""Static binary inspection without executing the analyzed file."""
+
+from .analyzer import inspect_file
+from .extract import extract_binary_parts, extract_embedded
+from .tokenizer import WordTokenizer
+
+__all__ = ["inspect_file", "extract_embedded", "extract_binary_parts", "WordTokenizer"]
+__version__ = "0.2.0"

appbinary_inspector-0.2.0/src/appbinary_inspector/cli.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from .analyzer import inspect_file
+from .extract import extract_embedded
+from .extract import extract_binary_parts
+from .tokenizer import WordTokenizer
+from .torch_builder import PRESETS
+
+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)
+    parts_cmd = commands.add_parser("binary-extract", help="export PE headers and raw sections")
+    parts_cmd.add_argument("file")
+    parts_cmd.add_argument("--output", required=True)
+    tokenize_cmd = commands.add_parser("tokenize", help="train a tokenizer and encode a text/source file")
+    tokenize_cmd.add_argument("file")
+    tokenize_cmd.add_argument("--vocab", default="tokenizer.json")
+    tokenize_cmd.add_argument("--max-vocab", type=int, default=20_000)
+    preset_cmd = commands.add_parser("model-template", help="print a PyTorch model configuration preset")
+    preset_cmd.add_argument("name", choices=sorted(PRESETS))
+    args = parser.parse_args()
+    if args.command == "inspect":
+        result = inspect_file(args.file, args.strings)
+    elif args.command == "extract":
+        result = extract_embedded(args.file, args.output)
+    elif args.command == "binary-extract":
+        result = extract_binary_parts(args.file, args.output)
+    elif args.command == "tokenize":
+        text = Path(args.file).read_text(encoding="utf-8", errors="replace")
+        tokenizer = WordTokenizer().fit([text], max_vocab=args.max_vocab)
+        tokenizer.save(args.vocab)
+        result = {"vocabulary_path": args.vocab, "vocabulary_size": len(tokenizer.vocabulary), "tokens": tokenizer.tokenize(text), "ids": tokenizer.encode(text)}
+    else:
+        result = PRESETS[args.name]
+    print(json.dumps(result, indent=2))
+
+if __name__ == "__main__":
+    main()

appbinary_inspector-0.2.0/src/appbinary_inspector/extract.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+import io
+import json
+import struct
+import zipfile
+from pathlib import Path
+
+from .formats import EMBEDDED_SIGNATURES
+
+
+def extract_binary_parts(path: str | Path, output_dir: str | Path) -> dict:
+    """Write raw PE sections and a manifest. Reads bytes only; never executes code."""
+    source, destination = Path(path), Path(output_dir)
+    destination.mkdir(parents=True, exist_ok=True)
+    data = source.read_bytes()
+    manifest: dict = {"source": str(source), "size_bytes": len(data), "parts": []}
+    if not data.startswith(b"MZ") or len(data) < 0x40:
+        raise ValueError("binary-parts currently supports Windows PE files beginning with MZ")
+    pe_offset = struct.unpack_from("<I", data, 0x3C)[0]
+    if data[pe_offset:pe_offset + 4] != b"PE\0\0":
+        raise ValueError("invalid PE header")
+    _, section_count, _, _, _, optional_size, _ = struct.unpack_from("<HHIIIHH", data, pe_offset + 4)
+    header_end = pe_offset + 24 + optional_size + section_count * 40
+    header_path = destination / "pe_headers.bin"
+    header_path.write_bytes(data[:min(header_end, len(data))])
+    manifest["parts"].append({"name": "headers", "offset": 0, "size": header_path.stat().st_size, "path": str(header_path)})
+    table_offset = pe_offset + 24 + optional_size
+    for index in range(section_count):
+        entry = table_offset + index * 40
+        name = data[entry:entry + 8].split(b"\0", 1)[0].decode("ascii", "replace") or f"section_{index}"
+        raw_size, raw_offset = struct.unpack_from("<II", data, entry + 16)
+        content = data[raw_offset:min(raw_offset + raw_size, len(data))] if raw_offset < len(data) else b""
+        safe_name = "".join(char if char.isalnum() or char in "._-" else "_" for char in name)
+        section_path = destination / f"{index:02d}_{safe_name}.bin"
+        section_path.write_bytes(content)
+        manifest["parts"].append({"name": name, "offset": raw_offset, "size": len(content), "path": str(section_path)})
+    (destination / "manifest.json").write_text(json.dumps(manifest, indent=2), encoding="utf-8")
+    return manifest
+
+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.
+
+    ZIP data is extracted only when it starts at a detected signature and passes
+    ZIP validation. Other formats are preserved from their signature to EOF for
+    analyst review, avoiding guesses about encrypted or packed payload bounds.
+    """
+    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.2.0/src/appbinary_inspector/tokenizer.py

@@ -0,0 +1,48 @@
+"""Small, dependency-free tokenizer for source, logs, and extracted text."""
+from __future__ import annotations
+
+import json
+import re
+from collections import Counter
+from pathlib import Path
+
+TOKEN_PATTERN = re.compile(r"[A-Za-z_][A-Za-z_0-9]*|\d+(?:\.\d+)?|[^\s]", re.UNICODE)
+SPECIAL_TOKENS = ("<pad>", "<unk>", "<bos>", "<eos>")
+
+
+class WordTokenizer:
+    """Train a compact word/code tokenizer without external model downloads."""
+
+    def __init__(self, vocabulary: dict[str, int] | None = None) -> None:
+        self.vocabulary = vocabulary or {token: index for index, token in enumerate(SPECIAL_TOKENS)}
+        self.inverse_vocabulary = {index: token for token, index in self.vocabulary.items()}
+
+    @staticmethod
+    def tokenize(text: str) -> list[str]:
+        return TOKEN_PATTERN.findall(text)
+
+    def fit(self, texts: list[str], max_vocab: int = 20_000, min_frequency: int = 1) -> "WordTokenizer":
+        if max_vocab < len(SPECIAL_TOKENS):
+            raise ValueError("max_vocab must allow the special tokens")
+        counts = Counter(token for text in texts for token in self.tokenize(text))
+        self.vocabulary = {token: index for index, token in enumerate(SPECIAL_TOKENS)}
+        for token, count in counts.most_common(max_vocab - len(SPECIAL_TOKENS)):
+            if count < min_frequency:
+                continue
+            self.vocabulary[token] = len(self.vocabulary)
+        self.inverse_vocabulary = {index: token for token, index in self.vocabulary.items()}
+        return self
+
+    def encode(self, text: str, add_boundaries: bool = False) -> list[int]:
+        ids = [self.vocabulary.get(token, self.vocabulary["<unk>"]) for token in self.tokenize(text)]
+        return ([self.vocabulary["<bos>"]] + ids + [self.vocabulary["<eos>"]]) if add_boundaries else ids
+
+    def decode(self, ids: list[int]) -> list[str]:
+        return [self.inverse_vocabulary.get(index, "<unk>") for index in ids]
+
+    def save(self, path: str | Path) -> None:
+        Path(path).write_text(json.dumps({"vocabulary": self.vocabulary}, indent=2), encoding="utf-8")
+
+    @classmethod
+    def load(cls, path: str | Path) -> "WordTokenizer":
+        return cls(json.loads(Path(path).read_text(encoding="utf-8"))["vocabulary"])

appbinary_inspector-0.2.0/src/appbinary_inspector/torch_builder.py

@@ -0,0 +1,70 @@
+"""Config-first PyTorch model construction with no hidden training framework."""
+from __future__ import annotations
+
+from copy import deepcopy
+
+PRESETS = {
+    "classifier": {"input_features": 128, "layers": [{"type": "linear", "out_features": 256}, {"type": "relu"}, {"type": "dropout", "p": 0.2}, {"type": "linear", "out_features": 10}]},
+    "autoencoder": {"input_features": 128, "layers": [{"type": "linear", "out_features": 64}, {"type": "relu"}, {"type": "linear", "out_features": 16}, {"type": "relu"}, {"type": "linear", "out_features": 64}, {"type": "relu"}, {"type": "linear", "out_features": 128}]},
+    "text_transformer": {"vocab_size": 20_000, "embedding_dim": 128, "sequence_length": 128, "transformer_layers": 2, "heads": 4, "classes": 2},
+}
+
+
+def preset(name: str) -> dict:
+    if name not in PRESETS:
+        raise ValueError(f"Unknown preset: {name}. Choose from {', '.join(PRESETS)}")
+    return deepcopy(PRESETS[name])
+
+
+def create_model(config: dict):
+    """Build an nn.Module from a transparent config. Requires ``pip install appbinary-inspector[torch]``."""
+    try:
+        import torch.nn as nn
+    except ImportError as error:
+        raise RuntimeError("PyTorch is optional. Install it with: pip install appbinary-inspector[torch]") from error
+
+    if config.get("kind") == "transformer" or "vocab_size" in config:
+        required = ("vocab_size", "embedding_dim", "sequence_length", "transformer_layers", "heads", "classes")
+        missing = [key for key in required if key not in config]
+        if missing:
+            raise ValueError(f"Missing transformer settings: {', '.join(missing)}")
+        d_model = config["embedding_dim"]
+        encoder = nn.TransformerEncoder(
+            nn.TransformerEncoderLayer(d_model=d_model, nhead=config["heads"], batch_first=True),
+            num_layers=config["transformer_layers"],
+        )
+
+        class TokenClassifier(nn.Module):
+            def __init__(self) -> None:
+                super().__init__()
+                self.embedding = nn.Embedding(config["vocab_size"], d_model)
+                self.encoder = encoder
+                self.head = nn.Linear(d_model, config["classes"])
+
+            def forward(self, token_ids):
+                encoded = self.encoder(self.embedding(token_ids))
+                return self.head(encoded.mean(dim=1))
+
+        return TokenClassifier()
+
+    features = config.get("input_features")
+    if not isinstance(features, int) or features < 1:
+        raise ValueError("input_features must be a positive integer")
+    layers = []
+    for spec in config.get("layers", []):
+        kind = spec.get("type", "").lower()
+        if kind == "linear":
+            out_features = spec.get("out_features")
+            if not isinstance(out_features, int) or out_features < 1:
+                raise ValueError("linear layers require positive out_features")
+            layers.append(nn.Linear(features, out_features))
+            features = out_features
+        elif kind in {"relu", "gelu", "tanh", "sigmoid", "flatten"}:
+            layers.append({"relu": nn.ReLU, "gelu": nn.GELU, "tanh": nn.Tanh, "sigmoid": nn.Sigmoid, "flatten": nn.Flatten}[kind]())
+        elif kind == "dropout":
+            layers.append(nn.Dropout(float(spec.get("p", 0.5))))
+        else:
+            raise ValueError(f"Unsupported layer type: {kind}")
+    if not layers:
+        raise ValueError("config requires at least one layer")
+    return nn.Sequential(*layers)

appbinary_inspector-0.1.0/PKG-INFO

@@ -1,41 +0,0 @@
-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

@@ -1,28 +0,0 @@
-# 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/src/appbinary_inspector/__init__.py

@@ -1,7 +0,0 @@
-"""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/cli.py

@@ -1,23 +0,0 @@
-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

@@ -1,41 +0,0 @@
-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