Using the Host Input Import Tool

Preparing to Run Host Input Imports
Writing Host Input Import Files
Host Input Import Syntax
Example Host Input Import File
Testing Your Import on the Management Center
Running a Host Input Import

Using the Host Input Import Tool

You can import data to the network map by creating an import file and processing it with the host input import tool.

See the following sections for more information:

Preparing to Run Host Input Imports

Some host import operations depend on product mapping information you supply using the Management Center web interface to map third-party product, fix, and vulnerability names and IDs to definitions in the Cisco database. Depending on the data you plan to import, you may need to perform the configuration steps described in the following sections before you run your import:

Creating a Third-Party Vulnerability Map

If you want to import data including third-party vulnerabilities and use that data for impact correlation, you must create a third-party vulnerability map set before importing the data. The third-party map set allows the system to translate the third-party vulnerability ID to the corresponding Cisco vulnerability ID. If you do not map a third-party vulnerability before import, the vulnerability does not map to a Cisco vulnerability ID and cannot be used for impact correlation. You can create a map set in two ways: using the Management Center web interface or using the AddScanResult command. If you import scan results using this command, be sure to edit the source definition for the input source in your network discovery policy to set the identity source type to Scanner.

Third-party vulnerability mappings can be created at any domain level. Use the SetMap command to specify a map name to use for the mappings. The map must be defined at the netmap being used in the CSV file or one of its parents.

For more information on mapping third-party vulnerabilities through the web interface, see the Firepower Management Center Configuration Guide. For more information on the SetMap and AddScanresult commands, see Understanding Import File Format.

Creating a Third-Party Product Map

When you import operating system or server data to a host, you can map third-party product name details to a Cisco product definition. You can create a third-party product map through the Management Center web interface.

The third-party product map set allows the system to translate the third-party vendor, product, and version to the corresponding Cisco definition. When you set a third-party product map containing a server definition or an operating system definition, within the same script you can then just define the display strings for a third-party server or operating system when you add or set it using the API.

If you map third-party fixes to Cisco fix definitions using a third-party product map, set the product map, and then add fixes to hosts using the third-party fix name, the system maps the fixes to the appropriate Cisco fix definitions and deactivates vulnerabilities addressed by the fix.

To map a third-party product to a Cisco product definition:

Access: Admin

1. Select Policies > Application Detectors, then click User Third-Party Mappings.

The User Third-Party Mappings page appears.

2. You have two choices:

To edit an existing map set, click Edit next to the map set.
To create a new map set, click Create Product Map Set.

The Edit Third-Party Product Mappings page appears.

3. Type a name for the mapping set in the Mapping Set Name field.

4. Type a description in the Description field.

5. You have two choices:

To map a third-party product, click Add Product Map.
To edit an existing third-party product map, click Edit next to the map set.

The Add Product Map page appears.

6. Type the vendor string used by the third-party product in the Vendor String field.

7. Type the product string used by the third-party product in the Product String field.

8. Type the version string used by the third-party product in the Version String field.

9. In the Product Mappings section, select the operating system, product, and versions you want to use for vulnerability mapping from the following lists (if applicable):

Vendor
Product
Major Version
Minor Version
Revision Version
Build
Patch
Extension

For example, if you want a host running a product whose name consists of third-party strings to use the vulnerabilities from Red Hat Linux 9, select Redhat, Inc. as the vendor, Redhat Linux as the product, and 9 as the version.

10. Click Save.

After you create the third-party product map, you can import data using the SetOS, SetService, or AddService commands. Note the third-party product name details and Cisco product definition before importing data.

To locate third-party and Cisco product details:

Access: Admin

1. Select Policies > Application Detectors.

The Application Detectors page appears.

2. Select User Third-Party Mappings.

The Third-Party Product Mappings page appears.

3. Click the edit icon () for your product map set.

The Edit Third-Party Product Mappings page appears.

4. Click the edit icon () for your product map.

The Add Product Map pop-up window appears. Note the Vendor String, Product String, and Version String values.

For more information on mapping third-party products, see the Firepower Management Center Configuration Guide.

Writing Host Input Import Files

This chapter provides details on the syntax to import data using the import commands of the host input import tool. When writing your import file, make sure you follow the instructions provided in the following sections:

Understanding Import File Format

In general terms, the import file is a text file containing one command per line, with comma-separated values (CSV format) specifying the command parameters. You must place a few key commands at the beginning of the file, if required by the operations in the file. Those key commands are described here, while all the other commands are described later in Host Input Import Syntax.

Caution: The system discards any data in the import file that it cannot interpret. To test your import file before running the import, see Testing Your Import on the Management Center.

Host input import files must begin with the SetDomain (if domains are used), SetSource, and SetMap commands, to provide an application source name and to set up third-party product name mappings for the imported data. For more information, see Understanding Import File Format.

After the SetDomain, SetSource, and SetMap commands, you can add additional command lines to the file. Each command line contains a single command with the parameters needed for that command and ends with a hard return. Note that some fields are required only in that you must supply that information to make sure that the host input succeeds and adds meaningful data to the network map. For example, you can add a fix to the system without providing a fix identification number or fix name that matches an existing Cisco fix definition and without mapping the third-party fix to a Cisco fix.

For more information on syntax for individual commands you can include, see the following sections:

To see an example of a complete import file and explanations of each section of the file, see Example Host Input Import File.

Setting the Domain

If your system has domains defined, then you may need to specify a target domain at the beginning of the import file. If neither the client certificate nor the import file specifies a leaf domain, then running the import will fail with an error message.

The system builds a separate network map for each leaf domain. In a multidomain deployment, you must specify the leaf domain where you are adding network map data.
If you will be using the Host Input Client to submit the CSV commands, then you can create separate client certificates for each leaf domain. When using such a certificate, all operations will target the certificate's domain. In this case, there is no reason to use the SetDomain command in the script.
If you intend to use the nmimport tool on a system with domains, then the import file must begin with the SetDomain command. If no leaf domain is specified by the SetDomain command or by the certificate, the import will immediately fail with an error message without processing any commands.
The domain name must be fully qualified with space-backslash-space between each domain level, such as Global \ Accounting or Global \ Sales \ East. The capitalization of the domain name must be identical to how the domain was defined.

To set the domain:

For the first line in your import file, use the following syntax:

SetDomain, DomainName

where SetDomain is the name of the command and DomainName is the fully qualified leaf domain to which you want to add the imported data.

Setting the Source Type

At the beginning of your import file, you must identify the source type for the data you plan to import. If you import scan results using this command, be sure to edit the source definition for the input source in your network discovery policy to set the identity source type to Scanner.

To set the source type:

1. Add a line to your import file using the following syntax:

SetSourceType, Sourcetype

where SetSourceType is the name of the command and Sourcetype is the type of source you want to add or use for the imported data. Valid values are 2 (scanner) or 3 (application).

If you do not use SetSourceType, the default is type is 3 (application).

Setting the Source ID

At the beginning of your import file, you must set the source ID for the data you plan to import.

To set the source application name:

1. Add a line to your import file using the following syntax:

SetSource, SourceID

where SetSource is the name of the command and SourceID is the identification string you want to display as the source application for the imported data.

The following is an example of the SetSource command:

# Set the current SOURCE_ID and Product Map to "Custom Utility"

SetSource, Custom Utility

To see these commands in context in an example file, see Entire Example File.

Setting a Third-Party Product Map

If you are planning to import third-party operating system, server, or fix definitions, you must create a user third-party product map for the third-party names. You can use this command to set the current third-party map for the current session. You create third-party mappings using the Management Center web interface to set up a reusable map between each third-party vendor, product, and version combination and the corresponding Cisco product definition. If you set a third-party map and then add or set host operating system or server data that includes third-party application names included in the map, the system uses the mappings to map the Cisco product definition, and associated vulnerabilities, to each host where the input occurs.

For instance, you could create a map set called “Custom Utility”, in which you define the third-party strings as follows:

Vendor String - Microsoft
Product String - Win7

You could select the following Cisco product mapping in the map set:

Vendor - Microsoft, Corp.
Product - Windows 7
Patch - SP3

If you set this product map by calling SetMap, Custom Utility, it maps Microsoft Win7 to the VDB entry for the Microsoft Windows 7 product.

To set the third-party product map set:

1. Add a line to your import file using the following syntax:

SetMap, Third-PartyProductMapName

where SetMap is the name of the command and Third-PartyProductMapName is the name of the third-party product map set you want to use for the import.

For example, you could put the following line of code following the SetSource command:

SetMap, Custom Utility

You can also use this command to change to a different third-party product map within an import file.

Host Input Import Syntax

After you set the source ID and product map for your import file, as described in Setting the Source ID, you can add lines to your import file to import the specific data you want to add to your network map using various host input commands. Each import command call must end in a hard return and imports one set of import data. For an example of a complete import file, see Example Host Input Import File.

For more information on specific commands you can use, see the following sections:

Host Commands

You can use the host input API to add and remove hosts in the network map and to set operating system definitions for hosts.

For more information on host commands, see the following sections:

AddHost

You can use the AddHost command to add a host to the network map. You can add an IP host (a host with an IP address and optionally a MAC address) or a MAC-only host (a host with only a MAC address). Hosts added in this matter are not subject to the normal host timeout.

The AddHost command will have no impact if the network map already contains a host with the specified IP address or primary MAC address. If your intention is to replace any existing information for a host in the network map with new information, you must use the DeleteHost command before AddHost.

Use this syntax:

AddHost, ip_address, mac_address

Table 1 AddHost Fields
Field	Description	Required	Values
ip_address	Indicates the IP address for the added host.	Yes (unless a MAC address is provided)	An IP address, or a CIDR mask range, or IP-IP range, or a quoted comma-separated list of such values.
mac_address	Indicates the MAC address for the added host.	Yes (unless an IP address is provided)	A single MAC address.

DeleteHost

You can use the DeleteHost command to remove a host (or hosts) from the network map. You can remove an IP host (a host with an IP address and optionally a MAC address) by specifying either the IP address or the MAC address for the host. To remove a MAC-only host (a host with only a MAC address), provide the MAC address

Use this syntax:

DeleteHost, ip_address, mac_address

Table 2 DeleteHost Fields
Field	Description	Required	Values
ip_address	Indicates the string containing the IP address or addresses for the affected host or hosts.	Yes (unless MAC addresses are provided)	A single IP address.
mac_address	Indicates the list of MAC addresses for the affected host or hosts.	Yes (unless IP addresses are provided)	A single MAC address.

SetOS

You can use the SetOS command to specify the vendor, product, version, and mobile device information for the operating system for specified hosts. When you import operating system information, you set the display strings for the vendor, product, version, and mobile device information. You can also map the third-party vendor, product, and version strings to a Cisco product definition. See Creating a Third-Party Product Map for more information.

If you map third-party operating system names to a Cisco definition, the vulnerabilities for that operating system in the Cisco database correspond to the host where the third-party data was imported. If you have already created a third-party product map set using the Management Center web interface, you can use the SetMap command to use the values you specified in that map set for the third-party application strings and corresponding Cisco definitions, as described in Setting a Third-Party Product Map.

The operating system identity displayed in a host profile is set by the highest priority source. Possible sources have the following priority order: user, scanner and application (set in the network discovery policy), Firepower, then NetFlow. Note that a new higher priority operating system identity will not override a current operating system identity if it has less detail than the current identity.

If you define a custom operating system for a host, the Management Center web interface indicates the source for the change in the Source Type field of the event view or the basic host information of the host profile.

Use this syntax:

SetOS, ip_address, vendor_str, product_str, version_str, vendor_id, product_id, major, minor, revision, build, patch, extension, device_string, mobile, jailbroken

Or, to set a new product map before you set the operating system, use this syntax:

SetMap, map_name

For more information on setting third-party product maps, see Setting a Third-Party Product Map.

Table 3 SetOS Fields
Field	Description	Required	Allowed Values
ip_address	Indicates the string containing the IP address or addresses for the affected host or hosts.	Yes	An IP address, or a CIDR mask range, or IP-IP range, or a quoted comma-separated list of such values.
vendor_str	Supplies the operating system vendor display name used by the third-party application.	No	string
product_str	Supplies the operating system product display name used by the third-party application.	No	string
version_str	Supplies the operating system version display name used by the third-party application.	No	string
vendor_id	Supplies the Cisco vendor definition to map to.	No	uint32
product_id	Supplies the Cisco product definition to map to.	No	uint32
major	Supplies the Cisco major version definition to map to.	No	uint32
minor	Supplies the Cisco minor version definition to map to.	No	uint32
revision	Supplies the Cisco revision string to map to.	No	uint32
build	Supplies the Cisco build definition to map to.	No	string
patch	Supplies the Cisco patch definition to map to.	No	string
extension	Supplies the Cisco extension definition to map to.	No	string
device_string	Supplies the detected mobile device hardware information.	No	string
mobile	Indicates whether the operating system is running on a mobile device.	No	uint8
jailbroken	Indicates whether the mobile device operating system is jailbroken.	No	uint8

UnsetOS

You can use the UnsetOS command to remove a previously set OS definition from specified hosts. It resets the OS definition to allow the system to track changes to the operating system in the future.

Use this syntax:

UnsetOS, ip_address

Where ip_address is a comma-separated list of IP addresses, CIDR blocks, and ranges of IP addresses representing the host or hosts where you want to reset the operating system identity.

Server Commands

You can update server information for hosts in the network map using the server commands.

For more information, see the following sections:

AddService

You can add a server to an existing host in the network map using the AddService command.

The server identity displayed in a host profile is set by the highest priority source. Possible sources have the following priority order: user, scanner and application (set in the network discovery policy), Firepower, then NetFlow. Note that a new higher priority server identity will not override a current operating server identity if it has less detail than the current identity.

Use this syntax:

AddService, ip_address, port, proto, server, vendor_str, version_str, vendor_id, product_id, major, minor, revision, build, patch, extension

Or, to set a new product map before you add the server, use this syntax:

SetMap, map_name

AddService, ip_address, port, proto, server, vendor_str, version_str, vendor_id, product_id, major, minor, revision, build, patch, extension

For more information on setting third-party product maps, see Creating a Third-Party Product Map and Setting a Third-Party Product Map.

Table 4 AddService Fields
Field	Description	Required	Values
ip_address	Indicates the string containing the IP address or addresses for the affected host or hosts.	Yes	An IP address, or a CIDR mask range, or IP-IP range, or a quoted comma-separated list of such values.
port	Use this field in combination with the `ip_address` and `proto` fields to specify the server to be added on the hosts where it should be added.	Yes	Integers in the range of 1-65535.
proto	Use this field in combination with the `ip_address` and `port` fields to specify the server to be added on the hosts where it should be added.	Yes	Either the strings `tcp` or `udp` or the appropriate protocol IDs `6` (tcp) or `17` (udp).
server	The name or ID of the server in the Cisco database.	No	To identify the server, you must include a value for either `service_name` or `service_id`. If neither is provided, the server will be listed as `unknown`. If a server name is provided, The system looks up the server ID. If no ID exists for the server name, the system creates an ID.
vendor_str	Supplies the server vendor display name used by the third-party application.	No	string
product_str	Supplies the server product display name used by the third-party application.	No	string
version_str	Supplies the server version display name used by the third-party application.	No	string
vendor_id	Supplies the Cisco vendor definition.	No	uint32
product_id	Supplies the Cisco product definition.	No	uint32
major	Supplies the Cisco major version definition.	No	uint32
minor	Supplies the Cisco minor version definition.	No	uint32
revision	Supplies the Cisco revision string.	No	uint32
build	Supplies the Cisco build definition to map to.	No	string
patch	Supplies the Cisco patch definition to map to.	No	string
extension	Supplies the Cisco extension definition to map to.	No	string

SetService

You can use the SetService command to specify the server protocol, vendor, product, and version for a specified server. You can set display strings for the server using service keys. By mapping a third-party product in the Management Center web interface (see Creating a Third-Party Product Map) or using the SetMap command (see Setting a Third-Party Product Map), you can associate third-party server data with the vulnerability information for specific Cisco product definitions.

If the server protocol does not already exist, this call causes a new server identity to be created for the string. If the specified server does not exist previously, the system creates it.

The server identity displayed in a host profile is set by the highest priority source. Possible sources have the following priority order: user, scanner and application (set in the network discovery policy), Firepower, then NetFlow. Note that a new higher priority server identity will not override a current server identity if it has less detail than the current identity.

If you define a third-party server definition for a host, the Firepower Management Center web interface indicates the source for the change in the Source Type field of the Servers table view of events or the Servers section of the host profile.

Note: If the number of servers stored in the network map for a specific host exceeds 100, new server information is ignored until servers are deleted from the host.

Use this syntax:

SetService, ip_address, port, proto, server, vendor_str, version_str, vendor_id, product_id, major, minor, revision, build, patch, extension

Or, to set a new product map before you set the server, use this syntax:

SetMap, map_name

SetService, ip_address, port, proto, server, vendor_str, version_str, vendor_id, product_id, major, minor, revision, build, patch, extension

For more information on setting third-party product maps, see Setting a Third-Party Product Map.

Table 5 SetService Fields
Field	Description	Required	Values
ip_address	Indicates the string containing the IP address or addresses for the affected host or hosts.	Yes	An IP address, or a CIDR mask range, or IP-IP range, or a quoted comma-separated list of such values.
port	Use this field in combination with the `ip_address` and `proto` fields to specify the server to be set on the hosts where it should be set.	Yes	Integers in the range of 1-65535.
proto	Use this field in combination with the `ip_address` and `port` fields to specify the server to be set on the hosts where it should be set.	Yes	Either the strings `tcp` or `udp` or the appropriate protocol IDs `6` (tcp) or `17` (udp).
server	The name or ID of the server in the Cisco database.	No	To identify the server, you must include a value for either `service_name` or `service_id`. If neither is provided, the server will be listed as `unknown`. If a server name is provided, the system looks up the server ID. If no ID exists for the server name, the system creates an ID.
vendor_str	Supplies the server vendor display name used by the third-party application.	No	string
product_str	Supplies the server product display name used by the third-party application.	No	string
version_str	Supplies the server version display name used by the third-party application.	No	string
vendor_id	Supplies the Cisco vendor definition.	No	uint32
product_id	Supplies the Cisco product definition.	No	uint32
major	Supplies the Cisco major version definition.	No	uint32
minor	Supplies the Cisco minor version definition.	No	uint32
revision	Supplies the Cisco revision string.	No	uint32
build	Supplies the Cisco build definition to map to.	No	string
patch	Supplies the Cisco patch definition to map to.	No	string
extension	Supplies the Cisco extension definition to map to.	No	string

UnsetService

You can use the UnsetService command to remove user-added server definitions from a specified host. UnsetService does not remove any server definitions detected through Firepower.

Note: If the number of servers stored in the network map for a specific host exceeds 100, new server information is ignored until servers are deleted from the host.

Use this syntax:

UnsetService, ip_address, port, proto

Table 6 UnsetService Fields
Field	Description	Required	Values
ip_address	Indicates the string containing the IP address or addresses for the affected host or hosts.	Yes	An IP address, or a CIDR mask range, or IP-IP range, or a quoted comma-separated list of such values.
port	Use this field in combination with the `ip_address` and `proto` fields to specify the server to be removed on the hosts where it should be removed.	Yes	Integers in the range of 1-65535.
proto	Use this field in combination with the `ip_address` and `port` fields to specify the server to be removed on the hosts where it should be removed.	Yes	Either the strings `tcp` or `udp` or the appropriate protocol IDs `6` (tcp) or `17` (udp).

DeleteService

You can use the DeleteService command to remove a server from a specified host. You must specify the port and protocol of the server you want to delete.

Use this syntax:

DeleteService, ip_address, port, proto

Table 7 DeleteService Fields
Field	Description	Required	Values
ip_address	Indicates the string containing the IP address or addresses for the affected host or hosts.	Yes	An IP address, or a CIDR mask range, or IP-IP range, or a quoted comma-separated list of such values.
port	Use this field in combination with the `ip_address` and `proto` fields to specify the server to be deleted on the hosts where it should be deleted.	Yes	Integers in the range of 1-65535.
proto	Use this field in combination with the `ip_address` and `port` fields to specify the server to be deleted on the hosts where it should be deleted.	Yes	Either the strings `tcp` or `udp` or the appropriate protocol IDs `6` (tcp) or `17` (udp).

Client Application Commands

You can use the client application commands to modify client application data for hosts in the network map.

For more information, see the following sections:

AddClientApp

You can use the AddClientApp command to add client applications to existing hosts in the network map. If the client application name does not already exist in the Cisco database, the system creates a new entry for the client application.

The client application identity displayed in a host profile is set by the highest priority source. Possible sources have the following priority order: user, scanner and application (set in the network discovery policy), Firepower, then NetFlow. Note that a new higher priority client application identity will not be override a current client application identity if it has less detail than the current identity.

Use this syntax:

AddClientApp, ip_address, app_name, app_type, version

Table 8 AddClientApp Fields
Field	Description	Required	Values
ip_address	Indicates the string containing the IP address or addresses for the affected host or hosts.	Yes	An IP address, or a CIDR mask range, or IP-IP range, or a quoted comma-separated list of such values.
app_name	Indicates the client application name.	Yes	A string consisting of alphanumeric characters or spaces. For existing applications, corresponds to ID values in the database. The system looks up the ID to see if it matches an existing client application ID. If it does not, a new ID is created.
app_type	This field is deprecated.	No	A null value.
version	Indicates the application version.	No	A string consisting of alphanumeric characters or spaces.

DeleteClientApp

You can use the DeleteClientApp command to remove a client application from the specified host.

Use this syntax:

DeleteClientApp, ip_address, app_name, app_type, version

Table 9 DeleteClientApp Fields
Field	Description	Required	Values
ip_address	Indicates the string containing the IP address or addresses for the affected host or hosts.	Yes	An IP address, or a CIDR mask range, or IP-IP range, or a quoted comma-separated list of such values.
app_name	Indicates the client application name.	Yes	A string consisting of alphanumeric characters or spaces. For existing applications, corresponds to ID values in the database. The system looks up the ID to see if it matches an existing client application ID. If it does not, a new ID is created.
app_type	This field is deprecated.	No	A null value.
version	Indicates the application version.	No	A string consisting of alphanumeric characters or spaces.

DeleteClientAppPayload

You can use the DeleteClientAppPayload command to remove a web application from the specified host.

Use this syntax:

DeleteClientAppPayload, ip_address, app_name, app_type, version, payload_type, payload_id

Table 10 DeleteClientAppPayload Fields
Field	Description	Required	Values
ip_address	Indicates the string containing the IP address or addresses for the affected host or hosts.	Yes	An IP address, or a CIDR mask range, or IP-IP range, or a quoted comma-separated list of such values.
app_name	Indicates the client application name.	Yes	A string consisting of alphanumeric characters or spaces. For existing applications, corresponds to ID values in the database. The system looks up the ID to see if it matches an existing client application ID. If it does not, a new ID is created.
app_type	This field is deprecated.	No	A null value.
version	Indicates the application version.	No	A string consisting of alphanumeric characters or spaces.
payload_type	Indicates the web application category.	Yes	The number `0`. For existing applications, corresponds to ID values in the database. The system looks up the type to see if it matches an existing web application type. If it does not, a new type is created.
payload_id	Indicates the web application name.	Yes	A string consisting of alphanumeric characters or spaces. For existing applications, corresponds to ID values in the database. The system looks up the ID to see if it matches an existing web application ID. If it does not, a new ID is created.

Protocol Commands

You can use the protocol commands to update protocol information for hosts in the network map.

For more information, see the following sections:

DeleteProtocol

You can use the DeleteProtocol command to remove a protocol from the specified IP or MAC host.

Use this syntax:

DeleteProtocol, ip_address, mac_address, proto, type

Table 11 DeleteProtocol Fields
Field	Description	Required	Values
ip_address	Indicates the string containing the IP address or addresses for the affected host or hosts.	Yes (unless MAC addresses are provided)	An IP address, or a CIDR mask range, or IP-IP range, or a quoted comma-separated list of such values.
mac_address	Indicates the list of MAC addresses for the affected host or hosts.	Yes (unless IP addresses are provided)	A list of MAC address strings, with or without separating colons.
proto	Indicates the identification string or name of the protocol to be deleted.	Yes	Valid protocol names consisting of alphanumeric characters or spaces. For transport protocols ( `“xport”`), protocols listed in the `/etc/protocols` file are acceptable. For network protocols (“ `net` ”), see Network Protocol Values.
type	Indicates the type of protocol to be deleted.	Yes	`“xport”` or `“net”`

AddProtocol

You can use the AddProtocol command to add either a network or transport protocol to an existing host in the network map. You can supply either a protocol ID, a transport protocol name that exists in the /etc/protocols file on your Management Center or a network protocol name from Network Protocol Values.

Note: You cannot add transport protocols to MAC-only hosts.

Use this syntax:

AddProtocol, ip_address, mac_address, proto, type

Table 12 AddProtocol Fields
Field	Description	Required	Values
ip_address	Indicates the string containing the IP address or addresses for the affected host or hosts.	Yes (unless MAC addresses are provided)	An IP address, or a CIDR mask range, or IP-IP range, or a quoted comma-separated list of such values.
mac_address	Indicates the list of MAC addresses for the affected host or hosts.	Yes (unless IP addresses are provided)	A list of MAC address strings, with or without separating colons.
proto	Indicates the identification string or name of the protocol to be added.	Yes	Valid protocol names consisting of alphanumeric characters or spaces. For transport protocols ( `“xport”`), protocols listed in the `/etc/protocols` file are acceptable. For network protocols (“ `net` ”), see Network Protocol Values.
type	Indicates the type of protocol to be added.	Yes	`“xport”` or `“net”`

Package Fix Commands

You can use the Package Fix commands to apply or remove fixes for hosts in the network map for the leaf domain where you import.

For more information, see the following sections:

AddFix

You can use the AddFix command to map a fix to a specified host or server. You can map a fix using a fix ID from the Cisco vulnerability database (VDB), or using a third-party fix that you map to a fix in the VDB using the Management Center web interface.

When you apply a fix to a host or server, the vulnerability mappings for the system are adjusted and the fixed vulnerabilities are marked as Invalid in the web interface and are not used for impact assessment. However, note that if the applied fix is not applicable to the OS or server identity the fix has no effect.

Use the following syntax:

AddFix, ip_address, port, proto, fix_id

Table 13 AddFix Fields
Field	Description	Required	Values
ip_address	Indicates the string containing the IP address or addresses for the affected host or hosts.	Yes	An IP address, or a CIDR mask range, or IP-IP range, or a quoted comma-separated list of such values.
port	With the `proto` field, identifies the server affected by the fix on the host where the import occurs.	Yes, if the fix applies to a server	Integers in the range of 1-65535.
proto	With the `port` field, identifies the server affected by the fix on the host where the import occurs.	No	Either the strings `tcp` or `udp` or the appropriate protocol IDs `6` (tcp) or `17` (udp).
fix_id	Indicates the identification string for the fix.	Yes	A Cisco fix identification number or a fix name defined in a third-party product map that you use by calling the `SetMap` command before invoking the `AddFix` command. For more information, see Setting a Third-Party Product Map.

RemoveFix

You can use the RemoveFix command to remove a fix mapping from the specified host or server. When you remove a fix, vulnerability mappings are updated accordingly.

Use this syntax:

RemoveFix, ip_address, port, proto, fix_id

Table 14 RemoveFix Fields
Field	Description	Required	Values
ip_address	Indicates the string containing the IP address or addresses for the affected host or hosts.	Yes	An IP address, or a CIDR mask range, or IP-IP range, or a quoted comma-separated list of such values.
port	With the `proto` field, identifies the server affected by the fix on the host where the import occurs.	Yes, if the fix applies to a server	Integers in the range of 1-65535.
proto	With the `port` field, identifies the server affected by the fix on the host where the import occurs.	No	Either the strings `tcp` or `udp` or the appropriate protocol IDs `6` (tcp) or `17` (udp).
fix	Indicates the identification string for the fix.	Yes	A Cisco fix name or a fix name defined in a third-party product map that you use by calling the `SetMap` command before invoking the `AddFix` command. For more information, see Setting a Third-Party Product Map.

Host Attribute Commands

You can use the host input import tool to set attribute values for the network map for the leaf domain where you import. For more information, see the following sections:

AddHostAttribute

You can use the AddHostAttribute command to add text or URL attributes. Note that adding a host attribute does not add a value for the attribute. For more information on setting an attribute value, see SetAttributeValue, below.

Use this syntax:

AddHostAttribute, attributename, attributetype

where attributename is the name of the attribute (consisting of alphanumeric characters and spaces.) and attributetype is the type of attribute ( text or URL).

DeleteHostAttribute

You can use the DeleteHostAttribute command to delete attributes.

Use this syntax:

DeleteHostAttribute, attributename

where attributename is the name of the attribute. (Valid names consist of alphanumeric characters and spaces.)

SetAttributeValue

You can use the SetAttributeValue command to set the value of an existing attribute to the specified value for specified hosts. This command can set the value of user-defined host attributes and the Criticality attribute. You can use this command to set the host criticality by using “criticality” as the attribute id.

Use this syntax:

SetAttributeValue, ip_address, attribute, value

Table 15 SetAttributeValue Fields
Field	Description	Required	Values
ip_address	Indicates the string containing the IP address or addresses for the affected host or hosts.	Yes	An IP address, or a CIDR mask range, or IP-IP range, or a quoted comma-separated list of such values.
attribute	Indicates the host attribute name.	Yes	Valid attribute names consisting of alphanumeric characters or spaces.
value	Indicates the host attribute value.	Yes	Valid attribute values for the named attribute, consisting of alphanumeric characters or spaces. If a value is passed in for a list attribute, the value must be an existing named value for the list attribute.

DeleteAttributeValue

You can use the DeleteAttributeValue command to remove an attribute value for a host.

Use this syntax:

DeleteAttributeValue, ip_address, attribute, value

Table 16 DeleteAttributeValue Fields
Field	Description	Required	Values
ip_address	Indicates the string containing the IP address or addresses for the affected host or hosts.	Yes	An IP address, or a CIDR mask range, or IP-IP range, or a quoted comma-separated list of such values.
id	Indicates the host attribute name.	Yes	Valid attribute names consisting of alphanumeric characters or spaces.
value	Indicates the host attribute value.	Yes	Valid attribute values for the named attribute, consisting of alphanumeric characters or spaces. If a value is passed in for a list attribute, the value must be an existing named value for the list attribute.

Vulnerabilities Commands

You can use the vulnerabilities commands to update the status of vulnerabilities on a host.

For more information, see the following sections:

SetInvalidVulns

You can use the SetInvalidVulns command to deactivate vulnerabilities on a host or set of hosts. For the command call to be effective, the vulnerability must exist on the host and be set to valid.

Use this syntax:

SetInvalidVulns, ip_address, port, proto, type, vuln_id

Table 17 SetInvalidVulns Fields
Field	Description	Required	Values
ip_address	Indicates the string containing the IP address or addresses for the affected host or hosts.	Yes	An IP address, or a CIDR mask range, or IP-IP range, or a quoted comma-separated list of such values.
port	With the `proto` field, identifies the server affected by the vulnerability on the host where the import occurs.	Yes, if the fix applies to a server	Integers in the range of 1-65535.
proto	With the `port` field, identifies the server affected by the vulnerability on the host where the import occurs.	Yes, if the fix applies to a server	Either the strings `tcp` or `udp` or the appropriate protocol IDs `6` (tcp) or `17` (udp).
vuln_id	Indicates the vulnerability ID for the vulnerability.	Yes	Valid Cisco vulnerability IDs, or mapped third-party vulnerability IDs. For third-party vulnerabilities, note that you must map the third-party vulnerability ID and reference the vulnerability map set in the `vuln_type` field. For more information, see Creating a Third-Party Vulnerability Map.

SetValidVulns

You can use the SetValidVulns command to activate vulnerabilities on a host or set of hosts. Once you set a vulnerability as Valid for a host, Management Center assigns a red impact to the event if the SID in the event is mapped to the valid vulnerability. For the command call to be effective, the vulnerability must exist on the host and be set to invalid.

Use this syntax:

SetValidVulns, ip_address, port, proto, type, vuln_id

Table 18 SetValidVulns Fields
Field	Description	Required	Values
ip_address	Indicates the string containing the IP address or addresses for the affected host or hosts.	Yes	An IP address, or a CIDR mask range, or IP-IP range, or a quoted comma-separated list of such values.
port	With the `proto` field, identifies the server affected by the vulnerability on the host where the import occurs.	Yes, if the fix applies to a server	Integers in the range of 1-65535.
proto	With the `port` field, identifies the server affected by the vulnerability on the host where the import occurs.	Yes, if the fix applies to a server	Either the strings `tcp` or `udp` or the appropriate protocol IDs `6` (tcp) or `17` (udp).
vuln_id	Indicates the vulnerability ID for the vulnerability.	Yes	Valid Cisco vulnerability IDs, or mapped third-party vulnerability IDs. For third-party vulnerabilities, note that you must map the third-party vulnerability ID and reference the vulnerability map set in the `vuln_type` field. For more information, see Creating a Third-Party Vulnerability Map.

Scan Result Commands

You can use the host input import tool to add scan results to your Management Center and to flush the added results to the database. When adding a scan result you can map third-party vulnerabilities in the results to CVE or BugTraq vulnerabilities.

See the following sections for more information:

AddScanResult Command

You can use the AddScanResult command to add scan results from a third-party vulnerability scanner and map each vulnerability to a BugTraq or CVE ID. If you import scan results using this command, be sure to edit the source definition for the input source in your network discovery policy to set the identity source type to Scanner.

Use this syntax:

AddScanResult, ipaddr, scanner_id, vuln_id, port, protocol, name, description, cve_ids, bugtraq_ids

Note: How results are added depends on whether you use the ScanUpdate or ScanFlush command. For more information, refer to ScanFlush Command and ScanUpdate Command.

Table 19 AddScanResult Fields
Field	Description	Required	Allowed Values
ipaddr	Indicates the IP address of the scanned host or hosts.	Yes	A single IP address.
scanner_id	Indicates the scanner ID for the scanner that obtained the scan results.	Yes	'scanner_id' where `scanner_id` is a string indicating the name of the scanner that is the source of the vulnerability data you add. To add scan results from a previously used scanner, indicate the specific scanner name listed in system policies on the Management Center where you added the results. Adding results from a new scanner ID adds that scanner to the system policy. New scanners are added as the lowest priority by default. If you want to change the priority of the scanner, you can do so in the system policy. For more information, see the Firepower Management Center Configuration Guide.
vuln_id	Indicates the vulnerability ID for the vulnerability.	Yes	Valid Cisco vulnerability IDs, or mapped third-party vulnerability IDs. If this field, port, protocol, bugtraq_ids, and cve_ids are empty, this is a generic scan result.
port	With the `proto` field, identifies the server affected by the vulnerability on the host where the import occurs.	Yes, if the vulnerability applies to a server	Integers in the range of 1-65535.
proto	With the `port` field, identifies the server affected by the vulnerability on the host where the import occurs.	Yes, if the vulnerability applies to a server	Either the strings `tcp` or `udp` or the appropriate protocol IDs `6` (tcp) or `17` (udp).
name	The name of the vulnerability being imported.	No	A string enclosed in single quotes; for example: `'Using NetBIOS to retrieve info from a Windows host'`
description	The description of the vulnerability being imported.	No	A string enclosed in single quotes; for example: `'The following 2 NetBIOS names have been gathered...'`
cve_ids	Space-separated list of CVE vulnerability IDs	No	Valid CVE vulnerability IDs; for example, `'cve_ids: CVE2003-0988'`. If this field, port, protocol, vuln_id, and bugtraq_ids are empty, this is a generic scan result.
bugtraq_ids	Space-separated list of BugTraq vulnerability IDs	No	Valid BugTraq vulnerability IDs; for example, `'bugtraq_ids: 9506'`. If this field, port, protocol, vuln_id, and cve_ids are empty, this is a generic scan result.

ScanFlush Command

After you add scan results to a Management Center using AddScanResult, you must use either the ScanUpdate or ScanFlush command to cause the AddScanResult commands to run on the Management Center so the scan results upload to the database.

The ScanFlush command does not require any arguments, and you can use it at whatever point in the import file that you want to upload data to the database.

If you use the ScanFlush command, it removes any existing scan results from the host and only adds the new results.

ScanUpdate Command

The ScanUpdate command does not require any arguments, and you can use it at whatever point in the import file that you want to upload data to the database.

If you use the ScanUpdate command, it does not remove the existing scan results from the host. It merges the new scan results with the existing scan results.

If you use the ScanUpdate command with the DeleteScanResult command, it deletes the specific results.

Note that a ScanUpdate automatically occurs when an import finishes even if it is not explicitly included in the import file, because the client connection closes.

DeleteScanResult Command

You can use the DeleteScanResult command with the ScanUpdate command to remove specific scan results from a specific host.

If you supply values for the optional parameters, this restricts results to those matching the parameters. If you do not supply values for the optional parameters, it deletes all results on the specified IP address.

Use this syntax:

DeleteScanResult, ipaddr, 'scanner_id', vuln_id, port, protocol

Table 20 DeleteScanResult Fields
Field	Description	Required	Allowed Values
ipaddr	Indicates the IP address of the scanned host or hosts.	Yes	A single IP address.
scanner_id	Indicates the scanner ID for the scanner that obtained the scan results.	No	'scanner_id' where `scanner_id` is a string indicating the name of the scanner that is the source of the vulnerability data you add. To add scan results from a previously used scanner, indicate the specific scanner name listed in system policies on the Management Center where you added the results. Adding results from a new scanner ID adds that scanner to the system policy. New scanners are added as the lowest priority by default. If you want to change the priority of the scanner, you can do so in the system policy. For more information, see the Firepower Management Center Configuration Guide.
vuln_id	Indicates the vulnerability ID for the vulnerability.	No	A valid third-party vulnerability ID.
port	With the `proto` field, identifies the server affected by the vulnerability on the host where the import occurs.	No	Integers in the range of 1-65535.
proto	With the `port` field, identifies the server affected by the vulnerability on the host where the import occurs.	No	Either the strings `tcp` or `udp` or the appropriate protocol IDs `6` (tcp) or `17` (udp).

Example Host Input Import File

The following sections illustrate how you might construct an import file to import data using the host input import tool.

The following sections, in sequential order, show each portion of the file:

Example: Setting the Source Domain, Source ID and Product Map

The example script starts with calls to set the domain, the name of the source application, and the product map to be used in the import:

# Set the current DOMAIN to Global \ Sales \ East

SetDomain, Global \ Sales \ East

# Set the current SOURCE_ID and Product Map to "Asset Management App"

SetSource, Asset Management App

SetMap, Asset Management App

This source domain provides the domain in which the host information will be added. The source ID value provides an application name for the system to use in host input events resulting from this import. If you viewed a host input event or a host profile for a host modified using this import, the Source Type value would be Application: Asset Management App.

Note that the product map called “Asset Management App” referenced by the SetMap command was created using the Management Center web interface.

Because the third-party product map is the Asset Management App map set, the system maps any third-party operating or server names in the commands contained in the import file to Cisco definitions using product maps or fix maps defined in that map set, as illustrated in Example: Setting the Operating System.

Example: Adding a Host

After the file sets the source application name and third-party product map, commands to import data follow. The data will be added to the network map for the leaf domain specified either with the SetDomain command or the certificate. The first import command is the AddHost command:

# Add an IP host with no Primary MAC

AddHost,1.2.3.4

Note that the IP address for the added host is 1.2.3.4 and no primary MAC address is set for the host.

Example: Adding a Protocol to the Host

The next command in the import file adds the ospf protocol to the 1.2.3.4 host:

# Add the ospf protocol to the host

AddProtocol, 1.2.3.4,,ospf,xport

Note that the protocol type for the protocol is xport.

Example: Adding a Server to the Host

The next command in the import file uses the AddService command to add the OpenSSH server to the 1.2.3.4 host:

# Add a server for the host

AddService,1.2.3.4, 22, tcp, ssh, OpenSSH, 4.1

Note that the command sets the port to 22, the protocol to tcp, the server type to ssh, the vendor display string to OpenSSH, and the version display string to 4.1.

Example: Setting the Operating System

The import file next sets the operating system value for the host using the SetOS command. The Asset Management App map set contains a product map mapping the third-party product name Microsoft Win2K to the Cisco product definition for Microsoft Windows 2000 SP3:

The command in the import file is as follows:

# Set the OS. Because the Map is set to "Asset Management App" these values resolve to the Windows 2000 SP3 definition

SetOS, 1.2.3.4, Microsoft, Win2k

Note that the SetOS command line includes values for the vendor_str and product_str fields to set the operating system display name to Microsoft Win2K. Because those match the Vendor String and Product String settings defined in the Asset Management App product map set, the system maps that third-party operating system name to the Cisco Microsoft Windows 2000 SP3 product definition.

Example: Adding a Third-Party Vulnerability

The import file next imports a third-party vulnerability to the 1.2.3.4 host. This example depends on a third-party vulnerability map set created using the Management Center web interface:

The command in the import file sets the Vuln003 vulnerability to valid:

# Add a third-party vulnerability (from third-party vulnerability map "Other Vulnerabilities Map Set") to the host

SetValidVuln, 1.2.3.4,,, Other Vulnerabilities Map Set, Vuln0003

Example: Setting the Host Criticality

The next command in the import file uses the SetAttributeValue command to set the criticality for the 1.2.3.4 host to High.

# Set the criticality of the host to "High"

SetAttributeValue, 1.2.3.4,criticality,high

Note that the attribute name is set to c riticality and the attribute value is set to “high”.

Example: Add Scan Results

The next set of commands in the import file uses the AddHost command to add a host and then the AddScanResult command to add data for that host from a third-party scanner.

# Add IP host for scan results to follow

AddHost,1.2.3.5

# Add the scan result from a Qualys scanner to the network map

AddScanResult,1.2.3.5,"Qualys",82003,,,"ICMP Timestamp Request","ICMP (Internet Control and Error Message Protocol) is a protocol encapsulated in IP packets. Its principal purpose is to provide a protocol layer able to inform gateways of the inter-connectivity and accessibility of other gateways or hosts. ping is a well-known program for determining if a host is up or down. It uses ICMP echo packets. ICMP timestamp packets are used to synchronize clocks between hosts.","cve_ids: CVE-1999-0524","bugtraq_ids:"

Example: Running Commands on the Management Center

The ScanFlush command indicates to the Management Center that it can run the queued commands above the ScanFlush line.

ScanFlush

Example: Adding a Client Application to the Host

The import file then uses the AddClientApp command to add a client application named BMC Remedy to the 1.2.3.4 host.

# Add a Client App

AddClientApp, 1.2.3.4, “BMC Remedy”, "Asset Manager", "0.0"

Note that the client application ID is set to BMC Remedy, the client application type is set to Asset Manager, and the version is set to 0.0.

Example: Adding a MAC-Only Host

Finally, the import file uses the AddHost command to add a MAC-only host:

# Add a MAC-only host

AddHost,,01:02:03:04:05:06

Note that the ip_address field is left blank and the MAC address is provided instead.

In addition, note that although there is no ScanFlush command at the end of the file, the remaining data from the script is sent to the network map when the import file finishes because the session disconnects.

Entire Example File

The full import file explained in the sections above looks like this:

# Example import file for Host Input Import Tool

# Set the DOMAIN to “Global \ Sales \ East”

# Set the current SOURCE_ID and Product Map to "Asset Management App"

SetDomain, Global \ Sales \ East

SetSource, Asset Management App

SetMap, Asset Management App

# Add an IP host with no Primary MAC

AddHost,1.2.3.4

# Add the ospf protocol to the host

AddProtocol, 1.2.3.4,,ospf,xport

# Add a server for the host

AddService,1.2.3.4, 22, tcp, ssh, OpenSSH, 4.1

# Set the OS. Because the Map is set to "Asset Management App" these values resolve to the Windows 2000 SP3 definition

SetOS, 1.2.3.4, Microsoft, Win2k

# Add a third-party vulnerability (from third-party map "Other Vulnerabilities Set") to the host

SetValidVuln, 1.2.3.4,,, Other Vulnerabilities Set, Vuln0003

# Set the criticality of the host to "High"

SetAttributeValue, 1.2.3.4,criticality,high

# Add IP host for scan results to follow

AddHost,1.2.3.5

# Add the scan result from a Qualys scanner to the network map

#Send the commands above to the host input service for processing

ScanFlush

# Add a Client App

AddClientApp, 1.2.3.4, "BMC Remedy", "Asset Manager", "0.0"

# Add a MAC only host

AddHost,,01:02:03:04:05:06

Testing Your Import on the Management Center

You can simulate an import with your import file to make sure it behaves as expected. Because many commands allow you to import duplicate data into the network map, you want to avoid running the same import multiple times. Running a test import avoids that problem. Additionally, the system discards any data in the import file that it cannot interpret, so you want to make sure that the import file will import completely. The test reports the results to the screen (or you can redirect them to a file) so you can then correct any problems with the file before you run the actual import.

To test an import file:

1. Copy the import file you created to the Management Center where you want to run the import.

2. Log into your Management Center with the admin account.

3. At the command line, type nmimport.pl -t filename.

To redirect the results of the test import to a log file, add > logfilename to the end of the command.

The system adds the imported data to the network map and either displays the result messages on the screen or redirects them to the file you specify.

Running a Host Input Import

You can run the host input import tool from the command line to process the import file you created.

Caution: The system discards any data in the import file that it cannot interpret. Additionally, if you run the same import multiple times, you may find duplicate data in your network map for some items. To prevent these issues, you may want to test import of your import file before running the actual import. For more information, see Testing Your Import on the Management Center.

Note that if you set up the host input reference client on a remote host with access to the Management Center, you can use the sf_host_input_agent.pl script to process an import file from the client. For more information on setting up the reference client, see Running the Host Input Reference Client.

To run an import:

1. Copy the import file you created to the Management Center where you want to run the import.

2. Log into your Management Center with the root account.

3. At the command line, type nmimport.pl filename.

To redirect the results of the test import to a log file, add > logfilename to the end of the command.

The system adds the imported data to the network map and either displays the result messages on the screen or redirects them to the file you specify.

Firepower System Host Input API Guide v6.0

Bias-Free Language

Results

Chapter: Using the Host Input Import Tool