Merge ac157a4421 into bb7a22ed0b

docs/install.md

@@ -7,11 +7,27 @@ Before proceeding, please note that MVT requires Python 3.6+ to run. While it sh
 First install some basic dependencies that will be necessary to build all required tools:
 
 ```bash
-sudo apt install python3 python3-pip libusb-1.0-0 sqlite3
+sudo apt install python3 python3-venv python3-pip sqlite3 libusb-1.0-0
 ```
 
 *libusb-1.0-0* is not required if you intend to only use `mvt-ios` and not `mvt-android`.
 
+(Recommended) Set up `pipx`
+
+For Ubuntu 23.04 or above:
+```bash
+sudo apt install pipx
+pipx ensurepath
+```
+
+For Ubuntu 22.04 or below:
+```
+python3 -m pip install --user pipx
+python3 -m pipx ensurepath
+```
+
+Other distributions: check for a `pipx` or `python-pipx` via your package manager.
+
 When working with Android devices you should additionally install [Android SDK Platform Tools](https://developer.android.com/studio/releases/platform-tools). If you prefer to install a package made available by your distribution of choice, please make sure the version is recent to ensure compatibility with modern Android devices.
 
 ## Dependencies on macOS
@@ -21,7 +37,7 @@ Running MVT on macOS requires Xcode and [homebrew](https://brew.sh) to be instal
 In order to install dependencies use:
 
 ```bash
-brew install python3 libusb sqlite3
+brew install python3 pipx libusb sqlite3
 ```
 
 *libusb* is not required if you intend to only use `mvt-ios` and not `mvt-android`.
@@ -42,24 +58,43 @@ It is recommended to try installing and running MVT from [Windows Subsystem Linu
 
 ## Installing MVT
 
-If you haven't done so, you can add this to your `.bashrc` or `.zshrc` file in order to add locally installed PyPI binaries to your `$PATH`:
+### Installing from PyPI with pipx (recommended)
+1. Install `pipx` following the instructions above for your OS/distribution. Make sure to run `pipx ensurepath` and open a new terminal window.
+2. ```bash
+   pipx install mvt
+   ```
 
+You now should have the `mvt-ios` and `mvt-android` utilities installed. If you run into problems with these commands not being found, ensure you have run `pipx ensurepath` and opened a new terminal window.
+
+### Installing from PyPI directly into a virtual environment
+You can use `pipenv`, `poetry` etc. for your virtual environment, but the provided example is with the built-in `venv` tool:
+
+1. Create the virtual environment in a folder in the current directory named `env`:
 ```bash
-export PATH=$PATH:~/.local/bin
+python3 -m venv env
 ```
 
-Then you can install MVT directly from [PyPI](https://pypi.org/project/mvt/)
-
+2. Activate the virtual environment:
 ```bash
-pip3 install mvt
+source env/bin/activate
 ```
 
-If you want to have the latest features in development, you can install MVT directly from the source code. If you installed MVT previously from pypi, you should first uninstall it using `pip3 uninstall mvt` and then install from the source code:
+3. Install `mvt` into the virtual environment:
+```bash
+pip install mvt
+```
+
+The `mvt-ios` and `mvt-android` utilities should now be available as commands whenever the virtual environment is active.
+
+### Installing from git source with pipx
+If you want to have the latest features in development, you can install MVT directly from the source code in git.
 
 ```bash
-git clone https://github.com/mvt-project/mvt.git
-cd mvt
-pip3 install .
+pipx install --force git+https://github.com/mvt-project/mvt.git
 ```
 
 You now should have the `mvt-ios` and `mvt-android` utilities installed.
+
+**Notes:**
+1. The `--force` flag is necessary to force the reinstallation of the package.
+2. To revert to using a PyPI version, it will be necessary to `pipx uninstall mvt` first.

mvt/common/alerting.py

@@ -0,0 +1,138 @@
+# Mobile Verification Toolkit (MVT)
+# Copyright (c) 2021-2023 The MVT Authors.
+# Use of this software is governed by the MVT License 1.1 that can be found at
+#   https://license.mvt.re/1.1/
+from enum import Enum
+
+
+class AlertLevel(Enum):
+    """
+    informational: Rule is intended for enrichment of events, e.g. by tagging them. No case or alerting should be triggered by such rules because it is expected that a huge amount of events will match these rules.
+    low: Notable event but rarely an incident. Low rated events can be relevant in high numbers or combination with others. Immediate reaction shouldn’t be necessary, but a regular review is recommended.
+    medium: Relevant event that should be reviewed manually on a more frequent basis.
+    high: Relevant event that should trigger an internal alert and requires a prompt review.
+    critical: Highly relevant event that indicates an incident. Critical events should be reviewed immediately.
+    """
+
+    INFORMATIONAL = 0
+    LOW = 10
+    MEDIUM = 20
+    HIGH = 30
+    CRITICAL = 40
+
+
+class AlertStore(object):
+    """
+    Track all of the alerts and detections generated during an analysis.
+
+    Results can be logged as log messages or in JSON format for processing by other tools.
+    """
+
+    def __init__(self) -> None:
+        self.alerts = []
+
+    def add_alert(
+        self, level, message=None, event_time=None, event=None, ioc=None, detected=True
+    ):
+        """
+        Add an alert to the alert store.
+        """
+        self.alerts.append(
+            Alert(
+                level=level,
+                message=message,
+                event_time=event_time,
+                event=event,
+                ioc=ioc,
+                detected=detected,
+            )
+        )
+
+    def informational(
+        self, message=None, event_time=None, event=None, ioc=None, detected=False
+    ):
+        self.add_alert(
+            AlertLevel.INFORMATIONAL,
+            message=message,
+            event_time=event_time,
+            event=event,
+            ioc=ioc,
+            detected=detected,
+        )
+
+    def low(self, message=None, event_time=None, event=None, ioc=None, detected=False):
+        self.add_alert(
+            AlertLevel.LOW,
+            message=message,
+            event_time=event_time,
+            event=event,
+            ioc=ioc,
+            detected=detected,
+        )
+
+    def medium(
+        self, message=None, event_time=None, event=None, ioc=None, detected=False
+    ):
+        self.add_alert(
+            AlertLevel.MEDIUM,
+            message=message,
+            event_time=event_time,
+            event=event,
+            ioc=ioc,
+            detected=detected,
+        )
+
+    def high(self, message=None, event_time=None, event=None, ioc=None, detected=False):
+        self.add_alert(
+            AlertLevel.HIGH,
+            message=message,
+            event_time=event_time,
+            event=event,
+            ioc=ioc,
+            detected=detected,
+        )
+
+    def critical(
+        self, message=None, event_time=None, event=None, ioc=None, detected=False
+    ):
+        self.add_alert(
+            AlertLevel.CRITICAL,
+            message=message,
+            event_time=event_time,
+            event=event,
+            ioc=ioc,
+            detected=detected,
+        )
+
+
+class Alert(object):
+    """
+    An alert generated by an MVT module.
+    """
+
+    def __init__(self, level, message, event_time, event, ioc, detected):
+        self.level = level
+        self.message = message
+        self.event_time = event_time
+        self.event = event
+        self.ioc = ioc
+        self.detected = detected
+
+    def __repr__(self):
+        return f"<Alert level={self.level} message={self.message} event_time={self.event_time} event={self.event}>"
+
+    def __str__(self):
+        return f"{self.level} {self.message} {self.event_time} {self.event}"
+
+    def to_log(self):
+        return f"{self.level} {self.message} {self.event_time} {self.event}"
+
+    def to_json(self):
+        return {
+            "level": self.level,
+            "message": self.message,
+            "event_time": self.event_time,
+            "event": self.event,
+            "ioc": self.ioc,
+            "detected": self.detected,
+        }

mvt/ios/modules/mixed/sms.py

@@ -68,9 +68,10 @@ class SMS(IOSExtraction):
         for message in self.results:
             alert = "ALERT: State-sponsored attackers may be targeting your iPhone"
             if message.get("text", "").startswith(alert):
-                self.log.warning(
-                    "Apple warning about state-sponsored attack received on the %s",
-                    message["isodate"],
+                self.alerts.medium(
+                    f"Apple warning about state-sponsored attack received on the {message['isodate']}",
+                    event_time=message["isodate"],
+                    event=message,
                 )
 
         if not self.indicators: