elfpeek 0.2.0__tar.gz

elfpeek-0.2.0/LICENSE

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

elfpeek-0.2.0/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.4
+Name: elfpeek
+Version: 0.2.0
+Summary: Parse ELF/PE binaries and render them as a structural map: section layout, entry point, dependencies, symbols, hardening features, entropy and strings.
+License-Expression: MIT
+Keywords: elf,binary,visualization,reverse-engineering,blue-team,static-analysis
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Topic :: Software Development :: Disassemblers
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# elfpeek
+
+把 ELF / PE 二进制解析成一张结构图：节区与段布局、内存映射、入口点、动态依赖与符号、加固特性、节区熵与字符串，一眼看清二进制骨架。
+
+- 纯 Python 标准库，零第三方依赖
+- 只读解析：不加载、不执行二进制中的任何代码
+- ELF 32/64 位、大小端均支持；PE/COFF 32/64 位支持
+- 输出面向逆向与蓝队：终端中文摘要 + 自包含 HTML（纯 SVG 布局图，无 JS，可直接截图存档）+ JSON
+
+## 安装
+
+```bash
+pip install elfpeek
+```
+
+## 使用
+
+```bash
+# 终端输出结构摘要（自动识别 ELF / PE）
+elfpeek /bin/true
+elfpeek sample.exe
+
+# 导出自包含 HTML 结构图（含布局条带，可截图）
+elfpeek /bin/true --html report.html
+
+# 导出 JSON 供其他工具消费
+elfpeek /bin/true --json report.json
+```
+
+## 输出内容
+
+| 板块 | 内容 |
+|------|------|
+| 文件总览 | 格式、大小、位宽、端序、类型、机器架构、入口地址、SONAME；PE 另含映像基址与子系统 |
+| 加固特性 | ELF：PIE / NX / RELRO（完整或部分）/ Canary / FORTIFY / RWX 段；PE：ASLR / DEP / CFG / 高熵 VA / SEHOP / RWX 节区 |
+| 文件布局 | 水平条带，按各节区在文件中的大小比例着色 |
+| 内存布局 | 按运行时虚拟地址排序的节区/段映射，标注地址区间与权限 |
+| 节区表 | 名称、偏移、地址、大小、标志（WAX / CDXR），并附节区熵值（高熵标红提示加壳或压缩） |
+| 动态依赖 | ELF：DT_NEEDED 共享库；PE：导入动态库 |
+| 符号与函数 | ELF：导入/导出函数摘要；PE：导入函数与导出函数列表 |
+| 字符串 | 可打印字符串提取，按 URL / IP / 路径 / 共享库分类 |
+
+## 开发
+
+```bash
+# 运行测试（含 ELF 与 PE builder fixture，无需真实系统文件）
+python3 -m pytest tests/ -q
+
+# 静态检查
+python3 -m ruff check .
+```
+
+架构说明：`parse.py` 用 `struct` 纯手工解析 ELF 头、程序头表、节区头表、动态段与符号表（32/64 位、大小端自适应）；`pe.py` 以同样方式解析 PE 的 DOS/COFF/可选头、节区、导入表与导出表，并含 RVA 到文件偏移换算；`checks.py` 负责加固特性判定、节区熵计算与字符串提取分类；`model.py` 是数据模型与类型常量映射；`render/` 负责终端与 HTML 渲染；`cli.py` 按魔数分发到对应解析器。
+
+## License
+
+MIT

elfpeek-0.2.0/README.md

@@ -0,0 +1,57 @@
+# elfpeek
+
+把 ELF / PE 二进制解析成一张结构图：节区与段布局、内存映射、入口点、动态依赖与符号、加固特性、节区熵与字符串，一眼看清二进制骨架。
+
+- 纯 Python 标准库，零第三方依赖
+- 只读解析：不加载、不执行二进制中的任何代码
+- ELF 32/64 位、大小端均支持；PE/COFF 32/64 位支持
+- 输出面向逆向与蓝队：终端中文摘要 + 自包含 HTML（纯 SVG 布局图，无 JS，可直接截图存档）+ JSON
+
+## 安装
+
+```bash
+pip install elfpeek
+```
+
+## 使用
+
+```bash
+# 终端输出结构摘要（自动识别 ELF / PE）
+elfpeek /bin/true
+elfpeek sample.exe
+
+# 导出自包含 HTML 结构图（含布局条带，可截图）
+elfpeek /bin/true --html report.html
+
+# 导出 JSON 供其他工具消费
+elfpeek /bin/true --json report.json
+```
+
+## 输出内容
+
+| 板块 | 内容 |
+|------|------|
+| 文件总览 | 格式、大小、位宽、端序、类型、机器架构、入口地址、SONAME；PE 另含映像基址与子系统 |
+| 加固特性 | ELF：PIE / NX / RELRO（完整或部分）/ Canary / FORTIFY / RWX 段；PE：ASLR / DEP / CFG / 高熵 VA / SEHOP / RWX 节区 |
+| 文件布局 | 水平条带，按各节区在文件中的大小比例着色 |
+| 内存布局 | 按运行时虚拟地址排序的节区/段映射，标注地址区间与权限 |
+| 节区表 | 名称、偏移、地址、大小、标志（WAX / CDXR），并附节区熵值（高熵标红提示加壳或压缩） |
+| 动态依赖 | ELF：DT_NEEDED 共享库；PE：导入动态库 |
+| 符号与函数 | ELF：导入/导出函数摘要；PE：导入函数与导出函数列表 |
+| 字符串 | 可打印字符串提取，按 URL / IP / 路径 / 共享库分类 |
+
+## 开发
+
+```bash
+# 运行测试（含 ELF 与 PE builder fixture，无需真实系统文件）
+python3 -m pytest tests/ -q
+
+# 静态检查
+python3 -m ruff check .
+```
+
+架构说明：`parse.py` 用 `struct` 纯手工解析 ELF 头、程序头表、节区头表、动态段与符号表（32/64 位、大小端自适应）；`pe.py` 以同样方式解析 PE 的 DOS/COFF/可选头、节区、导入表与导出表，并含 RVA 到文件偏移换算；`checks.py` 负责加固特性判定、节区熵计算与字符串提取分类；`model.py` 是数据模型与类型常量映射；`render/` 负责终端与 HTML 渲染；`cli.py` 按魔数分发到对应解析器。
+
+## License
+
+MIT

elfpeek-0.2.0/elfpeek/__init__.py

@@ -0,0 +1,10 @@
+"""elfpeek: render an ELF/PE binary as a structural map."""
+
+from __future__ import annotations
+
+from .model import ElfFile, PEFile
+from .parse import parse
+from .pe import parse_pe
+
+__version__ = "0.2.0"
+__all__ = ["ElfFile", "PEFile", "__version__", "parse", "parse_pe"]

elfpeek-0.2.0/elfpeek/checks.py

@@ -0,0 +1,179 @@
+"""Security feature detection, entropy and string extraction."""
+
+from __future__ import annotations
+
+import math
+import re
+
+from .model import ElfFile
+
+__all__ = [
+    "SecurityFeature",
+    "StringHit",
+    "extract_strings",
+    "section_entropy",
+    "security_features",
+]
+
+ET_DYN = 3
+PT_GNU_STACK = 0x6474E551
+PT_GNU_RELRO = 0x6474E552
+DF_BIND_NOW = 0x8
+DF_1_NOW = 0x1
+MIN_STRING_LEN = 4
+
+CANARY_SYMBOL = "__stack_chk_fail"
+FORTIFY_RE = re.compile(r"__(?:\w+)_chk$")
+URL_RE = re.compile(r"https?://[\w./%\-?=&#:+]+")
+PATH_RE = re.compile(r"(?:/[a-zA-Z0-9._\-]+){2,}")
+IP_RE = re.compile(r"\b(?:\d{1,3}\.){3}\d{1,3}\b")
+
+
+class SecurityFeature:
+    """One checksec-style property."""
+
+    __slots__ = ("detail", "name", "status")
+
+    def __init__(self, name: str, status: str, detail: str = "") -> None:
+        # status: "yes" / "no" / "unknown"
+        self.name = name
+        self.status = status
+        self.detail = detail
+
+
+class StringHit:
+    """One extracted printable string with a best-effort category."""
+
+    __slots__ = ("category", "offset", "value")
+
+    def __init__(self, value: str, category: str, offset: int) -> None:
+        self.value = value
+        self.category = category
+        self.offset = offset
+
+
+def security_features(elf: ElfFile) -> list[SecurityFeature]:
+    """Return checksec-style hardening properties for an ELF binary."""
+    features: list[SecurityFeature] = []
+
+    is_pie = elf.type == ET_DYN
+    features.append(
+        SecurityFeature(
+            "PIE",
+            "yes" if is_pie else "no",
+            "ET_DYN，加载基址随机化" if is_pie else "ET_EXEC，固定基址",
+        )
+    )
+
+    stack = next((seg for seg in elf.segments if seg.type == PT_GNU_STACK), None)
+    if stack is None:
+        features.append(SecurityFeature("NX", "unknown", "无 GNU_STACK 段，栈权限未知"))
+    elif stack.flags & 0x1:
+        features.append(SecurityFeature("NX", "no", "GNU_STACK 含可执行位，栈可执行"))
+    else:
+        features.append(SecurityFeature("NX", "yes", "栈不可执行"))
+
+    has_relro = any(seg.type == PT_GNU_RELRO for seg in elf.segments)
+    bind_now = bool(elf.dt_flags & DF_BIND_NOW) or bool(elf.dt_flags_1 & DF_1_NOW)
+    if has_relro and bind_now:
+        features.append(SecurityFeature("RELRO", "full", "GNU_RELRO + BIND_NOW，完全只读重定位"))
+    elif has_relro:
+        features.append(SecurityFeature("RELRO", "partial", "GNU_RELRO，部分只读重定位"))
+    else:
+        features.append(SecurityFeature("RELRO", "no", "无 RELRO 段"))
+
+    names = {sym.name for sym in elf.symbols}
+    features.append(
+        SecurityFeature(
+            "Canary",
+            "yes" if CANARY_SYMBOL in names else "no",
+            "检测到栈溢出保护符号" if CANARY_SYMBOL in names else "未发现栈溢出保护符号",
+        )
+    )
+    fortified = [name for name in names if FORTIFY_RE.match(name)]
+    features.append(
+        SecurityFeature(
+            "FORTIFY",
+            "yes" if fortified else "no",
+            f"检测到 {len(fortified)} 个 _chk 加固函数" if fortified else "未发现 FORTIFY 加固符号",
+        )
+    )
+
+    rwx = [seg for seg in elf.segments if seg.flags & 0x7 == 0x7]
+    if rwx:
+        features.append(
+            SecurityFeature("RWX段", "warn", f"存在可读可写可执行段：{', '.join(seg.type_name for seg in rwx)}")
+        )
+    else:
+        features.append(SecurityFeature("RWX段", "no", "无 RWX 段"))
+    return features
+
+
+def section_entropy(data: bytes, offset: int, size: int) -> float:
+    """Shannon entropy of a section's bytes (0-8 bits)."""
+    if size <= 0 or offset < 0 or offset >= len(data):
+        return 0.0
+    end = min(offset + size, len(data))
+    chunk = data[offset:end]
+    if not chunk:
+        return 0.0
+    counts = [0] * 256
+    for byte in chunk:
+        counts[byte] += 1
+    total = len(chunk)
+    entropy = 0.0
+    for count in counts:
+        if count:
+            p = count / total
+            entropy -= p * math.log2(p)
+    return entropy
+
+
+def fill_entropy(obj, data: bytes) -> None:
+    """Compute and store entropy on every section of a parsed binary."""
+    for sec in obj.sections:
+        offset = getattr(sec, "offset", None)
+        if offset is None:
+            offset = getattr(sec, "raw_offset", 0)
+        size = getattr(sec, "size", None)
+        if size is None:
+            size = getattr(sec, "raw_size", 0)
+        if getattr(sec, "is_nobits", False) or size <= 0:
+            sec.entropy = 0.0
+            continue
+        sec.entropy = section_entropy(data, offset, size)
+
+
+def extract_strings(data: bytes, *, min_len: int = MIN_STRING_LEN, limit: int = 200) -> list[StringHit]:
+    """Extract printable ASCII runs and classify URL/path/IP-like ones."""
+    hits: list[StringHit] = []
+    start = -1
+    n = len(data)
+    for i in range(n):
+        byte = data[i]
+        if 0x20 <= byte < 0x7F:
+            if start == -1:
+                start = i
+        else:
+            if start != -1 and i - start >= min_len:
+                _emit_string(hits, data[start:i], start)
+                if len(hits) >= limit:
+                    return hits
+            start = -1
+    if start != -1 and n - start >= min_len:
+        _emit_string(hits, data[start:n], start)
+    return hits
+
+
+def _emit_string(hits: list[StringHit], raw: bytes, offset: int) -> None:
+    value = raw.decode("ascii", "replace")
+    category = "other"
+    if URL_RE.search(value):
+        category = "URL"
+    elif IP_RE.search(value):
+        category = "IP"
+    elif PATH_RE.search(value):
+        category = "path"
+    elif value.strip().endswith(".so") or ".so." in value:
+        category = "library"
+    hits.append(StringHit(value, category, offset))

elfpeek-0.2.0/elfpeek/cli.py

@@ -0,0 +1,153 @@
+"""Command line entry point for elfpeek."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from . import __version__
+from .checks import extract_strings, fill_entropy
+from .model import PEFile
+from .parse import ParseError
+from .parse import parse as parse_elf
+from .pe import ParseError as PEParseError
+from .pe import parse_pe
+from .render import render_html, render_terminal
+
+__all__ = ["main"]
+
+
+def _load(path: Path):
+    """Dispatch parsing by file magic and inject entropy / strings."""
+    data = path.read_bytes()
+    if len(data) >= 4 and data[:4] == b"\x7fELF":
+        obj = parse_elf(data, str(path))
+    elif len(data) >= 2 and data[:2] == b"MZ":
+        obj = parse_pe(data, str(path))
+    else:
+        raise ParseError("不是 ELF 或 PE 文件（魔数不匹配）")
+    fill_entropy(obj, data)
+    obj.strings = extract_strings(data)
+    return obj
+
+
+def _to_dict(obj) -> dict:
+    base = {
+        "tool": "elfpeek",
+        "path": obj.path,
+        "size": obj.size,
+        "is_64": obj.is_64,
+        "type_name": obj.type_name,
+        "machine_name": obj.machine_name,
+        "entry": obj.entry,
+        "needed": list(obj.needed),
+        "strings": [
+            {"value": s.value, "category": s.category, "offset": s.offset} for s in obj.strings
+        ],
+    }
+    if isinstance(obj, PEFile):
+        base.update(
+            {
+                "format": "PE",
+                "image_base": obj.image_base,
+                "subsystem": obj.subsystem_name,
+                "exports": list(obj.exports),
+                "imports": list(obj.imports),
+                "sections": [
+                    {
+                        "name": sec.name,
+                        "vaddr": sec.virtual_address,
+                        "vsize": sec.virtual_size,
+                        "raw_offset": sec.raw_offset,
+                        "raw_size": sec.raw_size,
+                        "flags_text": sec.flags_text,
+                        "entropy": round(sec.entropy, 2),
+                    }
+                    for sec in obj.sections
+                ],
+            }
+        )
+    else:
+        base.update(
+            {
+                "format": "ELF",
+                "little_endian": obj.little_endian,
+                "soname": obj.soname,
+                "segments": [
+                    {
+                        "type_name": seg.type_name,
+                        "offset": seg.offset,
+                        "vaddr": seg.vaddr,
+                        "filesz": seg.filesz,
+                        "memsz": seg.memsz,
+                        "flags_text": seg.flags_text,
+                    }
+                    for seg in obj.segments
+                ],
+                "sections": [
+                    {
+                        "name": sec.name,
+                        "type_name": sec.type_name,
+                        "offset": sec.offset,
+                        "addr": sec.addr,
+                        "size": sec.size,
+                        "flags_text": sec.flags_text,
+                        "entropy": round(sec.entropy, 2),
+                    }
+                    for sec in obj.sections
+                ],
+                "symbols": [
+                    {"name": sym.name, "bind": sym.bind, "type": sym.type}
+                    for sym in obj.symbols
+                ],
+            }
+        )
+    return base
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="elfpeek",
+        description="把 ELF/PE 二进制解析成结构图：节区/段布局、入口、依赖、符号、安全特性与熵。",
+    )
+    parser.add_argument("file", metavar="FILE", help="待解析的 ELF 或 PE 文件路径")
+    parser.add_argument("--html", metavar="PATH", help="将结构报告导出为自包含 HTML")
+    parser.add_argument("--json", metavar="PATH", help="将解析结果导出为 JSON")
+    parser.add_argument("--version", action="version", version=f"elfpeek {__version__}")
+    args = parser.parse_args(argv)
+
+    path = Path(args.file)
+    try:
+        obj = _load(path)
+    except OSError as exc:
+        print(f"错误：无法读取文件 {path}：{exc}", file=sys.stderr)
+        return 2
+    except (ParseError, PEParseError) as exc:
+        print(f"错误：{exc}", file=sys.stderr)
+        return 1
+
+    print(render_terminal(obj))
+
+    status = 0
+    if args.html:
+        try:
+            Path(args.html).write_text(render_html(obj), encoding="utf-8")
+            print(f"HTML 报告已写入 {args.html}")
+        except OSError as exc:
+            print(f"错误：无法写入 HTML 文件 {args.html}：{exc}", file=sys.stderr)
+            status = 2
+    if args.json:
+        payload = json.dumps(_to_dict(obj), ensure_ascii=False, indent=2)
+        try:
+            Path(args.json).write_text(payload + "\n", encoding="utf-8")
+            print(f"JSON 报告已写入 {args.json}")
+        except OSError as exc:
+            print(f"错误：无法写入 JSON 文件 {args.json}：{exc}", file=sys.stderr)
+            status = 2
+    return status
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())