narvy-cli 1.0.0__py3-none-any.whl

narvy/apk_memory_preflight.py

@@ -0,0 +1,248 @@
+"""Pre-flight memory estimate for the JADX decompilation path: estimate the Java
+heap jadx needs from DEX header counts and warn before OOM. Advisory only; `--force` overrides."""
+
+import ctypes
+import logging
+import math
+import os
+import platform
+import re
+import struct
+import zipfile
+from typing import NamedTuple, Optional
+
+logger = logging.getLogger(__name__)
+
+# Class count is the discriminating estimator; the other two add caution under max().
+HEAP_MB_PER_CLASS = 0.050
+HEAP_MB_PER_METHOD = 0.0073
+HEAP_MB_PER_DEX_MB = 45.0
+
+MIN_ESTIMATE_MB = 512
+
+# JVM resident set = heap plus metaspace, stacks, GC, JIT cache, mapped DEX.
+JVM_RSS_OVERHEAD = 1.30
+
+RAM_SAFETY_RESERVE_MB = 1024
+
+
+class DexStats(NamedTuple):
+    methods: int
+    classes: int
+    dex_files: int
+    dex_bytes: int
+    ok: bool  # False => header read failed, callers must not gate on this
+
+
+class PreflightVerdict(NamedTuple):
+    should_block: bool
+    reason: str          # "" | "heap_too_small" | "ram_too_small"
+    message: str
+    estimated_mb: int
+    max_mem_mb: int
+    available_mb: Optional[int]
+    stats: DexStats
+
+
+def parse_mem_arg(value: str) -> Optional[int]:
+    """Parse a JVM-style memory string ('4g', '4096m', '512k') to MB, or None."""
+    if not value:
+        return None
+    m = re.fullmatch(r"\s*(\d+)\s*([kmgKMG]?)[bB]?\s*", str(value))
+    if not m:
+        return None
+    n = int(m.group(1))
+    unit = m.group(2).lower()
+    if unit == "g":
+        return n * 1024
+    if unit == "m":
+        return n
+    if unit == "k":
+        return max(1, n // 1024)
+    return max(1, n // (1024 * 1024))  # bare number = bytes, per java -Xmx
+
+
+def available_ram_mb() -> Optional[int]:
+    """Best-effort free memory in MB for this machine, or None if unknown."""
+    system = platform.system()
+    try:
+        if system == "Linux":
+            with open("/proc/meminfo", "r") as f:
+                for line in f:
+                    if line.startswith("MemAvailable:"):
+                        return int(line.split()[1]) // 1024
+        elif system == "Darwin":
+            # vm_stat exposes reclaimable inactive+purgeable pools that SC_AVPHYS_PAGES omits.
+            import subprocess
+            out = subprocess.run(["vm_stat"], capture_output=True, text=True, timeout=10).stdout
+            page = 4096
+            pm = re.search(r"page size of (\d+) bytes", out)
+            if pm:
+                page = int(pm.group(1))
+            counts = dict(re.findall(r"^(.+?):\s+(\d+)\.", out, re.M))
+            free = int(counts.get("Pages free", 0))
+            inactive = int(counts.get("Pages inactive", 0))
+            purgeable = int(counts.get("Pages purgeable", 0))
+            if free or inactive:
+                return ((free + inactive + purgeable) * page) // (1024 * 1024)
+        elif system == "Windows":
+            class _MemStatusEx(ctypes.Structure):
+                _fields_ = [
+                    ("dwLength", ctypes.c_ulong),
+                    ("dwMemoryLoad", ctypes.c_ulong),
+                    ("ullTotalPhys", ctypes.c_ulonglong),
+                    ("ullAvailPhys", ctypes.c_ulonglong),
+                    ("ullTotalPageFile", ctypes.c_ulonglong),
+                    ("ullAvailPageFile", ctypes.c_ulonglong),
+                    ("ullTotalVirtual", ctypes.c_ulonglong),
+                    ("ullAvailVirtual", ctypes.c_ulonglong),
+                    ("ullAvailExtendedVirtual", ctypes.c_ulonglong),
+                ]
+            stat = _MemStatusEx()
+            stat.dwLength = ctypes.sizeof(_MemStatusEx)
+            if ctypes.windll.kernel32.GlobalMemoryStatusEx(ctypes.byref(stat)):
+                return int(stat.ullAvailPhys) // (1024 * 1024)
+        # Generic POSIX fallback, also covers Linux if /proc is unreadable.
+        if hasattr(os, "sysconf") and "SC_AVPHYS_PAGES" in os.sysconf_names:
+            return (os.sysconf("SC_AVPHYS_PAGES") * os.sysconf("SC_PAGE_SIZE")) // (1024 * 1024)
+    except Exception as e:  # noqa: BLE001
+        logger.debug(f"available_ram_mb() failed on {system}: {e}")
+    return None
+
+
+def _is_app_dex(name: str) -> bool:
+    """True for app-code DEX (APK `classes*.dex` or App Bundle `<module>/dex/classes*.dex`), not asset .dex."""
+    base = name.rsplit("/", 1)[-1]
+    if not (base.startswith("classes") and base.endswith(".dex")):
+        return False
+    depth = name.count("/")
+    if depth == 0:
+        return True
+    return re.fullmatch(r"[^/]+/dex/classes\d*\.dex", name) is not None
+
+
+def read_dex_stats(apk_path: str) -> DexStats:
+    """Read method/class counts from DEX headers (Dalvik spec: method_ids_size @0x58, class_defs_size @0x60, uint32 LE)."""
+    methods = classes = count = 0
+    dex_bytes = 0
+    try:
+        with zipfile.ZipFile(apk_path) as zf:
+            for zi in zf.infolist():
+                if not _is_app_dex(zi.filename):
+                    continue
+                try:
+                    with zf.open(zi) as f:
+                        hdr = f.read(112)
+                except Exception:
+                    continue
+                if len(hdr) < 0x70 or hdr[:3] != b"dex":
+                    continue
+                m = struct.unpack_from("<I", hdr, 0x58)[0]
+                c = struct.unpack_from("<I", hdr, 0x60)[0]
+                # Corrupt-header guard: no real DEX holds these counts.
+                if m > 5_000_000 or c > 1_000_000:
+                    continue
+                methods += m
+                classes += c
+                dex_bytes += zi.file_size
+                count += 1
+    except Exception as e:  # noqa: BLE001
+        logger.debug(f"read_dex_stats({apk_path}) failed: {e}")
+        return DexStats(0, 0, 0, 0, ok=False)
+    return DexStats(methods, classes, count, dex_bytes, ok=count > 0)
+
+
+def estimate_heap_mb(stats: DexStats) -> int:
+    """Estimated -Xmx (MB) jadx needs to decompile an app of this size."""
+    if not stats.ok:
+        return 0
+    estimates = (
+        stats.classes * HEAP_MB_PER_CLASS,
+        stats.methods * HEAP_MB_PER_METHOD,
+        (stats.dex_bytes / (1024 * 1024)) * HEAP_MB_PER_DEX_MB,
+    )
+    return max(MIN_ESTIMATE_MB, int(max(estimates)))
+
+
+def _fmt_mb(mb: Optional[int]) -> str:
+    if mb is None:
+        return "unknown"
+    if mb >= 1024:
+        return f"{mb / 1024:.1f} GB"
+    return f"{mb} MB"
+
+
+def _round_up_gb(mb: int) -> int:
+    return max(1, math.ceil(mb / 1024))
+
+
+def check_memory_preflight(apk_path: str, max_mem: str,
+                           available_mb: Optional[int] = None) -> PreflightVerdict:
+    """Decide before spending jadx time whether this scan can work; never blocks on a low-confidence estimate."""
+    stats = read_dex_stats(apk_path)
+    max_mem_mb = parse_mem_arg(max_mem)
+    if available_mb is None:
+        available_mb = available_ram_mb()
+
+    no_block = PreflightVerdict(False, "", "", estimate_heap_mb(stats),
+                                max_mem_mb or 0, available_mb, stats)
+    if not stats.ok or not max_mem_mb:
+        return no_block
+
+    need_mb = estimate_heap_mb(stats)
+    scale = (
+        f"~{stats.methods:,} methods / ~{stats.classes:,} classes across "
+        f"{stats.dex_files} DEX file(s), {stats.dex_bytes / (1024 * 1024):.0f} MB of bytecode"
+    )
+
+    if need_mb > max_mem_mb:
+        suggest_gb = _round_up_gb(int(need_mb * 1.1))
+        need_rss_mb = int(suggest_gb * 1024 * JVM_RSS_OVERHEAD)
+        head = (
+            f"This app is very large: {scale}. Decompiling it typically needs around "
+            f"{_fmt_mb(need_mb)} of Java heap, but this scan is limited to "
+            f"{_fmt_mb(max_mem_mb)} (--max-mem {max_mem}). JADX will most likely run out "
+            f"of memory partway through, after several minutes of work."
+        )
+        if available_mb is not None and need_rss_mb > (available_mb - RAM_SAFETY_RESERVE_MB):
+            body = (
+                f"\n\nRaising --max-mem on its own will not be enough: {suggest_gb}g of heap needs "
+                f"roughly {_fmt_mb(need_rss_mb)} of real memory, and this machine only has "
+                f"{_fmt_mb(available_mb)} available right now. Options:\n"
+                f"  - free up that much memory (close other apps), then re-run with --max-mem {suggest_gb}g\n"
+                f"  - scan this app on a bigger machine, or use the hosted scan (`--upload`)\n"
+                f"  - run it anyway with --force if you know your setup can take it"
+            )
+        else:
+            avail_note = (f" (this machine has {_fmt_mb(available_mb)} available)"
+                          if available_mb is not None else "")
+            body = (
+                f"\n\nOptions:\n"
+                f"  - re-run with --max-mem {suggest_gb}g{avail_note}\n"
+                f"  - run it anyway at {max_mem} with --force"
+            )
+        return PreflightVerdict(True, "heap_too_small", head + body,
+                                need_mb, max_mem_mb, available_mb, stats)
+
+    if available_mb is not None:
+        needed_rss = int(max_mem_mb * JVM_RSS_OVERHEAD)
+        if needed_rss > (available_mb - RAM_SAFETY_RESERVE_MB):
+            safe_gb = max(1, int((available_mb - RAM_SAFETY_RESERVE_MB) / JVM_RSS_OVERHEAD / 1024))
+            lower_line = f"  - lower to --max-mem {safe_gb}g, which fits in what's free"
+            if safe_gb * 1024 < need_mb:
+                lower_line += (f" (though this app looks like it needs about {_fmt_mb(need_mb)}, "
+                               f"so it may still not be enough)")
+            msg = (
+                f"--max-mem {max_mem} asks JADX for {_fmt_mb(max_mem_mb)} of Java heap, which needs "
+                f"about {_fmt_mb(needed_rss)} of real memory once JVM overhead is counted. This "
+                f"machine only has {_fmt_mb(available_mb)} available right now.\n\n"
+                f"Running this would push the machine into swap and most likely get JADX killed by "
+                f"the OS out-of-memory killer (and may take other apps down with it). Options:\n"
+                f"  - free up memory and try again\n"
+                f"{lower_line}\n"
+                f"  - run it anyway with --force"
+            )
+            return PreflightVerdict(True, "ram_too_small", msg,
+                                    need_mb, max_mem_mb, available_mb, stats)
+
+    return no_block

narvy/auth.py

@@ -0,0 +1,40 @@
+import json
+import os
+import stat
+
+CONFIG_DIR = os.path.expanduser("~/.narvy")
+CREDENTIALS_PATH = os.path.join(CONFIG_DIR, "credentials")
+
+
+def save_token(token, email, plan):
+    os.makedirs(CONFIG_DIR, exist_ok=True)
+    # 0600 at creation so the token file is never briefly readable by others.
+    fd = os.open(CREDENTIALS_PATH, os.O_CREAT | os.O_WRONLY | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w") as f:
+        json.dump({"token": token, "email": email, "plan": plan}, f)
+    os.chmod(CREDENTIALS_PATH, stat.S_IRUSR | stat.S_IWUSR)
+
+
+def _env(name):
+    """Read a NARVY_<name> environment override."""
+    return os.environ.get(f"NARVY_{name}", "").strip()
+
+
+def load_credentials():
+    # NARVY_TOKEN overrides the stored file for CI / parallel use.
+    env_token = _env("TOKEN")
+    if env_token:
+        return {
+            "token": env_token,
+            "email": _env("EMAIL"),
+            "plan": _env("PLAN"),
+        }
+    if not os.path.exists(CREDENTIALS_PATH):
+        return None
+    with open(CREDENTIALS_PATH) as f:
+        return json.load(f)
+
+
+def logout():
+    if os.path.exists(CREDENTIALS_PATH):
+        os.remove(CREDENTIALS_PATH)

narvy/ci_templates/bitbucket.yml

@@ -0,0 +1,25 @@
+# Narvy SAST - free security scanning in Bitbucket Pipelines.
+# `narvy init-ci --bitbucket` writes this file. Safe to edit and commit.
+#
+# If you ALREADY have a bitbucket-pipelines.yml, do NOT overwrite it - copy the
+# step below into your existing pipeline instead.
+#
+# What it does: runs the Narvy CLI over the repository, emits SARIF
+# (stored as a build artifact), and fails the build when a finding is at or
+# above the severity you choose with --fail-on.
+#
+# NOTE: to surface findings in Bitbucket's Code Insights panel you would POST
+# the SARIF via the Bitbucket Reports API (an extra step / pipe), which this
+# template does not do. The build gate (--fail-on) works as-is.
+image: python:3.11
+
+pipelines:
+  default:
+    - step:
+        name: Narvy SAST
+        script:
+          - pip install --upgrade pip
+          - pip install narvy
+          - narvy scan . --output sarif --file narvy-results.sarif --fail-on high
+        artifacts:
+          - narvy-results.sarif

narvy/ci_templates/github.yml

@@ -0,0 +1,60 @@
+# Narvy SAST - free security scanning in GitHub Actions.
+# `narvy init-ci --github` writes this file. Safe to edit and commit.
+#
+# What it does: runs the Narvy CLI over this repository (mobile / web /
+# backend source SAST + SCA), emits SARIF, uploads it to GitHub code scanning
+# (the repo's Security tab), and fails the build when a finding is at or above
+# the severity you choose with --fail-on.
+name: Narvy SAST
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  security-events: write   # required to upload SARIF to code scanning
+
+jobs:
+  narvy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install Narvy CLI
+        run: |
+          python -m pip install --upgrade pip
+          pip install narvy
+
+      - name: Run Narvy scan
+        # The SARIF file is written before the --fail-on gate runs, so the
+        # Security tab is populated even on a failing build (see the upload
+        # step's `if: always()`).
+        run: |
+          narvy scan . \
+            --output sarif \
+            --file narvy-results.sarif \
+            --fail-on high
+
+      - name: Upload SARIF to GitHub code scanning
+        if: always()   # upload even when the scan step failed the build via --fail-on
+        uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: narvy-results.sarif
+
+# ---------------------------------------------------------------------------
+# Scanning a web app URL too? Add a second step (needs no account):
+#   - name: Narvy passive web scan
+#     run: narvy web-scan "https://staging.example.com" --format sarif --output-file web.sarif --fail-on high
+#   - if: always()
+#     uses: github/codeql-action/upload-sarif@v3
+#     with:
+#       sarif_file: web.sarif
+#       category: narvy-web
+# ---------------------------------------------------------------------------

narvy/ci_templates/gitlab.yml

@@ -0,0 +1,32 @@
+# Narvy SAST - free security scanning in GitLab CI.
+# `narvy init-ci --gitlab` writes this file. Safe to edit and commit.
+#
+# If you ALREADY have a .gitlab-ci.yml, do NOT overwrite it - copy the
+# `narvy_sast` job below into your existing pipeline instead.
+#
+# What it does: runs the Narvy CLI over the repository, emits SARIF,
+# saves it as a job artifact, and fails the pipeline when a finding is at or
+# above the severity you choose with --fail-on.
+#
+# NOTE on GitLab's Security Dashboard: native ingestion
+# (artifacts:reports:sast) expects GitLab's OWN SAST report schema, which this
+# CLI does not emit. The SARIF is stored as a plain downloadable artifact and
+# the pipeline gate (--fail-on) still blocks the MR. Surfacing findings inside
+# the Security tab would require converting SARIF -> GitLab SAST schema, which
+# this template does not do.
+stages:
+  - test
+
+narvy_sast:
+  stage: test
+  image: python:3.11-slim
+  before_script:
+    - pip install --upgrade pip
+    - pip install narvy
+  script:
+    - narvy scan . --output sarif --file narvy-results.sarif --fail-on high
+  artifacts:
+    when: always   # keep the SARIF even when --fail-on failed the pipeline
+    paths:
+      - narvy-results.sarif
+    expire_in: 1 week