narvy-cli 1.0.0__py3-none-any.whl

narvy/third_party_filter.py

@@ -0,0 +1,211 @@
+"""Decide whether a source file is the app's own code or third-party SDK code.
+Prefers an own-package allowlist from the manifest, falling back to a denylist of known SDK namespaces."""
+from __future__ import annotations
+
+import os
+import re
+from typing import Optional
+
+from .scope_config import ScopeConfig, segment_prefix_match
+
+# jadx's manifest output path depends on the input container type.
+_MANIFEST_RELATIVE_PATHS = (
+    os.path.join("resources", "AndroidManifest.xml"),           # plain .apk
+    os.path.join("resources", "base", "manifest", "AndroidManifest.xml"),  # .aab
+)
+
+
+def _find_decompiled_manifest_path(decompiled_root: str) -> Optional[str]:
+    for rel in _MANIFEST_RELATIVE_PATHS:
+        candidate = os.path.join(decompiled_root, rel)
+        if os.path.isfile(candidate):
+            return candidate
+    return None
+
+
+def parse_manifest_package_attr(manifest_content: str) -> Optional[str]:
+    m = re.search(r'package\s*=\s*"([a-zA-Z0-9_.]+)"', manifest_content)
+    return m.group(1) if m else None
+
+
+def detect_own_package(decompiled_root: str) -> str | None:
+    manifest_path = _find_decompiled_manifest_path(decompiled_root)
+    if not manifest_path:
+        return None
+    try:
+        with open(manifest_path, "r", encoding="utf-8", errors="ignore") as f:
+            head = f.read(4096)
+    except OSError:
+        return None
+    return parse_manifest_package_attr(head)
+
+
+_COMPONENT_TAG_RE = re.compile(
+    r'<(?:activity|service|receiver|provider|application)\b[^>]*?'
+    r'android:name\s*=\s*"([^"]+)"',
+    re.DOTALL,
+)
+
+# Too generic to trust as a one-segment namespace root, so 2 segments are used.
+_GENERIC_TLD_SEGMENTS = {"com", "org", "io", "net", "edu", "gov", "co"}
+
+
+def _root_is_known_third_party(candidate: str) -> bool:
+    cand_path = candidate.replace(".", "/") + "/"
+    for p in THIRD_PARTY_PREFIXES:
+        p_path = p.replace(".", "/")
+        if cand_path.startswith(p_path) or p_path.startswith(cand_path):
+            return True
+    return False
+
+
+def extract_component_package_roots(manifest_content: str, root_pkg: Optional[str] = None) -> set[str]:
+    roots: set[str] = set()
+    for m in _COMPONENT_TAG_RE.finditer(manifest_content):
+        name = m.group(1)
+        if name.startswith("."):
+            if not root_pkg:
+                continue
+            name = root_pkg + name
+        segments = [s for s in name.rsplit(".", 1)[0].split(".") if s]
+        if not segments:
+            continue
+        if segments[0].lower() in _GENERIC_TLD_SEGMENTS and len(segments) >= 2:
+            candidate = ".".join(segments[:2])
+        else:
+            candidate = segments[0]
+        if _root_is_known_third_party(candidate):
+            continue
+        roots.add(candidate)
+    return roots
+
+
+def get_own_package_roots(decompiled_root: str) -> set[str]:
+    """The manifest's applicationId plus the root of every declared component."""
+    roots: set[str] = set()
+    root_pkg = detect_own_package(decompiled_root)
+    if root_pkg:
+        roots.add(root_pkg)
+
+    manifest_path = _find_decompiled_manifest_path(decompiled_root)
+    if not manifest_path:
+        return roots
+    try:
+        with open(manifest_path, "r", encoding="utf-8", errors="ignore") as f:
+            content = f.read()
+    except OSError:
+        return roots
+
+    roots |= extract_component_package_roots(content, root_pkg)
+    return roots
+
+
+# Anchors for a file's package path: jadx uses 'sources/', Gradle 'src/<variant>/java|kotlin/'.
+JADX_SOURCE_MARKERS = (r"sources/",)
+GRADLE_SOURCE_MARKERS = (r"src/[^/]+/java/", r"src/[^/]+/kotlin/")
+
+
+def _rightmost_marker_match(fp: str, markers) -> Optional["re.Match"]:
+    best = None
+    for marker in markers:
+        for m in re.finditer(marker, fp):
+            if best is None or m.start() > best.start():
+                best = m
+    return best
+
+
+def is_own_package_path(file_path: str, own_roots, markers=JADX_SOURCE_MARKERS) -> bool:
+    """True if this source file lives under any of own_roots (a string or set)."""
+    if isinstance(own_roots, str):
+        own_roots = {own_roots}
+    fp = file_path.replace("\\", "/").lower()
+    for root in own_roots:
+        root_path = re.escape(root.replace(".", "/").lower())
+        for marker in markers:
+            if re.search(marker + root_path + "/", fp):
+                return True
+    return False
+
+
+# Dotted form, matched against the path with '/' as the separator.
+THIRD_PARTY_PREFIXES = (
+    "org.bouncycastle.", "org.spongycastle.", "com.google.crypto.tink.", "org.conscrypt.",
+    "org.acra.", "io.sentry.", "com.bugsnag.", "com.crashlytics.", "io.fabric.",
+    "com.microsoft.appcenter.", "com.microsoft.azure.",
+    "com.google.android.", "com.google.firebase.", "com.google.gson.",
+    "com.google.protobuf.", "com.google.common.", "com.google.api.", "com.google.auth.",
+    "com.google.maps.",
+    # An own applicationId under com.android is added by the manifest read, not this denylist.
+    "com.android.",
+    "com.huawei.",
+    "androidx.", "android.support.", "android.arch.",
+    "kotlin.", "kotlinx.",
+    "org.jetbrains.",
+    "okhttp3.", "okio.", "retrofit2.", "com.squareup.",
+    "io.reactivex.", "rx.",
+    "com.facebook.",
+    "dagger.", "hilt.", "javax.inject.", "butterknife.",
+    "timber.log.", "org.slf4j.", "ch.qos.logback.", "org.apache.log4j.",
+    "com.bumptech.glide.", "com.airbnb.lottie.",
+    "org.apache.",
+    "com.amazonaws.", "com.newrelic.", "com.appsflyer.", "com.adjust.",
+    "com.segment.", "com.mixpanel.", "com.amplitude.", "io.netty.", "io.grpc.",
+    "com.fasterxml.", "org.json.", "io.flutter.", "com.flurry.",
+    "io.ktor.", "ktor.",
+    "com.liulishuo.",
+)
+
+_THIRD_PARTY_SLASHED = tuple(p.replace(".", "/") for p in THIRD_PARTY_PREFIXES)
+
+
+def is_third_party_path(file_path: str, markers=JADX_SOURCE_MARKERS) -> bool:
+    """True if this file lives under a known third-party SDK namespace (marker stripped first so a 'kotlin' source-root doesn't collide with the 'kotlin.' prefix)."""
+    fp = file_path.replace("\\", "/").lower()
+    for marker in markers:
+        m = re.search(marker, fp)
+        if m:
+            fp = fp[m.end():]
+            break
+    for prefix in _THIRD_PARTY_SLASHED:
+        if f"/{prefix}" in fp or fp.startswith(prefix):
+            return True
+    return False
+
+
+def _file_package_path(file_path: str, markers=JADX_SOURCE_MARKERS) -> Optional[str]:
+    """The file's full dotted package path, or None if it matches no marker."""
+    fp = file_path.replace("\\", "/").lower()
+    m = _rightmost_marker_match(fp, markers)
+    if m is None:
+        return None
+    segments = [s for s in fp[m.end():].split("/") if s][:-1]
+    if not segments:
+        return None
+    return ".".join(segments)
+
+
+def check_android_override(file_path: str, config: Optional[ScopeConfig], markers=JADX_SOURCE_MARKERS) -> Optional[str]:
+    """Return 'own', 'vendor', or None for this file, per .narvy-scope.yml."""
+    if not config:
+        return None
+    pkg_path = _file_package_path(file_path, markers=markers)
+    if pkg_path is None:
+        return None
+    if any(segment_prefix_match(e, pkg_path) for e in config.own):
+        return "own"
+    if any(segment_prefix_match(e, pkg_path) for e in config.vendor):
+        return "vendor"
+    return None
+
+
+def resolve_file_scope(file_path: str, own_roots, override_config: Optional[ScopeConfig] = None,
+                        markers=JADX_SOURCE_MARKERS) -> bool:
+    """True to scan as first-party, False to skip as third-party. A .narvy-scope.yml entry wins over own_roots and the denylist; pass GRADLE_SOURCE_MARKERS for a Gradle checkout."""
+    override = check_android_override(file_path, override_config, markers=markers)
+    if override == "own":
+        return True
+    if override == "vendor":
+        return False
+    if own_roots:
+        return file_path.endswith('.xml') or is_own_package_path(file_path, own_roots, markers=markers)
+    return not is_third_party_path(file_path, markers=markers)

narvy/uploader.py

@@ -0,0 +1,92 @@
+import os
+
+import requests
+
+# NARVY_URL overrides the default API endpoint.
+API_BASE = (os.environ.get("NARVY_URL") or "https://narvy.io").rstrip("/")
+
+
+def _network_error(exc):
+    """Return the (status, data) shape callers handle; status 0 never matches a real HTTP code."""
+    return 0, {
+        "error": (
+            f"could not reach the Narvy server at {API_BASE} ({exc}). "
+            "Check your internet connection, VPN/proxy or firewall, then retry."
+        )
+    }
+
+
+def _json_or_error(r):
+    try:
+        return r.status_code, r.json()
+    except ValueError:
+        return r.status_code, {"error": f"non-JSON response from server (HTTP {r.status_code})"}
+
+
+def whoami(token):
+    try:
+        r = requests.get(
+            f"{API_BASE}/api/v1/whoami",
+            headers={"X-API-Token": token},
+            timeout=15,
+        )
+    except requests.exceptions.RequestException as e:
+        return _network_error(e)
+    return _json_or_error(r)
+
+
+def upload_scan(apk_path, token, platform="android", analysis_type="sast", confirm_warning=False):
+    # confirm_warning proceeds past the API's 409 malware-triage warning.
+    data = {"platform": platform, "type": analysis_type}
+    if confirm_warning:
+        data["confirm_warning"] = "true"
+    try:
+        with open(apk_path, "rb") as f:
+            r = requests.post(
+                f"{API_BASE}/api/v1/analyze",
+                headers={"X-API-Token": token},
+                data=data,
+                files={"input_file": f},
+                timeout=300,
+            )
+    except requests.exceptions.RequestException as e:
+        return _network_error(e)
+    return _json_or_error(r)
+
+
+def ingest_results(token, app_name, platform, scan_mode, findings, version=None):
+    """POST this scan's findings to /api/v1/ingest (no binary leaves this machine)."""
+    body = {
+        "app_name": app_name,
+        "platform": platform,
+        "scan_mode": scan_mode,
+        "version": version,
+        "findings": findings,
+    }
+    try:
+        r = requests.post(
+            f"{API_BASE}/api/v1/ingest",
+            headers={"X-API-Token": token, "Content-Type": "application/json"},
+            json=body,
+            timeout=120,
+        )
+    except requests.exceptions.RequestException as e:
+        return _network_error(e)
+    return _json_or_error(r)
+
+
+def list_scans(token, limit=20, offset=0, status=None):
+    """List recent scans on the caller's account via GET /api/v1/scans."""
+    params = {"limit": limit, "offset": offset}
+    if status:
+        params["status"] = status
+    try:
+        r = requests.get(
+            f"{API_BASE}/api/v1/scans",
+            headers={"X-API-Token": token},
+            params=params,
+            timeout=15,
+        )
+    except requests.exceptions.RequestException as e:
+        return _network_error(e)
+    return _json_or_error(r)

narvy/weak_prng_context.py

@@ -0,0 +1,270 @@
+"""Usage-context classifier for the `android-weak-prng` rule (CWE-338): re-grade every
+match into security (HIGH), non_security (INFO) or unknown (LOW) from file evidence. Nothing is dropped."""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Dict, List, Optional, Tuple
+
+RULE_ID = "android-weak-prng"
+
+SEVERITY_SECURITY = "HIGH"
+SEVERITY_UNKNOWN = "LOW"
+SEVERITY_NON_SECURITY = "INFO"
+
+_FALLBACK_BACK = 6
+_FALLBACK_FWD = 12
+_MAX_BLOCK_LINES = 120
+
+# Platform class names, so these survive minification.
+_SEC_API_RE = re.compile(
+    r"\b(?:"
+    r"SecretKeySpec|IvParameterSpec|PBEKeySpec|GCMParameterSpec|"
+    r"KeyGenerator|KeyPairGenerator|KeyGenParameterSpec|SecureRandom|"
+    r"Cipher\s*\.\s*getInstance|Mac\s*\.\s*getInstance|"
+    r"MessageDigest\s*\.\s*getInstance|Signature\s*\.\s*getInstance|"
+    r"KeyStore\s*\.\s*getInstance|PublicKeyCredential"
+    r")\b"
+)
+
+# Raw byte output is almost always key/nonce/IV/salt material; survives obfuscation.
+_NEXT_BYTES_RE = re.compile(r"\.\s*nextBytes\s*\(")
+
+# Strong identifiers only; 'key'/'iv'/'mac'/'auth'/'crypto'/'uuid' are too ambiguous.
+_SEC_TOKEN_RE = re.compile(
+    r"(?<![a-z])(?:"
+    r"token|nonce|salt|otp|passwd|password|passphrase|secret|"
+    r"apikey|api_key|privatekey|private_key|keymaterial|key_material|"
+    r"seedbytes|challenge|credential|csrf|xsrf|verifier|"
+    r"sessionkey|session_key|authcode|auth_code|encrypt|decrypt|signing"
+    r")(?![a-z])",
+    re.IGNORECASE,
+)
+
+# Package layout usually survives obfuscation, so this holds on minified code.
+_SEC_PATH_RE = re.compile(
+    r"(?:^|/)(?:auth|authentication|authenticator|identity|crypto|"
+    r"cryptography|security|keystore|keychain|credentials?|login|signin|"
+    r"session|oauth|jwt|fido|webauthn|password)(?:s)?(?:/|$)",
+    re.IGNORECASE,
+)
+
+# Language-level sink shapes, so these survive obfuscation too.
+_NONSEC_SINK_RE = re.compile(
+    r"(?:"
+    r"Thread\s*\.\s*sleep\s*\(|"
+    r"\.\s*postDelayed\s*\(|"
+    r"\.\s*setDuration\s*\(|"
+    r"\.\s*setStartDelay\s*\(|"
+    r"\.\s*setPeriodic\s*\(|"
+    r"\.\s*setInexactRepeating\s*\(|"
+    r"\.\s*scheduleAtFixedRate\s*\(|"
+    r"\.\s*scheduleWithFixedDelay\s*\(|"
+    r"ValueAnimator|ObjectAnimator|PropertyValuesHolder|AnimatorSet|"
+    r"\bPaint\b|\bCanvas\b|\.\s*setColor\s*\(|\.\s*setAlpha\s*\(|"
+    r"\bJobInfo\s*\.\s*Builder\b|\bAlarmManager\b|"
+    r"\bColor\s*\.\s*(?:HSVToColor|argb|rgb|parseColor)\s*\(|"
+    r"\.\s*setBackgroundColor\s*\("
+    r")"
+)
+
+_SAMPLING_CMP_RE = re.compile(
+    r"(?:Math\s*\.\s*random\s*\(\s*\)|\.\s*next(?:Int|Double|Float)\s*\([^;]*\))"
+    r"[^;]*?[<>]=?"
+)
+
+_NONSEC_PATH_RE = re.compile(
+    r"(?:metric|metrics|analytic|analytics|telemetry|tracking|clickstream|"
+    r"nexus|minerva|weblab|logging|logger|sampling|sample|experiment|canary|"
+    r"abtest|ab_test|animation|animator|particle|firefly|backoff|retry|"
+    r"throttle|ratelimiter|rate_limiter|jitter|splash|onboarding)",
+    re.IGNORECASE,
+)
+
+_NONSEC_TOKEN_RE = re.compile(
+    r"(?<![a-z])(?:"
+    r"jitter|backoff|back_off|retry|retries|throttle|samplerate|sample_rate|"
+    r"sampling|analytics|telemetry|clickstream|animator|animation|"
+    r"interpolator|dialup|bucket|placeholder|shuffle|avatar|confetti|"
+    r"filename|file_name|tmpfile|tmp_file|tempfile|temp_file|"
+    r"displayid|display_id|nickname"
+    r")(?![a-z])",
+    re.IGNORECASE,
+)
+
+_ASSIGN_RE = re.compile(
+    r"(?:^|[^\w.])(?:(?:private|public|protected|static|final|volatile|"
+    r"transient)\s+)*(?:java\.util\.)?Random\s+(\w+)\s*="
+)
+_FIELD_ASSIGN_RE = re.compile(r"this\s*\.\s*(\w+)\s*=\s*new\s+(?:java\.util\.)?Random\s*\(")
+
+
+def _enclosing_block(lines: List[str], line_idx: int) -> Tuple[int, int]:
+    """Best-effort enclosing method body for a 0-based line index."""
+    start = max(0, line_idx - _FALLBACK_BACK)
+    cur_indent = len(lines[line_idx]) - len(lines[line_idx].lstrip())
+    for i in range(line_idx, max(-1, line_idx - _MAX_BLOCK_LINES), -1):
+        stripped = lines[i].strip()
+        if not stripped:
+            continue
+        indent = len(lines[i]) - len(lines[i].lstrip())
+        if indent < cur_indent and stripped.endswith("{"):
+            start = i
+            break
+
+    depth = 0
+    end = min(len(lines) - 1, line_idx + _FALLBACK_FWD)
+    opened = False
+    for i in range(start, min(len(lines), start + _MAX_BLOCK_LINES)):
+        depth += lines[i].count("{") - lines[i].count("}")
+        if lines[i].count("{"):
+            opened = True
+        if opened and depth <= 0 and i >= line_idx:
+            end = i
+            break
+    return start, max(end, line_idx)
+
+
+def _assigned_name(line: str) -> Optional[str]:
+    m = _FIELD_ASSIGN_RE.search(line)
+    if m:
+        return m.group(1)
+    m = _ASSIGN_RE.search(line)
+    if m:
+        return m.group(1)
+    return None
+
+
+def _usage_lines(lines: List[str], name: str, decl_idx: int) -> List[str]:
+    """Every line in the file that calls a method on `name`."""
+    use_re = re.compile(r"(?<![\w.])(?:this\s*\.\s*)?" + re.escape(name) + r"\s*\.\s*\w+\s*\(")
+    out = []
+    for i, ln in enumerate(lines):
+        if i == decl_idx:
+            continue
+        if use_re.search(ln):
+            out.append(ln)
+            if len(out) >= 40:
+                break
+    return out
+
+
+def classify(content: str, line: int, file_path: str = "") -> Dict[str, Any]:
+    """Grade one weak-PRNG hit. `line` is 1-based, per semgrep."""
+    lines = content.split("\n")
+    idx = max(0, min(len(lines) - 1, line - 1))
+
+    start, end = _enclosing_block(lines, idx)
+    block = "\n".join(lines[start:end + 1])
+
+    name = _assigned_name(lines[idx])
+    uses = _usage_lines(lines, name, idx) if name else []
+    scan = block + "\n" + "\n".join(uses)
+
+    path_norm = (file_path or "").replace("\\", "/")
+
+    # Evidence precedence: what the value flows to outranks where the file lives.
+    if _NEXT_BYTES_RE.search(scan):
+        return _res("security", "random value read as raw bytes (nextBytes) - "
+                                "key/nonce/credential material shape")
+    m = _SEC_API_RE.search(scan)
+    if m:
+        return _res("security", f"used in the same block as a crypto/security API ({m.group(0)})")
+    m = _SEC_TOKEN_RE.search(scan)
+    if m:
+        return _res("security", f"security-material identifier near the call site ('{m.group(0)}')")
+
+    m = _NONSEC_SINK_RE.search(scan)
+    if m:
+        return _res("non_security", f"value flows to a non-security sink ({m.group(0).strip()})")
+    if _SAMPLING_CMP_RE.search(scan):
+        return _res("non_security", "value compared against a rate threshold (sampling / coin flip)")
+
+    m = _SEC_PATH_RE.search(path_norm)
+    if m:
+        return _res("security", f"call site is inside a security component path ('{m.group(0).strip('/')}')")
+
+    m = _NONSEC_TOKEN_RE.search(scan)
+    if m:
+        return _res("non_security", f"non-security usage keyword near the call site ('{m.group(0)}')")
+    m = _NONSEC_PATH_RE.search(path_norm)
+    if m:
+        return _res("non_security", f"call site is inside a non-security component path ('{m.group(0)}')")
+
+    return _res("unknown", "no evidence found that the value is (or is not) used as security material")
+
+
+def _res(context: str, evidence: str) -> Dict[str, Any]:
+    sev = {
+        "security": SEVERITY_SECURITY,
+        "non_security": SEVERITY_NON_SECURITY,
+        "unknown": SEVERITY_UNKNOWN,
+    }[context]
+    return {"context": context, "severity": sev, "evidence": evidence}
+
+
+_MESSAGES = {
+    "security": (
+        "java.util.Random / Math.random() is not cryptographically secure, and "
+        "the value produced here reaches security-sensitive material. Use "
+        "java.security.SecureRandom."
+    ),
+    "non_security": (
+        "java.util.Random / Math.random() used in what looks like a "
+        "NON-security context. Kept for completeness at Info severity - "
+        "review only if this value ever becomes security-relevant. Use "
+        "SecureRandom for tokens, keys, nonces, salts and session ids."
+    ),
+    "unknown": (
+        "java.util.Random / Math.random() is not cryptographically secure. No "
+        "evidence was found that this value is used as security material, and "
+        "none that it isn't - graded Low pending review. Use SecureRandom for "
+        "tokens, keys, nonces, salts and session ids."
+    ),
+}
+
+
+def apply(findings: List[Dict[str, Any]], source_dir: str) -> List[Dict[str, Any]]:
+    """Re-grade every android-weak-prng finding in place (unreadable file keeps original severity)."""
+    import os
+
+    cache: Dict[str, Optional[str]] = {}
+    for f in findings:
+        if f.get("rule_id") != RULE_ID:
+            continue
+        rel = f.get("file_path") or ""
+        abs_path = os.path.join(source_dir, rel)
+        if abs_path not in cache:
+            try:
+                with open(abs_path, "r", encoding="utf-8", errors="ignore") as fh:
+                    cache[abs_path] = fh.read()
+            except OSError:
+                cache[abs_path] = None
+        content = cache[abs_path]
+        if content is None:
+            f.setdefault("details", {})["prng_context"] = "unreadable"
+            continue
+
+        verdict = classify(content, int(f.get("line") or 1), rel)
+        f["original_severity"] = f.get("severity")
+        f["severity"] = verdict["severity"]
+        details = f.setdefault("details", {})
+        details["prng_context"] = verdict["context"]
+        details["prng_context_evidence"] = verdict["evidence"]
+        details["description"] = _MESSAGES[verdict["context"]]
+        details["recommendation"] = _MESSAGES[verdict["context"]]
+        f["name"] = _MESSAGES[verdict["context"]][:120]
+    return findings
+
+
+def dedupe_by_location(findings: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    """Collapse identical (rule_id, file_path, line) findings."""
+    seen = set()
+    out = []
+    for f in findings:
+        key = (f.get("rule_id"), f.get("file_path"), f.get("line"))
+        if key in seen:
+            continue
+        seen.add(key)
+        out.append(f)
+    return out

narvy/web/nuclei_binary.py

@@ -0,0 +1,105 @@
+"""Resolve a `nuclei` binary, downloading a pinned release if none on PATH."""
+
+import logging
+import os
+import platform
+import shutil
+import stat
+import subprocess
+import zipfile
+
+import requests
+
+logger = logging.getLogger(__name__)
+
+# Pinned by hand: a floating version would change scan behaviour between runs.
+NUCLEI_VERSION = "3.5.1"
+TOOLS_DIR = os.path.expanduser("~/.narvy/tools")
+NUCLEI_HOME = os.path.join(TOOLS_DIR, f"nuclei-{NUCLEI_VERSION}")
+_IS_WINDOWS = platform.system() == "Windows"
+_IS_MAC = platform.system() == "Darwin"
+NUCLEI_BIN = os.path.join(NUCLEI_HOME, "nuclei.exe" if _IS_WINDOWS else "nuclei")
+
+
+def _release_asset_name() -> str:
+    """Release zip filename: nuclei_<version>_<os>_<arch>.zip (os linux/macOS/windows)."""
+    machine = platform.machine().lower()
+    if machine in ("x86_64", "amd64"):
+        arch = "amd64"
+    elif machine in ("aarch64", "arm64"):
+        arch = "arm64"
+    elif machine in ("armv7l", "armv6l", "arm"):
+        arch = "arm"
+    elif machine in ("i386", "i686", "x86"):
+        arch = "386"
+    else:
+        raise RuntimeError(
+            f"No known nuclei release for CPU architecture {machine!r}. "
+            "Install nuclei yourself and put it on PATH: "
+            "https://github.com/projectdiscovery/nuclei/releases"
+        )
+
+    if _IS_WINDOWS:
+        os_name = "windows"
+    elif _IS_MAC:
+        os_name = "macOS"
+    else:
+        os_name = "linux"
+
+    return f"nuclei_{NUCLEI_VERSION}_{os_name}_{arch}.zip"
+
+
+def _download_nuclei():
+    os.makedirs(TOOLS_DIR, exist_ok=True)
+    asset_name = _release_asset_name()
+    url = (
+        f"https://github.com/projectdiscovery/nuclei/releases/download/"
+        f"v{NUCLEI_VERSION}/{asset_name}"
+    )
+    zip_path = os.path.join(TOOLS_DIR, asset_name)
+    logger.info(f"nuclei not found on PATH - downloading {url}")
+    resp = requests.get(url, stream=True, timeout=120, allow_redirects=True)
+    resp.raise_for_status()
+    with open(zip_path, "wb") as f:
+        for chunk in resp.iter_content(chunk_size=1 << 20):
+            f.write(chunk)
+    os.makedirs(NUCLEI_HOME, exist_ok=True)
+    with zipfile.ZipFile(zip_path) as z:
+        z.extractall(NUCLEI_HOME)
+    os.remove(zip_path)
+    if not os.path.exists(NUCLEI_BIN):
+        raise RuntimeError(
+            f"nuclei archive extracted to {NUCLEI_HOME} but no binary found "
+            f"at the expected path {NUCLEI_BIN} - unexpected archive layout."
+        )
+    if not _IS_WINDOWS:
+        st = os.stat(NUCLEI_BIN)
+        os.chmod(NUCLEI_BIN, st.st_mode | stat.S_IEXEC | stat.S_IXGRP | stat.S_IXOTH)
+    logger.info(f"nuclei {NUCLEI_VERSION} installed to {NUCLEI_BIN}")
+
+
+def resolve_nuclei_binary() -> str:
+    """Prefer nuclei on PATH, else download the pinned release to ~/.narvy/tools."""
+    on_path = shutil.which("nuclei")
+    if on_path:
+        return on_path
+    if os.path.exists(NUCLEI_BIN):
+        return NUCLEI_BIN
+    _download_nuclei()
+    return NUCLEI_BIN
+
+
+def verify_nuclei(nuclei_bin: str) -> str:
+    try:
+        result = subprocess.run(
+            [nuclei_bin, "-version"], capture_output=True, text=True, timeout=15
+        )
+    except Exception as e:
+        raise RuntimeError(f"Could not run nuclei ({nuclei_bin}): {e}")
+    # nuclei prints its version banner to stderr and exits 0.
+    out = (result.stdout or "") + (result.stderr or "")
+    if result.returncode != 0 or not out.strip():
+        raise RuntimeError(
+            f"nuclei ({nuclei_bin}) did not run cleanly (exit {result.returncode}): {out[:300]}"
+        )
+    return out.strip()