@sonde/packs 0.1.8 → 0.1.9

package/dist/integrations/unifi.js

@@ -0,0 +1,215 @@
+// --- API helper ---
+/**
+ * Fetch a UniFi Network official API endpoint.
+ * Auth: X-API-KEY header. Base path: /proxy/network/integration
+ * Docs: Settings > Control Plane > Integrations on your controller,
+ * or https://developer.ui.com/network/v10.1.84/gettingstarted
+ */
+export async function unifiFetch(path, config, credentials, fetchFn) {
+    const apiKey = credentials.credentials.apiKey ?? '';
+    const endpoint = config.endpoint.replace(/\/$/, '');
+    const url = `${endpoint}/proxy/network/integration${path}`;
+    const res = await fetchFn(url, {
+        headers: {
+            'X-API-KEY': apiKey,
+            Accept: 'application/json',
+            ...config.headers,
+        },
+    });
+    if (!res.ok) {
+        throw new Error(`UniFi Network API returned ${res.status}: ${res.statusText}`);
+    }
+    return (await res.json());
+}
+/** Collect all pages from a paginated endpoint (max 200 per page) */
+async function fetchAllPages(path, config, credentials, fetchFn, maxItems = 1000) {
+    const results = [];
+    let offset = 0;
+    const limit = 200;
+    while (results.length < maxItems) {
+        const sep = path.includes('?') ? '&' : '?';
+        const page = await unifiFetch(`${path}${sep}offset=${offset}&limit=${limit}`, config, credentials, fetchFn);
+        results.push(...page.data);
+        if (results.length >= page.totalCount)
+            break;
+        offset += limit;
+    }
+    return results;
+}
+/** Resolve the siteId — uses the first site unless overridden */
+async function resolveSiteId(config, credentials, fetchFn) {
+    const explicit = credentials.credentials.siteId ?? '';
+    if (explicit)
+        return explicit;
+    const sites = await unifiFetch('/v1/sites?limit=1', config, credentials, fetchFn);
+    const first = sites.data[0];
+    if (!first)
+        throw new Error('No sites found on this UniFi controller');
+    return first.id;
+}
+// --- Probe handlers ---
+const appInfo = async (_params, config, credentials, fetchFn) => {
+    return unifiFetch('/v1/info', config, credentials, fetchFn);
+};
+const sites = async (_params, config, credentials, fetchFn) => {
+    const result = await fetchAllPages('/v1/sites', config, credentials, fetchFn);
+    return { sites: result, count: result.length };
+};
+const devices = async (_params, config, credentials, fetchFn) => {
+    const siteId = await resolveSiteId(config, credentials, fetchFn);
+    const result = await fetchAllPages(`/v1/sites/${siteId}/devices`, config, credentials, fetchFn);
+    return {
+        devices: result.map((d) => ({
+            id: d.id,
+            macAddress: d.macAddress,
+            ipAddress: d.ipAddress,
+            name: d.name,
+            model: d.model,
+            state: d.state,
+            firmwareVersion: d.firmwareVersion,
+            firmwareUpdatable: d.firmwareUpdatable,
+            features: d.features,
+        })),
+        count: result.length,
+    };
+};
+const deviceDetail = async (params, config, credentials, fetchFn) => {
+    const deviceId = params?.device_id ?? '';
+    if (!deviceId) {
+        throw new Error('device_id parameter is required (device UUID)');
+    }
+    const siteId = await resolveSiteId(config, credentials, fetchFn);
+    return unifiFetch(`/v1/sites/${siteId}/devices/${deviceId}`, config, credentials, fetchFn);
+};
+const deviceStats = async (params, config, credentials, fetchFn) => {
+    const deviceId = params?.device_id ?? '';
+    if (!deviceId) {
+        throw new Error('device_id parameter is required (device UUID)');
+    }
+    const siteId = await resolveSiteId(config, credentials, fetchFn);
+    return unifiFetch(`/v1/sites/${siteId}/devices/${deviceId}/statistics/latest`, config, credentials, fetchFn);
+};
+const clients = async (_params, config, credentials, fetchFn) => {
+    const siteId = await resolveSiteId(config, credentials, fetchFn);
+    const result = await fetchAllPages(`/v1/sites/${siteId}/clients`, config, credentials, fetchFn);
+    return {
+        clients: result.map((c) => ({
+            id: c.id,
+            name: c.name,
+            type: c.type,
+            ipAddress: c.ipAddress,
+            connectedAt: c.connectedAt,
+        })),
+        count: result.length,
+    };
+};
+const networks = async (_params, config, credentials, fetchFn) => {
+    const siteId = await resolveSiteId(config, credentials, fetchFn);
+    const result = await fetchAllPages(`/v1/sites/${siteId}/networks`, config, credentials, fetchFn);
+    return { networks: result, count: result.length };
+};
+const wans = async (_params, config, credentials, fetchFn) => {
+    const siteId = await resolveSiteId(config, credentials, fetchFn);
+    const result = await fetchAllPages(`/v1/sites/${siteId}/wans`, config, credentials, fetchFn);
+    return { wans: result, count: result.length };
+};
+// --- Pack definition ---
+export const unifiPack = {
+    manifest: {
+        name: 'unifi',
+        type: 'integration',
+        version: '0.2.0',
+        description: 'Ubiquiti UniFi Network — devices, clients, networks, WAN, device stats (official API)',
+        requires: { groups: [], files: [], commands: [] },
+        probes: [
+            {
+                name: 'info',
+                description: 'Application version and basic info',
+                capability: 'observe',
+                params: {},
+                timeout: 10000,
+            },
+            {
+                name: 'sites',
+                description: 'List all sites on this controller',
+                capability: 'observe',
+                params: {},
+                timeout: 15000,
+            },
+            {
+                name: 'devices',
+                description: 'List adopted devices with state, model, firmware, features',
+                capability: 'observe',
+                params: {},
+                timeout: 15000,
+            },
+            {
+                name: 'device.detail',
+                description: 'Full device details including interfaces and uplink',
+                capability: 'observe',
+                params: {
+                    device_id: {
+                        type: 'string',
+                        description: 'Device UUID',
+                        required: true,
+                    },
+                },
+                timeout: 15000,
+            },
+            {
+                name: 'device.stats',
+                description: 'Latest device statistics — CPU, memory, uptime, load averages',
+                capability: 'observe',
+                params: {
+                    device_id: {
+                        type: 'string',
+                        description: 'Device UUID',
+                        required: true,
+                    },
+                },
+                timeout: 15000,
+            },
+            {
+                name: 'clients',
+                description: 'Connected clients with type, IP, connection time',
+                capability: 'observe',
+                params: {},
+                timeout: 15000,
+            },
+            {
+                name: 'networks',
+                description: 'List configured networks (VLANs, etc.)',
+                capability: 'observe',
+                params: {},
+                timeout: 15000,
+            },
+            {
+                name: 'wans',
+                description: 'WAN interface definitions',
+                capability: 'observe',
+                params: {},
+                timeout: 15000,
+            },
+        ],
+        runbook: {
+            category: 'network',
+            probes: ['info', 'devices', 'clients'],
+            parallel: true,
+        },
+    },
+    handlers: {
+        info: appInfo,
+        sites,
+        devices,
+        'device.detail': deviceDetail,
+        'device.stats': deviceStats,
+        clients,
+        networks,
+        wans,
+    },
+    testConnection: async (config, credentials, fetchFn) => {
+        const result = await unifiFetch('/v1/info', config, credentials, fetchFn);
+        return typeof result.applicationVersion === 'string';
+    },
+};
+//# sourceMappingURL=unifi.js.map

package/dist/integrations/unifi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unifi.js","sourceRoot":"","sources":["../../src/integrations/unifi.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sonde/packs",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "private": false,
   "type": "module",
   "main": "dist/index.js",
@@ -18,7 +18,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@sonde/shared": "*"
+    "@sonde/shared": "*",
+    "@keeper-security/secrets-manager-core": "17.4.0"
   },
   "devDependencies": {
     "vitest": "^2.1.8"

package/src/index.ts

@@ -48,6 +48,9 @@ export { thousandeyesPack } from './integrations/thousandeyes.js';
 export { merakiPack } from './integrations/meraki.js';
 export { checkpointPack } from './integrations/checkpoint.js';
 export { a10Pack } from './integrations/a10.js';
+export { unifiPack } from './integrations/unifi.js';
+export { unifiAccessPack } from './integrations/unifi-access.js';
+export { keeperPack, initializeKeeper, regionToHostname } from './integrations/keeper.js';
 export { proxmoxDiagnosticRunbooks } from './runbooks/proxmox.js';
 export { nutanixDiagnosticRunbooks } from './runbooks/nutanix.js';
 

package/src/integrations/keeper.ts

@@ -0,0 +1,106 @@
+import type { IntegrationPack } from '@sonde/shared';
+
+const REGION_HOSTNAMES: Record<string, string> = {
+  US: 'keepersecurity.com',
+  EU: 'keepersecurity.eu',
+  AU: 'keepersecurity.com.au',
+  GOV: 'govcloud.keepersecurity.us',
+  JP: 'keepersecurity.jp',
+  CA: 'keepersecurity.ca',
+};
+
+async function loadSdk(): Promise<typeof import('@keeper-security/secrets-manager-core')> {
+  return await import('@keeper-security/secrets-manager-core');
+}
+
+/**
+ * Rebuild an in-memory KeyValueStorage from a previously
+ * serialized device config JSON string.
+ */
+export async function rebuildStorage(
+  deviceConfigJson: string,
+): Promise<import('@keeper-security/secrets-manager-core').KeyValueStorage> {
+  const sdk = await loadSdk();
+  return sdk.inMemoryStorage(JSON.parse(deviceConfigJson));
+}
+
+/**
+ * Initialize a new Keeper device binding using a one-time access token.
+ * Returns the serialized device config JSON to store encrypted in the DB.
+ * The one-time token is consumed during this call and cannot be reused.
+ */
+export async function initializeKeeper(oneTimeToken: string, hostname?: string): Promise<string> {
+  const sdk = await loadSdk();
+  const configObj: Record<string, string> = {};
+  const storage = sdk.inMemoryStorage(configObj);
+
+  if (hostname) {
+    await storage.saveString('hostname', hostname);
+  }
+
+  await sdk.initializeStorage(storage, oneTimeToken, hostname);
+  const { records } = await sdk.getSecrets({ storage });
+
+  // Verify the binding worked by checking we got a response
+  if (!records) {
+    throw new Error('Keeper initialization failed: no records returned');
+  }
+
+  return JSON.stringify(configObj);
+}
+
+/**
+ * Resolve the hostname for a given region code.
+ * Returns undefined for unknown regions (SDK will use its default).
+ */
+export function regionToHostname(region?: string): string | undefined {
+  if (!region) return undefined;
+  return REGION_HOSTNAMES[region.toUpperCase()];
+}
+
+export const keeperPack: IntegrationPack = {
+  manifest: {
+    name: 'keeper',
+    type: 'integration',
+    version: '0.1.0',
+    description: 'Keeper Secrets Manager — pull credentials from Keeper vault',
+    requires: { groups: [], files: [], commands: [] },
+    probes: [
+      {
+        name: 'list-records',
+        description: 'List accessible record UIDs and titles',
+        capability: 'observe',
+        timeout: 15000,
+      },
+    ],
+    runbook: {
+      category: 'keeper',
+      probes: ['list-records'],
+      parallel: false,
+    },
+  },
+
+  handlers: {
+    'list-records': async (_params, _config, credentials) => {
+      const deviceConfig = credentials.credentials.deviceConfig;
+      if (!deviceConfig) throw new Error('Keeper device config not found');
+      const sdk = await loadSdk();
+      const storage = await rebuildStorage(deviceConfig);
+      const { records } = await sdk.getSecrets({ storage });
+      return records.map((r) => ({
+        uid: r.recordUid,
+        title: r.data.title,
+        type: r.data.type,
+      }));
+    },
+  },
+
+  testConnection: async (_config, credentials) => {
+    const deviceConfig = credentials.credentials.deviceConfig;
+    if (!deviceConfig) return false;
+    const sdk = await loadSdk();
+    const storage = await rebuildStorage(deviceConfig);
+    const { records } = await sdk.getSecrets({ storage });
+    return Array.isArray(records);
+  },
+};

package/src/integrations/servicenow.test.ts

@@ -1,6 +1,6 @@
 import type { IntegrationConfig, IntegrationCredentials } from '@sonde/shared';
-import { describe, expect, it, vi } from 'vitest';
-import { servicenowPack } from './servicenow.js';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { clearTokenCache, servicenowPack } from './servicenow.js';
 
 const config: IntegrationConfig = {
   endpoint: 'https://instance.service-now.com',
@@ -15,10 +15,11 @@ const basicCreds: IntegrationCredentials = {
 const oauthCreds: IntegrationCredentials = {
   packName: 'servicenow',
   authMethod: 'oauth2',
-  credentials: {},
-  oauth2: { accessToken: 'my-token' },
+  credentials: { clientId: 'my-client-id', clientSecret: 'my-secret' },
 };
 
+afterEach(() => clearTokenCache());
+
 const handler = (name: string) => {
   const h = servicenowPack.handlers[name];
   if (!h) throw new Error(`Handler ${name} not found`);
@@ -73,12 +74,34 @@ describe('servicenow pack', () => {
       expect(init.headers.Authorization).toBe(expected);
     });
 
-    it('uses bearer token for oauth2 method', async () => {
-      const fetchFn = mockFetch([{ name: 'web01' }]);
+    it('exchanges client_credentials for bearer token on oauth2 method', async () => {
+      let callCount = 0;
+      const fetchFn = vi.fn().mockImplementation((url: string) => {
+        callCount++;
+        if (callCount === 1) {
+          // Token exchange call to /oauth_token.do
+          expect(url).toBe('https://instance.service-now.com/oauth_token.do');
+          return Promise.resolve(
+            new Response(
+              JSON.stringify({ access_token: 'tok-123', expires_in: 1800 }),
+              { status: 200, headers: { 'Content-Type': 'application/json' } },
+            ),
+          );
+        }
+        // Table API call
+        return Promise.resolve(
+          new Response(
+            JSON.stringify({ result: [{ name: 'web01' }] }),
+            { status: 200, headers: { 'Content-Type': 'application/json' } },
+          ),
+        );
+      });
+
       await handler('ci.lookup')({ query: 'web01' }, config, oauthCreds, fetchFn);
 
-      const init = callArgs(fetchFn, 0)[1] as { headers: Record<string, string> };
-      expect(init.headers.Authorization).toBe('Bearer my-token');
+      expect(fetchFn).toHaveBeenCalledTimes(2);
+      const apiInit = callArgs(fetchFn, 1)[1] as { headers: Record<string, string> };
+      expect(apiInit.headers.Authorization).toBe('Bearer tok-123');
     });
   });
 

package/src/integrations/servicenow.ts

@@ -6,12 +6,76 @@ import type {
   IntegrationProbeHandler,
 } from '@sonde/shared';
 
+// --- OAuth2 client_credentials token cache ---
+
+interface CachedToken {
+  accessToken: string;
+  expiresAt: number;
+}
+
+let tokenCache: CachedToken | null = null;
+
+/** Clear the cached token (used for testing) */
+export function clearTokenCache(): void {
+  tokenCache = null;
+}
+
+/**
+ * Acquire or reuse a ServiceNow OAuth2 token via client_credentials grant.
+ * Requires Washington DC release or newer with the OAuth 2.0 plugin enabled
+ * and `glide.oauth.inbound.client.credential.grant_type.enabled = true`.
+ * Token endpoint: POST https://<instance>/oauth_token.do
+ */
+async function ensureAccessToken(
+  config: IntegrationConfig,
+  credentials: IntegrationCredentials,
+  fetchFn: FetchFn,
+): Promise<string> {
+  if (tokenCache && Date.now() < tokenCache.expiresAt - 30_000) {
+    return tokenCache.accessToken;
+  }
+
+  const clientId = credentials.credentials.clientId ?? '';
+  const clientSecret = credentials.credentials.clientSecret ?? '';
+  const endpoint = config.endpoint.replace(/\/$/, '');
+
+  const res = await fetchFn(`${endpoint}/oauth_token.do`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams({
+      grant_type: 'client_credentials',
+      client_id: clientId,
+      client_secret: clientSecret,
+    }).toString(),
+  });
+
+  if (!res.ok) {
+    throw new Error(
+      `ServiceNow OAuth token request failed: ${res.status} ${res.statusText}`,
+    );
+  }
+
+  const data = (await res.json()) as {
+    access_token: string;
+    expires_in: number;
+  };
+  tokenCache = {
+    accessToken: data.access_token,
+    expiresAt: Date.now() + data.expires_in * 1000,
+  };
+  return tokenCache.accessToken;
+}
+
 /** Build Authorization header based on auth method */
-function buildAuthHeaders(credentials: IntegrationCredentials): Record<string, string> {
-  if (credentials.authMethod === 'oauth2' && credentials.oauth2?.accessToken) {
-    return { Authorization: `Bearer ${credentials.oauth2.accessToken}` };
+async function buildAuthHeaders(
+  config: IntegrationConfig,
+  credentials: IntegrationCredentials,
+  fetchFn: FetchFn,
+): Promise<Record<string, string>> {
+  if (credentials.authMethod === 'oauth2') {
+    const token = await ensureAccessToken(config, credentials, fetchFn);
+    return { Authorization: `Bearer ${token}` };
   }
-  // api_key = basic auth with username:password
   const { username, password } = credentials.credentials;
   if (username && password) {
     const encoded = Buffer.from(`${username}:${password}`).toString('base64');
@@ -45,9 +109,10 @@ async function snowFetch(
   credentials: IntegrationCredentials,
   fetchFn: FetchFn,
 ): Promise<{ result: unknown[] }> {
+  const authHeaders = await buildAuthHeaders(config, credentials, fetchFn);
   const headers: Record<string, string> = {
     Accept: 'application/json',
-    ...buildAuthHeaders(credentials),
+    ...authHeaders,
     ...config.headers,
   };
   const res = await fetchFn(url, { headers });
@@ -269,9 +334,10 @@ export const servicenowPack: IntegrationPack = {
     const url = buildUrl(config.endpoint, 'sys_properties', undefined, ['name']);
     const parsed = new URL(url);
     parsed.searchParams.set('sysparm_limit', '1');
+    const authHeaders = await buildAuthHeaders(config, credentials, fetchFn);
     const headers: Record<string, string> = {
       Accept: 'application/json',
-      ...buildAuthHeaders(credentials),
+      ...authHeaders,
       ...config.headers,
     };
     const res = await fetchFn(parsed.toString(), { headers });