External Data Connector (EDC)

Device data from data connectors external to Asset Manager can be successfully ingested to Asset Manager via API and incorporated to its data tables. This feature provides a way to cue the additional scanning of addresses discovered through other means and via other systems. It is available as a call to the Asset Manager API only; this feature does not show on the Asset Manager web browser interface.

When Asset Manager receives a list of IPs and discovery types via the EDC, it handles these devices as though they had been found via Host and Path Discovery. Asset Manager continues scanning the devices, honoring any restrictions imposed by the Eligible, Avoid, and Stop lists.  Each call to the API generates response records with a scantype number of “External High.” When the Zones field isn’t populated, Asset Manager adds the devices and responses to the database for every zone. When the Zones field is populated, response and device records are stored to only the zones provided. 

API Specifications

The API supporting EDC is "extdevice," and an example call to it is https://10.9.0.173/api/rest/publish/extdevice, where 10.9.0.173 is the name or IP address of your Command Center.

The API call presents with the following input fields:

  1. Addresses (One, Required):  An IPv4/IPv6 host address

  2. Source (One, Required, Length 1-16 Characters): A string that describes the source system (e.g., “DNS Feed”)

  3. Detail (One, Optional, Length 1-256 Characters): A string that will be associated with the responses we insert into the system.  This could be used to provide context. For example “DNS Name: foo.bar.com”

  4. Priority (One, Optional, default to “Normal”): “High” or “Normal”

  5. Zones (Zone names, one or More, Optional):  If present, the zone names of the zones that we want to consider these addresses for.  Use High priority for fast targeting. If you don't know what zone a device is in, leave the Zones field empty.

  6. MAC Address (Optional)

This might look like the following and should be submitted as an array or a single entry.

{ip: 10.0.0.1, source: “DHCP”, detail: “DHCP Hostname foo.foo.com”, zone: “Zone1”, mac : “00:00:00:00:00:00”}

Curl Example

curl -v -k -g -d "@./devices.json" -X PUThttps://10.9.0.173/api/rest/publish/extdevice -H "Content-Type: application/json" -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRlIjoxNTI4Mzk3OTU0NTM2LCJ1c2VyIjoiYWRtaW4ifQ.q1fnqlSlOmQT3mi3qz3

The device input file

The device input file devices.json has the following format:

{

"device" : [

{"ip":"12.12.12.13", "source":"Asset Manager Feed", "priority":"high"},

{"ip":"12.12.12.15", "source":"Asset Manager Feed", "priority":"high", "zone":["Asset Manager"]},

{"ip":"12.12.12.12", "source":"Asset Manager Feed", "detail":"Asset Manager Detail Info", "priority":"high", "zone":["Asset Manager"]},

{"ip":"12.12.12.16", "source":"Asset Manager Feed", "detail":"Asset Manager Detail Info", "priority":"high", "mac":"BB:34:9B:AF:A7:83", "zone":["Asset Manager"]},

{"ip":"12.12.12.14", "source":"Asset Manager Feed"}]

}

IP Prioritization

Asset Manager selectively prioritizes incoming IPs from the external data connector for scanning as follows:

  • High
    Devices are added to a new zone.target_highpriority table.     These responses get a scan type of External High. These devices are added subject to existing targeting rules and are subject to eligible, avoid, etc rules. To implement the high priority functionality the algorithm the scouts use to get their targets has been modified.

    • Targets will be initially provided from the high priority table.  Then additional targets from the existing target table will be specified to complete the Scout’s request
    • Targets are deleted from the high priority table once provided to Scout
    • If there are no high priority targets, all targets are obtained from the zone.target table as usual

  • Normal

    • These responses get a scan type of “External”
    • These addresses are eventually added to the target list through normal response handling (they are not prioritized)

    • Validating Results

    To validate that EDC is functioning correctly:

    1. Browse to Reports > Browse Real-Time.
    2. Select an zone–one that is enabled and scanning.
    3. Select the Discovery Statistics by Discovery Types report.

    Statistics for External and External High display. Click a segment to display the supporting details.

    Another check you can do is to search for a known EDC device and verify that its discovery type is listed as External (or High External).