Skip to content

A free open source IT asset/license management system

7.2 KB
Raw Blame
<?php

namespace App\SyncAdapters\Unifi;

use App\SyncAdapters\HostInventoryRecord;
use App\SyncAdapters\SyncAdapter;
use Carbon\Carbon;
use Illuminate\Support\Arr;

/**
 * UniFi adapter. Pulls network-hardware inventory (APs, switches,
 * gateways, cameras) from a UniFi controller and normalizes it into
 * HostInventoryRecord objects.
 *
 * Uses UniFi's modern Network Integration API with X-API-KEY bearer
 * auth (UniFi OS 4.0.6+ / Network Application 9.0.108+ / Site Manager
 * cloud). Older controllers on session-cookie auth are not supported.
 * Admins should upgrade UniFi rather than us carrying the legacy
 * cookie flow.
 *
 * Site scoping: the UniFi API is site-scoped. The Site ID field pins
 * this instance to one site. Multi-site controllers create one
 * sync-adapter instance per site (each with its own tab under
 * Settings -> Sync Adapters).
 */
class UnifiAdapter extends SyncAdapter
{
    public static function typeLabel(): string
    {
        return 'UniFi';
    }

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

    public static function docsUrl(): ?string
    {
        return 'https://developer.ui.com/network/v10.4.57/gettingstarted';
    }

    public function baseUrlPlaceholder(): ?string
    {
        // A local UniFi console / Network Application
        // reachable from this Snipe-IT install, or `https://api.ui.com`
        // for the Site Manager cloud API (the latter is what hosted
        // Snipe-IT installs want when the UniFi consoles are behind NAT).
        return 'https://your-controller:8443 or https://api.ui.com';
    }

    public function settingsSchema(): array
    {
        // Site ID renders as a select backed by cachedSites(). Admins
        // hit "Refresh Sites" (gated on api_key + base URL being set)
        // to populate it from the vendor. Before that, the only option
        // is whatever value is already stored, so a mid-upgrade admin
        // who had "default" saved under the old help text still sees
        // their stale value and can swap once they refresh.
        $siteOptions = [];
        foreach ($this->cachedSites() as $site) {
            $siteOptions[$site['id']] = $site['label'];
        }

        // Read site_id directly through SyncAdapterConfig rather than
        // credential() to avoid recursing: credential() calls
        // settingsSchema() to look up the field, and we're inside it.
        $storedSite = \App\Models\SyncAdapterConfig::get($this->instance->id, 'site_id') ?? '';
        if ($storedSite !== '' && ! array_key_exists($storedSite, $siteOptions)) {
            $siteOptions[$storedSite] = $storedSite;
        }

        return [
            [
                'key' => 'api_key',
                'label' => trans('admin/settings/sync_adapters.label_api_key'),
                'secret' => true,
                'help' => trans('admin/settings/sync_adapters.unifi_api_key_help'),
            ],
            [
                'key' => 'site_id',
                'label' => trans('admin/settings/sync_adapters.label_site_id'),
                'type' => 'select',
                'options' => $siteOptions,
                'help' => trans('admin/settings/sync_adapters.unifi_site_id_help'),
                // Inline refresh button next to the select. Sends the
                // in-form URL + api_key to the endpoint so the admin
                // can populate the list before saving anything.
                'refresh_route_name' => 'settings.adapters.refresh_sites',
                'refresh_response_key' => 'sites',
                'depends_on' => ['url' => 'url', 'api_key' => 'api_key'],
            ],
        ];
    }

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

    public function vendorSiteLabel(): string
    {
        return 'Site';
    }

    public function fetchSites(array $overrides = []): array
    {
        // Prefer values the admin just typed into the form over the
        // stored copy. Lets a first-time setup list sites before the
        // adapter is saved for real.
        $url = $overrides['url'] ?? null;
        if ($url === null || $url === '') {
            $url = $this->url();
        }
        $apiKey = $overrides['api_key'] ?? null;
        if ($apiKey === null || $apiKey === '') {
            $apiKey = $this->credential('api_key');
        }

        $client = new UnifiClient(
            baseUrl: $url,
            apiKey: $apiKey,
        );

        $sites = [];
        foreach ($client->sites() as $site) {
            $id = $site['id'] ?? null;
            if ($id === null || $id === '') {
                continue;
            }
            $name = $site['name'] ?? $site['displayName'] ?? $id;
            $sites[] = ['id' => (string) $id, 'label' => (string) $name];
        }

        return $sites;
    }

    public function extraFields(): array
    {
        return [
            'unifi_model_key' => ['label_key' => 'admin/settings/sync_adapters.extra_model_code'],
            'unifi_state' => ['label_key' => 'admin/settings/sync_adapters.extra_device_state'],
            'unifi_uplink_mac' => ['label_key' => 'admin/settings/sync_adapters.extra_uplink_mac'],
            'unifi_adopted' => ['label_key' => 'admin/settings/sync_adapters.extra_adopted', 'type' => 'boolean'],
        ];
    }

    public function pull(): iterable
    {
        $client = new UnifiClient(
            baseUrl: $this->url(),
            apiKey: $this->credential('api_key'),
            siteId: $this->credential('site_id'),
        );

        foreach ($client->devices() as $device) {
            yield $this->normalize($device);
        }
    }

    /**
     * Convert a UniFi device payload into the normalized record shape.
     * UniFi's `id` (UUID) is stable per adopted device and is what we
     * key asset_external_sources on. Serial is populated on most
     * device types but occasionally null on virtual or legacy devices.
     * SyncAdapter treats null serials as acceptable so the
     * asset still lands even when the controller doesn't report one.
     *
     * @param  array<string, mixed>  $device
     */
    private function normalize(array $device): HostInventoryRecord
    {
        return new HostInventoryRecord(
            sourceKey: $this->name(),
            sourceId: (string) Arr::get($device, 'id'),
            hostname: Arr::get($device, 'name'),
            hardwareSerial: Arr::get($device, 'serialNumber'),
            hardwareModel: Arr::get($device, 'model'),
            manufacturer: 'Ubiquiti',
            primaryMac: Arr::get($device, 'macAddress'),
            primaryIp: Arr::get($device, 'ipAddress'),
            os: 'UniFi',
            osVersion: Arr::get($device, 'firmwareVersion'),
            lastSeen: $this->parseTimestamp(Arr::get($device, 'lastSeen')),
            extra: [
                'unifi_model_key' => Arr::get($device, 'modelKey'),
                'unifi_state' => Arr::get($device, 'state'),
                'unifi_uplink_mac' => Arr::get($device, 'uplink.mac'),
                'unifi_adopted' => Arr::get($device, 'adopted'),
            ],
        );
    }

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

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