gitrupt 0.1.0__py3-none-any.whl

gitrupt/scanners/binaries.py

@@ -0,0 +1,185 @@
+"""
+Binary heuristic analysis.
+
+Detects:
+    - Executables (PE, ELF, Mach-O) in unexpected file extensions
+    - Known packer section names
+    - Encrypted / packed section patterns
+
+Never executes any file. Pure byte inspection.
+"""
+
+from __future__ import annotations
+
+import math
+from collections import Counter
+
+from gitrupt.models import Finding, Severity
+
+# ── File format magic bytes ─────────────────────────────────────────────────
+
+PE_MAGIC = b"MZ"
+ELF_MAGIC = b"\x7fELF"
+MACHO_MAGICS = (
+    b"\xfe\xed\xfa\xce",  # 32-bit big-endian
+    b"\xfe\xed\xfa\xcf",  # 64-bit big-endian
+    b"\xce\xfa\xed\xfe",  # 32-bit little-endian
+    b"\xcf\xfa\xed\xfe",  # 64-bit little-endian
+    b"\xca\xfe\xba\xbe",  # Universal / fat binary
+)
+
+# Extensions where an executable is *expected* and not suspicious by itself.
+_EXECUTABLE_EXTENSIONS = frozenset({
+    ".exe", ".dll", ".sys", ".scr", ".com", ".msi", ".cpl", ".ocx",
+    ".so", ".dylib", ".bundle", ".ko", ".o", ".a",
+    ".elf", ".bin", ".out",
+})
+
+# Extensions that should NEVER contain a native executable.
+# Presence of PE/ELF/Mach-O magic in these is highly suspicious.
+_NEVER_EXECUTABLE_EXTENSIONS = frozenset({
+    ".txt", ".md", ".json", ".yaml", ".yml", ".toml", ".ini", ".cfg",
+    ".csv", ".tsv", ".log", ".xml", ".html", ".htm", ".css", ".js",
+    ".png", ".jpg", ".jpeg", ".gif", ".bmp", ".ico", ".svg", ".webp",
+    ".mp3", ".mp4", ".wav", ".avi", ".mov", ".mkv",
+    ".pdf", ".doc", ".docx", ".xls", ".xlsx", ".ppt", ".pptx",
+})
+
+# Packer section names — case-insensitive substring match.
+_PACKER_SECTION_MARKERS = (
+    b"UPX0", b"UPX1", b"UPX2",
+    b".MPRESS1", b".MPRESS2",
+    b".aspack", b".adata",
+    b".petite",
+    b"pebundle",
+    b"FSG!",
+    b"PECompact2",
+    b".nsp0", b".nsp1", b".nsp2",
+)
+
+# How many bytes to sample for entropy.
+_ENTROPY_SAMPLE = 4096
+
+
+def detect_executable_format(data: bytes) -> str | None:
+    """Return 'pe', 'elf', 'macho', or None."""
+    if len(data) < 4:
+        return None
+    if data[:2] == PE_MAGIC:
+        # Confirm with the PE\0\0 header located via the DOS e_lfanew pointer.
+        # The header (4 bytes) must fit entirely inside the buffer:
+        #   pe_off + 4 <= len(data)   ⇔   pe_off <= len(data) - 4
+        if len(data) >= 0x40:
+            pe_off = int.from_bytes(data[0x3C:0x40], "little")
+            if 0 < pe_off <= len(data) - 4 and data[pe_off : pe_off + 4] == b"PE\x00\x00":
+                return "pe"
+        # MZ alone is weak; only treat as PE if header confirmed.
+        return None
+    if data[:4] == ELF_MAGIC:
+        return "elf"
+    if data[:4] in MACHO_MAGICS:
+        return "macho"
+    return None
+
+
+def shannon_entropy(data: bytes) -> float:
+    """Byte-level Shannon entropy (0.0 – 8.0)."""
+    if not data:
+        return 0.0
+    counts = Counter(data)
+    total = len(data)
+    return -sum((c / total) * math.log2(c / total) for c in counts.values())
+
+
+def find_packer_marker(data: bytes) -> str | None:
+    """Return the first packer marker found in the sample, or None."""
+    sample = data[:_ENTROPY_SAMPLE * 4]
+    for marker in _PACKER_SECTION_MARKERS:
+        if marker in sample:
+            return marker.decode("ascii", errors="replace")
+    return None
+
+
+def scan_binary_heuristics(path: str, data: bytes) -> list[Finding]:
+    """
+    Analyze one file's bytes and return findings.
+
+    Never raises. Never executes.
+    """
+    findings: list[Finding] = []
+    if not data:
+        return findings
+
+    lowered = path.lower()
+    suffix = "." + lowered.rsplit(".", 1)[-1] if "." in lowered.rsplit("/", 1)[-1] else ""
+
+    # 1. Executable format in a non-executable extension
+    fmt = detect_executable_format(data)
+    if fmt and suffix and suffix not in _EXECUTABLE_EXTENSIONS:
+        severity = Severity.CRITICAL if suffix in _NEVER_EXECUTABLE_EXTENSIONS else Severity.HIGH
+        findings.append(
+            Finding(
+                scanner="malware",
+                rule_id=f"bin-{fmt}-wrong-extension",
+                severity=severity,
+                confidence=0.9,
+                file=path,
+                line=None,
+                message=f"{fmt.upper()} executable with '{suffix}' extension",
+                description=(
+                    f"File is a native {fmt.upper()} binary but has extension '{suffix}'. "
+                    "This is a common disguise technique."
+                ),
+                evidence=f"magic={data[:4].hex()}",
+                recommendation="Verify the file's origin; do not commit executables under false extensions.",
+                can_override=False,
+            )
+        )
+
+    # 2. Packer signature
+    marker = find_packer_marker(data)
+    if marker:
+        findings.append(
+            Finding(
+                scanner="malware",
+                rule_id="bin-packer-signature",
+                severity=Severity.HIGH,
+                confidence=0.85,
+                file=path,
+                line=None,
+                message=f"Packer signature detected ({marker})",
+                description=(
+                    "The file contains a known executable packer signature. "
+                    "Packers are commonly used to hide malicious payloads."
+                ),
+                evidence=f"marker={marker}",
+                recommendation="Inspect the file's origin; unpack and review if untrusted.",
+                can_override=False,
+            )
+        )
+
+    # 3. High entropy on an executable — likely encrypted/packed payload
+    if fmt:
+        sample = data[:_ENTROPY_SAMPLE]
+        entropy = shannon_entropy(sample)
+        if entropy > 7.2:
+            findings.append(
+                Finding(
+                    scanner="malware",
+                    rule_id="bin-high-entropy-section",
+                    severity=Severity.MEDIUM,
+                    confidence=0.6,
+                    file=path,
+                    line=None,
+                    message=f"Very high entropy in {fmt.upper()} file ({entropy:.2f}/8.0)",
+                    description=(
+                        "Entropy above 7.2 suggests encrypted or compressed content. "
+                        "Legitimate, unpacked executables normally fall below this."
+                    ),
+                    evidence=f"entropy={entropy:.2f}",
+                    recommendation="If this file is unexpected, do not commit it.",
+                    can_override=True,
+                )
+            )
+
+    return findings

gitrupt/scanners/code_rules/__init__.py

@@ -0,0 +1,36 @@
+"""
+Registry of suspicious-code rules.
+
+Adding a language:
+    1. Create a new module (e.g. rust.py) that exports a RULES list.
+    2. Import it below and add it to _ALL_RULES.
+    3. Done — the scanner picks it up automatically.
+"""
+
+from __future__ import annotations
+
+from gitrupt.scanners.code_rules.base import CodeRule
+from gitrupt.scanners.code_rules.go import RULES as _GO
+from gitrupt.scanners.code_rules.javascript import RULES as _JS
+from gitrupt.scanners.code_rules.php import RULES as _PHP
+from gitrupt.scanners.code_rules.powershell import RULES as _PS
+from gitrupt.scanners.code_rules.python import RULES as _PY
+from gitrupt.scanners.code_rules.ruby import RULES as _RB
+from gitrupt.scanners.code_rules.shell import RULES as _SH
+from gitrupt.scanners.code_rules.rust import RULES as _RS
+
+_ALL_RULES: tuple[CodeRule, ...] = (
+    _PY + _JS + _SH + _PS + _PHP + _RB + _GO + _RS
+)
+
+
+def get_all_rules() -> tuple[CodeRule, ...]:
+    return _ALL_RULES
+
+
+def get_rules_for_language(language: str) -> tuple[CodeRule, ...]:
+    return tuple(r for r in _ALL_RULES if r.language == language)
+
+
+def supported_languages() -> tuple[str, ...]:
+    return tuple(sorted({r.language for r in _ALL_RULES}))

gitrupt/scanners/code_rules/base.py

@@ -0,0 +1,27 @@
+"""Base model for language-specific suspicious-code rules."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from gitrupt.models import Severity
+
+
+@dataclass(frozen=True)
+class CodeRule:
+    """
+    A single suspicious-code rule.
+
+    Rules are data, not code. Adding a language = adding a module of CodeRule
+    objects. The scanner never needs to change.
+    """
+
+    rule_id: str
+    language: str          # "python", "javascript", "shell", ...
+    pattern: re.Pattern    # compiled regex, matched against a single added line
+    severity: Severity
+    confidence: float      # 0.0 .. 1.0
+    message: str           # short, shown next to file:line
+    description: str = ""  # longer explanation
+    recommendation: str = ""

gitrupt/scanners/code_rules/go.py

@@ -0,0 +1,65 @@
+"""Suspicious-code rules for Go."""
+
+from __future__ import annotations
+
+import re
+
+from gitrupt.models import Severity
+from gitrupt.scanners.code_rules.base import CodeRule
+
+RULES: tuple[CodeRule, ...] = (
+    CodeRule(
+        rule_id="go-os-exec",
+        language="go",
+        pattern=re.compile(r"\bexec\.Command(?:Context)?\s*\("),
+        severity=Severity.LOW,
+        confidence=0.5,
+        message="os/exec Command call",
+        description="Executes an external process.",
+        recommendation="Pass an argument list — never build the command from untrusted strings.",
+    ),
+    CodeRule(
+        rule_id="go-shell-true-equivalent",
+        language="go",
+        pattern=re.compile(r"exec\.Command\s*\(\s*\"(?:sh|bash|cmd|powershell)\""),
+        severity=Severity.MEDIUM,
+        confidence=0.7,
+        message="Shell invocation via exec.Command",
+        description="Executing a shell interpreter re-exposes shell injection.",
+        recommendation="Call the target program directly instead of through a shell.",
+    ),
+    CodeRule(
+        rule_id="go-base64-decode",
+        language="go",
+        pattern=re.compile(r"base64\.StdEncoding\.DecodeString\s*\("),
+        severity=Severity.LOW,
+        confidence=0.5,
+        message="base64 decode in source",
+        description="Encoded payloads may indicate obfuscation.",
+        recommendation="Inspect what the decoded bytes are used for.",
+    ),
+
+
+
+
+    CodeRule(
+    rule_id="go-reverse-shell",
+    language="go",
+    pattern=re.compile(r"net\.Dial\s*\([^)]*\)[^\n]*exec\.Command"),
+    severity=Severity.CRITICAL,
+    confidence=0.85,
+    message="Go reverse shell pattern",
+    description="Outbound connection followed by exec.Command.",
+    recommendation="Audit carefully. This is a backdoor shape.",
+),
+CodeRule(
+    rule_id="go-exec-sh",
+    language="go",
+    pattern=re.compile(r"exec\.Command\s*\(\s*\"(?:/bin/)?(?:ba)?sh\"\s*,\s*\"-c\""),
+    severity=Severity.HIGH,
+    confidence=0.8,
+    message="Shell invocation with -c",
+    description="Command injection risk if arguments are user-controlled.",
+    recommendation="Avoid shell wrappers; call the target binary directly.",
+),
+)

gitrupt/scanners/code_rules/javascript.py

@@ -0,0 +1,106 @@
+"""Suspicious-code rules for JavaScript / TypeScript / Node.js."""
+
+from __future__ import annotations
+
+import re
+
+from gitrupt.models import Severity
+from gitrupt.scanners.code_rules.base import CodeRule
+
+RULES: tuple[CodeRule, ...] = (
+    CodeRule(
+        rule_id="js-eval-dynamic",
+        language="javascript",
+        pattern=re.compile(r"\beval\s*\(\s*(?!['\"])"),
+        severity=Severity.MEDIUM,
+        confidence=0.7,
+        message="Dynamic eval() call",
+        description="eval() on non-literal input executes arbitrary code.",
+        recommendation="Replace eval() with a safer parser or dispatch.",
+    ),
+    CodeRule(
+        rule_id="js-function-constructor",
+        language="javascript",
+        pattern=re.compile(r"\bnew\s+Function\s*\("),
+        severity=Severity.MEDIUM,
+        confidence=0.65,
+        message="new Function() constructor",
+        description="The Function constructor behaves like eval().",
+        recommendation="Avoid new Function(); use a normal function.",
+    ),
+    CodeRule(
+        rule_id="js-child-process-exec",
+        language="javascript",
+        pattern=re.compile(r"\bchild_process\.exec(?:Sync)?\s*\("),
+        severity=Severity.MEDIUM,
+        confidence=0.65,
+        message="child_process.exec() call",
+        description="child_process.exec runs a shell command.",
+        recommendation="Use execFile() or spawn() with an argument array.",
+    ),
+    CodeRule(
+        rule_id="js-curl-pipe-sh",
+        language="javascript",
+        pattern=re.compile(r"curl[^\"'`\n]*\|\s*(?:ba)?sh\b"),
+        severity=Severity.HIGH,
+        confidence=0.8,
+        message="curl piped to shell",
+        description="Download-and-execute one-liner.",
+        recommendation="Download, verify, then execute as separate steps.",
+    ),
+    CodeRule(
+        rule_id="js-base64-buffer",
+        language="javascript",
+        pattern=re.compile(r"Buffer\.from\s*\([^)]*['\"]base64['\"]"),
+        severity=Severity.LOW,
+        confidence=0.5,
+        message="base64 decode in source",
+        description="Encoded payload in source — verify intent.",
+        recommendation="Check what the decoded bytes are used for.",
+    ),
+
+
+
+
+
+    CodeRule(
+    rule_id="js-reverse-shell",
+    language="javascript",
+    pattern=re.compile(r"require\(['\"]net['\"]\)\s*\.\s*connect\s*\("),
+    severity=Severity.CRITICAL,
+    confidence=0.8,
+    message="Possible reverse shell via net.connect",
+    description="Raw TCP connection often used in Node.js backdoors.",
+    recommendation="Audit the connection target and surrounding logic.",
+),
+CodeRule(
+    rule_id="js-process-env-dump",
+    language="javascript",
+    pattern=re.compile(r"JSON\.stringify\s*\(\s*process\.env\s*\)"),
+    severity=Severity.HIGH,
+    confidence=0.8,
+    message="process.env serialization — credential exfiltration",
+    description="Dumps all environment variables, including secrets.",
+    recommendation="Never serialize process.env; pass explicit values.",
+),
+CodeRule(
+    rule_id="js-vm-runincontext",
+    language="javascript",
+    pattern=re.compile(r"\bvm\.runIn(?:This)?Context\s*\("),
+    severity=Severity.HIGH,
+    confidence=0.75,
+    message="vm.runInContext — sandbox escape risk",
+    description="Eval-like in a VM context.",
+    recommendation="Use vm2 or another isolated sandbox.",
+),
+CodeRule(
+    rule_id="js-settimeout-string",
+    language="javascript",
+    pattern=re.compile(r"\bset(?:Timeout|Interval)\s*\(\s*['\"]"),
+    severity=Severity.MEDIUM,
+    confidence=0.7,
+    message="setTimeout/setInterval with string argument",
+    description="String form behaves like eval().",
+    recommendation="Pass a function, not a string.",
+),
+)

gitrupt/scanners/code_rules/php.py

@@ -0,0 +1,71 @@
+"""Suspicious-code rules for PHP."""
+
+from __future__ import annotations
+
+import re
+
+from gitrupt.models import Severity
+from gitrupt.scanners.code_rules.base import CodeRule
+
+RULES: tuple[CodeRule, ...] = (
+    CodeRule(
+        rule_id="php-shell-exec",
+        language="php",
+        pattern=re.compile(r"\b(?:shell_exec|passthru|proc_open|popen)\s*\("),
+        severity=Severity.HIGH,
+        confidence=0.8,
+        message="PHP shell execution function",
+        description="Executes an OS-level command.",
+        recommendation="Avoid shell functions on user input; sanitize strictly.",
+    ),
+    CodeRule(
+        rule_id="php-exec-system",
+        language="php",
+        pattern=re.compile(r"\b(?:exec|system)\s*\([^)]*\$"),
+        severity=Severity.HIGH,
+        confidence=0.75,
+        message="PHP exec/system with variable input",
+        description="Shell injection risk when passing untrusted input.",
+        recommendation="Use escapeshellarg() and validate input.",
+    ),
+    CodeRule(
+        rule_id="php-eval-dynamic",
+        language="php",
+        pattern=re.compile(r"\beval\s*\(\s*(?!['\"])"),
+        severity=Severity.HIGH,
+        confidence=0.75,
+        message="Dynamic eval() call",
+        description="eval() on non-literal input executes arbitrary code.",
+        recommendation="Replace eval() with explicit logic.",
+    ),
+
+
+
+
+
+
+
+
+    CodeRule(
+    rule_id="php-reverse-shell",
+    language="php",
+    pattern=re.compile(
+        r"fsockopen\s*\([^)]*\)[^;]*;\s*(?:while|exec|system|passthru|shell_exec)"
+    ),
+    severity=Severity.CRITICAL,
+    confidence=0.9,
+    message="PHP reverse shell pattern",
+    description="Socket open followed by command execution.",
+    recommendation="Treat the file as malicious.",
+),
+CodeRule(
+    rule_id="php-assert-dynamic",
+    language="php",
+    pattern=re.compile(r"\bassert\s*\(\s*(?!['\"])"),
+    severity=Severity.HIGH,
+    confidence=0.75,
+    message="assert() with non-literal argument",
+    description="assert() on a variable can execute arbitrary code in older PHP.",
+    recommendation="Replace assert() with explicit validation.",
+),
+)

gitrupt/scanners/code_rules/powershell.py

@@ -0,0 +1,85 @@
+"""Suspicious-code rules for PowerShell."""
+
+from __future__ import annotations
+
+import re
+
+from gitrupt.models import Severity
+from gitrupt.scanners.code_rules.base import CodeRule
+
+RULES: tuple[CodeRule, ...] = (
+    CodeRule(
+        rule_id="ps-iex-downloadstring",
+        language="powershell",
+        pattern=re.compile(
+            r"\bIEX\b[^\n]*DownloadString|DownloadString[^\n]*\bIEX\b",
+            re.IGNORECASE,
+        ),
+        severity=Severity.CRITICAL,
+        confidence=0.9,
+        message="PowerShell download-and-execute",
+        description="IEX + DownloadString fetches and runs remote code.",
+        recommendation="Never run untrusted remote scripts.",
+    ),
+    CodeRule(
+        rule_id="ps-encoded-command",
+        language="powershell",
+        pattern=re.compile(r"-EncodedCommand\b|-enc\s+[A-Za-z0-9+/=]{20,}"),
+        severity=Severity.HIGH,
+        confidence=0.85,
+        message="PowerShell encoded command",
+        description="Base64-encoded PowerShell is a common obfuscation.",
+        recommendation="Decode and inspect the command before running.",
+    ),
+    CodeRule(
+        rule_id="ps-invoke-expression",
+        language="powershell",
+        pattern=re.compile(r"\bInvoke-Expression\b"),
+        severity=Severity.MEDIUM,
+        confidence=0.65,
+        message="Invoke-Expression",
+        description="Invoke-Expression runs a string as code.",
+        recommendation="Avoid Invoke-Expression; use direct command calls.",
+    ),
+
+
+
+
+
+    CodeRule(
+    rule_id="ps-defender-disable",
+    language="powershell",
+    pattern=re.compile(r"Set-MpPreference\s+[^\n]*-Disable(?:RealtimeMonitoring|BehaviorMonitoring|IOAVProtection)"),
+    severity=Severity.CRITICAL,
+    confidence=0.95,
+    message="Windows Defender disable attempt",
+    description="Attempts to turn off Defender protection.",
+    recommendation="Never run untrusted scripts containing this.",
+),
+CodeRule(
+    rule_id="ps-invoke-webrequest-iex",
+    language="powershell",
+    pattern=re.compile(
+        r"(?:Invoke-WebRequest|iwr|DownloadString)[^\n]*\|\s*(?:IEX|Invoke-Expression)",
+        re.IGNORECASE,
+    ),
+    severity=Severity.CRITICAL,
+    confidence=0.9,
+    message="PowerShell download-pipe-execute",
+    description="Fetches remote content and pipes it to IEX.",
+    recommendation="Never execute remote scripts.",
+),
+CodeRule(
+    rule_id="ps-amsi-bypass",
+    language="powershell",
+    pattern=re.compile(
+        r"(?:amsi|AmsiUtils|System\.Management\.Automation\.AmsiUtils)",
+        re.IGNORECASE,
+    ),
+    severity=Severity.HIGH,
+    confidence=0.7,
+    message="AMSI bypass indicator",
+    description="References to AMSI internals often indicate evasion.",
+    recommendation="Treat the script as hostile.",
+),
+)