Discovery action functions

The following discovery functions retrieve information from discovery targets. They take positional arguments. They return none if an error occurs in performing the discovery.

discovery.fileGet(target, filename)

Retrieves the specified file. target is a node used to identify the discovery target, either a directly discovered data node, or a Host node. Returns a DiscoveredFile node.

discovery.fileInfo(target, filename) – Foundation 7.2 and later

Retrieves information about the specified file, but not the file content, which is useful if the file is a binary file or particularly large. Returns a DiscoveredFile node with no content attribute.

discovery.registryKey(target, key)

Retrieves a registry key from a Windows machine. Returns a DiscoveredRegistryValue node.

discovery.wmiQuery(target, query, namespace)

Performs a WMI query on a Windows machine. Returns a list of DiscoveredWMI nodes.

discovery.runCommand(target, command)

Returns a DiscoveredCommandResult node containing the result of running the specified command.

Possible post-processing required on UNIX/Linux hosts When a pattern executes a command on a UNIX/Linux host, the result returned may contain control characters used to display colours and other formatting. The pattern should not rely on being able to use the result without some additional processing such as regular expression matching and extraction.

discovery.snmpGet(target, oid_table) – Foundation 7.1 and later

Performs an SNMP query on the target and returns a DiscoveredSNMP node. The oid_table is a table that lists the SNMP OIDs to retrieve, mapped to the attribute names to set. e.g.

table oids 1.0
  "1.3.6.1.2.1.1.1" -> "one";
  "1.3.6.1.2.3.4.5" -> "two";
end table;

The call succeeds if any of the requested OIDs are available; the attributes corresponding to any OIDs that were not available are not set on the DiscoveredSNMP node. If none of the OIDs are available, the discovery request fails and the snmpGet function returns none.

discovery.snmpGetTable(target, table_oid, column_table) – Foundation 7.1 and later

Performs an SNMP query that returns a table on the target. Returns a list of DiscoveredSNMPRow nodes or none if the SNMP query failed. The table_oid parameter specifies the SNMP OID for the table; the sub-OIDs within the table are mapped to attribute names using the column_table. Not all column OIDs need to be listed in the storage table. If a column OID is not mapped it will be dropped and not stored in the DiscoveredSNMPRow nodes. Similarly, if a mapping for a non-existent column OID is given, it will be ignored. For example, to retrieve a table of storage information:

table storage_map 1.0
  "1" -> "index";
  "2" -> "type";
  "3" -> "descr";
  "4" -> "allocation_units";
end table;

pattern example 1.0
...
  body
    rows := discovery.snmpGetTable(host, "1.3.6.1.2.1.99.99", storage_map);
...

OID usage with snmpGetTable When using snmpGetTable, specifying the OID of a table object, a DiscoveredSNMPRow node is created for every requested value in every row in the table rather than a single node for each row in the table. To avoid this you should use the OID for the entry object. For example, rather than using .1.3.6.1.2.1.2.2 (ifTable) you need to use .1.3.6.1.2.1.2.2.1 (ifEntry).

Discovery data manipulation functions

The following functions in the discovery module navigate across the stored directly discovered data. They do not perform any discovery actions. They take positional arguments.

discovery.process(source)

Returns the process node corresponding to the source node, which must be a ListeningPort or NetworkConnection node.

discovery.children(process)

Returns a list of the child processes for the given DiscoveredProcess node. Returns an empty list if there no children or the parameter is not a DiscoveredProcess node.

discovery.descendents(process)

Returns a list consisting of the children of the given DIscoveredProcess node, and recursively all of the children's children.

discovery.parent(process)

Returns the parent process for the given DiscoveredProcess node. Returns none if the process has no parent.

discovery.allProcesses(source)

Returns a list of all processes corresponding to the directly discovered data source node. Returns an empty list if the source node is not a valid directly discovered data node.

discovery.access(source)

Returns the DiscoveryAccess node for the source node, which must be a directly discovered data node. Returns none if the source is not valid.