Skip to content

A free open source IT asset/license management system

10.6 KB
Raw Blame
<?php

namespace App\SyncAdapters\Kandji;

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;

/**
 * Kandji adapter. Pulls device inventory from a Kandji tenant via the
 * Kandji Enterprise API and normalizes it into HostInventoryRecord
 * objects. Also pushes Snipe-IT-authoritative fields back to Kandji
 * (asset_tag today) when the admin marks the mapping row as 'push'.
 */
class KandjiAdapter extends PushableSyncAdapter
{
    use UsesAppleDbEnrichment;

    public static function typeLabel(): string
    {
        return 'Iru (Kandji)';
    }

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

    public static function docsUrl(): ?string
    {
        return 'https://api-docs.kandji.io/';
    }

    public function baseUrlPlaceholder(): ?string
    {
        return 'https://your-subdomain.api.kandji.io';
    }

    public function baseUrlHelp(): ?string
    {
        return trans('admin/settings/sync_adapters.kandji_base_url_help');
    }

    public function settingsSchema(): array
    {
        return [
            [
                'key' => 'token',
                'label' => trans('admin/settings/sync_adapters.label_api_token'),
                'secret' => true,
                'help' => trans('admin/settings/sync_adapters.kandji_token_help'),
            ],
            $this->appleDbSettingsField(),
        ];
    }

    public function extraFields(): array
    {
        return [
            ...$this->appleDbExtraFieldsDeclaration(),
            'kandji_blueprint_id' => ['label_key' => 'admin/settings/sync_adapters.extra_blueprint_id'],
            'kandji_mdm_enabled' => ['label_key' => 'admin/settings/sync_adapters.extra_mdm_enabled', 'type' => 'boolean'],
            'kandji_is_missing' => ['label_key' => 'admin/settings/sync_adapters.extra_marked_missing', 'type' => 'boolean'],
            'kandji_model_identifier' => ['label_key' => 'admin/settings/sync_adapters.extra_model_identifier'],
        ];
    }

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

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

    public function fetchGroups(): array
    {
        $client = new KandjiClient(baseUrl: $this->url(), token: $this->credential('token'));

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

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

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

        foreach ($client->devices() as $device) {
            // Kandji's list endpoint omits the AppleDB-shape hardware
            // identifier so an enrichment-enabled pull hits
            // /devices/{id}/details per record. Pays N+1 API cost for
            // the enrichment, which is why the toggle is opt-in.
            $identifier = null;
            if ($enrichmentEnabled && Arr::get($device, 'platform') !== null) {
                $details = $client->deviceDetails((string) Arr::get($device, 'device_id'));
                $identifier = $details !== null ? $this->extractKandjiIdentifier($details) : null;
            }

            $record = $this->normalize($device, $identifier);
            if ($enrichmentEnabled) {
                $enrichmentHandled = $this->enrichFromAppleDb($record, $enrichmentHandled);
            }
            yield $record;
        }
    }

    /**
     * Kandji's /devices/{id}/details response nests the AppleDB-
     * shape identifier under hardware_overview on Macs. iPads /
     * iPhones place the equivalent under a different key depending
     * on the model class, so walk the two most common locations and
     * accept whichever responds. Non-Apple devices (if Kandji ever
     * adds them) are already filtered out before this is called via
     * the enrichment toggle gate.
     *
     * @param  array<string, mixed>  $details
     */
    private function extractKandjiIdentifier(array $details): ?string
    {
        $identifier = Arr::get($details, 'hardware_overview.model_identifier')
            ?? Arr::get($details, 'general.model_identifier');

        return is_string($identifier) && $identifier !== '' ? $identifier : null;
    }

    /**
     * Pass the Kandji record to the shared enrichment flow. Uses
     * the normalized hardwareModel as the AssetModel name, same as
     * the list-endpoint behavior before enrichment landed. The
     * details-fetched identifier flows through the record extras.
     *
     * @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['kandji_model_identifier'] ?? null;
        if (! is_string($productType) || $productType === '') {
            return $handled;
        }

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

    /**
     * Convert a Kandji device payload into the normalized record shape.
     * Kandji's `device_id` is stable per enrolled device and is what we
     * key asset_external_sources on.
     *
     * The bulk /devices endpoint doesn't return network interfaces, so
     * primaryMac stays null here. A future enrichment pass could hit
     * /devices/{id}/details per record to fill it in, at the cost of
     * N+1 requests per sync run.
     *
     * @param  array<string, mixed>  $device
     */
    private function normalize(array $device, ?string $modelIdentifier = null): HostInventoryRecord
    {
        $modelName = Arr::get($device, 'model');
        $canonical = $this->canonicalIdentityFor($modelIdentifier, $modelName);
        $appleDbExtras = $this->appleDbExtrasFor($modelIdentifier, $modelName);

        return new HostInventoryRecord(
            sourceKey: $this->name(),
            sourceId: (string) Arr::get($device, 'device_id'),
            hostname: Arr::get($device, 'device_name'),
            hardwareSerial: Arr::get($device, 'serial_number'),
            hardwareModel: $modelName,
            manufacturer: Arr::get($device, 'platform') === 'Mac' ? 'Apple' : null,
            primaryMac: null,
            primaryIp: null,
            os: Arr::get($device, 'platform'),
            osVersion: Arr::get($device, 'os_version'),
            lastSeen: $this->parseTimestamp(Arr::get($device, 'last_check_in')),
            assetTag: Arr::get($device, 'asset_tag'),
            assignedUserEmail: Arr::get($device, 'user.email'),
            assignedUserName: Arr::get($device, 'user.name'),
            vendorGroupId: Arr::has($device, 'assigned_blueprint_id') ? (string) Arr::get($device, 'assigned_blueprint_id') : null,
            extra: [
                ...$appleDbExtras,
                'kandji_blueprint_id' => Arr::get($device, 'assigned_blueprint_id'),
                'kandji_mdm_enabled' => Arr::get($device, 'mdm_enabled'),
                'kandji_is_missing' => Arr::get($device, 'is_missing'),
                'kandji_model_identifier' => $modelIdentifier,
            ],
            canonicalMarketingName: $canonical['canonicalMarketingName'],
            canonicalModelNumber: $canonical['canonicalModelNumber'],
        );
    }

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

        return Carbon::parse($value);
    }

    /**
     * Kandji's device API accepts writes on any Admin API token so
     * push is always available for a configured instance (no tier
     * gate the way Fleet's manual labels have).
     */
    public function canPush(): bool
    {
        return true;
    }

    /**
     * Kandji devices carry a single freeform `notes` field that
     * admins commonly repurpose for composed asset info from
     * Snipe-IT. When the admin has set a push_notes_template we
     * render it via composeNotesForPush() and PATCH the notes field
     * alongside any other push-directed fields.
     */
    public function notesFieldTarget(): ?string
    {
        return 'notes';
    }

    /**
     * Push Snipe-IT-authoritative fields to Kandji. Delegates to the
     * base template, which runs the prologue guards, splices composed
     * notes, handles the dry-run branch, and writes the success log
     * line. Kandji provides the vendor-shape payload and the vendor
     * dispatch call via the two hooks below.
     *
     * @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 = [];
        foreach ($this->pushDirectedFields() as $field) {
            $mapped = self::sourceFieldToKandjiField($field);
            if ($mapped === null) {
                continue;
            }

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

            $payload[$mapped] = $value;
        }

        return [$payload, []];
    }

    /**
     * @param  array<string, mixed>  $payload
     */
    protected function dispatchPush(\App\Models\AssetExternalSource $externalSource, array $payload): void
    {
        $client = new KandjiClient(baseUrl: $this->url(), token: $this->credential('token'));
        $client->updateDevice($externalSource->external_id, $payload);
    }

    /**
     * Map a source-field name (from MappingTargets::FIELDS or the
     * adapter's extraFields) to Kandji's device-endpoint form field
     * name. Returns null when there's no writable equivalent, which
     * excludes read-only vendor state like hostname (Kandji derives
     * it from the device itself, not admin metadata).
     */
    private static function sourceFieldToKandjiField(string $field): ?string
    {
        return match ($field) {
            'asset_tag' => 'asset_tag',
            default => null,
        };
    }
}