Add update checker management command and documentation

api_app/core/tasks.py

@@ -0,0 +1,12 @@
+from celery import shared_task
+
+from api_app.core.update_checker import check_for_update
+
+
+@shared_task
+def scheduled_update_check():
+    """
+    Periodic task to check for IntelOwl updates.
+    Intended to be triggered via celery beat.
+    """
+    check_for_update()

api_app/core/update_checker.py

@@ -0,0 +1,161 @@
+import logging
+from typing import Optional, Tuple
+
+import requests
+from django.conf import settings
+from django.db import IntegrityError, transaction
+from django.utils.timezone import now
+
+from api_app.models import UpdateCheckStatus
+
+logger = logging.getLogger(__name__)
+
+try:
+    from api_app.user_events_manager.queryset import UserEventQuerySet
+except Exception:
+    UserEventQuerySet = None
+
+try:
+    from certego_saas_notifications.models import Notification
+except Exception:
+    Notification = None
+
+STORED_TAG_MAX_LEN = UpdateCheckStatus._meta.get_field("latest_version").max_length
+
+
+def normalize_version(v: str) -> Tuple[int, ...]:
+    parts: list[int] = []
+    for x in str(v).split("."):
+        if x.isdigit():
+            parts.append(int(x))
+        else:
+            break
+    return tuple(parts)
+
+
+def fetch_latest_version() -> Tuple[Optional[str], Optional[str]]:
+    url = getattr(settings, "UPDATE_CHECK_URL", None)
+    if not url:
+        return None, "UPDATE_CHECK_URL not configured"
+
+    try:
+        resp = requests.get(url, headers={"User-Agent": "IntelOwl-Update-Checker"}, timeout=5)
+    except requests.RequestException as exc:
+        logger.error("Update check HTTP request failed: %s", exc)
+        return None, "Failed to fetch release information"
+
+    try:
+        resp.raise_for_status()
+    except requests.RequestException as exc:
+        logger.error("Update check HTTP error: %s", exc)
+        return None, "Update server returned an error"
+
+    try:
+        data = resp.json()
+    except ValueError:
+        logger.error("Invalid JSON from update server")
+        return None, "Invalid response from update server"
+
+    tag = data.get("tag_name")
+    if not tag:
+        logger.warning("Update response missing tag_name")
+        return None, "Release response missing tag_name"
+
+    return str(tag).lstrip("v"), None
+
+
+def _notify_admins(title: str, message: str) -> None:
+    try:
+        if UserEventQuerySet is not None:
+            UserEventQuerySet.notify_admins(title=title, message=message, persistent=True, severity="warning")
+            return
+        if Notification is not None:
+            Notification.objects.create(
+                title=title,
+                description=message,
+                level="info",
+                for_admins=True,
+            )
+            return
+        logger.info("No notification backend available; skipping admin notification")
+    except Exception:
+        logger.exception("Failed to send admin notification")
+
+
+def check_for_update() -> Tuple[bool, str]:
+    current_version = getattr(settings, "INTEL_OWL_VERSION", None)
+    if not current_version:
+        return False, "INTEL_OWL_VERSION setting missing"
+
+    latest, err = fetch_latest_version()
+    if err:
+        return False, err
+
+    latest_full = latest or ""
+    stored_latest = latest_full[:STORED_TAG_MAX_LEN] if latest_full else None
+    current_str = str(current_version).lstrip("v")
+
+    current_v = normalize_version(current_str)
+    latest_v = normalize_version(latest_full)
+
+    try:
+        with transaction.atomic():
+            try:
+                state, _ = UpdateCheckStatus.objects.select_for_update().get_or_create(pk=1)
+            except IntegrityError:
+                state = UpdateCheckStatus.objects.select_for_update().get(pk=1)
+
+            state.last_checked_at = now()
+
+            if not current_v or not latest_v:
+                if latest_full != current_str:
+                    message = f"Update available: {latest_full} (current: {current_str})"
+                else:
+                    message = f"IntelOwl version up to date ({current_str})"
+
+                state.save(update_fields=["last_checked_at"])
+                return True, message
+
+            if latest_v > current_v:
+                message = f"New IntelOwl version available: {latest_full} (current: {current_str})"
+
+                should_notify = (state.latest_version != stored_latest) or (not state.notified)
+                if should_notify:
+                    state.latest_version = stored_latest
+                    state.notified = True
+                    state.save(update_fields=["latest_version", "notified", "last_checked_at"])
+
+                    def _send_notification():
+                        _notify_admins(
+                            "New IntelOwl version available",
+                            f"Version {latest_full} is available (current: {current_str})",
+                        )
+
+                    if getattr(settings, "TESTING", False):
+                        _send_notification()
+                    else:
+                        transaction.on_commit(_send_notification)
+
+                    logger.info(
+                        "New IntelOwl version available (notified scheduled): %s (current: %s)",
+                        latest_full,
+                        current_str,
+                    )
+                else:
+                    state.save(update_fields=["last_checked_at"])
+
+                return True, message
+
+            if latest_v < current_v:
+                state.save(update_fields=["last_checked_at"])
+                return (
+                    True,
+                    f"Local version ahead of release: {current_str} > {latest_full}",
+                )
+
+            state.save(update_fields=["last_checked_at"])
+            return True, f"IntelOwl version up to date ({current_str})"
+
+    except Exception:
+        logger.exception("Unexpected error during update check (db/transaction)")
+        return False, "Unexpected error during update check. See logs for details."

api_app/management/commands/check_updates.py

@@ -0,0 +1,24 @@
+import logging
+
+from django.core.management.base import BaseCommand, CommandError
+
+from api_app.core.update_checker import check_for_update
+
+logger = logging.getLogger(__name__)
+
+
+class Command(BaseCommand):
+    help = "Check for newer IntelOwl releases"
+
+    def handle(self, *args, **options):
+        try:
+            success, message = check_for_update()
+        except Exception:
+            logger.exception("Unexpected error during update check")
+            raise CommandError("Unexpected error during update check. See logs for details.")
+
+        if not success:
+            logger.info("Update check failed: %s", message)
+            raise CommandError(message)
+
+        self.stdout.write(self.style.SUCCESS(message))

api_app/migrations/0072_update_check_system.py

@@ -0,0 +1,95 @@
+import json
+
+import django.utils.timezone
+from django.db import migrations, models
+
+
+def create_weekly_update_task(apps, schema_editor):
+    IntervalSchedule = apps.get_model("django_celery_beat", "IntervalSchedule")
+    PeriodicTask = apps.get_model("django_celery_beat", "PeriodicTask")
+
+    schedule, _ = IntervalSchedule.objects.get_or_create(
+        every=7,
+        period="days",
+    )
+
+    PeriodicTask.objects.update_or_create(
+        name="Weekly IntelOwl Update Check",
+        defaults={
+            "interval": schedule,
+            "task": "api_app.core.tasks.scheduled_update_check",
+            "kwargs": json.dumps({}),
+            "enabled": True,
+        },
+    )
+
+
+def remove_weekly_update_task(apps, schema_editor):
+    PeriodicTask = apps.get_model("django_celery_beat", "PeriodicTask")
+    PeriodicTask.objects.filter(name="Weekly IntelOwl Update Check").delete()
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("api_app", "0071_delete_last_elastic_report"),
+        ("django_celery_beat", "__latest__"),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="UpdateCheckStatus",
+            fields=[
+                (
+                    "id",
+                    models.BigAutoField(
+                        auto_created=True,
+                        primary_key=True,
+                        serialize=False,
+                        verbose_name="ID",
+                    ),
+                ),
+                (
+                    "latest_version",
+                    models.CharField(
+                        max_length=20,
+                        null=True,
+                        blank=True,
+                        help_text="Latest version detected during update check",
+                    ),
+                ),
+                (
+                    "notified",
+                    models.BooleanField(
+                        default=False,
+                        help_text="Whether notification has already been sent",
+                    ),
+                ),
+                (
+                    "last_checked_at",
+                    models.DateTimeField(
+                        null=True,
+                        blank=True,
+                        help_text="Last time update check ran",
+                    ),
+                ),
+                (
+                    "created_at",
+                    models.DateTimeField(
+                        default=django.utils.timezone.now,
+                        editable=False,
+                    ),
+                ),
+                (
+                    "updated_at",
+                    models.DateTimeField(auto_now=True),
+                ),
+            ],
+            options={
+                "verbose_name": "Update check info",
+            },
+        ),
+        migrations.RunPython(
+            create_weekly_update_task,
+            remove_weekly_update_task,
+        ),
+    ]

api_app/models.py

@@ -70,6 +70,39 @@
 logger = logging.getLogger(__name__)
 
 
+class UpdateCheckStatus(models.Model):
+    """
+    Stores global state for IntelOwl update checks.
+    This model is intended to be used as a singleton (accessed via get_or_create(pk=1)).
+    Ensures that update notifications are emitted only once per version.
+    """
+
+    latest_version = models.CharField(
+        max_length=20,
+        null=True,
+        blank=True,
+        help_text="Latest version detected during update check",
+    )
+    notified = models.BooleanField(
+        default=False,
+        help_text="Whether a notification has already been sent for this version",
+    )
+    last_checked_at = models.DateTimeField(
+        null=True,
+        blank=True,
+        help_text="Last time the update check was executed",
+    )
+
+    created_at = models.DateTimeField(default=now, editable=False)
+    updated_at = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        verbose_name = "Update check info"
+
+    def __str__(self) -> str:
+        return f"Update check info (latest: {self.latest_version or 'unknown'})"
+
+
 class PythonModule(models.Model):
     """
     Represents a Python module model used in the application.

api_app/serializers/system.py

@@ -0,0 +1,33 @@
+from django.conf import settings
+from rest_framework import serializers
+
+from api_app.core.update_checker import normalize_version
+from api_app.models import UpdateCheckStatus
+
+
+class SystemUpdateStatusSerializer(serializers.Serializer):
+    current_version = serializers.CharField()
+    latest_version = serializers.CharField(allow_null=True)
+    update_available = serializers.BooleanField()
+    last_checked_at = serializers.DateTimeField(allow_null=True)
+    notified = serializers.BooleanField()
+
+    @staticmethod
+    def from_state(state: UpdateCheckStatus | None):
+        current_version = str(getattr(settings, "INTEL_OWL_VERSION", "")).lstrip("v")
+
+        latest_version = state.latest_version if state else None
+        last_checked_at = state.last_checked_at if state else None
+        notified = state.notified if state else False
+
+        update_available = False
+        if latest_version and normalize_version(latest_version) > normalize_version(current_version):
+            update_available = True
+
+        return {
+            "current_version": current_version,
+            "latest_version": latest_version,
+            "update_available": update_available,
+            "last_checked_at": last_checked_at,
+            "notified": notified,
+        }

api_app/urls.py

@@ -17,6 +17,7 @@
     ask_analysis_availability,
     ask_multi_analysis_availability,
     plugin_state_viewer,
+    system_update_check_view,
 )
 
 # Routers provide an easy way of automatically determining the URL conf.
@@ -30,6 +31,7 @@
 urlpatterns = [
     # standalone endpoints
     path("ask_analysis_availability", ask_analysis_availability),
+    path("system/update-check/", system_update_check_view, name="system-update-check"),
     path("ask_multi_analysis_availability", ask_multi_analysis_availability),
     path("analyze_file", analyze_file),
     path("analyze_multiple_files", analyze_multiple_files, name="analyze_multiple_files"),