git-oops 1.0.0__py3-none-any.whl

src/mcp_server.py

@@ -0,0 +1,124 @@
+"""
+Git-Oops Native Model Context Protocol (MCP) Server
+Allows Claude Desktop, Cursor, Windsurf, and Antigravity to attach to git-oops.
+Speaks standard JSON-RPC 2.0 over stdio without any external networking baggage.
+"""
+
+import sys
+import json
+from src.firewall import check_command_safety
+from src.squeezer import compress_traceback, redact_secrets
+from src.guardian import check_ghost_imports
+from src.engine import diagnose_and_patch, apply_patch_to_file
+
+MCP_TOOLS = [
+    {
+        "name": "git_oops_diagnose",
+        "description": "Analyzes a terminal crash traceback, roasts the code, and generates a surgical git diff patch.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "filepath": {"type": "string", "description": "Target file path"},
+                "error": {"type": "string", "description": "Crash traceback or exception message"}
+            },
+            "required": ["filepath", "error"]
+        }
+    },
+    {
+        "name": "git_oops_safe_exec",
+        "description": "Runs a shell command through the Blast-Radius firewall, preventing destructive deletions.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "command": {"type": "string", "description": "Command line to execute"}
+            },
+            "required": ["command"]
+        }
+    },
+    {
+        "name": "git_oops_squeezer",
+        "description": "Compresses noisy multi-thousand line terminal output into high-density context and redacts secrets.",
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "raw_logs": {"type": "string", "description": "Raw noisy logs"}
+            },
+            "required": ["raw_logs"]
+        }
+    }
+]
+
+
+def run_mcp_server():
+    """Stdio JSON-RPC loop for Model Context Protocol agents."""
+    sys.stderr.write("⚡ [GIT-OOPS MCP SERVER] Active and listening on stdio (JSON-RPC 2.0)...\n")
+    sys.stderr.flush()
+
+    for line in sys.stdin:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            req = json.loads(line)
+        except Exception:
+            continue
+
+        req_id = req.get("id")
+        method = req.get("method")
+        params = req.get("params", {})
+
+        if method == "initialize":
+            res = {
+                "jsonrpc": "2.0",
+                "id": req_id,
+                "result": {
+                    "protocolVersion": "2024-11-05",
+                    "capabilities": {"tools": {}},
+                    "serverInfo": {"name": "git-oops", "version": "0.2.0"}
+                }
+            }
+        elif method == "tools/list":
+            res = {
+                "jsonrpc": "2.0",
+                "id": req_id,
+                "result": {"tools": MCP_TOOLS}
+            }
+        elif method == "tools/call":
+            tool_name = params.get("name")
+            args = params.get("arguments", {})
+            
+            if tool_name == "git_oops_safe_exec":
+                cmd = args.get("command", "")
+                safe, reason = check_command_safety(cmd)
+                content = [{"type": "text", "text": json.dumps({"allowed": safe, "reason": reason})}]
+            elif tool_name == "git_oops_squeezer":
+                logs = args.get("raw_logs", "")
+                compressed = compress_traceback(logs)
+                content = [{"type": "text", "text": compressed}]
+            elif tool_name == "git_oops_diagnose":
+                fp = args.get("filepath", "")
+                err = args.get("error", "")
+                try:
+                    with open(fp, "r", encoding="utf-8") as f:
+                        code_ctx = f.read()
+                    diag = diagnose_and_patch(err, code_ctx, fp)
+                    content = [{"type": "text", "text": json.dumps(diag)}]
+                except Exception as ex:
+                    content = [{"type": "text", "text": json.dumps({"error": str(ex)})}]
+            else:
+                content = [{"type": "text", "text": f"Unknown tool: {tool_name}"}]
+
+            res = {
+                "jsonrpc": "2.0",
+                "id": req_id,
+                "result": {"content": content}
+            }
+        else:
+            res = {
+                "jsonrpc": "2.0",
+                "id": req_id,
+                "result": {}
+            }
+
+        sys.stdout.write(json.dumps(res) + "\n")
+        sys.stdout.flush()

src/replay.py

@@ -0,0 +1,100 @@
+"""
+Git-Oops Post-Mortem Crash Replay Time-Machine:
+Reconstructs terminal variables, locals, and scope right at the moment of the crash.
+Zero dependencies: Uses native traceback inspections and saved snapshot states.
+"""
+
+import os
+import sys
+import json
+import traceback
+from typing import Dict, Any, Optional
+
+CRASH_SNAPSHOT_DIR = os.path.expanduser("~/.git_oops/crashes")
+
+
+def record_crash_scope(filepath: str, error_log: str, local_vars: Optional[Dict[str, Any]] = None):
+    """Saves post-mortem scope variables to local storage."""
+    os.makedirs(CRASH_SNAPSHOT_DIR, exist_ok=True)
+    clean_locals = {}
+    if local_vars:
+        for k, v in local_vars.items():
+            if not k.startswith("__"):
+                clean_locals[k] = str(v)[:150]
+
+    record = {
+        "timestamp": os.path.getmtime(filepath) if os.path.exists(filepath) else 0,
+        "filepath": filepath,
+        "error_log": error_log.strip()[:1000],
+        "locals": clean_locals
+    }
+    
+    snap_file = os.path.join(CRASH_SNAPSHOT_DIR, "last_crash.json")
+    with open(snap_file, "w", encoding="utf-8") as f:
+        json.dump(record, f, indent=2)
+
+
+def get_last_crash_replay() -> Optional[Dict[str, Any]]:
+    """Loads the last recorded post-mortem crash state."""
+    snap_file = os.path.join(CRASH_SNAPSHOT_DIR, "last_crash.json")
+    if not os.path.exists(snap_file):
+        return None
+    try:
+        with open(snap_file, "r", encoding="utf-8") as f:
+            return json.load(f)
+    except Exception:
+        return None
+
+
+def record_crash_snapshot(
+    target_file: str,
+    exception_type: str,
+    exception_message: str,
+    stack_frames: list = None,
+    local_vars: Optional[Dict[str, Any]] = None
+) -> str:
+    """Records detailed crash snapshot into ~/.git_oops/crashes/<id>.json."""
+    os.makedirs(CRASH_SNAPSHOT_DIR, exist_ok=True)
+    import time
+    snap_id = f"crash_{int(time.time() * 1000)}.json"
+    clean_locals = {}
+    if local_vars:
+        for k, v in local_vars.items():
+            if not k.startswith("__"):
+                clean_locals[k] = v
+
+    data = {
+        "snapshot_id": snap_id,
+        "timestamp": time.strftime("%Y-%m-%d %H:%M:%S"),
+        "target_file": target_file,
+        "exception_type": exception_type,
+        "exception_message": exception_message,
+        "stack_frames": stack_frames or [],
+        "local_variables": clean_locals
+    }
+    with open(os.path.join(CRASH_SNAPSHOT_DIR, snap_id), "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=2)
+    # Also link as last_crash.json
+    with open(os.path.join(CRASH_SNAPSHOT_DIR, "last_crash.json"), "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=2)
+    return snap_id
+
+
+def inspect_crash_snapshot(snap_id: str = "last_crash.json") -> Dict[str, Any]:
+    """Inspects a recorded crash snapshot."""
+    target_path = os.path.join(CRASH_SNAPSHOT_DIR, snap_id) if not os.path.isabs(snap_id) else snap_id
+    if not os.path.exists(target_path):
+        return {"status": "NOT_FOUND", "path": target_path}
+    try:
+        with open(target_path, "r", encoding="utf-8") as f:
+            return json.load(f)
+    except Exception as e:
+        return {"status": "ERROR", "details": str(e)}
+
+
+def list_crash_snapshots(limit: int = 10) -> list:
+    """Lists recent crash snapshots."""
+    if not os.path.exists(CRASH_SNAPSHOT_DIR):
+        return []
+    files = sorted([f for f in os.listdir(CRASH_SNAPSHOT_DIR) if f.startswith("crash_") and f.endswith(".json")], reverse=True)
+    return files[:limit]

src/reviewer.py

@@ -0,0 +1,157 @@
+"""
+Git-Oops Pre-PR Gatekeeper & Staff Engineer Audit Engine
+Audits outgoing branch changes against base branch before Pull Request creation.
+Verifies L3 security, complexity drift, test coverage parity, and secret leaks.
+"""
+
+import os
+import sys
+import json
+import subprocess
+from pathlib import Path
+from typing import Dict, Any, List, Tuple
+
+from src.hooks import scan_diff_for_secrets, scan_file_ast
+from src.sentinel import check_code_complexity
+
+
+def get_default_base_branch() -> str:
+    """Detects default remote base branch (origin/main or main or master)."""
+    for candidate in ("origin/main", "main", "origin/master", "master"):
+        res = subprocess.run(
+            ["git", "rev-parse", "--verify", candidate],
+            capture_output=True, text=True, errors="replace"
+        )
+        if res.returncode == 0:
+            return candidate
+    return "HEAD~1"
+
+
+def review_pull_request(base_branch: str = None) -> Dict[str, Any]:
+    """
+    Performs comprehensive Pre-PR audit:
+    - Diff analysis vs base_branch
+    - Secret & token leak inspection
+    - AST security (CodeQL CWE mirrors)
+    - Code bloat & complexity check
+    - Test parity verification
+    """
+    base = base_branch or get_default_base_branch()
+
+    # Get diff against base
+    diff_proc = subprocess.run(
+        ["git", "diff", f"{base}...HEAD"],
+        capture_output=True, text=True, errors="replace"
+    )
+    diff_text = diff_proc.stdout
+
+    # Get changed files
+    files_proc = subprocess.run(
+        ["git", "diff", "--name-only", f"{base}...HEAD"],
+        capture_output=True, text=True, errors="replace"
+    )
+    changed_files = [f.strip() for f in files_proc.stdout.splitlines() if f.strip()]
+
+    # 1. Secret scanning
+    secret_findings = scan_diff_for_secrets(diff_text)
+
+    # 2. AST security & complexity on modified Python files
+    ast_findings: List[Dict[str, Any]] = []
+    complexity_warnings: List[Dict[str, Any]] = []
+
+    src_changed = False
+    tests_changed = False
+
+    for fpath in changed_files:
+        if fpath.startswith("tests/") or "test" in fpath.lower():
+            tests_changed = True
+        elif fpath.startswith("src/") or fpath.endswith(".py"):
+            src_changed = True
+
+        if fpath.endswith(".py") and os.path.exists(fpath):
+            findings = scan_file_ast(fpath)
+            ast_findings.extend(findings)
+
+            # Check complexity
+            try:
+                with open(fpath, "r", encoding="utf-8", errors="replace") as f:
+                    content = f.read()
+                ok, err = check_code_complexity(content, max_allowed_complexity=12)
+                if not ok:
+                    complexity_warnings.append({"file": fpath, "details": err})
+            except Exception:
+                pass
+
+    # 3. Test parity warning
+    test_parity_warning = None
+    if src_changed and not tests_changed:
+        test_parity_warning = "Application code modified without accompanying test updates in tests/."
+
+    # Determine verdict
+    critical_issues = len(secret_findings) + len([f for f in ast_findings if f.get("severity") in ("CRITICAL", "HIGH")])
+    if critical_issues > 0:
+        verdict = "BLOCKED"
+    elif complexity_warnings or test_parity_warning:
+        verdict = "WARNINGS"
+    else:
+        verdict = "APPROVED"
+
+    # Churn stats
+    added_lines = sum(1 for line in diff_text.splitlines() if line.startswith("+") and not line.startswith("+++"))
+    deleted_lines = sum(1 for line in diff_text.splitlines() if line.startswith("-") and not line.startswith("---"))
+
+    report = {
+        "verdict": verdict,
+        "base_branch": base,
+        "changed_files_count": len(changed_files),
+        "changed_files": changed_files,
+        "lines_added": added_lines,
+        "lines_deleted": deleted_lines,
+        "secret_findings": secret_findings,
+        "ast_findings": ast_findings,
+        "complexity_warnings": complexity_warnings,
+        "test_parity_warning": test_parity_warning
+    }
+    return report
+
+
+def format_pr_review_markdown(report: Dict[str, Any]) -> str:
+    """Formats PR audit report as clean GitHub Flavored Markdown."""
+    verdict = report["verdict"]
+    badge = "🟢 **APPROVED**" if verdict == "APPROVED" else ("🟡 **WARNINGS**" if verdict == "WARNINGS" else "🔴 **BLOCKED**")
+
+    lines = [
+        "## 🛡️ Git-Oops Pre-PR Gatekeeper Audit Report",
+        "",
+        f"**Verdict**: {badge} (Base branch: `{report['base_branch']}`)",
+        f"**Diff Churn**: `{report['changed_files_count']}` files modified (+{report['lines_added']} / -{report['lines_deleted']} lines)",
+        ""
+    ]
+
+    if report["secret_findings"]:
+        lines.append("### 🚨 Critical Secret Leaks Detected")
+        for s in report["secret_findings"]:
+            lines.append(f"- **{s['label']}** at line {s['line']}: `{s['snippet']}`")
+        lines.append("")
+
+    if report["ast_findings"]:
+        lines.append("### ⚠️ AST Security & CodeQL Violations")
+        for a in report["ast_findings"]:
+            lines.append(f"- **[{a.get('severity', 'HIGH')}] {a.get('rule', 'AST')}** in `{a.get('file')}:{a.get('line')}`: {a.get('msg')}")
+        lines.append("")
+
+    if report["test_parity_warning"]:
+        lines.append("### 🧪 Test Parity Notice")
+        lines.append(f"- ⚠️ {report['test_parity_warning']}")
+        lines.append("")
+
+    if report["complexity_warnings"]:
+        lines.append("### 📈 Complexity Drift")
+        for c in report["complexity_warnings"]:
+            lines.append(f"- `{c['file']}`: {c['details']}")
+        lines.append("")
+
+    if verdict == "APPROVED":
+        lines.append("✨ All L3 security checks passed cleanly. Ready for production merge!")
+
+    return "\n".join(lines)

src/rules.py

@@ -0,0 +1,291 @@
+"""
+Git-Oops Dynamic OTA Security Rules Engine
+Decouples security signatures from Python source code.
+Automatically syncs latest CVEs, malicious packages, and secret regex patterns
+in the background when internet is available, with pure offline baseline fallback.
+"""
+
+import os
+import sys
+import json
+import time
+import urllib.request
+import urllib.error
+import threading
+from pathlib import Path
+from typing import Dict, Any, List, Tuple, Optional
+
+RULES_DIR = Path.home() / ".git_oops" / "rules"
+RULES_FILE = RULES_DIR / "security_rules.json"
+RULES_CACHE_META = RULES_DIR / "rules_meta.json"
+
+# 24-hour cache TTL
+SYNC_INTERVAL_SECONDS = 86400
+
+# Built-in offline baseline rules (Hardened fallback - zero network required)
+OFFLINE_BASELINE_RULES: Dict[str, Any] = {
+    "version": "1.0.0-baseline",
+    "last_updated": 1731550000,
+    "secret_patterns": [
+        {"pattern": r"(?i)(?:api[_-]?key|secret|password|passwd|auth[_-]?token)\s*[:=]\s*['\"]([a-zA-Z0-9_\-\.]{16,})['\"]", "label": "Exposed Secret Literal", "severity": "CRITICAL"},
+        {"pattern": r"(?i)sk-[a-zA-Z0-9]{32,}", "label": "OpenAI API Key", "severity": "CRITICAL"},
+        {"pattern": r"(?i)AKIA[0-9A-Z]{16}", "label": "AWS Access Key ID", "severity": "CRITICAL"},
+        {"pattern": r"(?i)ghp_[a-zA-Z0-9]{36}", "label": "GitHub Personal Access Token", "severity": "CRITICAL"},
+        {"pattern": r"(?i)xox[baprs]-[0-9a-zA-Z]{10,48}", "label": "Slack OAuth Token", "severity": "CRITICAL"},
+        {"pattern": r"-----BEGIN (?:RSA|OPENSSH|DSA|EC|PGP)? PRIVATE KEY-----", "label": "Cryptographic Private Key", "severity": "CRITICAL"}
+    ],
+    "malicious_packages": [
+        "reqeusts", "colorma", "djagno", "falsk", "beautiflsoup",
+        "cryptograpy", "numpay", "scipyy", "pandass", "tensoflow",
+        "pytocrh", "opencvv", "selenuim", "urlib3", "certifii"
+    ],
+    "cwe_thresholds": {
+        "max_cyclomatic_complexity": 10,
+        "shannon_entropy_threshold": 4.6
+    }
+}
+
+# Upstream OTA rule endpoints (Primary GitHub Raw feed + fallback)
+OTA_FEED_URLS = [
+    "https://raw.githubusercontent.com/Hao610/git-oops/main/rules/security_rules.json",
+    "https://api.github.com/repos/Hao610/git-oops/contents/rules/security_rules.json"
+]
+
+
+# ---------------------------------------------------------------------------
+# Additive User-Custom Policy Support (Immutable Baseline + Additive Custom)
+# ---------------------------------------------------------------------------
+
+CUSTOM_GLOBAL_RULES_FILE = RULES_DIR / "custom_rules.json"
+
+
+def find_repo_custom_rules_file() -> Optional[Path]:
+    """Finds repo-level custom rules file (.oops/rules.json or .oops-rules.json)."""
+    cwd = Path.cwd()
+    for cand in (cwd / ".oops" / "rules.json", cwd / ".oops-rules.json", cwd / "oops-rules.json"):
+        if cand.exists():
+            return cand
+    return None
+
+
+def load_user_custom_rules() -> Dict[str, Any]:
+    """
+    Loads user-defined custom security rules from:
+    1. Repo root (.oops/rules.json or .oops-rules.json)
+    2. Global custom rules (~/.git_oops/rules/custom_rules.json)
+    Users can ONLY ADD custom rules; they CANNOT delete or bypass system baselines.
+    """
+    custom = {
+        "extra_secret_patterns": [],
+        "extra_banned_packages": [],
+        "extra_forbidden_calls": []
+    }
+
+    # 1. Global custom rules
+    if CUSTOM_GLOBAL_RULES_FILE.exists():
+        try:
+            with open(CUSTOM_GLOBAL_RULES_FILE, "r", encoding="utf-8") as f:
+                data = json.load(f)
+                custom["extra_secret_patterns"].extend(data.get("extra_secret_patterns", []))
+                custom["extra_banned_packages"].extend(data.get("extra_banned_packages", []))
+                custom["extra_forbidden_calls"].extend(data.get("extra_forbidden_calls", []))
+        except Exception:
+            pass
+
+    # 2. Repo-level custom rules (takes precedence for repo-specific policies)
+    repo_rules = find_repo_custom_rules_file()
+    if repo_rules:
+        try:
+            with open(repo_rules, "r", encoding="utf-8") as f:
+                data = json.load(f)
+                custom["extra_secret_patterns"].extend(data.get("extra_secret_patterns", []))
+                custom["extra_banned_packages"].extend(data.get("extra_banned_packages", []))
+                custom["extra_forbidden_calls"].extend(data.get("extra_forbidden_calls", []))
+        except Exception:
+            pass
+
+    return custom
+
+
+def is_valid_regex(pattern_str: str) -> bool:
+    """Checks if regex compiles without syntax error."""
+    import re
+    if not pattern_str or not isinstance(pattern_str, str):
+        return False
+    try:
+        re.compile(pattern_str)
+        return True
+    except Exception:
+        return False
+
+
+def load_security_rules() -> Dict[str, Any]:
+    """
+    Loads merged security rules with cryptographic integrity and tamper resistance:
+    [Hardcoded Immutable Baseline] + [OTA Live Dynamic Signatures] + [User Custom Additions]
+    Baseline checks CANNOT be removed, overridden, or hollowed out by tampering.
+    """
+    # 1. Start with immutable baseline constant directly from Python memory
+    merged = json.loads(json.dumps(OFFLINE_BASELINE_RULES))
+
+    # 2. Layer OTA dynamic signatures if available (with tamper & corruption check)
+    tamper_detected = False
+    try:
+        if RULES_FILE.exists():
+            with open(RULES_FILE, "r", encoding="utf-8") as f:
+                ota_data = json.load(f)
+                if isinstance(ota_data, dict):
+                    # Union malicious packages
+                    incoming_pkgs = ota_data.get("malicious_packages", [])
+                    if isinstance(incoming_pkgs, list):
+                        pkgs = set(merged.get("malicious_packages", [])) | set(incoming_pkgs)
+                        merged["malicious_packages"] = sorted(list(pkgs))
+
+                    # Union secret patterns (discarding any invalid or tampered regexes)
+                    curr_patts = {p["pattern"]: p for p in merged.get("secret_patterns", [])}
+                    for p in ota_data.get("secret_patterns", []):
+                        if isinstance(p, dict) and is_valid_regex(p.get("pattern", "")):
+                            curr_patts[p["pattern"]] = p
+                    merged["secret_patterns"] = list(curr_patts.values())
+        else:
+            tamper_detected = True
+    except Exception:
+        tamper_detected = True
+
+    # 3. Layer User's Custom Additions (Additive-Only)
+    user_custom = load_user_custom_rules()
+    if user_custom["extra_banned_packages"]:
+        merged["malicious_packages"] = sorted(list(set(merged.get("malicious_packages", [])) | set(user_custom["extra_banned_packages"])))
+
+    if user_custom["extra_secret_patterns"]:
+        curr_patts = {p["pattern"]: p for p in merged.get("secret_patterns", [])}
+        for p in user_custom["extra_secret_patterns"]:
+            if isinstance(p, dict) and is_valid_regex(p.get("pattern", "")):
+                curr_patts[p["pattern"]] = p
+        merged["secret_patterns"] = list(curr_patts.values())
+
+    merged["custom_forbidden_calls"] = user_custom.get("extra_forbidden_calls", [])
+
+    # 4. Anti-Tamper Invariant Check:
+    # Baseline packages and secret patterns must be strictly preserved.
+    # If file was deleted or corrupted, instantly self-heal and re-serialize to disk.
+    baseline_pkgs = set(OFFLINE_BASELINE_RULES["malicious_packages"])
+    if not baseline_pkgs.issubset(set(merged["malicious_packages"])) or tamper_detected or not RULES_FILE.exists():
+        save_security_rules(merged)
+
+    return merged
+
+
+def save_security_rules(rules: Dict[str, Any]) -> bool:
+    """Saves updated dynamic security rules to ~/.git_oops/rules/security_rules.json."""
+    try:
+        RULES_DIR.mkdir(parents=True, exist_ok=True)
+        with open(RULES_FILE, "w", encoding="utf-8") as f:
+            json.dump(rules, f, indent=2, ensure_ascii=False)
+        return True
+    except Exception:
+        return False
+
+
+def is_sync_due() -> bool:
+    """Checks if 24 hours have elapsed since the last OTA check."""
+    try:
+        if not RULES_CACHE_META.exists():
+            return True
+        with open(RULES_CACHE_META, "r", encoding="utf-8") as f:
+            meta = json.load(f)
+            last_sync = meta.get("last_sync_timestamp", 0)
+            return (time.time() - last_sync) > SYNC_INTERVAL_SECONDS
+    except Exception:
+        return True
+
+
+def record_sync_timestamp(status: str = "success"):
+    """Records the timestamp of the last OTA rule check."""
+    try:
+        RULES_DIR.mkdir(parents=True, exist_ok=True)
+        with open(RULES_CACHE_META, "w", encoding="utf-8") as f:
+            json.dump({"last_sync_timestamp": time.time(), "status": status}, f)
+    except Exception:
+        pass
+
+
+def fetch_remote_rules(timeout: float = 2.0) -> Tuple[bool, Dict[str, Any]]:
+    """
+    Attempts to download latest dynamic security rules from remote OTA feed.
+    Times out in 2.0 seconds so it never hangs.
+    """
+    for url in OTA_FEED_URLS:
+        try:
+            req = urllib.request.Request(
+                url,
+                headers={"User-Agent": "git-oops-ota-client/1.0.0"}
+            )
+            with urllib.request.urlopen(req, timeout=timeout) as response:
+                if response.status == 200:
+                    raw_data = response.read().decode("utf-8")
+                    parsed = json.loads(raw_data)
+                    # If returned from GitHub API base64
+                    if isinstance(parsed, dict) and "content" in parsed and "encoding" in parsed:
+                        import base64
+                        decoded = base64.b64decode(parsed["content"]).decode("utf-8")
+                        parsed = json.loads(decoded)
+                    if isinstance(parsed, dict) and "secret_patterns" in parsed:
+                        return True, parsed
+        except Exception:
+            continue
+    return False, {}
+
+
+def sync_security_rules_foreground(force: bool = False) -> Tuple[bool, str]:
+    """
+    Synchronous rule update function.
+    Downloads, validates, merges and saves updated security definitions.
+    """
+    if not force and not is_sync_due():
+        return True, "Dynamic security rules are up to date (cached within 24h)."
+
+    ok, remote_rules = fetch_remote_rules(timeout=2.5)
+    record_sync_timestamp(status="success" if ok else "offline")
+
+    if not ok:
+        return False, "Offline or remote rules feed unreachable. Using verified local baseline."
+
+    # Merge remote rules with local rules safely
+    current_rules = load_security_rules()
+
+    # Merge malicious packages (deduplicated set)
+    current_pkgs = set(current_rules.get("malicious_packages", []))
+    remote_pkgs = set(remote_rules.get("malicious_packages", []))
+    merged_pkgs = sorted(list(current_pkgs | remote_pkgs))
+
+    # Merge secret patterns
+    curr_patterns = {p["pattern"]: p for p in current_rules.get("secret_patterns", [])}
+    for p in remote_rules.get("secret_patterns", []):
+        curr_patterns[p["pattern"]] = p
+
+    current_rules["malicious_packages"] = merged_pkgs
+    current_rules["secret_patterns"] = list(curr_patterns.values())
+    current_rules["version"] = remote_rules.get("version", "1.0.0-ota")
+    current_rules["last_updated"] = int(time.time())
+
+    save_security_rules(current_rules)
+    return True, f"Successfully synced security rules (v{current_rules['version']}): {len(merged_pkgs)} malicious packages, {len(current_rules['secret_patterns'])} secret patterns active."
+
+
+def trigger_ota_update_background():
+    """
+    Fires a non-blocking background daemon thread to silently refresh security rules.
+    Takes 0ms on the calling thread.
+    """
+    if not is_sync_due():
+        return
+
+    def _worker():
+        try:
+            sync_security_rules_foreground(force=False)
+        except Exception:
+            pass
+
+    t = threading.Thread(target=_worker, daemon=True)
+    t.start()