narvy-cli 1.0.0__py3-none-any.whl

narvy/ios/plist_checks.py

@@ -0,0 +1,249 @@
+"""Info.plist and *.entitlements checks for iOS source-mode SAST: ATS, custom
+URL schemes and Universal Links (parsed with plistlib, not the source engines)."""
+from __future__ import annotations
+
+import glob
+import os
+import plistlib
+from typing import Any, Dict, List, Optional, Tuple
+
+from .third_party_filter import is_ios_vendor_dir_path
+
+_SYSTEM_URL_SCHEMES = {
+    "http", "https", "mailto", "tel", "sms", "facetime", "facetime-audio",
+    "itms-apps", "itms-appss",
+}
+
+_WEAK_TLS_VERSIONS = {"TLSv1.0", "TLSv1.1"}
+
+
+def _rule_def(rule_id: str, name: str, severity: str, cwe: str, masvs: str,
+              description: str, recommendation: str) -> Dict[str, Any]:
+    return {
+        "id": rule_id,
+        "name": name,
+        "severity": severity,
+        "details": {
+            "cwe": cwe,
+            "masvs": masvs,
+            "description": description,
+            "recommendation": recommendation,
+        },
+    }
+
+
+_RULE_DEFS: Dict[str, Dict[str, Any]] = {
+    d["id"]: d for d in [
+        _rule_def(
+            "IOS-PLIST-ATS-001", "ATS Allows Arbitrary Loads (HTTP Everywhere)",
+            "HIGH", "CWE-319", "MSTG-NETWORK-1",
+            "NSAllowsArbitraryLoads is true in NSAppTransportSecurity, disabling App Transport Security app-wide. The app can connect over insecure HTTP and with weak/legacy TLS settings to any host.",
+            "Remove NSAllowsArbitraryLoads (or set it to false) and use NSExceptionDomains for the specific hosts that genuinely need an exception, with the narrowest exception flags possible.",
+        ),
+        _rule_def(
+            "IOS-PLIST-ATS-002", "ATS Allows Arbitrary Loads in Web Content",
+            "MEDIUM", "CWE-319", "MSTG-NETWORK-1",
+            "NSAllowsArbitraryLoadsInWebContent is true, letting WKWebView/UIWebView load insecure HTTP sub-resources even though top-level ATS is otherwise enforced. Enables mixed-content attacks against content rendered in the app's own WebViews.",
+            "Set NSAllowsArbitraryLoadsInWebContent to false unless the app must render arbitrary third-party web content that cannot be upgraded to HTTPS.",
+        ),
+        _rule_def(
+            "IOS-PLIST-ATS-003", "ATS Exception Domain Allows Insecure HTTP",
+            "MEDIUM", "CWE-319", "MSTG-NETWORK-1",
+            "An NSExceptionDomains entry sets NSExceptionAllowsInsecureHTTPLoads to true for a specific domain, permitting cleartext HTTP traffic to that host.",
+            "Use HTTPS for this domain and remove the exception. If the domain genuinely cannot support TLS, treat all traffic to it as untrusted/interceptable.",
+        ),
+        _rule_def(
+            "IOS-PLIST-ATS-004", "ATS Exception Domain Allows Weak TLS Version",
+            "HIGH", "CWE-326", "MSTG-NETWORK-2",
+            "An NSExceptionDomains entry sets NSExceptionMinimumTLSVersion to TLSv1.0 or TLSv1.1, both deprecated and vulnerable to known protocol-level attacks (e.g. POODLE, BEAST).",
+            "Set NSExceptionMinimumTLSVersion to TLSv1.2 or higher, or remove the exception entirely if the server supports modern TLS.",
+        ),
+        _rule_def(
+            "IOS-PLIST-URL-001", "Custom URL Scheme Declared",
+            "LOW", "CWE-284", "MSTG-PLATFORM-3",
+            "The app registers one or more custom (non-system) URL schemes via CFBundleURLTypes. Any other installed app can invoke these schemes, making the handler part of the app's attack surface (deep link hijacking / spoofed invocation) - this is an attack-surface note, not by itself a proven vulnerability. See the app's URL/deep-link handler source for whether incoming URLs are validated.",
+            "Validate the source of incoming URLs where possible (options[.sourceApplication] on iOS <9, or treat all incoming custom-scheme URLs as untrusted input). Prefer Universal Links for anything security-sensitive.",
+        ),
+        _rule_def(
+            "IOS-PLIST-URL-002", "Custom URL Schemes Without Universal Links",
+            "MEDIUM", "CWE-284", "MSTG-PLATFORM-3",
+            "The app declares custom URL scheme(s) via CFBundleURLTypes but its entitlements do not declare a corresponding applinks: Universal Link domain. Universal Links are strictly more secure for deep linking (they require the destination domain to serve a signed apple-app-site-association file, so only the verified domain owner can trigger them - unlike a custom scheme, which any app can register).",
+            "Implement Universal Links (com.apple.developer.associated-domains with an applinks: entry) for any deep-link flow that carries sensitive actions (login, payment, account changes), and treat the custom scheme as a legacy/best-effort fallback only.",
+        ),
+        _rule_def(
+            "IOS-PLIST-URL-003", "Wildcard Universal Link Domain",
+            "MEDIUM", "CWE-284", "MSTG-PLATFORM-3",
+            "An applinks: entry in com.apple.developer.associated-domains uses a wildcard domain (*.example.com). Any subdomain - including ones the app owner does not control or has forgotten about - can trigger Universal Link handling in the app.",
+            "Use specific, fully-qualified domains instead of a wildcard. If a wildcard is genuinely required, validate the host explicitly in the Universal Link handler before acting on it.",
+        ),
+    ]
+}
+
+
+def get_rule_defs() -> List[Dict[str, Any]]:
+    """All rule definitions this module can emit, for SARIF."""
+    return list(_RULE_DEFS.values())
+
+
+def _find_own_info_plists(source_dir: str) -> List[str]:
+    """Info.plist files under source_dir, excluding vendored and build trees."""
+    results = []
+    for path in glob.iglob(os.path.join(source_dir, "**", "Info.plist"), recursive=True):
+        rel = os.path.relpath(path, source_dir)
+        if is_ios_vendor_dir_path(rel):
+            continue
+        results.append(path)
+    return results
+
+
+def _find_entitlements_for(info_plist_path: str, source_dir: str,
+                            _all_entitlements_cache: List[str]) -> Optional[str]:
+    """Best-effort entitlements file for an Info.plist (same directory first), or None."""
+    same_dir = os.path.dirname(info_plist_path)
+    local_matches = glob.glob(os.path.join(same_dir, "*.entitlements"))
+    if local_matches:
+        return local_matches[0]
+    return _all_entitlements_cache[0] if _all_entitlements_cache else None
+
+
+def _all_entitlements(source_dir: str) -> List[str]:
+    results = []
+    for path in glob.iglob(os.path.join(source_dir, "**", "*.entitlements"), recursive=True):
+        rel = os.path.relpath(path, source_dir)
+        if is_ios_vendor_dir_path(rel):
+            continue
+        results.append(path)
+    return results
+
+
+def _load_plist(path: str) -> Optional[Dict[str, Any]]:
+    try:
+        with open(path, "rb") as f:
+            return plistlib.load(f)
+    except Exception:
+        return None
+
+
+def _check_ats(ats: Dict[str, Any], rel_path: str) -> List[Dict[str, Any]]:
+    findings = []
+    if not ats:
+        # No ATS block means the iOS default (strict, HTTPS-only) applies.
+        return findings
+
+    if ats.get("NSAllowsArbitraryLoads"):
+        findings.append(_make_finding("IOS-PLIST-ATS-001", rel_path, 1))
+
+    if ats.get("NSAllowsArbitraryLoadsInWebContent"):
+        findings.append(_make_finding("IOS-PLIST-ATS-002", rel_path, 1))
+
+    exception_domains = ats.get("NSExceptionDomains", {}) or {}
+    if isinstance(exception_domains, dict):
+        for domain, config in exception_domains.items():
+            if not isinstance(config, dict):
+                continue
+            if config.get("NSExceptionAllowsInsecureHTTPLoads"):
+                findings.append(_make_finding(
+                    "IOS-PLIST-ATS-003", rel_path, 1,
+                    extra_desc=f' Domain: "{domain}".'))
+            if config.get("NSExceptionMinimumTLSVersion") in _WEAK_TLS_VERSIONS:
+                tls = config.get("NSExceptionMinimumTLSVersion")
+                findings.append(_make_finding(
+                    "IOS-PLIST-ATS-004", rel_path, 1,
+                    extra_desc=f' Domain: "{domain}", version: {tls}.'))
+    return findings
+
+
+def _declared_url_schemes(plist_content: Dict[str, Any]) -> List[str]:
+    schemes = []
+    for url_type in (plist_content.get("CFBundleURLTypes") or []):
+        if not isinstance(url_type, dict):
+            continue
+        for scheme in (url_type.get("CFBundleURLSchemes") or []):
+            if isinstance(scheme, str) and scheme.strip():
+                schemes.append(scheme.strip())
+    return schemes
+
+
+def _check_url_schemes_and_universal_links(
+        plist_content: Dict[str, Any], rel_plist_path: str,
+        entitlements: Optional[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    findings = []
+    schemes = _declared_url_schemes(plist_content)
+    custom_schemes = [s for s in schemes if s.lower() not in _SYSTEM_URL_SCHEMES]
+    if not custom_schemes:
+        return findings
+
+    findings.append(_make_finding(
+        "IOS-PLIST-URL-001", rel_plist_path, 1,
+        extra_desc=f' Declared scheme(s): {", ".join(custom_schemes)}.'))
+
+    if entitlements is None:
+        # Universal Links live in entitlements only; without one they can't be ruled out.
+        return findings
+
+    domains = entitlements.get("com.apple.developer.associated-domains", []) or []
+    applinks_domains = [
+        d[len("applinks:"):] for d in domains
+        if isinstance(d, str) and d.startswith("applinks:")
+    ]
+    if not applinks_domains:
+        findings.append(_make_finding(
+            "IOS-PLIST-URL-002", rel_plist_path, 1,
+            extra_desc=f' Declared scheme(s): {", ".join(custom_schemes)}.'))
+
+    for domain in applinks_domains:
+        if domain.startswith("*."):
+            findings.append(_make_finding(
+                "IOS-PLIST-URL-003", rel_plist_path, 1,
+                extra_desc=f' Domain: "{domain}".'))
+
+    return findings
+
+
+def _make_finding(rule_id: str, file_path: str, line: int,
+                   extra_desc: str = "") -> Dict[str, Any]:
+    rule = _RULE_DEFS[rule_id]
+    details = dict(rule["details"])
+    if extra_desc:
+        details["description"] = details["description"] + extra_desc
+    return {
+        "rule_id": rule_id,
+        "file_path": file_path,
+        "name": rule["name"],
+        "severity": rule["severity"],
+        "line": line,
+        "engine": "plist",
+        "details": details,
+    }
+
+
+def analyze_plist_and_entitlements(source_dir: str) -> Tuple[List[Dict[str, Any]], List[str], int]:
+    """Scan every non-vendored Info.plist. Returns (findings, notes, count)."""
+    findings: List[Dict[str, Any]] = []
+    notes: List[str] = []
+
+    info_plists = _find_own_info_plists(source_dir)
+    if not info_plists:
+        return findings, notes, 0
+
+    entitlements_files = _all_entitlements(source_dir)
+    if not entitlements_files:
+        notes.append(
+            "No *.entitlements file found in the repo - Universal Links "
+            "checks were skipped for all Info.plist targets (cannot prove "
+            "Universal Links are absent without the real entitlements)."
+        )
+
+    for plist_path in info_plists:
+        rel_plist = os.path.relpath(plist_path, source_dir)
+        plist_content = _load_plist(plist_path)
+        if plist_content is None:
+            continue
+
+        findings.extend(_check_ats(plist_content.get("NSAppTransportSecurity", {}) or {}, rel_plist))
+
+        entitlements_path = _find_entitlements_for(plist_path, source_dir, entitlements_files)
+        entitlements = _load_plist(entitlements_path) if entitlements_path else None
+        findings.extend(_check_url_schemes_and_universal_links(plist_content, rel_plist, entitlements))
+
+    return findings, notes, len(info_plists)

narvy/ios/source_analyzer.py

@@ -0,0 +1,301 @@
+"""iOS source-mode (Swift/ObjC) SAST entry point: ObjC regex pass, Swift Semgrep
+pass, plist/entitlements pass. Public API: analyze_source()."""
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+from typing import Any, Dict, List, Optional, Tuple
+
+import yaml
+
+from narvy.rule_engine import load_rules_from_dir, run_rules_on_file
+from narvy import semgrep_engine
+from narvy import comment_filter
+from narvy.ios.third_party_filter import is_ios_vendor_dir_path, IOS_VENDOR_DIR_NAMES
+from narvy.ios import plist_checks
+from narvy.ios import trust_all_context
+
+_HERE = os.path.dirname(__file__)
+OBJC_RULES_DIR = os.path.join(_HERE, "..", "rules", "ios", "objc")
+SWIFT_SEMGREP_RULES_PATH = os.path.join(_HERE, "..", "rules", "ios_swift.yml")
+
+_OBJC_EXTENSIONS = (".m", ".mm", ".h")
+_SWIFT_EXTENSION = ".swift"
+
+# Skips the npm tree a React Native project keeps beside its Xcode project.
+_EXTRA_SKIP_DIR_NAMES = frozenset({"node_modules", ".git"})
+
+# Suffix match: Xcode names test folders <TargetName>Tests / <TargetName>UITests.
+_TEST_DIR_SUFFIXES = ("Tests", "UITests")
+
+_SEMGREP_SEVERITY_MAP = {
+    "ERROR": "CRITICAL",
+    "WARNING": "HIGH",
+    "INFO": "MEDIUM",
+}
+
+
+def _is_test_dir_name(name: str) -> bool:
+    return name.endswith(_TEST_DIR_SUFFIXES)
+
+
+def _is_extra_skip_path(rel_path: str) -> bool:
+    parts = rel_path.replace("\\", "/").split("/")
+    return any(part in _EXTRA_SKIP_DIR_NAMES or _is_test_dir_name(part) for part in parts)
+
+
+def _is_skipped_path(rel_path: str) -> bool:
+    return is_ios_vendor_dir_path(rel_path) or _is_extra_skip_path(rel_path)
+
+
+def _detect_react_native(source_dir: str) -> bool:
+    """Structural signal that this is (at least partly) a React Native app."""
+    if os.path.isdir(os.path.join(source_dir, "node_modules", "react-native")):
+        return True
+    for fname in ("Podfile", "Podfile.lock"):
+        fpath = os.path.join(source_dir, fname)
+        if os.path.isfile(fpath):
+            try:
+                with open(fpath, "r", encoding="utf-8", errors="ignore") as f:
+                    content = f.read()
+            except OSError:
+                continue
+            if "React-Core" in content or "react-native" in content.lower():
+                return True
+    return False
+
+
+def _collect_source_files(source_dir: str) -> Tuple[List[str], List[str], int]:
+    """Return (swift_files, objc_files, skipped_third_party_count)."""
+    swift_files: List[str] = []
+    objc_files: List[str] = []
+    skipped = 0
+
+    for root, _dirs, files in os.walk(source_dir):
+        for fname in files:
+            fpath = os.path.join(root, fname)
+            rel_path = os.path.relpath(fpath, source_dir)
+            is_swift = fname.endswith(_SWIFT_EXTENSION)
+            is_objc = fname.endswith(_OBJC_EXTENSIONS)
+            if not (is_swift or is_objc):
+                continue
+            if _is_skipped_path(rel_path):
+                skipped += 1
+                continue
+            if is_swift:
+                swift_files.append(fpath)
+            else:
+                objc_files.append(fpath)
+
+    return swift_files, objc_files, skipped
+
+
+def _load_swift_semgrep_rule_defs() -> List[Dict[str, Any]]:
+    """Synthesize a rule-def dict per rule id in ios_swift.yml, for SARIF."""
+    try:
+        with open(SWIFT_SEMGREP_RULES_PATH, "r") as f:
+            data = yaml.safe_load(f)
+    except OSError:
+        return []
+
+    defs = []
+    for rule in (data or {}).get("rules", []):
+        meta = rule.get("metadata", {}) or {}
+        defs.append({
+            "id": rule["id"],
+            "name": rule.get("message", rule["id"])[:120],
+            "severity": _SEMGREP_SEVERITY_MAP.get(rule.get("severity", "INFO"), "MEDIUM"),
+            "details": {
+                "cwe": meta.get("cwe", ""),
+                "masvs": meta.get("masvs", ""),
+                "description": rule.get("message", ""),
+                "recommendation": rule.get("message", ""),
+            },
+        })
+    return defs
+
+
+def _run_swift_semgrep(source_dir: str,
+                       timeout: Optional[int] = None) -> Optional[List[Dict[str, Any]]]:
+    """Run Semgrep against ios_swift.yml over source_dir."""
+    if not semgrep_engine.is_available():
+        semgrep_engine._record_run('unavailable')
+        return None
+
+    file_count = semgrep_engine.count_source_files(source_dir)
+    if timeout is None:
+        timeout = semgrep_engine.compute_semgrep_timeout(source_dir)
+
+    # --exclude args must be BARE names: a '/' anchors the pattern to the scan root.
+    exclude_args: List[str] = []
+    for name in sorted(IOS_VENDOR_DIR_NAMES | _EXTRA_SKIP_DIR_NAMES):
+        exclude_args += ["--exclude", name]
+    for suffix in _TEST_DIR_SUFFIXES:
+        exclude_args += ["--exclude", f"*{suffix}"]
+
+    cmd = (
+        ["semgrep", "--config", SWIFT_SEMGREP_RULES_PATH, source_dir,
+         "--include", "*.swift",
+         "--json", "--quiet", "--no-git-ignore",
+         "--timeout", "60"]
+        + exclude_args
+    )
+    try:
+        proc = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)
+    except subprocess.TimeoutExpired:
+        semgrep_engine._record_run('timeout', timeout_s=timeout,
+                                   file_count=file_count)
+        return []
+
+    if not proc.stdout:
+        semgrep_engine._record_run('ok', timeout_s=timeout,
+                                   file_count=file_count)
+        return []
+
+    try:
+        data = json.loads(proc.stdout)
+    except json.JSONDecodeError:
+        semgrep_engine._record_run(
+            'error', timeout_s=timeout, file_count=file_count,
+            message="semgrep output was not valid JSON")
+        return []
+
+    semgrep_engine._record_run('ok', timeout_s=timeout, file_count=file_count)
+
+    # Per-file (content, comment-mask) cache: read each file at most once.
+    file_cache: Dict[str, Tuple[str, Optional[List[bool]]]] = {}
+
+    def _get_file(abs_path: str) -> Tuple[str, Optional[List[bool]]]:
+        if abs_path not in file_cache:
+            try:
+                with open(abs_path, "r", encoding="utf-8", errors="ignore") as fh:
+                    content = fh.read()
+            except OSError:
+                file_cache[abs_path] = ("", None)
+                return file_cache[abs_path]
+            mask = None
+            if "//" in content or "/*" in content:
+                mask = comment_filter.build_comment_mask(content)
+            file_cache[abs_path] = (content, mask)
+        return file_cache[abs_path]
+
+    findings = []
+    for r in data.get("results", []):
+        abs_path = r.get("path", "")
+        rel_path = os.path.relpath(abs_path, source_dir)
+        extra = r.get("extra", {})
+        meta = extra.get("metadata", {})
+        # Semgrep prefixes local-config ids with a dotted namespace; ours have no dots.
+        check_id = r.get("check_id", "semgrep-finding").rsplit(".", 1)[-1]
+        line_no = r.get("start", {}).get("line", 1)
+        col_no = r.get("start", {}).get("col", 1)
+
+        content, mask = _get_file(abs_path)
+
+        # Drop regex-rule hits that sit inside a comment (AST rules never do).
+        if mask is not None and comment_filter.line_col_in_comment(
+            content, line_no, col_no, mask
+        ):
+            continue
+
+        severity = _SEMGREP_SEVERITY_MAP.get(extra.get("severity", "INFO"), "MEDIUM")
+        message = extra.get("message", "")
+
+        # Downgrade trust-all-certs when guarded by a per-request opt-in flag.
+        if check_id == "ios-swift-trust-all-certs" and content:
+            flag = trust_all_context.opt_in_trust_flag(content, line_no)
+            if flag:
+                severity = "MEDIUM"
+                message = (
+                    message.rstrip()
+                    + f" [Narvy: this path is reachable only when the opt-in "
+                    f"flag `{flag}` is set (per-request, not unconditional), so "
+                    f"severity is lowered - verify that flag is never enabled "
+                    f"in production builds.]"
+                )
+
+        findings.append({
+            "rule_id": check_id,
+            "file_path": rel_path,
+            "name": message[:120] if message else extra.get("message", r.get("check_id", ""))[:120],
+            "severity": severity,
+            "line": line_no,
+            "details": {
+                "cwe": meta.get("cwe", ""),
+                "masvs": meta.get("masvs", ""),
+                "description": message,
+                "recommendation": message,
+            },
+            "engine": "semgrep",
+        })
+    return findings
+
+
+def analyze_source(source_dir: str) -> Dict[str, Any]:
+    """Scan a checked-out Swift/ObjC repo (read-only); returns the findings dict."""
+    if not source_dir or not os.path.isdir(source_dir):
+        return {
+            "ok": False,
+            "error": f"Not a directory: {source_dir}",
+            "findings": [],
+            "rule_defs": [],
+            "swift_files_scanned": 0,
+            "objc_files_scanned": 0,
+            "skipped_third_party": 0,
+            "notes": [],
+        }
+
+    notes: List[str] = []
+    all_findings: List[Dict[str, Any]] = []
+
+    objc_rules = load_rules_from_dir(OBJC_RULES_DIR)
+    swift_semgrep_rule_defs = _load_swift_semgrep_rule_defs()
+
+    swift_files, objc_files, skipped_third_party = _collect_source_files(source_dir)
+
+    if _detect_react_native(source_dir):
+        notes.append(
+            "This looks like a React Native app (node_modules/react-native "
+            "or a Podfile referencing React-Core was found). This scanner "
+            "only covers the native Swift/Objective-C shell - the app's "
+            "JS/TS business logic is out of scope and was not analyzed."
+        )
+
+    for file_path in objc_files:
+        rel_path = os.path.relpath(file_path, source_dir)
+        findings_in_file = run_rules_on_file(file_path, objc_rules)
+        for finding in findings_in_file:
+            finding["file_path"] = rel_path
+            finding["engine"] = "regex"
+        all_findings.extend(findings_in_file)
+
+    if semgrep_engine.is_available():
+        swift_findings = _run_swift_semgrep(source_dir)
+        if swift_findings:
+            all_findings.extend(swift_findings)
+        _sg_note = semgrep_engine.degraded_coverage_note()
+        if _sg_note:
+            notes.append(_sg_note)
+    else:
+        notes.append(
+            "semgrep not found - install with `pip install semgrep` for "
+            "Swift analysis. ObjC regex rules still ran."
+        )
+
+    plist_findings, plist_notes, _plist_count = plist_checks.analyze_plist_and_entitlements(source_dir)
+    all_findings.extend(plist_findings)
+    notes.extend(plist_notes)
+
+    rule_defs = list(objc_rules) + swift_semgrep_rule_defs + plist_checks.get_rule_defs()
+
+    return {
+        "ok": True,
+        "error": None,
+        "findings": all_findings,
+        "rule_defs": rule_defs,
+        "swift_files_scanned": len(swift_files),
+        "objc_files_scanned": len(objc_files),
+        "skipped_third_party": skipped_third_party,
+        "notes": notes,
+    }