elfpeek 0.2.0__py3-none-any.whl

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/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/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())

elfpeek/model.py

@@ -0,0 +1,331 @@
+"""Data model for a parsed ELF binary."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+__all__ = [
+    "DT_NAMES",
+    "MACHINE_NAMES",
+    "SECTION_TYPE_NAMES",
+    "SEGMENT_TYPE_NAMES",
+    "SYMBOL_BIND_NAMES",
+    "SYMBOL_TYPE_NAMES",
+    "TYPE_NAMES",
+    "ElfFile",
+    "PEFile",
+    "PESection",
+    "Section",
+    "Segment",
+    "Symbol",
+]
+
+TYPE_NAMES: dict[int, str] = {
+    1: "可重定位",
+    2: "可执行",
+    3: "共享库",
+    4: "核心转储",
+}
+
+SEGMENT_TYPE_NAMES: dict[int, str] = {
+    0: "NULL",
+    1: "LOAD",
+    2: "DYNAMIC",
+    3: "INTERP",
+    4: "NOTE",
+    5: "SHLIB",
+    6: "PHDR",
+    7: "TLS",
+    0x6474e550: "GNU_EH_FRAME",
+    0x6474e551: "GNU_STACK",
+    0x6474e552: "GNU_RELRO",
+    0x6474e553: "GNU_PROPERTY",
+}
+
+SECTION_TYPE_NAMES: dict[int, str] = {
+    0: "NULL",
+    1: "PROGBITS",
+    2: "SYMTAB",
+    3: "STRTAB",
+    4: "RELA",
+    5: "HASH",
+    6: "DYNAMIC",
+    7: "NOTE",
+    8: "NOBITS",
+    9: "REL",
+    10: "SHLIB",
+    11: "DYNSYM",
+    14: "INIT_ARRAY",
+    15: "FINI_ARRAY",
+    16: "PREINIT_ARRAY",
+    17: "GROUP",
+    18: "SYMTAB_SHNDX",
+}
+
+DT_NAMES: dict[int, str] = {
+    0: "NULL",
+    1: "NEEDED",
+    2: "PLTRELSZ",
+    3: "PLTGOT",
+    4: "HASH",
+    5: "STRTAB",
+    6: "SYMTAB",
+    7: "RELA",
+    8: "RELASZ",
+    9: "RELAENT",
+    10: "STRSZ",
+    11: "SYMENT",
+    12: "INIT",
+    13: "FINI",
+    14: "SONAME",
+    15: "RPATH",
+    16: "SYMBOLIC",
+    17: "REL",
+    20: "PLTREL",
+    21: "DEBUG",
+    23: "JMPREL",
+    24: "BIND_NOW",
+}
+
+SYMBOL_BIND_NAMES: dict[int, str] = {
+    0: "局部",
+    1: "全局",
+    2: "弱",
+}
+
+SYMBOL_TYPE_NAMES: dict[int, str] = {
+    0: "未类型",
+    1: "对象",
+    2: "函数",
+    3: "节区",
+    4: "文件",
+    5: "COMMON",
+    6: "TLS",
+}
+
+MACHINE_NAMES: dict[int, str] = {
+    0: "未指定",
+    3: "x86",
+    40: "ARM",
+    62: "x86_64",
+    183: "AArch64",
+    243: "RISC-V",
+}
+
+PE_MACHINE_NAMES: dict[int, str] = {
+    0x14C: "x86",
+    0x8664: "x86_64",
+    0xAA64: "AArch64",
+    0x1C0: "ARM Thumb",
+}
+
+PE_SUBSYSTEM_NAMES: dict[int, str] = {
+    1: "原生",
+    2: "Windows 图形",
+    3: "Windows 控制台",
+    7: "POSIX",
+    9: "Windows CE",
+    10: "EFI 应用",
+}
+
+PE_SECTION_FLAG_TEXT = {
+    0x00000020: "C",  # CNT_CODE
+    0x00000040: "D",  # CNT_INITIALIZED_DATA
+    0x00000080: "U",  # CNT_UNINITIALIZED_DATA
+    0x20000000: "X",  # MEM_EXECUTE
+    0x40000000: "R",  # MEM_READ
+    0x80000000: "W",  # MEM_WRITE
+}
+
+
+@dataclass
+class Section:
+    """One ELF section header."""
+
+    name: str
+    type: int
+    type_name: str
+    flags: int
+    addr: int
+    offset: int
+    size: int
+    link: int
+    info: int
+    addralign: int
+    entsize: int
+    entropy: float = 0.0
+
+    @property
+    def flags_text(self) -> str:
+        return "".join(
+            char
+            for bit, char in (
+                (0x1, "W"),
+                (0x2, "A"),
+                (0x4, "X"),
+                (0x10, "M"),
+                (0x20, "S"),
+                (0x40, "I"),
+                (0x80, "L"),
+            )
+            if self.flags & bit
+        )
+
+    @property
+    def is_nobits(self) -> bool:
+        return self.type == 8
+
+
+@dataclass
+class Segment:
+    """One ELF program header."""
+
+    type: int
+    type_name: str
+    flags: int
+    offset: int
+    vaddr: int
+    paddr: int
+    filesz: int
+    memsz: int
+    align: int
+
+    @property
+    def flags_text(self) -> str:
+        return "".join(
+            char
+            for bit, char in ((0x4, "R"), (0x2, "W"), (0x1, "X"))
+            if self.flags & bit
+        )
+
+
+@dataclass
+class Symbol:
+    """One symbol from .symtab or .dynsym."""
+
+    name: str
+    bind: int
+    type: int
+    shndx: int
+    value: int
+    size: int
+
+    @property
+    def bind_name(self) -> str:
+        return SYMBOL_BIND_NAMES.get(self.bind, str(self.bind))
+
+    @property
+    def type_name(self) -> str:
+        return SYMBOL_TYPE_NAMES.get(self.type, str(self.type))
+
+
+@dataclass
+class ElfFile:
+    """Parsed view of an ELF binary."""
+
+    path: str
+    size: int
+    is_64: bool
+    little_endian: bool
+    type: int
+    machine: int
+    entry: int
+    flags: int
+    segments: list[Segment] = field(default_factory=list)
+    sections: list[Section] = field(default_factory=list)
+    needed: list[str] = field(default_factory=list)
+    symbols: list[Symbol] = field(default_factory=list)
+    soname: str = ""
+    dt_flags: int = 0
+    dt_flags_1: int = 0
+    strings: list = field(default_factory=list)
+
+    @property
+    def type_name(self) -> str:
+        return TYPE_NAMES.get(self.type, f"0x{self.type:x}")
+
+    @property
+    def machine_name(self) -> str:
+        return MACHINE_NAMES.get(self.machine, f"0x{self.machine:x}")
+
+    @property
+    def dynamic_symbols(self) -> list[Symbol]:
+        # Symbols parsed from .dynsym carry non-empty names from .dynstr.
+        return [sym for sym in self.symbols if sym.name]
+
+    @property
+    def functions(self) -> list[Symbol]:
+        return [sym for sym in self.dynamic_symbols if sym.type == 2]
+
+    @property
+    def imported_functions(self) -> list[Symbol]:
+        # Undefined dynamic symbols (shndx == 0 / UNDEF) are imports.
+        return [sym for sym in self.functions if sym.shndx == 0]
+
+    @property
+    def exported_functions(self) -> list[Symbol]:
+        return [sym for sym in self.functions if sym.shndx != 0]
+
+
+@dataclass
+class PESection:
+    """One PE/COFF section header."""
+
+    name: str
+    virtual_address: int
+    virtual_size: int
+    raw_offset: int
+    raw_size: int
+    flags: int
+    entropy: float = 0.0
+
+    @property
+    def flags_text(self) -> str:
+        return "".join(
+            char for bit, char in PE_SECTION_FLAG_TEXT.items() if self.flags & bit
+        )
+
+    @property
+    def is_code(self) -> bool:
+        return bool(self.flags & 0x00000020)
+
+
+@dataclass
+class PEFile:
+    """Parsed view of a PE/COFF binary."""
+
+    path: str
+    size: int
+    is_64: bool
+    type: int  # 0x2000 DLL, 0x0002 EXEC
+    machine: int
+    entry: int
+    image_base: int
+    subsystem: int
+    dll_characteristics: int
+    characteristics: int
+    sections: list[PESection] = field(default_factory=list)
+    needed: list[str] = field(default_factory=list)
+    exports: list[str] = field(default_factory=list)
+    imports: list[str] = field(default_factory=list)
+    strings: list = field(default_factory=list)
+
+    @property
+    def type_name(self) -> str:
+        if self.type & 0x2000:
+            return "动态链接库"
+        if self.type & 0x0002:
+            return "可执行"
+        return "未知"
+
+    @property
+    def machine_name(self) -> str:
+        return PE_MACHINE_NAMES.get(self.machine, f"0x{self.machine:x}")
+
+    @property
+    def subsystem_name(self) -> str:
+        return PE_SUBSYSTEM_NAMES.get(self.subsystem, str(self.subsystem))
+
+    @property
+    def little_endian(self) -> bool:
+        return True