Skip to content

A free open source IT asset/license management system

23.6 KB
Raw Blame
<?php

namespace App\SyncAdapters\Jamf;

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;

/**
 * Jamf Pro adapter. Pulls computer inventory via the Jamf Pro API and
 * normalizes it into HostInventoryRecord objects. Authenticates via
 * OAuth 2.0 client credentials against Jamf Pro's /api/oauth/token
 * endpoint (Jamf Pro does not issue long-lived personal tokens, so
 * this is the only workable flow). Also pushes Snipe-IT-authoritative
 * fields (asset_tag today) back to Jamf via the
 * /api/v1/computers-inventory-detail/{id} PATCH endpoint using the
 * same exchanged bearer.
 */
class JamfAdapter extends PushableSyncAdapter
{
    use UsesAppleDbEnrichment;

    public static function typeLabel(): string
    {
        return 'Jamf Pro';
    }

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

    public static function docsUrl(): ?string
    {
        return 'https://developer.jamf.com/jamf-pro/reference';
    }

    public function baseUrlPlaceholder(): ?string
    {
        return 'https://your-subdomain.jamfcloud.com';
    }

    public function settingsSchema(): array
    {
        return [
            [
                'key' => 'client_id',
                'label' => trans('admin/settings/sync_adapters.label_client_id'),
                'help' => trans('admin/settings/sync_adapters.jamf_client_id_help'),
            ],
            [
                'key' => 'client_secret',
                'label' => trans('admin/settings/sync_adapters.label_client_secret'),
                'secret' => true,
                'help' => trans('admin/settings/sync_adapters.jamf_client_secret_help'),
            ],
            [
                'key' => 'include_mobile_devices',
                'label' => trans('admin/settings/sync_adapters.jamf_label_include_mobile_devices'),
                'type' => 'checkbox',
                'required' => false,
                'help' => trans('admin/settings/sync_adapters.jamf_include_mobile_devices_help'),
            ],
            [
                'key' => 'group_filter',
                'label' => trans('admin/settings/sync_adapters.jamf_group_filter_label'),
                'required' => false,
                'help' => trans('admin/settings/sync_adapters.jamf_group_filter_help'),
            ],
            $this->appleDbSettingsField(),
        ];
    }

    public function extraFields(): array
    {
        return [
            ...$this->appleDbExtraFieldsDeclaration(),
            'jamf_udid' => ['label_key' => 'admin/settings/sync_adapters.extra_udid'],
            'jamf_last_enrolled' => ['label_key' => 'admin/settings/sync_adapters.extra_last_enrolled', 'type' => 'date'],
            'jamf_model_identifier' => ['label_key' => 'admin/settings/sync_adapters.extra_model_identifier'],
            // Computer-only hardware fields. Values normalize to GB so
            // they line up with the other adapters (Addigy, Levelio,
            // Mosyle, AxM device_capacity) which all speak GB natively.
            // Conversion from Jamf's native MB divides by 1000 (decimal
            // GB, same convention Apple uses in marketed capacity).
            'jamf_ram_gb' => ['label_key' => 'admin/settings/sync_adapters.jamf_extra_ram_gb'],
            'jamf_storage_gb' => ['label_key' => 'admin/settings/sync_adapters.jamf_extra_storage_gb'],
            // Mobile-only fields. Blank on computer records so admins
            // can still map them without worrying about overwriting a
            // computer's custom field with an empty string.
            'jamf_mobile_device_type' => ['label_key' => 'admin/settings/sync_adapters.jamf_extra_mobile_device_type'],
            'jamf_mobile_managed' => ['label_key' => 'admin/settings/sync_adapters.jamf_extra_mobile_managed', 'type' => 'boolean'],
            'jamf_mobile_supervised' => ['label_key' => 'admin/settings/sync_adapters.jamf_extra_mobile_supervised', 'type' => 'boolean'],
            'jamf_mobile_storage_gb' => ['label_key' => 'admin/settings/sync_adapters.jamf_extra_mobile_storage_gb'],
        ];
    }

    public function supportsGroupScoping(): bool
    {
        return true;
    }

    public function vendorGroupLabel(): string
    {
        return trans('admin/settings/sync_adapters.vendor_group_jamf_site');
    }

    public function fetchGroups(): array
    {
        $client = new JamfClient(
            baseUrl: $this->url(),
            clientId: $this->credential('client_id'),
            clientSecret: $this->credential('client_secret'),
        );

        return array_map(
            fn (array $site) => [
                'id' => (string) ($site['id'] ?? ''),
                'label' => (string) ($site['name'] ?? $site['id'] ?? '?'),
            ],
            $client->sites(),
        );
    }

    public function pull(): iterable
    {
        $client = new JamfClient(
            baseUrl: $this->url(),
            clientId: $this->credential('client_id'),
            clientSecret: $this->credential('client_secret'),
        );

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

        $filter = $this->resolveGroupFilter($client);

        foreach ($client->computers() as $computer) {
            if ($filter !== null && ! isset($filter['computerIds'][(int) Arr::get($computer, 'id')])) {
                continue;
            }
            $record = $this->normalizeComputer($computer);
            if ($enrichmentEnabled) {
                $enrichmentHandled = $this->enrichFromAppleDb($record, $enrichmentHandled);
            }
            yield $record;
        }

        if ($this->shouldPullMobileDevices()) {
            foreach ($client->mobileDevices() as $device) {
                if ($filter !== null && ! isset($filter['mobileIds'][(int) Arr::get($device, 'id')])) {
                    continue;
                }
                $record = $this->normalizeMobileDevice($device);
                if ($enrichmentEnabled) {
                    $enrichmentHandled = $this->enrichFromAppleDb($record, $enrichmentHandled);
                }
                yield $record;
            }
        }
    }

    /**
     * Resolve the admin-entered group_filter into the union of computer
     * and mobile-device IDs that belong to any of the named groups.
     * Entries can be group names (friendly) or raw IDs (short-circuit).
     * Names are resolved against the full group list once per sync.
     * Unresolvable names log a warning and get skipped, matching the
     * Intune scope-tag flow, so one bad entry does not kill the pull.
     *
     * Mobile device groups are only consulted when the include-mobile
     * toggle is also on, so Jamf tenants that don't have mobile devices
     * enabled never pay for the extra classic-API calls.
     *
     * Returns null when no filter is configured so the pull short-
     * circuits the membership gate entirely.
     *
     * @return array{computerIds: array<int, int>, mobileIds: array<int, int>}|null
     */
    private function resolveGroupFilter(JamfClient $client): ?array
    {
        $raw = '';
        try {
            $raw = (string) $this->credential('group_filter');
        } catch (\Throwable) {
            // Credential not set yet. Treat as unconfigured.
        }

        $entries = array_values(array_filter(array_map('trim', explode(',', $raw))));
        if ($entries === []) {
            return null;
        }

        $computerIds = [];
        $mobileIds = [];

        $this->collectMembersForFilter(
            $entries,
            $client->computerGroups(),
            fn (int $id) => $client->computerGroupMembers($id),
            $computerIds,
            'computer',
        );

        if ($this->shouldPullMobileDevices()) {
            $this->collectMembersForFilter(
                $entries,
                $client->mobileDeviceGroups(),
                fn (int $id) => $client->mobileDeviceGroupMembers($id),
                $mobileIds,
                'mobile',
            );
        }

        return [
            'computerIds' => array_flip($computerIds),
            'mobileIds' => array_flip($mobileIds),
        ];
    }

    /**
     * Shared resolution helper used for both computer groups and mobile
     * device groups. Builds a name-and-id index from the group list,
     * resolves each entry to a concrete group id, and asks $memberFetcher
     * for that group's members. Unresolvable entries log once per
     * namespace so an admin typo in a filter names "Law School Macs" is
     * visible in the sync-adapters log.
     *
     * @param  array<int, string>  $entries
     * @param  array<int, array<string, mixed>>  $groups
     * @param  callable(int): array<int, int>  $memberFetcher
     * @param  array<int, int>  &$into
     */
    private function collectMembersForFilter(
        array $entries,
        array $groups,
        callable $memberFetcher,
        array &$into,
        string $namespace,
    ): void {
        $nameToId = [];
        $idSet = [];
        foreach ($groups as $group) {
            $name = (string) ($group['name'] ?? '');
            $id = isset($group['id']) ? (int) $group['id'] : null;
            if ($name === '' || $id === null) {
                continue;
            }
            $nameToId[strtolower($name)] = $id;
            $idSet[$id] = true;
        }

        foreach ($entries as $entry) {
            $lower = strtolower($entry);
            $groupId = null;
            if (isset($nameToId[$lower])) {
                $groupId = $nameToId[$lower];
            } elseif (ctype_digit($entry) && isset($idSet[(int) $entry])) {
                $groupId = (int) $entry;
            }

            if ($groupId === null) {
                // Computer groups and mobile-device groups are separate
                // namespaces in Jamf. An entry that doesn't resolve in
                // this namespace may still resolve in the other, so log
                // debug rather than warn here. A true typo is caught
                // because it fails in both namespaces and the admin
                // notices zero devices are matching.
                Log::channel('sync-adapters')->debug(sprintf(
                    '%s: group_filter entry "%s" did not match any %s group. Skipping in this namespace.',
                    $this->name(),
                    $entry,
                    $namespace,
                ));

                continue;
            }

            foreach ($memberFetcher($groupId) as $memberId) {
                $into[] = $memberId;
            }
        }
    }

    /**
     * Pass the Jamf record to the shared enrichment flow. Both the
     * computer and mobile normalize paths put the AppleDB-shape
     * hardware identifier into jamf_model_identifier, so the lookup
     * is unified here. hardwareModel ends up as the AssetModel name
     * (Jamf's model string is already the marketing-ish shape
     * admins see in Snipe-IT today).
     *
     * @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['jamf_model_identifier'] ?? null;
        if (! is_string($productType) || $productType === '') {
            return $handled;
        }

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

    /**
     * Opt-in toggle for syncing iOS / iPadOS / tvOS devices alongside
     * computers. Off by default so adding the mobile pull doesn't
     * surprise existing installs on their next scheduled run. Reads via
     * credential() because the base class's config storage treats
     * every schema entry (secret or not) through the same get/set
     * path.
     */
    private function shouldPullMobileDevices(): bool
    {
        try {
            return $this->credential('include_mobile_devices') === '1';
        } catch (\Throwable) {
            return false;
        }
    }

    /**
     * Convert a Jamf computer payload into the normalized record shape.
     * Jamf's numeric `id` is stable per enrollment and is what we key
     * asset_external_sources on. Fields come from the GENERAL, HARDWARE, and
     * OPERATING_SYSTEM sections (the client only requests those).
     *
     * Computer sourceIds stay bare numeric to preserve back-compat with
     * every existing asset_external_sources.external_id row written by
     * this adapter before mobile support landed. The mobile path uses a
     * `mobile:` prefix instead to keep the two Jamf namespaces from
     * colliding (Jamf's computer id 42 and mobile id 42 are unrelated).
     *
     * @param  array<string, mixed>  $computer
     */
    private function normalizeComputer(array $computer): HostInventoryRecord
    {
        $productType = Arr::get($computer, 'hardware.modelIdentifier');
        $modelName = Arr::get($computer, 'hardware.model');
        $canonical = $this->canonicalIdentityFor($productType, $modelName);
        $appleDbExtras = $this->appleDbExtrasFor($productType, $modelName);

        return new HostInventoryRecord(
            sourceKey: $this->name(),
            sourceId: (string) Arr::get($computer, 'id'),
            hostname: Arr::get($computer, 'general.name'),
            hardwareSerial: Arr::get($computer, 'hardware.serialNumber'),
            hardwareModel: Arr::get($computer, 'hardware.model'),
            manufacturer: Arr::get($computer, 'hardware.make'),
            primaryMac: Arr::get($computer, 'hardware.macAddress'),
            primaryIp: null,
            os: Arr::get($computer, 'operatingSystem.name'),
            osVersion: Arr::get($computer, 'operatingSystem.version'),
            lastSeen: $this->parseTimestamp(Arr::get($computer, 'general.lastContactTime')),
            assetTag: Arr::get($computer, 'general.assetTag'),
            assignedUserEmail: Arr::get($computer, 'userAndLocation.email'),
            assignedUserName: Arr::get($computer, 'userAndLocation.username'),
            vendorGroupId: Arr::has($computer, 'general.site.id') ? (string) Arr::get($computer, 'general.site.id') : null,
            extra: [
                ...$appleDbExtras,
                'jamf_udid' => Arr::get($computer, 'udid'),
                'jamf_last_enrolled' => Arr::get($computer, 'general.lastEnrolledDate'),
                'jamf_model_identifier' => Arr::get($computer, 'hardware.modelIdentifier'),
                'jamf_ram_gb' => self::megabytesToGb(Arr::get($computer, 'hardware.totalRamMegabytes')),
                'jamf_storage_gb' => self::megabytesToGb(self::primaryDiskMegabytes($computer)),
            ],
            canonicalMarketingName: $canonical['canonicalMarketingName'],
            canonicalModelNumber: $canonical['canonicalModelNumber'],
        );
    }

    /**
     * Extract the Mac's internal boot disk size from a Jamf STORAGE
     * section. Jamf returns an array of disks under storage.disks that
     * includes any external drive plugged in at inventory time, so
     * taking the first disk or summing the array would inflate the
     * value. Each disk's partitions carry a partitionType enum, and
     * exactly one partition across the whole machine carries
     * partitionType="BOOT" (the macOS boot volume), so the disk that
     * contains that partition is the internal SSD. Fall back to
     * disks[0] when Jamf doesn't tag any partition as BOOT (older
     * Jamf versions and some edge states), which is still correct in
     * practice because the first disk is disk0 on every modern Mac.
     *
     * Returns null when Jamf didn't return a storage section for this
     * computer (common on offline-at-inventory machines or on tenants
     * that haven't enabled STORAGE collection).
     *
     * @param  array<string, mixed>  $computer
     */
    /**
     * Normalize an MB value to GB for cross-adapter unit consistency.
     * Divides by 1000 (decimal), matching Apple's marketed-capacity
     * convention and the GB unit the other storage/memory extras
     * across sync adapters already use. Null/non-numeric input returns
     * null so empty storage sections stay empty rather than becoming 0
     * (which an admin filter would misread as a real zero-GB value).
     */
    private static function megabytesToGb(mixed $megabytes): int|float|null
    {
        if (! is_numeric($megabytes)) {
            return null;
        }
        $gb = $megabytes / 1000;

        return $gb == (int) $gb ? (int) $gb : round($gb, 2);
    }

    private static function primaryDiskMegabytes(array $computer): ?int
    {
        $disks = Arr::get($computer, 'storage.disks');
        if (! is_array($disks) || $disks === []) {
            return null;
        }

        foreach ($disks as $disk) {
            $partitions = Arr::get($disk, 'partitions', []);
            if (! is_array($partitions)) {
                continue;
            }
            foreach ($partitions as $partition) {
                if ((Arr::get($partition, 'partitionType') ?? '') === 'BOOT') {
                    $size = Arr::get($disk, 'sizeMegabytes');

                    return is_numeric($size) ? (int) $size : null;
                }
            }
        }

        $size = Arr::get($disks[0], 'sizeMegabytes');

        return is_numeric($size) ? (int) $size : null;
    }

    /**
     * Convert a /api/v2/mobile-devices list entry into the normalized
     * record shape. Mobile Jamf payloads are flatter than computer
     * ones: everything except assigned-user info lives at the top
     * level, so no section dot-paths. Manufacturer isn't carried
     * either (Jamf Pro's mobile fleet is Apple-only in practice), so
     * we hard-code 'Apple' to match what the computer path emits for
     * macs and let model-dedup land both on the same manufacturer.
     *
     * @param  array<string, mixed>  $device
     */
    private function normalizeMobileDevice(array $device): HostInventoryRecord
    {
        $sourceId = 'mobile:'.(string) Arr::get($device, 'id');
        $productType = Arr::get($device, 'modelIdentifier');
        $modelName = Arr::get($device, 'model');
        $canonical = $this->canonicalIdentityFor($productType, $modelName);
        $appleDbExtras = $this->appleDbExtrasFor($productType, $modelName);

        return new HostInventoryRecord(
            sourceKey: $this->name(),
            sourceId: $sourceId,
            hostname: Arr::get($device, 'name'),
            hardwareSerial: Arr::get($device, 'serialNumber'),
            hardwareModel: Arr::get($device, 'model'),
            manufacturer: 'Apple',
            primaryMac: Arr::get($device, 'wifiMacAddress'),
            primaryIp: Arr::get($device, 'ipAddress'),
            os: Arr::get($device, 'osType'),
            osVersion: Arr::get($device, 'osVersion'),
            lastSeen: $this->parseTimestamp(Arr::get($device, 'lastInventoryUpdateTimestamp')),
            assetTag: Arr::get($device, 'assetTag'),
            assignedUserEmail: Arr::get($device, 'location.emailAddress'),
            assignedUserName: Arr::get($device, 'location.username'),
            vendorGroupId: Arr::has($device, 'site.id') ? (string) Arr::get($device, 'site.id') : null,
            extra: [
                ...$appleDbExtras,
                'jamf_udid' => Arr::get($device, 'udid'),
                'jamf_model_identifier' => Arr::get($device, 'modelIdentifier'),
                'jamf_mobile_device_type' => Arr::get($device, 'deviceType'),
                'jamf_mobile_managed' => Arr::get($device, 'managed'),
                'jamf_mobile_supervised' => Arr::get($device, 'supervised'),
                'jamf_mobile_storage_gb' => self::megabytesToGb(Arr::get($device, 'capacityMb')),
            ],
            canonicalMarketingName: $canonical['canonicalMarketingName'],
            canonicalModelNumber: $canonical['canonicalModelNumber'],
        );
    }

    private function parseTimestamp(mixed $value): ?Carbon
    {
        if ($value === null || $value === '') {
            return null;
        }

        return Carbon::parse($value);
    }

    /**
     * Jamf Pro writes are gated by the API Client's role privileges.
     * Both pull + push work with the same OAuth client when the role
     * grants the "Update Computers" privilege. No tier / license gate,
     * so canPush is always true for a configured instance.
     */
    public function canPush(): bool
    {
        return true;
    }

    /**
     * Jamf Pro's computer record has a freeform notes field at
     * general.notes on the inventory-detail JSON. Dotted path so
     * Arr::set can slot the composed value into the right nested
     * object.
     */
    public function notesFieldTarget(): ?string
    {
        return 'general.notes';
    }

    /**
     * Push Snipe-IT-authoritative fields to Jamf Pro via the newer
     * JSON detail endpoint. The payload uses Jamf's nested-object
     * shape (assetTag lives inside general per the ComputerGeneralUpdate
     * schema, not userAndLocation), so sourceFieldToJamfPath() returns
     * dotted paths that get assembled via Arr::set before the PATCH.
     *
     * @param  array<int, string>  $changedFields
     */
    public function push(Asset $asset, array $changedFields = []): bool
    {
        return $this->pushViaSinglePayload($asset, $changedFields);
    }

    /**
     * @return array{0: array<string, mixed>, 1: array<int, string>}
     */
    protected function buildPushPayload(Asset $asset): array
    {
        $payload = [];
        $touched = [];
        foreach ($this->pushDirectedFields() as $field) {
            $path = self::sourceFieldToJamfPath($field);
            if ($path === null) {
                continue;
            }

            $value = $this->assetValueForSourceField($asset, $field);
            if ($value === null) {
                continue;
            }

            Arr::set($payload, $path, $value);
            $touched[] = $path;
        }

        return [$payload, $touched];
    }

    /**
     * @param  array<string, mixed>  $payload
     */
    protected function dispatchPush(\App\Models\AssetExternalSource $externalSource, array $payload): void
    {
        // Mobile Jamf devices are pull-only in this adapter. The push
        // path only runs against /api/v1/computers-inventory-detail, so
        // short-circuit on the `mobile:` prefix the mobile normalizer
        // writes. Snipe-IT-authoritative fields on a mobile asset stay
        // local to Snipe-IT.
        if (str_starts_with($externalSource->external_id, 'mobile:')) {
            return;
        }

        $client = new JamfClient(
            baseUrl: $this->url(),
            clientId: $this->credential('client_id'),
            clientSecret: $this->credential('client_secret'),
        );
        $client->updateComputerDetail($externalSource->external_id, $payload);
    }

    /**
     * Map a source-field name to its dotted path in Jamf's
     * computers-inventory-detail JSON. Return null for fields Jamf
     * doesn't expose as writable (hostname is derived from the device
     * itself, not admin-settable).
     */
    private static function sourceFieldToJamfPath(string $field): ?string
    {
        return match ($field) {
            // Jamf's ComputerGeneralUpdate schema is where assetTag
            // lives. userAndLocation does NOT accept assetTag on the
            // PATCH side (confirmed against Jamf Pro 11.32 OpenAPI
            // schema, see issue #19851). The pull side already reads
            // from general.assetTag, so push matches.
            'asset_tag' => 'general.assetTag',
            default => null,
        };
    }
}