theta-suite/docs/sso/agents.md

layout, title, nav_order

layout	title	nav_order
default	Discovery Agents	5

Discovery Agents

Theta Directory supports a robust agent architecture for auto-discovering devices, hosts, and services across your home lab or data center. Agents run on a scheduled cron and feed their data into a central Reconciliation Engine that smartly merges information based on MAC addresses and IPs.

Writing a Custom Agent

Agents are simple JavaScript files placed in nodejs/agents/discovery/.

A agent must export a single discover async function that returns a standardized graph of resources and edges.

Agent Skeleton

// nodejs/agents/discovery/my_custom_agent.js
module.exports = {
  discover: async (config) => {
    const { url, apiKey } = config; // Provided by your configuration
    
    const resources = [];
    const edges = [];

    // 1. Fetch your data from an API
    // const data = await fetch(...);

    // 2. Map data to Resources
    resources.push({
      kind: 'network_device', // 'host', 'service', 'network_device', 'unmanaged_device'
      name: 'My Switch',
      slug: 'my-switch-01',
      metadata: {
        make: 'Vendor',
        model: 'Model X',
        interfaces: [
          { mac: '00:1A:2B:3C:4D:5E', ip: '10.0.0.5' }
        ]
      }
    });

    // 3. Map relations to Edges (optional)
    edges.push({
      parentSlug: 'my-switch-01',
      childSlug: 'some-connected-client-slug',
      relation: 'connected_to' // 'hosts', 'exposes', 'connected_to'
    });

    return { resources, edges };
  }
};

Configuration

Agents are automatically loaded and executed by the internal BullMQ job scheduler. You configure them in your config/sso-secrets.js:

module.exports = {
  // ... existing config ...
  discovery: {
    agents: {
      my_custom_agent: {
        enabled: true,
        cron: '*/30 * * * *', // Run every 30 minutes
        url: 'https://api.example.com',
        apiKey: 'secret-key'
      },
      nmap: {
        enabled: true,
        cron: '0 * * * *',
        targetRange: '192.168.1.0/24'
      }
    }
  }
};

The Reconciliation Engine

When your agent returns its graph, the Reconciliation Engine takes over:

1. Matching: It tries to find an existing device in the database matching any MAC address provided in the interfaces array. If no MAC matches, it falls back to IP address, and then to slug.
2. Merging: If it finds a match, it gracefully merges the metadata (so your agent can add CPU info to a host that NMAP previously found).
3. Source Tracking: It records your agent's filename in the discovery_sources array on the resource, and updates the last_seen timestamp.
4. LDAP Spam Prevention: Brand new devices are marked as managed: false. They will not pollute your LDAP directory until an admin explicitly promotes them.