Merge branch 'main' into fix/dumpsys-battery-daily-order

* intrusion_logs: alert on certificate events and run heuristics without IOCs

SecurityEvent.check_indicators() returned early when no indicator set was
loaded, so none of its heuristic alerts (key integrity, wipe failure, crypto
self-test, certificate events) reached the alert store on a default run. On
top of that, cert_authority_installed and cert_validation_failure only emitted
log.warning and never alerted even when indicators were present.

Run the heuristic alerts independently of the loaded indicators (matching the
accessibility fix in #807) and surface the two certificate events through the
alert store at medium severity. A successfully installed root CA and a
certificate validation failure are interception/MITM-relevant signals that
belong in the alert report.

Adds regression tests for both certificate events and for heuristics firing
with no indicators loaded.

* intrusion_logs: gate certificate authority install alert on success

Failed install attempts log a warning instead of raising the
"Certificate authority installed" alert. Add a regression test
covering success encoded as bool and as int.

---------

Co-authored-by: John Kavanagh <668351+kavanista@users.noreply.github.com>
Co-authored-by: besendorf <janik@besendorf.org>

.github/workflows/mypy.yml

@@ -1,5 +1,8 @@
 name: Mypy
-on: workflow_dispatch
+on:
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
 
 jobs:
   mypy_py3:

docs/development.md

@@ -21,6 +21,24 @@ make check
 
 Run these tests before making new commits or opening pull requests.
 
+## Module dependencies
+
+Modules can require other modules to run first by declaring their classes in
+`dependencies`. The command runner uses a stable topological ordering, so the
+existing module list order is preserved wherever dependency constraints allow.
+
+```python
+class DependentModule(MVTModule):
+    dependencies = (PrerequisiteModule,)
+
+    def run(self):
+        prerequisite_results = self.get_dependency_results(PrerequisiteModule)
+```
+
+Selecting a single module also runs its transitive dependencies. If a dependency
+is unavailable or the dependency graph contains a cycle, the command logs a
+warning and does not run any modules.
+
 ## Profiling
 
 Some MVT modules extract and process significant amounts of data during the analysis process or while checking results against known indicators. Care must be

src/mvt/android/artifacts/dumpsys_battery_daily.py

@@ -50,13 +50,11 @@ class DumpsysBatteryDailyArtifact(AndroidArtifact):
     def parse(self, output: str) -> None:
         daily = None
         daily_updates: list[dict[str, Any]] = []
-        package_versions: dict[
-            str, str
-        ] = {}  # Track package versions to detect downgrades
+        records: list[dict[str, Any]] = []
         for line in output.splitlines():
             if line.startswith("  Daily from "):
                 if len(daily_updates) > 0:
-                    self.results.extend(daily_updates)
+                    records.extend(daily_updates)
                     daily_updates = []
 
                 timeframe = line[13:].strip()
@@ -89,35 +87,53 @@ class DumpsysBatteryDailyArtifact(AndroidArtifact):
                     "vers": vers_nr,
                 }
 
-                # Check for uninstall (version 0)
-                if vers_nr == "0":
-                    self.alertstore.medium(
-                        f"Detected uninstall of package {package_name} (vers 0)",
-                        daily["from"],
-                        update_record,
-                    )
-                # Check for downgrade
-                elif package_name in package_versions:
-                    try:
-                        current_vers = int(vers_nr)
-                        previous_vers = int(package_versions[package_name])
-                        if current_vers < previous_vers:
-                            update_record["action"] = "downgrade"
-                            update_record["previous_vers"] = str(previous_vers)
-                            self.alertstore.medium(
-                                f"Detected downgrade of package {package_name} "
-                                f"from vers {previous_vers} to vers {current_vers}",
-                                daily["from"],
-                                update_record,
-                            )
-                    except ValueError:
-                        # If version numbers aren't integers, skip comparison
-                        pass
-
-                # Update tracking dictionary
-                package_versions[package_name] = vers_nr
-
                 daily_updates.append(update_record)
 
         if len(daily_updates) > 0:
-            self.results.extend(daily_updates)
+            records.extend(daily_updates)
+
+        self._detect_uninstalls_and_downgrades(records)
+        self.results.extend(records)
+
+    def _detect_uninstalls_and_downgrades(
+        self, records: list[dict[str, Any]]
+    ) -> None:
+        package_versions: dict[str, int] = {}
+
+        for record in sorted(
+            records,
+            key=lambda record: (
+                record["from"],
+                record["to"],
+                record["package_name"],
+            ),
+        ):
+            package_name = record["package_name"]
+            vers_nr = record["vers"]
+
+            if vers_nr == "0":
+                self.alertstore.medium(
+                    f"Detected uninstall of package {package_name} (vers 0)",
+                    record["from"],
+                    record,
+                )
+                package_versions.pop(package_name, None)
+                continue
+
+            try:
+                current_vers = int(vers_nr)
+            except ValueError:
+                continue
+
+            previous_vers = package_versions.get(package_name)
+            if previous_vers is not None and current_vers < previous_vers:
+                record["action"] = "downgrade"
+                record["previous_vers"] = str(previous_vers)
+                self.alertstore.medium(
+                    f"Detected downgrade of package {package_name} "
+                    f"from vers {previous_vers} to vers {current_vers}",
+                    record["from"],
+                    record,
+                )
+
+            package_versions[package_name] = current_vers

src/mvt/android/modules/intrusion_logs/security_event.py

@@ -264,6 +264,7 @@ SECURITY_EVENT_TAGS = {
 }
 
 SECURITY_EVENT_METADATA_KEYS = {
+    "event_id",
     "event_time",
     "event_type",
     "timestamp",
@@ -302,10 +303,15 @@ class SecurityEvent(IntrusionLogsModule):
 
     def check_indicators(self) -> None:
         """Check security events against indicators of compromise."""
-        if not self.indicators:
-            return
-
         for result in self.results:
+            # Heuristic alerts are intrinsic to the event, so they run even
+            # when no indicator set is loaded.
+            self._check_security_heuristics(result)
+
+            # The remaining checks match events against loaded indicators.
+            if not self.indicators:
+                continue
+
             # Check app process start events for suspicious package names
             if "app_process_start" in result:
                 process_info = result["app_process_start"]
@@ -389,60 +395,73 @@ class SecurityEvent(IntrusionLogsModule):
                                 matched_indicator=ioc.ioc,
                             )
 
-            # Flag failed cryptographic operations as potentially suspicious
-            if "key_generated" in result:
-                if not result["key_generated"].get("success", True):
-                    self.log.warning(
-                        "Failed key generation detected for key_id: %s",
-                        result["key_generated"].get("key_id", "unknown"),
-                    )
-
-            # Flag certificate validation failures
-            if "cert_validation_failure" in result:
+    def _check_security_heuristics(self, result: dict) -> None:
+        """Raise alerts for events that are intrinsically suspicious,
+        independent of any loaded indicators."""
+        # Flag failed cryptographic operations as potentially suspicious
+        if "key_generated" in result:
+            if not result["key_generated"].get("success", True):
                 self.log.warning(
-                    "Certificate validation failure detected: %s",
-                    result.get("cert_validation_failure"),
+                    "Failed key generation detected for key_id: %s",
+                    result["key_generated"].get("key_id", "unknown"),
                 )
 
-            # Flag key integrity violations
-            if "key_integrity_violation" in result:
+        # Flag certificate validation failures
+        if "cert_validation_failure" in result:
+            self.alertstore.medium(
+                "Certificate validation failure detected: "
+                f"{result.get('cert_validation_failure')}",
+                result.get("timestamp") or "",
+                result,
+            )
+
+        # Flag key integrity violations
+        if "key_integrity_violation" in result:
+            self.alertstore.medium(
+                f"Key integrity violation detected: {result.get('key_integrity_violation')}",
+                result.get("timestamp") or "",
+                result,
+            )
+
+        # Flag successful certificate authority installations (potential
+        # MITM); a missing success field is treated as installed
+        if "cert_authority_installed" in result:
+            cert_info = result["cert_authority_installed"]
+            if cert_info.get("success", True):
                 self.alertstore.medium(
-                    f"Key integrity violation detected: {result.get('key_integrity_violation')}",
+                    "Certificate authority installed: "
+                    f"{cert_info.get('subject', 'unknown')}",
                     result.get("timestamp") or "",
                     result,
                 )
-
-            # Flag certificate authority installations (potential MITM)
-            if "cert_authority_installed" in result:
-                cert_info = result["cert_authority_installed"]
+            else:
                 self.log.warning(
-                    "Certificate authority installed: %s (success: %s)",
+                    "Failed certificate authority install attempt: %s",
                     cert_info.get("subject", "unknown"),
-                    cert_info.get("success", "unknown"),
                 )
 
-            # Flag wipe failures
-            if "wipe_failure" in result:
+        # Flag wipe failures
+        if "wipe_failure" in result:
+            self.alertstore.medium(
+                "Device wipe failure detected",
+                result.get("timestamp") or "",
+                result,
+            )
+
+        # Flag crypto self test failures
+        if "crypto_self_test_completed" in result:
+            test_result = result["crypto_self_test_completed"]
+            if isinstance(test_result, dict):
+                success = test_result.get("success", True)
+            else:
+                success = test_result == 1
+            if not success:
                 self.alertstore.medium(
-                    "Device wipe failure detected",
+                    "Cryptographic self test failed",
                     result.get("timestamp") or "",
                     result,
                 )
 
-            # Flag crypto self test failures
-            if "crypto_self_test_completed" in result:
-                test_result = result["crypto_self_test_completed"]
-                if isinstance(test_result, dict):
-                    success = test_result.get("success", True)
-                else:
-                    success = test_result == 1
-                if not success:
-                    self.alertstore.medium(
-                        "Cryptographic self test failed",
-                        result.get("timestamp") or "",
-                        result,
-                    )
-
     def serialize(self, record: dict) -> Union[dict, list]:
         """Serialize a security event record for timeline output."""
         # Determine the event sub-type

src/mvt/common/command.py

@@ -8,6 +8,7 @@ import logging
 import os
 import sys
 from datetime import datetime
+from heapq import heappop, heappush
 from typing import Any, Optional
 
 from rich.console import Console
@@ -18,6 +19,7 @@ from .alerts import AlertLevel, AlertStore
 from .config import settings
 from .indicators import Indicators
 from .module import EncryptedBackupError, MVTModule, run_module, save_timeline
+from .module_types import ModuleTimeline
 from .utils import (
     CustomJSONEncoder,
     convert_datetime_to_iso,
@@ -44,7 +46,7 @@ class Command:
         disable_indicator_check: bool = False,
     ) -> None:
         self.name = ""
-        self.modules: list[Any] = []
+        self.modules: list[type[MVTModule]] = []
 
         self.target_path = target_path
         self.results_path = results_path
@@ -63,10 +65,10 @@ class Command:
 
         # This list will contain all executed modules.
         # We can use this to reference e.g. self.executed[0].results.
-        self.executed: list[Any] = []
+        self.executed: list[MVTModule] = []
         self.hashes = hashes
         self.hash_values: list[dict[str, Any]] = []
-        self.timeline: list[dict[str, Any]] = []
+        self.timeline: ModuleTimeline = []
 
         # Load IOCs
         self._create_storage()
@@ -258,20 +260,84 @@ class Command:
         console.print("")
         console.print(panel)
 
+    def _ordered_modules(self) -> Optional[list[type[MVTModule]]]:
+        """Return enabled modules in stable topological order."""
+        module_indexes = {module: index for index, module in enumerate(self.modules)}
+
+        if self.module_name:
+            selected = [
+                module for module in self.modules if module.__name__ == self.module_name
+            ]
+        else:
+            selected = [module for module in self.modules if module.enabled]
+
+        required = set(selected)
+        pending = list(selected)
+        while pending:
+            module = pending.pop()
+            for dependency in module.dependencies:
+                if dependency not in module_indexes:
+                    self.log.warning(
+                        "Module %s depends on unavailable module %s. "
+                        "No modules will be run.",
+                        module.__name__,
+                        dependency.__name__,
+                    )
+                    return None
+                if dependency not in required:
+                    required.add(dependency)
+                    pending.append(dependency)
+
+        dependents: dict[type[MVTModule], list[type[MVTModule]]] = {
+            module: [] for module in required
+        }
+        indegree = {module: 0 for module in required}
+        for module in required:
+            for dependency in module.dependencies:
+                if dependency not in required:
+                    continue
+                dependents[dependency].append(module)
+                indegree[module] += 1
+
+        ready: list[tuple[int, type[MVTModule]]] = []
+        for module, count in indegree.items():
+            if count == 0:
+                heappush(ready, (module_indexes[module], module))
+
+        ordered = []
+        while ready:
+            _, module = heappop(ready)
+            ordered.append(module)
+            for dependent in dependents[module]:
+                indegree[dependent] -= 1
+                if indegree[dependent] == 0:
+                    heappush(ready, (module_indexes[dependent], dependent))
+
+        if len(ordered) != len(required):
+            cyclic_modules = sorted(
+                (module.__name__ for module, count in indegree.items() if count > 0)
+            )
+            self.log.warning(
+                "Circular module dependency detected involving: %s. "
+                "No modules will be run.",
+                ", ".join(cyclic_modules),
+            )
+            return None
+
+        return ordered
+
     def run(self) -> None:
+        ordered_modules = self._ordered_modules()
+        if ordered_modules is None:
+            return
+
         try:
             self.init()
         except NotImplementedError:
             pass
 
-        for module in self.modules:
-            if self.module_name and module.__name__ != self.module_name:
-                continue
-
-            if not module.enabled and not (
-                self.module_name and module.__name__ == self.module_name
-            ):
-                continue
+        executed_by_type: dict[type[MVTModule], MVTModule] = {}
+        for module in ordered_modules:
 
             module_logger = logging.getLogger(module.__module__)
 
@@ -281,6 +347,10 @@ class Command:
                 module_options=self.module_options,
                 log=module_logger,
             )
+            m.dependency_modules = {
+                dependency: executed_by_type[dependency]
+                for dependency in module.dependencies
+            }
 
             if self.iocs.total_ioc_count:
                 m.indicators = self.iocs
@@ -304,6 +374,7 @@ class Command:
                 return
 
             self.executed.append(m)
+            executed_by_type[module] = m
             self.timeline.extend(m.timeline)
             self.alertstore.extend(m.alertstore.alerts)
 

src/mvt/common/module.py

@@ -9,7 +9,7 @@ import logging
 import os
 import re
 from dataclasses import asdict, is_dataclass
-from typing import Any, Dict, Optional
+from typing import Any, Dict, Optional, Sequence
 
 from .alerts import AlertStore
 from .indicators import Indicators
@@ -43,6 +43,7 @@ class MVTModule:
 
     enabled: bool = True
     slug: Optional[str] = None
+    dependencies: Sequence[type["MVTModule"]] = ()
 
     def __init__(
         self,
@@ -71,6 +72,7 @@ class MVTModule:
         self.file_path: Optional[str] = file_path
         self.target_path: Optional[str] = target_path
         self.results_path: Optional[str] = results_path
+        self.serial: Optional[str] = None
         self.module_options: Dict[str, Any] = module_options if module_options else {}
 
         self.log = log
@@ -79,6 +81,13 @@ class MVTModule:
 
         self.results: ModuleResults = results if results is not None else []
         self.timeline: ModuleTimeline = []
+        self.dependency_modules: Dict[type["MVTModule"], "MVTModule"] = {}
+
+    def get_dependency_results(
+        self, module_class: type["MVTModule"]
+    ) -> ModuleResults:
+        """Return the results produced by a prerequisite module."""
+        return self.dependency_modules[module_class].results
 
     @classmethod
     def from_json(cls, json_path: str, log: logging.Logger):

tests/android/test_artifact_dumpsys_battery_daily.py

@@ -69,3 +69,65 @@ class TestDumpsysBatteryDailyArtifact:
         assert downgrade_alert.event["package_name"] == "com.example.app"
         assert downgrade_alert.event["action"] == "downgrade"
         assert downgrade_alert.event["previous_vers"] == "10"
+
+    def test_newest_first_update_is_not_reported_as_downgrade(self):
+        dba = DumpsysBatteryDailyArtifact()
+        dba.parse(
+            """
+  Daily from 2026-01-10 to 2026-01-11:
+      Update com.example.app vers=102
+  Daily from 2026-01-05 to 2026-01-06:
+      Update com.example.app vers=101
+"""
+        )
+
+        assert len(dba.results) == 2
+        assert len(dba.alertstore.alerts) == 0
+        assert all(result["action"] == "update" for result in dba.results)
+
+    def test_newest_first_downgrade_creates_medium_alert(self):
+        dba = DumpsysBatteryDailyArtifact()
+        dba.parse(
+            """
+  Daily from 2026-01-10 to 2026-01-11:
+      Update com.example.app vers=101
+  Daily from 2026-01-05 to 2026-01-06:
+      Update com.example.app vers=102
+"""
+        )
+
+        assert len(dba.results) == 2
+        assert len(dba.alertstore.alerts) == 1
+
+        downgrade_alert = dba.alertstore.alerts[0]
+        assert downgrade_alert.level == AlertLevel.MEDIUM
+        assert downgrade_alert.message == (
+            "Detected downgrade of package com.example.app from vers 102 to vers 101"
+        )
+        assert downgrade_alert.event_time == "2026-01-10"
+        assert downgrade_alert.event["package_name"] == "com.example.app"
+        assert downgrade_alert.event["action"] == "downgrade"
+        assert downgrade_alert.event["previous_vers"] == "102"
+
+    def test_reinstall_after_uninstall_is_not_reported_as_downgrade(self):
+        dba = DumpsysBatteryDailyArtifact()
+        dba.parse(
+            """
+  Daily from 2026-01-15 to 2026-01-16:
+      Update com.example.app vers=10
+  Daily from 2026-01-10 to 2026-01-11:
+      Update com.example.app vers=0
+  Daily from 2026-01-05 to 2026-01-06:
+      Update com.example.app vers=102
+"""
+        )
+
+        assert len(dba.results) == 3
+        assert len(dba.alertstore.alerts) == 1
+
+        uninstall_alert = dba.alertstore.alerts[0]
+        assert uninstall_alert.level == AlertLevel.MEDIUM
+        assert uninstall_alert.message == (
+            "Detected uninstall of package com.example.app (vers 0)"
+        )
+        assert uninstall_alert.event_time == "2026-01-10"

tests/android/test_intrusion_logs.py

@@ -6,12 +6,14 @@
 import json
 import logging
 
+import pytest
 from click.testing import CliRunner
 
 from mvt.android.cli import check_intrusion_logs
 from mvt.android.cmd_check_intrusion_logs import CmdAndroidCheckIntrusionLogs
 from mvt.android.modules.intrusion_logs.base import IntrusionLogsModule
 from mvt.android.modules.intrusion_logs.security_event import SecurityEvent
+from mvt.common.alerts import AlertLevel
 
 
 def _write_ndjson(path, records):
@@ -143,6 +145,58 @@ def test_check_intrusion_logs_parses_core_and_unknown_security_events(
     assert "Please open an issue on GitHub" in caplog.text
 
 
+def test_check_intrusion_logs_treats_event_id_as_security_event_metadata(
+    tmp_path, caplog
+):
+    _write_ndjson(
+        tmp_path / "intrusion.txt",
+        [
+            {
+                "security_event": {
+                    "event_id": 191,
+                    "event_time": 1_700_000_002_000_000_000,
+                    "keyguard_dismiss_auth_attempt": {
+                        "success": True,
+                        "method_strength": 0,
+                    },
+                }
+            },
+            {
+                "security_event": {
+                    "event_id": 192,
+                    "event_time": 1_700_000_003_000_000_000,
+                    "keyguard_dismissed": {},
+                }
+            },
+        ],
+    )
+
+    with caplog.at_level(logging.WARNING):
+        cmd = CmdAndroidCheckIntrusionLogs(target_path=str(tmp_path))
+        cmd.run()
+
+    security_module = next(
+        module for module in cmd.executed if isinstance(module, SecurityEvent)
+    )
+    assert security_module.event_type_counts == {
+        "keyguard_dismiss_auth_attempt": 1,
+        "keyguard_dismissed": 1,
+    }
+    assert [event["event_id"] for event in security_module.results] == [191, 192]
+
+    keyguard_events = {
+        event["event"]: event
+        for event in cmd.timeline
+        if event["event"]
+        in {"keyguard_dismiss_auth_attempt", "keyguard_dismissed"}
+    }
+    assert "Auth attempt: Success" in keyguard_events[
+        "keyguard_dismiss_auth_attempt"
+    ]["data"]
+    assert keyguard_events["keyguard_dismissed"]["data"] == "Keyguard dismissed"
+    assert "unknown intrusion logging security event type(s): event_id" not in caplog.text
+
+
 def test_check_intrusion_logs_cli_lists_modules(tmp_path):
     _write_ndjson(tmp_path / "intrusion.txt", [])
 
@@ -152,3 +206,82 @@ def test_check_intrusion_logs_cli_lists_modules(tmp_path):
     assert "DnsEvent" in result.output
     assert "ConnectEvent" in result.output
     assert "SecurityEvent" in result.output
+
+
+def _run_security_heuristics(results):
+    # No indicators loaded: heuristic alerts must still fire.
+    module = SecurityEvent(results=results)
+    module.check_indicators()
+    return module.alertstore.alerts
+
+
+def test_cert_authority_installed_raises_medium_alert_without_indicators():
+    alerts = _run_security_heuristics(
+        [
+            {
+                "timestamp": "2024-01-01 00:00:00.000",
+                "cert_authority_installed": {
+                    "subject": "CN=Unexpected Root CA",
+                    "success": True,
+                },
+            }
+        ]
+    )
+
+    assert len(alerts) == 1
+    assert alerts[0].level == AlertLevel.MEDIUM
+    assert "Certificate authority installed" in alerts[0].message
+    assert "Unexpected Root CA" in alerts[0].message
+
+
+# Exported logs encode success as a JSON bool, raw SecurityLog as int 0/1.
+@pytest.mark.parametrize("success", [False, 0])
+def test_failed_cert_authority_install_does_not_alert(success, caplog):
+    with caplog.at_level(logging.WARNING):
+        alerts = _run_security_heuristics(
+            [
+                {
+                    "timestamp": "2024-01-01 00:00:00.000",
+                    "cert_authority_installed": {
+                        "subject": "CN=Unexpected Root CA",
+                        "success": success,
+                    },
+                }
+            ]
+        )
+
+    assert alerts == []
+    assert "Failed certificate authority install attempt" in caplog.text
+    assert "Unexpected Root CA" in caplog.text
+
+
+def test_cert_validation_failure_raises_medium_alert_without_indicators():
+    alerts = _run_security_heuristics(
+        [
+            {
+                "timestamp": "2024-01-01 00:00:00.000",
+                "cert_validation_failure": "chain validation failed",
+            }
+        ]
+    )
+
+    assert len(alerts) == 1
+    assert alerts[0].level == AlertLevel.MEDIUM
+    assert "Certificate validation failure" in alerts[0].message
+
+
+def test_security_heuristics_fire_when_no_indicators_loaded():
+    # check_indicators() previously returned early with no indicators loaded,
+    # so none of the heuristic alerts fired on a default run.
+    alerts = _run_security_heuristics(
+        [
+            {"timestamp": "2024-01-01 00:00:00.000", "wipe_failure": {"reason": "x"}},
+            {
+                "timestamp": "2024-01-01 00:00:00.000",
+                "key_integrity_violation": {"key_id": "k1"},
+            },
+        ]
+    )
+
+    assert len(alerts) == 2
+    assert all(alert.level == AlertLevel.MEDIUM for alert in alerts)

tests/common/test_command.py

@@ -4,11 +4,59 @@
 #   https://license.mvt.re/1.1/
 
 import json
+import logging
 
 from mvt.common.command import Command
+from mvt.common.module import MVTModule
+
+
+class RecordingModule(MVTModule):
+    run_order: list[str] = []
+
+    def run(self):
+        self.run_order.append(self.__class__.__name__)
+
+    def check_indicators(self):
+        pass
+
+
+class FirstModule(RecordingModule):
+    def run(self):
+        super().run()
+        self.results = ["first"]
+
+
+class SecondModule(RecordingModule):
+    dependencies = (FirstModule,)
+
+    def run(self):
+        super().run()
+        self.results = self.get_dependency_results(FirstModule) + ["second"]
+
+
+class ThirdModule(RecordingModule):
+    dependencies = (SecondModule,)
+
+
+class IndependentModule(RecordingModule):
+    pass
+
+
+class RecordingCommand(Command):
+    def init(self):
+        self.initialized = True
+
+    def module_init(self, module):
+        pass
+
+    def finish(self):
+        pass
 
 
 class TestCommand:
+    def setup_method(self):
+        RecordingModule.run_order = []
+
     def test_store_alerts_handles_bytes(self, tmp_path):
         cmd = Command(results_path=str(tmp_path))
         cmd.alertstore.medium(
@@ -21,3 +69,66 @@ class TestCommand:
 
         alerts = json.loads((tmp_path / "alerts.json").read_text())
         assert alerts[0]["event"]["payload"] == "\\xa8\\xa9"
+
+    def test_modules_run_in_stable_topological_order(self):
+        cmd = RecordingCommand()
+        cmd.modules = [ThirdModule, IndependentModule, SecondModule, FirstModule]
+
+        cmd.run()
+
+        assert RecordingModule.run_order == [
+            "IndependentModule",
+            "FirstModule",
+            "SecondModule",
+            "ThirdModule",
+        ]
+        second = next(module for module in cmd.executed if isinstance(module, SecondModule))
+        assert second.results == ["first", "second"]
+
+    def test_selected_module_runs_transitive_dependencies(self):
+        cmd = RecordingCommand(module_name="ThirdModule")
+        cmd.modules = [ThirdModule, SecondModule, FirstModule, IndependentModule]
+
+        cmd.run()
+
+        assert RecordingModule.run_order == [
+            "FirstModule",
+            "SecondModule",
+            "ThirdModule",
+        ]
+
+    def test_circular_dependency_warns_and_stops(self, caplog):
+        class CircularOne(RecordingModule):
+            pass
+
+        class CircularTwo(RecordingModule):
+            dependencies = (CircularOne,)
+
+        CircularOne.dependencies = (CircularTwo,)
+
+        cmd = RecordingCommand()
+        cmd.modules = [CircularOne, CircularTwo]
+
+        with caplog.at_level(logging.WARNING):
+            cmd.run()
+
+        assert RecordingModule.run_order == []
+        assert not hasattr(cmd, "initialized")
+        assert "Circular module dependency detected" in caplog.text
+
+    def test_unavailable_dependency_warns_and_stops(self, caplog):
+        class UnavailableModule(RecordingModule):
+            pass
+
+        class DependentModule(RecordingModule):
+            dependencies = (UnavailableModule,)
+
+        cmd = RecordingCommand()
+        cmd.modules = [DependentModule]
+
+        with caplog.at_level(logging.WARNING):
+            cmd.run()
+
+        assert RecordingModule.run_order == []
+        assert not hasattr(cmd, "initialized")
+        assert "depends on unavailable module UnavailableModule" in caplog.text