Skip to content

A free open source IT asset/license management system

19.6 KB
Raw Blame
<?php

namespace App\SyncAdapters\Addigy;

use App\Models\Asset;
use App\Models\AssetExternalSource;
use App\Models\SyncAdapterConfig;
use App\Models\User;
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;

/**
 * Addigy adapter. Pulls device inventory from Addigy API v2 and
 * normalizes it into HostInventoryRecord objects. Uses Addigy's single
 * `x-api-key` header (v2) rather than the retired v1 client-id +
 * client-secret pair.
 *
 * Push surface: Snipe-IT asset name -> Addigy device name via the Set
 * Device Name MDM command. End-user assignment (Snipe-IT assigned
 * user -> Addigy end-user tied to the device) is opt-in per instance
 * because it requires an Addigy end-user ID lookup per push.
 */
class AddigyAdapter extends PushableSyncAdapter
{
    use UsesAppleDbEnrichment;

    /**
     * Device-fact identifiers to request on every `POST /devices` call.
     * v2's response shape is a `facts` map keyed by identifier (each
     * value is `{type, value}`), so the client has to tell the server
     * up front which facts it wants. These names come from the v2
     * OpenAPI vocabulary (`AuditFilter.audit_field` example uses
     * `device_model_name`) plus the matching v1 field names where
     * Addigy preserved them. If a tenant renames or lacks a built-in
     * fact, its key is simply missing from the response map and
     * normalize() reads null.
     *
     * @var list<string>
     */
    private const DESIRED_FACTS = [
        'device_name',
        'serial_number',
        'device_model_name',
        // Addigy's "model identifier of the hardware" fact (e.g.
        // "MacBookPro18,3"). Needed for AppleDB enrichment lookup
        // since device_model_name only carries the marketing name.
        // Source: support.addigy.com Device Facts Overview.
        // This *might* be wrong.
        'product_name',
        'network_mac_address',
        'network_ip_address',
        'os_type',
        'os_version',
        'last_online_at',
        'asset_tag',
        'user_email',
        'policy_id',
        'is_supervised',
        'agent_version',
        // Mappable inventory
        'build_version',
        'udid',
        'has_mdm',
        'filevault_enabled',
        'firewall_enabled',
        'total_memory_gb',
        'disk_total_space_gb',
        'disk_free_space_gb',
        'warranty_expiration_date',
    ];

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

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

    public static function docsUrl(): ?string
    {
        return 'https://api.addigy.com/api/v2/documentation/';
    }

    /**
     * Addigy v2's host is fixed at api.addigy.com, so the admin doesn't
     * type a URL. The client hardcodes the base URL.
     */
    public function usesConfigurableUrl(): bool
    {
        return false;
    }

    public function settingsSchema(): array
    {
        return [
            [
                'key' => 'api_key',
                'label' => trans('admin/settings/sync_adapters.label_api_key'),
                'secret' => true,
                'help' => trans('admin/settings/sync_adapters.addigy_api_key_help'),
            ],
            [
                'key' => 'push_end_user_assignment',
                'label' => trans('admin/settings/sync_adapters.addigy_push_end_user_assignment_label'),
                'type' => 'checkbox',
                'required' => false,
                'help' => trans('admin/settings/sync_adapters.addigy_push_end_user_assignment_help'),
            ],
            $this->appleDbSettingsField(),
        ];
    }

    public function extraFields(): array
    {
        return [
            ...$this->appleDbExtraFieldsDeclaration(),
            'addigy_policy_id' => ['label_key' => 'admin/settings/sync_adapters.extra_policy_id'],
            'addigy_supervised' => ['label_key' => 'admin/settings/sync_adapters.extra_supervised', 'type' => 'boolean'],
            'addigy_agent_version' => ['label_key' => 'admin/settings/sync_adapters.extra_agent_version'],
            'addigy_product_name' => ['label_key' => 'admin/settings/sync_adapters.extra_model_identifier'],
            // Mappable inventory + posture surface (parity with ABM /
            // Mosyle / Jamf extras plus Addigy-unique warranty data).
            'addigy_build_version' => ['label_key' => 'admin/settings/sync_adapters.addigy_extra_build_version'],
            'addigy_udid' => ['label_key' => 'admin/settings/sync_adapters.extra_udid'],
            'addigy_has_mdm' => ['label_key' => 'admin/settings/sync_adapters.addigy_extra_has_mdm', 'type' => 'boolean'],
            'addigy_filevault_enabled' => ['label_key' => 'admin/settings/sync_adapters.addigy_extra_filevault_enabled', 'type' => 'boolean'],
            'addigy_firewall_enabled' => ['label_key' => 'admin/settings/sync_adapters.addigy_extra_firewall_enabled', 'type' => 'boolean'],
            'addigy_total_memory_gb' => ['label_key' => 'admin/settings/sync_adapters.addigy_extra_total_memory_gb'],
            'addigy_disk_total_space_gb' => ['label_key' => 'admin/settings/sync_adapters.addigy_extra_disk_total_space_gb'],
            'addigy_disk_free_space_gb' => ['label_key' => 'admin/settings/sync_adapters.addigy_extra_disk_free_space_gb'],
            'addigy_warranty_expiration_date' => ['label_key' => 'admin/settings/sync_adapters.addigy_extra_warranty_expiration_date', 'type' => 'date'],
        ];
    }

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

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

    public function fetchGroups(): array
    {
        $client = $this->makeClient();

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

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

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

        foreach ($client->devices(self::DESIRED_FACTS) as $device) {
            // Cache orgid off the first DeviceAudit we see so push can
            // target `/o/{orgid}/end-users/*` without the admin
            // supplying it. v2 has no "get my current org" endpoint,
            // but every DeviceAudit carries the field. The write
            // short-circuits when nothing changed so repeated pulls
            // don't thrash the config table.
            $this->cacheOrganizationId((string) ($device['orgid'] ?? ''));

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

    /**
     * Pass the Addigy record to the shared enrichment flow. The
     * product_name fact is Addigy's name for the AppleDB-shape
     * identifier (e.g. "MacBookPro18,3") per
     * support.addigy.com/hc/en-us/articles/5435826890259. The marketing
     * name (device_model_name) remains hardwareModel so admin-visible
     * AssetModel.name is unchanged by the enrichment opt-in.
     *
     * @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['addigy_product_name'] ?? null;
        if (!is_string($productType) || $productType === '') {
            return $handled;
        }

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

    /**
     * Convert an Addigy v2 DeviceAudit payload into the normalized
     * record shape. `agentid` is stable per enrolled device and is
     * what we key asset_external_sources on. Everything else lives
     * in the `facts` map keyed by identifier.
     *
     * @param  array<string, mixed>  $device
     */
    private function normalize(array $device): HostInventoryRecord
    {
        $productType = self::fact($device, 'product_name');
        $modelName = self::fact($device, 'device_model_name');
        $canonical = $this->canonicalIdentityFor($productType, $modelName);
        $appleDbExtras = $this->appleDbExtrasFor($productType, $modelName);

        return new HostInventoryRecord(
            sourceKey: $this->name(),
            sourceId: (string) Arr::get($device, 'agentid'),
            hostname: self::fact($device, 'device_name'),
            hardwareSerial: self::fact($device, 'serial_number'),
            hardwareModel: $modelName,
            manufacturer: 'Apple',
            primaryMac: self::fact($device, 'network_mac_address'),
            primaryIp: self::fact($device, 'network_ip_address'),
            os: self::fact($device, 'os_type'),
            osVersion: self::fact($device, 'os_version'),
            lastSeen: $this->parseTimestamp(self::fact($device, 'last_online_at')),
            // Addigy's "asset_tag" is the operator-assigned tag from
            // their inventory settings, distinct from the Snipe-IT one.
            assetTag: self::fact($device, 'asset_tag'),
            assignedUserEmail: self::fact($device, 'user_email'),
            vendorGroupId: ($policyId = self::fact($device, 'policy_id')) !== null ? (string) $policyId : null,
            extra: [
                ...$appleDbExtras,
                'addigy_policy_id' => self::fact($device, 'policy_id'),
                'addigy_supervised' => self::fact($device, 'is_supervised'),
                'addigy_agent_version' => self::fact($device, 'agent_version'),
                'addigy_product_name' => $productType,
                'addigy_build_version' => self::fact($device, 'build_version'),
                'addigy_udid' => self::fact($device, 'udid'),
                'addigy_has_mdm' => self::fact($device, 'has_mdm'),
                'addigy_filevault_enabled' => self::fact($device, 'filevault_enabled'),
                'addigy_firewall_enabled' => self::fact($device, 'firewall_enabled'),
                'addigy_total_memory_gb' => self::fact($device, 'total_memory_gb'),
                'addigy_disk_total_space_gb' => self::fact($device, 'disk_total_space_gb'),
                'addigy_disk_free_space_gb' => self::fact($device, 'disk_free_space_gb'),
                'addigy_warranty_expiration_date' => self::fact($device, 'warranty_expiration_date'),
            ],
            canonicalMarketingName: $canonical['canonicalMarketingName'],
            canonicalModelNumber: $canonical['canonicalModelNumber'],
        );
    }

    /**
     * Pull a single fact value out of a v2 DeviceAudit payload.
     * Returns null when the fact is missing, the server reported an
     * error_msg on it, or the value is explicitly null.
     */
    private static function fact(array $device, string $identifier): mixed
    {
        $fact = Arr::get($device, 'facts.'.$identifier);
        if (! is_array($fact)) {
            return null;
        }
        if (! empty($fact['error_msg'])) {
            return null;
        }

        return $fact['value'] ?? null;
    }

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

        if (is_numeric($value)) {
            // Addigy occasionally emits timestamps as Unix epoch
            // seconds (seen on last_online_at). Treat anything numeric
            // as epoch so Carbon::parse doesn't try to interpret it as
            // a year.
            return Carbon::createFromTimestamp((int) $value);
        }

        return Carbon::parse($value);
    }

    /**
     * Push is always available on a configured instance. Both
     * Set-Device-Name and end-user assignment use the same API key as
     * pull, so if pull works push works too.
     */
    public function canPush(): bool
    {
        return true;
    }

    /**
     * Addigy exposes no device-level freeform notes field writable via
     * the API, so composed-notes push has no target here. Returning
     * null disables the composed-notes section of the settings UI.
     */
    public function notesFieldTarget(): ?string
    {
        return null;
    }

    /**
     * Hostname is the only standard field Addigy accepts writes on
     * (via the Set Device Name MDM command). Narrowing the pushable
     * set hides push/both from the direction picker for every other
     * standard field so the admin can't opt into a push that would
     * silently drop at payload build time.
     */
    public function pushableFields(): array
    {
        return ['hostname'];
    }

    /**
     * Push Snipe-IT-authoritative fields to Addigy. Two separate
     * surfaces, each toggled independently:
     *
     *  1. Hostname -> Set Device Name MDM command, when `hostname` is
     *     push-directed in the mapping UI.
     *  2. Assigned user -> Addigy end-user device assignment, when
     *     the per-instance `push_end_user_assignment` flag is on and
     *     the asset has an assigned user with a resolvable email.
     *
     * The two don't share a payload (two different endpoints), so this
     * doesn't delegate to pushViaSinglePayload. Return true when at
     * least one surface actually fired.
     *
     * @param  array<int, string>  $changedFields
     */
    public function push(Asset $asset, array $changedFields = []): bool
    {
        $hostnameConfigured = $this->shouldPushHostname($changedFields);
        $endUserConfigured = $this->pushEndUserAssignmentEnabled() && $this->assignedUserChanged($changedFields);

        if (! $hostnameConfigured && ! $endUserConfigured) {
            Log::channel('sync-adapters')->info(
                $this->name().' push: skipped asset '.$asset->id
                .' (asset_tag='.($asset->asset_tag ?? '(none)').') - no push surface configured.',
            );

            return false;
        }

        // Direct external-source lookup. Base class pushPrologue bakes
        // in a pushDirectedFields check that assumes mapping-field
        // semantics, which end-user assignment sits outside, so we
        // read the external_source row ourselves.
        $externalSource = AssetExternalSource::query()
            ->where('asset_id', $asset->id)
            ->where('source', $this->name())
            ->first();

        if ($externalSource === null) {
            Log::channel('sync-adapters')->info(
                $this->name().' push: skipped asset '.$asset->id
                .' (asset_tag='.($asset->asset_tag ?? '(none)').') - no asset_external_sources row for this adapter instance.',
            );

            return false;
        }

        $client = $this->makeClient();
        $dispatched = false;

        if ($hostnameConfigured && $this->pushHostname($asset, $externalSource, $client)) {
            $dispatched = true;
        }

        if ($endUserConfigured && $this->pushEndUserAssignment($asset, $externalSource, $client)) {
            $dispatched = true;
        }

        return $dispatched;
    }

    private function shouldPushHostname(array $changedFields): bool
    {
        if (! in_array('hostname', $this->pushDirectedFields(), true)) {
            return false;
        }

        // Respect the pushPrologue intersection check: if the caller
        // handed us a specific changedFields set, hostname has to be
        // in it. Empty set means "push everything directed push" so
        // we still fire.
        return $changedFields === [] || in_array('hostname', $changedFields, true);
    }

    private function pushHostname(Asset $asset, AssetExternalSource $externalSource, AddigyClient $client): bool
    {
        $name = $asset->name;
        if ($name === null || $name === '') {
            return false;
        }

        if ($this->isPushDryRun()) {
            Log::channel('sync-adapters')->info(
                $this->name().' push [dry-run]: would set Addigy device '.$externalSource->external_id.' name='.$name,
            );

            return true;
        }

        $client->setDeviceName((string) $externalSource->external_id, (string) $name);

        Log::channel('sync-adapters')->info(
            $this->name().' push: set Addigy device '.$externalSource->external_id.' name='.$name,
        );

        return true;
    }

    private function pushEndUserAssignmentEnabled(): bool
    {
        return (bool) SyncAdapterConfig::get($this->instance->id, 'push_end_user_assignment');
    }

    /**
     * Snipe-IT doesn't surface "assigned user" in changedFields today
     * (it's not a mapping field). Treat an empty changedFields set as
     * "push everything configured" and let the end-user branch run.
     * When the caller sends a specific set, only run if `assigned_to`
     * is in it so a hostname-only save doesn't re-check end-user state.
     */
    private function assignedUserChanged(array $changedFields): bool
    {
        return $changedFields === [] || in_array('assigned_to', $changedFields, true);
    }

    private function pushEndUserAssignment(Asset $asset, AssetExternalSource $externalSource, AddigyClient $client): bool
    {
        $orgId = (string) (SyncAdapterConfig::get($this->instance->id, 'cached_orgid') ?? '');
        if ($orgId === '') {
            Log::channel('sync-adapters')->info(
                $this->name().' push: skipped end-user assignment for asset '.$asset->id
                .' - cached_orgid not yet captured. Run a pull first.',
            );

            return false;
        }

        if (! ($asset->assignedTo instanceof User) || empty($asset->assignedTo->email)) {
            Log::channel('sync-adapters')->info(
                $this->name().' push: skipped end-user assignment for asset '.$asset->id
                .' - no assigned user with an email on the Snipe-IT side.',
            );

            return false;
        }

        $email = (string) $asset->assignedTo->email;

        if ($this->isPushDryRun()) {
            Log::channel('sync-adapters')->info(
                $this->name().' push [dry-run]: would resolve Addigy end user by email='.$email
                .' and assign to device '.$externalSource->external_id,
            );

            return true;
        }

        $endUserId = $client->findEndUserIdByEmail($orgId, $email);
        if ($endUserId === null) {
            Log::channel('sync-adapters')->info(
                $this->name().' push: skipped end-user assignment for asset '.$asset->id
                .' - no unique Addigy end-user match for email='.$email,
            );

            return false;
        }

        $client->assignDeviceToEndUser($orgId, (string) $externalSource->external_id, $endUserId);

        Log::channel('sync-adapters')->info(
            $this->name().' push: assigned Addigy device '.$externalSource->external_id
            .' to end-user '.$endUserId.' (email='.$email.')',
        );

        return true;
    }

    private function cacheOrganizationId(string $orgId): void
    {
        if ($orgId === '') {
            return;
        }
        if (SyncAdapterConfig::get($this->instance->id, 'cached_orgid') === $orgId) {
            return;
        }
        SyncAdapterConfig::put($this->instance->id, 'cached_orgid', $orgId);
    }

    private function makeClient(): AddigyClient
    {
        return new AddigyClient(apiKey: $this->credential('api_key'));
    }
}