Skip to content

A free open source IT asset/license management system

16.2 KB
Raw Blame
<?php

namespace App\SyncAdapters\MosyleBusiness;

use App\Models\Asset;
use App\SyncAdapters\HostInventoryRecord;
use App\SyncAdapters\PushableSyncAdapter;
use App\SyncAdapters\Traits\UsesAppleDbEnrichment;
use Carbon\Carbon;
use Illuminate\Support\Arr;
use Illuminate\Support\Facades\Log;

/**
 * Mosyle Business adapter. Pulls device inventory from a Mosyle
 * Business v1 tenant and normalizes it into HostInventoryRecord
 * objects. Also pushes Snipe-IT-authoritative asset_tag and composed
 * notes back via Mosyle's dispatcher-style /devices endpoint.
 *
 * Sibling to MosyleAdapter (Manager v2). The two share almost all of
 * their device-field names, so normalize() is nearly identical, but
 * the auth model, endpoint URL, response wrapping, OS enum, and push
 * payload shape differ enough that they live in separate adapter +
 * client pairs. See the MosyleBusinessClient docblock for the full
 * compare.
 *
 * Key difference admins care about: Business exposes a `notes` push
 * field. This adapter wires that up through the composed-notes
 * framework.
 */
class MosyleBusinessAdapter extends PushableSyncAdapter
{
    use UsesAppleDbEnrichment;

    public static function typeLabel(): string
    {
        return 'Mosyle Business';
    }

    public static function typeSlug(): string
    {
        return 'mosyle_business';
    }

    public static function docsUrl(): ?string
    {
        return 'https://school.mosyle.com/solutions/macos/privilege-management';
    }

    public function baseUrlPlaceholder(): ?string
    {
        return 'https://businessapi.mosyle.com/v1';
    }

    public function settingsSchema(): array
    {
        return [
            [
                'key' => 'access_token',
                'label' => trans('admin/settings/sync_adapters.label_access_token'),
                'secret' => true,
                'help' => trans('admin/settings/sync_adapters.mosyle_business_access_token_help'),
            ],
            [
                'key' => 'email',
                'label' => trans('general.email'),
                'help' => trans('admin/settings/sync_adapters.mosyle_business_email_help'),
            ],
            [
                'key' => 'password',
                'label' => trans('general.password'),
                'secret' => true,
                'help' => trans('admin/settings/sync_adapters.mosyle_business_password_help'),
            ],
            $this->appleDbSettingsField(),
        ];
    }

    /**
     * Business and Manager return almost identical device fields, so
     * the same extras set applies to both. Lang keys are reused from
     * the Manager adapter's mosyle_extra_* namespace to keep the
     * translator community from carrying 60 duplicate strings.
     */
    public function extraFields(): array
    {
        return [
            ...$this->appleDbExtraFieldsDeclaration(),
            // Hardware / inventory
            'mosyle_battery' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_battery'],
            'mosyle_total_disk' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_total_disk'],
            'mosyle_available_disk' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_available_disk'],
            'mosyle_bluetooth_mac' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_bluetooth_mac'],
            'mosyle_ethernet_mac' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_ethernet_mac'],
            'mosyle_device_type' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_device_type'],
            'mosyle_build_version' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_build_version'],
            // Cellular
            'mosyle_carrier' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_carrier'],
            'mosyle_imei' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_imei'],
            'mosyle_meid' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_meid'],
            // Security / posture
            'mosyle_activation_lock_enabled' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_activation_lock_enabled', 'type' => 'boolean'],
            'mosyle_device_locator_enabled' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_device_locator_enabled', 'type' => 'boolean'],
            'mosyle_cloud_backup_enabled' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_cloud_backup_enabled', 'type' => 'boolean'],
            'mosyle_last_cloud_backup_date' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_last_cloud_backup_date', 'type' => 'date'],
            'mosyle_sip_enabled' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_sip_enabled', 'type' => 'boolean'],
            'mosyle_device_attestation_status' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_device_attestation_status'],
            // MDM / lifecycle
            'mosyle_enrollment_type' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_enrollment_type'],
            'mosyle_status' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_status'],
            'mosyle_management_status' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_management_status'],
            'mosyle_os_update_status' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_os_update_status'],
            'mosyle_date_last_beat' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_date_last_beat', 'type' => 'date'],
            'mosyle_date_last_push' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_date_last_push', 'type' => 'date'],
            'mosyle_user_id' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_user_id'],
            'mosyle_supervised' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_supervised', 'type' => 'boolean'],
            // User / scoping
            'mosyle_user_type' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_user_type'],
            'mosyle_location' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_location'],
            'mosyle_tags' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_tags'],
            // Network
            'mosyle_last_ssid' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_last_ssid'],
            // Lost-mode fields (only populated when device is in lost mode)
            'mosyle_lost_mode_status' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_lost_mode_status'],
            'mosyle_latitude' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_latitude'],
            'mosyle_longitude' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_longitude'],
            'mosyle_altitude' => ['label_key' => 'admin/settings/sync_adapters.mosyle_extra_altitude'],
            'mosyle_device_model' => ['label_key' => 'admin/settings/sync_adapters.extra_model_identifier'],
        ];
    }

    public function pull(): iterable
    {
        $client = $this->makeClient();

        $enrichmentEnabled = $this->appleDbEnrichmentEnabled();
        $enrichmentHandled = [];

        foreach ($client->devices() as $device) {
            $record = $this->normalize($device);
            if ($enrichmentEnabled) {
                $enrichmentHandled = $this->enrichFromAppleDb($record, $enrichmentHandled);
            }
            yield $record;
        }
    }

    /**
     * Pass the Mosyle Business record to the shared enrichment flow.
     * Business and Manager share field semantics: `device_model` is
     * the AppleDB identifier shape ("iPad12,1" per the Business API
     * reference), `device_model_name` is the marketing shape.
     *
     * @param  array<string, bool>  $handled
     * @return array<string, bool>
     */
    private function enrichFromAppleDb(HostInventoryRecord $record, array $handled): array
    {
        $modelName = $record->hardwareModel;
        if (! is_string($modelName) || $modelName === '') {
            return $handled;
        }

        $productType = $record->extra['mosyle_device_model'] ?? null;
        if (! is_string($productType) || $productType === '') {
            return $handled;
        }

        return $this->enrichModelFromAppleDb($modelName, $productType, null, $handled);
    }

    /**
     * Convert a Mosyle Business device payload into the normalized
     * record shape. Field names match the Business v1 /devices list
     * response. `username` not `usename`, `last_lan_ip` for the
     * device IP, same as Manager v2.
     *
     * @param  array<string, mixed>  $device
     */
    private function normalize(array $device): HostInventoryRecord
    {
        $productType = Arr::get($device, 'device_model');
        $modelName = Arr::get($device, 'device_model_name') ?? $productType;
        $canonical = $this->canonicalIdentityFor($productType, $modelName);
        $appleDbExtras = $this->appleDbExtrasFor($productType, $modelName);

        return new HostInventoryRecord(
            sourceKey: $this->name(),
            sourceId: (string) Arr::get($device, 'deviceudid'),
            hostname: Arr::get($device, 'device_name'),
            hardwareSerial: Arr::get($device, 'serial_number'),
            hardwareModel: $modelName,
            manufacturer: 'Apple',
            primaryMac: Arr::get($device, 'wifi_mac_address'),
            primaryIp: Arr::get($device, 'last_lan_ip'),
            os: Arr::get($device, 'os'),
            osVersion: Arr::get($device, 'osversion'),
            lastSeen: $this->parseTimestamp(Arr::get($device, 'date_info')),
            assetTag: Arr::get($device, 'asset_tag'),
            assignedUserEmail: Arr::get($device, 'useremail'),
            assignedUserName: Arr::get($device, 'username'),
            extra: [
                ...$appleDbExtras,
                // Hardware / inventory
                'mosyle_battery' => Arr::get($device, 'battery'),
                'mosyle_total_disk' => Arr::get($device, 'total_disk'),
                'mosyle_available_disk' => Arr::get($device, 'available_disk'),
                'mosyle_bluetooth_mac' => Arr::get($device, 'bluetooth_mac_address'),
                'mosyle_ethernet_mac' => Arr::get($device, 'ethernet_mac_address'),
                'mosyle_device_type' => Arr::get($device, 'device_type'),
                'mosyle_build_version' => Arr::get($device, 'BuildVersion'),
                // Cellular
                'mosyle_carrier' => Arr::get($device, 'carrier'),
                'mosyle_imei' => Arr::get($device, 'imei'),
                'mosyle_meid' => Arr::get($device, 'meid'),
                // Security / posture
                'mosyle_activation_lock_enabled' => Arr::get($device, 'isActivationLockEnabled'),
                'mosyle_device_locator_enabled' => Arr::get($device, 'isDeviceLocatorServiceEnabled'),
                'mosyle_cloud_backup_enabled' => Arr::get($device, 'isCloudBackupEnabled'),
                'mosyle_last_cloud_backup_date' => Arr::get($device, 'LastCloudBackupDate'),
                'mosyle_sip_enabled' => Arr::get($device, 'SystemIntegrityProtectionEnabled'),
                'mosyle_device_attestation_status' => Arr::get($device, 'DeviceAttestationStatus'),
                // MDM / lifecycle
                'mosyle_enrollment_type' => Arr::get($device, 'enrollment_type'),
                'mosyle_status' => Arr::get($device, 'status'),
                'mosyle_management_status' => Arr::get($device, 'ManagementStatus'),
                'mosyle_os_update_status' => Arr::get($device, 'OSUpdateStatus'),
                'mosyle_date_last_beat' => Arr::get($device, 'date_last_beat'),
                'mosyle_date_last_push' => Arr::get($device, 'date_last_push'),
                'mosyle_user_id' => Arr::get($device, 'userid'),
                'mosyle_supervised' => Arr::get($device, 'is_supervised'),
                // User / scoping
                'mosyle_user_type' => Arr::get($device, 'usertype'),
                'mosyle_location' => Arr::get($device, 'location'),
                'mosyle_tags' => Arr::get($device, 'tags'),
                // Network
                'mosyle_last_ssid' => Arr::get($device, 'last_ssid'),
                // Lost-mode
                'mosyle_lost_mode_status' => Arr::get($device, 'lostmode_status'),
                'mosyle_latitude' => Arr::get($device, 'latitude'),
                'mosyle_longitude' => Arr::get($device, 'longitude'),
                'mosyle_altitude' => Arr::get($device, 'altitude'),
                'mosyle_device_model' => $productType,
            ],
            canonicalMarketingName: $canonical['canonicalMarketingName'],
            canonicalModelNumber: $canonical['canonicalModelNumber'],
        );
    }

    /**
     * Mosyle Business returns timestamps as Unix epoch seconds (same
     * as Manager v2). Numeric values in the plausible Unix-time range
     * get routed through createFromTimestamp. ISO strings fall back
     * to Carbon::parse. Any failure logs and returns null rather than
     * aborting a sync run on one bad device.
     */
    private function parseTimestamp(mixed $value): ?Carbon
    {
        if ($value === null || $value === '') {
            return null;
        }

        try {
            if (is_numeric($value) && $value >= 1_000_000_000 && $value <= 100_000_000_000) {
                return Carbon::createFromTimestampUTC((int) $value);
            }

            return Carbon::parse($value);
        } catch (\Throwable $e) {
            Log::channel('sync-adapters')->warning(
                $this->name().': skipped unparseable Mosyle Business timestamp ('.var_export($value, true).'): '.$e->getMessage()
            );

            return null;
        }
    }

    /**
     * Business writes use the same credential set as reads. No tier
     * / license gate, so canPush is always true for a configured
     * instance.
     */
    public function canPush(): bool
    {
        return true;
    }

    /**
     * Business DOES support a notes push field (Manager does not).
     * The dispatcher endpoint accepts notes as a top-level string
     * on operation=update_device.
     */
    public function notesFieldTarget(): ?string
    {
        return 'notes';
    }

    /**
     * Push Snipe-IT asset_tag (and optionally composed notes) back
     * to Mosyle Business. Both land in a single update_device call
     * because the dispatcher accepts multiple writable fields in one
     * payload.
     *
     * @param  array<int, string>  $changedFields
     */
    public function push(Asset $asset, array $changedFields = []): bool
    {
        $externalSource = $this->pushPrologue($asset, $changedFields);
        if ($externalSource === null) {
            return false;
        }

        $serial = $asset->serial;
        if ($serial === null || $serial === '') {
            $serial = $externalSource->external_id;
        }

        $fields = [];
        $pushedLabels = [];

        if (in_array('asset_tag', $this->pushDirectedFields(), true)) {
            $value = $this->assetValueForSourceField($asset, 'asset_tag');
            if ($value !== null && $value !== '') {
                $fields['asset_tag'] = (string) $value;
                $pushedLabels[] = 'asset_tag';
            }
        }

        $composedNotes = $this->composeNotesForPush($asset);
        if ($composedNotes !== null) {
            $fields[$composedNotes['target']] = $composedNotes['value'];
            $pushedLabels[] = 'notes';
        }

        if ($fields === []) {
            return false;
        }

        if ($this->isPushDryRun()) {
            Log::channel('sync-adapters')->info(
                $this->name().' push [dry-run]: would update Mosyle Business device serial='.$serial.' fields ['.implode(', ', $pushedLabels).']'
            );

            return true;
        }

        $this->makeClient()->updateDeviceBySerial($serial, $fields);

        Log::channel('sync-adapters')->info(
            $this->name().' push: updated Mosyle Business device serial='.$serial.' fields ['.implode(', ', $pushedLabels).']'
        );

        return true;
    }

    private function makeClient(): MosyleBusinessClient
    {
        return new MosyleBusinessClient(
            baseUrl: $this->url(),
            accessToken: $this->credential('access_token'),
            email: $this->credential('email'),
            password: $this->credential('password'),
        );
    }
}