more documentation and comments on methods.

Author: mosen

commandment/enroll/__init__.py

@@ -27,7 +27,7 @@ class DeviceAttributes(Enum):
     DeviceAttributes.DEVICE_NAME.value,
     DeviceAttributes.SERIAL.value,
     DeviceAttributes.MODEL.value,
-    DeviceAttributes.MAC_ADDRESS_EN0.value,
+    # DeviceAttributes.MAC_ADDRESS_EN0.value,
     DeviceAttributes.MEID.value,
     DeviceAttributes.IMEI.value,
     DeviceAttributes.ICCID.value,

commandment/mdm/decorators.py

@@ -0,0 +1,13 @@
+from functools import wraps
+
+
+def handle_error_status(func):
+    """This decorator looks at the request for an Error status, then handles the error accordingly:
+
+    """
+    @wraps(func)
+    def handler(*args, **kwargs):
+        return func(*args, **kwargs)
+    return handler
+
+

commandment/mdm/handlers.py

@@ -1,5 +1,4 @@
 from binascii import hexlify
-import uuid
 
 from cryptography import x509
 from cryptography.hazmat.backends import default_backend
@@ -22,11 +21,11 @@
 
 
 @command_router.route('DeviceInformation')
-def ack_device_information(command: DBCommand, device: Device, response: dict):
-    """Acknowledge a ``DeviceInformation`` response.
+def ack_device_information(request: DBCommand, device: Device, response: dict):
+    """Acknowledge a response to the ``DeviceInformation`` command.
 
     Args:
-        request (DeviceInformation): The command instance that generated this response.
+        request (Command): An instance of the command that prompted the device to come back with this request.
         device (Device): The device responding to the command.
         response (dict): The raw response dictionary, de-serialized from plist.
     Returns:
@@ -135,6 +134,16 @@ def ack_profile_list(request: DBCommand, device: Device, response: dict):
 
 @command_router.route('CertificateList')
 def ack_certificate_list(request: DBCommand, device: Device, response: dict):
+    """Acknowledge a response to the ``CertificateList`` command.
+
+    Args:
+        request (Command): An instance of the command that prompted the device to come back with this request.
+        device (Device): The database model of the device responding.
+        response (dict): The response plist data, as a dictionary.
+
+    Returns:
+        void: Nothing is returned but this behaviour is subject to change.
+    """
     for c in device.installed_certificates:
         db.session.delete(c)
 
@@ -162,7 +171,7 @@ def ack_certificate_list(request: DBCommand, device: Device, response: dict):
 
 @command_router.route('InstalledApplicationList')
 def ack_installed_app_list(request: DBCommand, device: Device, response: dict):
-    """Acknowledge a response to ``InstalledApplicationList``.
+    """Acknowledge a response to the ``InstalledApplicationList`` command.
     
     .. note:: There is no composite key which can uniquely identify an item in the installed applications list.
         Some applications may not contain any version information at all. For this reason, the entire list of installed
@@ -279,39 +288,63 @@ def ack_install_application(request: DBCommand, device: Device, response: dict):
 @command_router.route('ManagedApplicationList')
 def ack_managed_application_list(request: DBCommand, device: Device, response: dict):
     """Acknowledge a response to `ManagedApplicationList`."""
-    for bundle_id, status in response['ManagedApplicationList'].items():
-        try:
-            ma = db.session.query(ManagedApplication).filter(
-                Device.id == device.id,
-                ManagedApplication.bundle_id == bundle_id
-            ).one()
-        except NoResultFound:
-            ma = ManagedApplication(bundle_id=bundle_id, device=device)
+    if response.get('Status', None) == 'Error':
+        pass
+    else:
+        for bundle_id, status in response['ManagedApplicationList'].items():
+            try:
+                ma = db.session.query(ManagedApplication).filter(
+                    Device.id == device.id,
+                    ManagedApplication.bundle_id == bundle_id
+                ).one()
+            except NoResultFound:
+                ma = ManagedApplication(bundle_id=bundle_id, device=device)
+
+            ma.status = ManagedAppStatus(status['Status'])
+            ma.external_version_id = status.get('ExternalVersionIdentifier', None)  # Does not exist in iOS 11.3.1
+            ma.has_configuration = status['HasConfiguration']
+            ma.has_feedback = status['HasFeedback']
+            ma.is_validated = status['IsValidated']
+            ma.management_flags = status['ManagementFlags']
 
-        ma.status = ManagedAppStatus(status['Status'])
-        ma.external_version_id = status.get('ExternalVersionIdentifier', None)  # Does not exist in iOS 11.3.1
-        ma.has_configuration = status['HasConfiguration']
-        ma.has_feedback = status['HasFeedback']
-        ma.is_validated = status['IsValidated']
-        ma.management_flags = status['ManagementFlags']
+            db.session.add(ma)
 
-        db.session.add(ma)
+        db.session.commit()
 
-    db.session.commit()
+        for tag in device.tags:
+            for app in tag.applications:
+                # TODO: need to check with new versions being available. This is very primitive.
+                if app.bundle_id in response['ManagedApplicationList'].keys():
+                    continue
 
-    for tag in device.tags:
-        for app in tag.applications:
-            # TODO: need to check with new versions being available. This is very primitive.
-            if app.bundle_id in response['ManagedApplicationList'].keys():
-                continue
+                c = commands.InstallApplication(application=app)
+                dbc = DBCommand.from_model(c)
+                dbc.device = device
+                db.session.add(dbc)
 
-            c = commands.InstallApplication(application=app)
-            dbc = DBCommand.from_model(c)
-            dbc.device = device
-            db.session.add(dbc)
+                ma = ManagedApplication(device=device, application=app, ia_command=dbc, status=ManagedAppStatus.Queued)
+                db.session.add(ma)
 
-            ma = ManagedApplication(device=device, application=app, ia_command=dbc, status=ManagedAppStatus.Queued)
-            db.session.add(ma)
+        db.session.commit()
 
-    db.session.commit()
 
+@command_router.route('RestartDevice')
+def ack_restart_device(request: DBCommand, device: Device, response: dict):
+    """Acknowledge a response to `RestartDevice`.
+
+    On macOS 10.13.6, the MDM client comes back with an `Idle` check in upon restart as part of launchd starting up.
+    This happens BEFORE the loginwindow (at about 40% of the progress bar at startup). This is the same Power-on
+    behaviour.
+    """
+    pass
+
+
+@command_router.route('ShutDownDevice')
+def ack_restart_device(request: DBCommand, device: Device, response: dict):
+    """Acknowledge a response to `ShutDownDevice`.
+
+    On macOS 10.13.6, the MDM client comes back with an `Idle` check in upon restart as part of launchd starting up.
+    This happens BEFORE the loginwindow (at about 40% of the progress bar at startup). This is the same Power-on
+    behaviour.
+    """
+    pass

commandment/mdm/routers.py

@@ -19,6 +19,9 @@ class CommandRouter(object):
      that was registered for the RequestType associated with that command. The handler is then called with the specific
      instance of the command that generated the response, and an instance of the device that is making the request to
      the MDM endpoint.
+
+    Not handling the error status here allows handlers to freely interpret the error conditions of each response, which
+    is generally a better approach as some errors are command specific.
     
     Args:
           app (app): The flask application or blueprint instance

doc/developer/microservices.rst

@@ -0,0 +1,80 @@
+Microservices Architecture
+==========================
+
+MDM only has certain limitations which means that microservices have only a limited range of definition in terms of where
+dependent services can live.
+
+Here's some ideas for services
+
+
+DEP Scanner + Default Profiler
+------------------------------
+
+- Some process needs to scan/sync DEP
+- This is a good point in time to evaluate which DEP profile should be assigned to the devices as they come in.
+- If there was a rules based evaluation of DEP profile assignment, that could also happen here.
+- Manual DEP assignment does NOT have to live here, because it is performed imperatively against collections of objects.
+- This process can create new device records when it finds new DEP records. These can exist in a "pre-enrolled" state.
+
+
+APNS Pusher
+-----------
+
+- Most MDM systems have some sort of Queue monitor/APNS push watcher.
+- After a certain amount of time, devices with >0 commands to send are evaluated.
+- Some commands are imperative and you would expect them to happen almost immediately (Shutdown, Restart). with exception
+  to device collections larger than 100, where the push may take some time.
+- Some commands are expected to happen in good time (InstallProfile, InstallApplication).
+
+
+Inventory
+---------
+
+- End users expect REASONABLY recent device inventory.
+- Some process needs to Queue inventory commands at a refresh interval, but not queue all devices at once.
+- It must also not queue commands if they are already queued.
+- It must also not queue commands for recently refreshed inventory.
+
+
+Profiles
+--------
+
+- Try not to introspect profile payload structure because it can literally be anything almost.
+- Examine desired profiles vs installed profiles and create a command for it.
+
+
+Applications
+------------
+
+- Same theoretical application as PRofiles but with a different object type.
+
+Calculated Groups (Classifier)
+------------------------------
+
+- Isolate a sub-population of devices by attribute predicates.
+- Many cloud providers de-prioritise the calculation of these groups in order to reduce impact, but this also results in
+  sluggish feedback.
+- Tactics for speeding up or lessening impact of calculated groups:
+  - Do not recalculate if inventory data did not change: therefore track devices which did change in the last x duration.
+  - Newly created groups must force a recalculation of membership immediately to provide feedback to the user.
+  - Compound predicates are the union intersection of simple predicates, so maybe this can be exploited to lower the cost
+    of group calculation.
+  - Consider groupable attributes for indexing
+- Groups can be used to functionally identify the workflow state of a device from its pre-enrolled DEP state through
+  DeviceConfigured into enrolled.
+- Pre-defined groups:
+  - By form factor (Desktop, Tablet, Phone, ATV)
+  - Workflow state (DEP -> AwaitConfiguration -> Enrolled -> Stale -> Unenrolled)
+  - OS Flavour+Major Version (becomes a derivative of form factor groups)
+	- Minor Version (becomes a derivative of major version)
+  - Cellular v non cellular (subset of union Tablet+Phone)
+- Freestyle composite groups:
+  - Nominate a pre-defined group to limit calculation results.
+  - Enforce a predicate on that.
+
+
+Reaper
+------
+
+- Scan age of devices and mark them as Stale if no communications recently.
+- Unenroll devices once they have not communicated in a long amount of time,

doc/installing/index.rst

@@ -0,0 +1,4 @@
+==========
+Installing
+==========
+

doc/developer/install.rst doc/installing/install.rstdoc/developer/install.rst renamed to doc/installing/install.rst

@@ -31,9 +31,17 @@ at :file:`/usr/local/commandment/server.key` and a certificate, located at :file
 For a production instance, you will require an SSL certificate issued by a 3rd party for the chosen domain. However,
 as this is a macOS installation guide, You may also use a self-signed certificate.
 
-
 .. note:: Creating SSL certificates is outside of the scope of this document.
 
+Handy tip for extracting PEM/key pair out of a .p12 exported by Keychain Assistant::
+
+	openssl pkcs12 -in yourP12File.p12 -nocerts -out privatekey.pem
+	openssl pkcs12 -in yourP12File.p12 -clcerts -nokeys -out certificate.pem
+
+For converting DER to PEM::
+
+	openssl x509 -inform DER -outform PEM -text -in mykey.der -out mykey.pem
+
 
 Push Notification Certificate
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

doc/installing/macos.rst

@@ -151,14 +151,22 @@ Symlink to **sites-enabled**::
 
 	sudo ln -s /etc/nginx/sites-available/commandment.conf /etc/nginx/sites-enabled/commandment.conf
 
-2.3 SSL Certificate(s)
-^^^^^^^^^^^^^^^^^^^^^^
+3 SSL Certificate(s)
+--------------------
 
 NGiNX will fail to start until we actually create an SSL certificate for this site.
 
-If this is a non-public, development, sandbox environment you can use a self-signed certificate. If you ever intend to
-make it public (internet) facing, you need to sort out SSL certificates, maybe with LetsEncrypt.
+If this is a non-public, development, sandbox environment you can use a self-signed certificate.
+This means that you're either developing with commandment or you dont mind being restricted to a home (W)LAN network.
+I usually couple this with Bonjour for a hassle free testbed, hosting on something like computer.local.
 
+If you ever intend to make it public (internet) facing, you need to sort out an SSL certificate and DNS name that are
+externally verifiable and visible. This means having a DNS name or hosting on a service which gives you a static domain
+name for your site AND getting a 3rd party certificate issued. The cheapest recommended option for that is to use
+LetsEncrypt.
+
+3.1 Self-Signed Certificate(s)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 To use self-signed certificates, first check that your hostname will be the fqdn that devices can access your machine with::
 

doc/installing/ubuntu-server.rst

@@ -22,7 +22,6 @@
     "babel-runtime": "^6.26.0",
     "eslint": "^5.16.0",
     "eslint-plugin-react": "^7.13.0",
-    "tslint": "^5.17.0",
     "webpack-bundle-analyzer": "^3.3.2",
     "webpack-cli": "^3.1.2",
     "webpack-dev-server": "^3.1.4",