Skip to content

A free open source IT asset/license management system

7.9 KB
Raw Blame
<?php

namespace App\SyncAdapters\JumpCloud;

use App\SyncAdapters\HostInventoryRecord;
use App\SyncAdapters\SyncAdapter;
use Carbon\Carbon;
use Illuminate\Http\Client\RequestException;
use Illuminate\Support\Arr;
use Illuminate\Support\Facades\Log;

/**
 * JumpCloud adapter. Pulls managed-system inventory via the JumpCloud
 * Systems API and normalizes it into HostInventoryRecord objects.
 * Auth uses the tenant's static API key in the x-api-key header, not
 * a bearer token.
 */
class JumpCloudAdapter extends SyncAdapter
{
    public static function typeLabel(): string
    {
        return 'JumpCloud';
    }

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

    public static function docsUrl(): ?string
    {
        return 'https://docs.jumpcloud.com/api/2.0/index.html';
    }

    public function baseUrlPlaceholder(): ?string
    {
        return 'https://console.jumpcloud.com/api';
    }

    public function settingsSchema(): array
    {
        return [
            [
                'key' => 'token',
                'label' => trans('admin/settings/sync_adapters.label_api_key'),
                'secret' => true,
                'help' => trans('admin/settings/sync_adapters.jumpcloud_token_help'),
            ],
        ];
    }

    public function extraFields(): array
    {
        return [
            'jumpcloud_arch' => ['label_key' => 'admin/settings/sync_adapters.extra_architecture'],
            'jumpcloud_os_family' => ['label_key' => 'admin/settings/sync_adapters.extra_os_family'],
            'jumpcloud_agent_version' => ['label_key' => 'admin/settings/sync_adapters.extra_agent_version'],
            'jumpcloud_active' => ['label_key' => 'admin/settings/sync_adapters.extra_active', 'type' => 'boolean'],
        ];
    }

    public function pull(): iterable
    {
        $client = new JumpCloudClient(baseUrl: $this->url(), apiKey: $this->credential('token'));

        // V2 System Insights carries the authoritative hardware_model
        // and hardware_vendor strings for every OS. V1 /systems only
        // has `systemType` (free-form, often null for non-Mac) and no
        // vendor. Prefetch once, join on system_id while iterating V1.
        //
        // System Insights is included on every paid JumpCloud plan,
        // but a scoped API key without the right permission bits can
        // still 403. A 403 (or any transport error) here is not fatal,
        // we fall back to V1-only normalization and the record keeps
        // the same way it worked before this adapter added V2 support.
        $insightsBySystemId = $this->fetchSystemInsights($client);

        foreach ($client->systems() as $system) {
            $systemId = (string) Arr::get($system, '_id');
            $insight = $insightsBySystemId[$systemId] ?? null;
            yield $this->normalize($system, $insight);
        }
    }

    /**
     * Load every V2 System Insights `system_info` record into a map
     * keyed by system_id. Returns an empty array when the API key is
     * missing System Insights permission (403) or when the endpoint
     * fails for any other reason. The adapter then falls back to V1
     * fields on every record.
     *
     * @return array<string, array<string, mixed>>
     */
    private function fetchSystemInsights(JumpCloudClient $client): array
    {
        $map = [];

        try {
            foreach ($client->systemInsights() as $insight) {
                $systemId = Arr::get($insight, 'system_id');
                if (is_string($systemId) && $systemId !== '') {
                    $map[$systemId] = $insight;
                }
            }
        } catch (RequestException $e) {
            // 403 is the signal that this tenant's plan does not
            // include System Insights, which is a design-expected
            // outcome, not a configuration bug. Lower the log level
            // and keep going. Other 4xx/5xx get warning-level since
            // they likely need operator attention.
            $status = $e->response->status();
            if ($status === 403) {
                Log::channel('sync-adapters')->info(
                    $this->name().': API key does not have System Insights permission (403), falling back to V1 /systems fields only.',
                );

                return $map;
            }

            Log::channel('sync-adapters')->warning(
                $this->name().': V2 System Insights fetch failed (HTTP '.$status.'), falling back to V1 /systems fields only.',
                ['exception' => $e->getMessage()],
            );
        }

        return $map;
    }

    /**
     * Convert a JumpCloud system payload into the normalized record
     * shape. JumpCloud's `_id` is stable per enrolled system and is
     * what we key asset_external_sources on.
     *
     * When a V2 System Insights record is available for the same
     * system_id, prefer its hardware_model and hardware_vendor since
     * those are the fields JumpCloud actually populates for every OS.
     * V1 systemType / the darwin => Apple guess are the fallbacks.
     *
     * The bulk /systems endpoint doesn't return network interfaces, so
     * primaryMac stays null. A future enrichment pass could hit
     * /systems/{id}/networkinterfaces per record to fill it in, at the
     * cost of N+1 requests per sync run.
     *
     * @param  array<string, mixed>  $system
     * @param  array<string, mixed>|null  $insight
     */
    private function normalize(array $system, ?array $insight = null): HostInventoryRecord
    {
        $insightModel = $insight !== null ? Arr::get($insight, 'hardware_model') : null;
        $insightVendor = $insight !== null ? Arr::get($insight, 'hardware_vendor') : null;

        return new HostInventoryRecord(
            sourceKey: $this->name(),
            sourceId: (string) Arr::get($system, '_id'),
            hostname: Arr::get($system, 'hostname') ?? Arr::get($system, 'displayName'),
            hardwareSerial: Arr::get($system, 'serialNumber'),
            hardwareModel: $this->firstNonEmptyString($insightModel, Arr::get($system, 'systemType')),
            manufacturer: $this->firstNonEmptyString($insightVendor, $this->guessManufacturer(Arr::get($system, 'osFamily'))),
            primaryMac: null,
            primaryIp: null,
            os: Arr::get($system, 'os'),
            osVersion: Arr::get($system, 'version'),
            lastSeen: $this->parseTimestamp(Arr::get($system, 'lastContact')),
            extra: [
                'jumpcloud_arch' => Arr::get($system, 'arch'),
                'jumpcloud_os_family' => Arr::get($system, 'osFamily'),
                'jumpcloud_agent_version' => Arr::get($system, 'agentVersion'),
                'jumpcloud_active' => Arr::get($system, 'active'),
            ],
        );
    }

    /**
     * Pick the first non-empty string from the arguments, or null when
     * none qualify. Lets normalize() express "prefer V2, fall back to
     * V1" without triggering on empty strings that V2 sometimes emits
     * for fields the agent could not collect.
     */
    private function firstNonEmptyString(mixed ...$candidates): ?string
    {
        foreach ($candidates as $candidate) {
            if (is_string($candidate) && $candidate !== '') {
                return $candidate;
            }
        }

        return null;
    }

    /**
     * JumpCloud V1 doesn't return a manufacturer field. Infer from
     * osFamily so downstream mapping still gets a reasonable value
     * when the V2 hardware_vendor fallback also isn't available.
     * darwin => Apple, windows / linux stay unknown because the vendor
     * varies per hardware.
     */
    private function guessManufacturer(?string $osFamily): ?string
    {
        return $osFamily === 'darwin' ? 'Apple' : null;
    }

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

        return Carbon::parse($value);
    }
}