Importing customer networks data into Argus with argus-cli

This guide will quickly go through the steps required to create and update Argus customer networks from CSV data. It assumes argus-cli is already installed and configured.

The argus-cli command used for importing customer network data is argus-cli customer-networks update.

Preparing data for the import

The customer-networks update command expects CSV data with some constraints :

With than in mind, we can prepare data for the import. As an example, we can use the following CSV data :

10.10.1.0/24,first network
10.10.1.0/24,second network

This contains the bare minimum : the network address and its description.

The rest of this section will go through the different fields that can be added to the data - note that the order of fields in the CSV does not matter and can be specified when running the import command.

network addresses

As shown above, network addresses can be provided using decimal notation, optionally providing the netmask using slash notation.

Example without netmask :

10.10.1.0,first network
10.10.1.0,second network

Warning

If the netmask is not provided, it will default to /32.

Example with netmask :

10.10.1.0/24,first network
10.10.1.0/24,second network

subnet masks

Subnet masks can be specified as part of the network address, as shown in the example above. However, it is also possible to provide them in a separate column. In that case, the full mask must be provided. As an example, the example data above can also be provided as :

10.10.1.0,255.255.255.0,first network
10.10.1.0,255.255.255.0,second network

zones

A network can be assigned one of 4 zones :

  • UNKNOWN

  • INTERNAL

  • EXTERNAL

  • DMZ

If an unexpected value is found in the CSV data, it will be set to the default : UNKNOWN.

Example :

10.10.1.0/24,first network,INTERNAL
10.10.1.0/24,second network,INTERNAL

locations

The location indicates the physical location of a given network. In order for a network to be attached to a given location, that location must exist in Argus and be accessible to the user running the import.

The list of available locations can be obtained with the customer-networks list command :

argus-cli customer-networks list-locations <customer>

Where <customer> is the customer’s shortName.

Note

There is a set of “global” shared locations that can always be used, but they will only be listed if the API key used to run that command has the viewGlobalLocations function enabled.

If a location can not be resolved, it will be set to the default : unknown.

Running the import

Once the data data is ready, it can be imported into Argus using the customer-networks update command.

The synopsys of the command is :

argus-cli customer-networks update CUSTOMER FILE

where CUSTOMER is the customer’s Argus short name and FILE the path to the CSV file with the data.

Specifying the input format

As mentioned above, the order of fields does not matter and can be specified. There are two ways of specigying the format : using the --format option, or using CSV headers.

Warning

Only valid fields should be present in the data. Unexpected fields will cause unexpected behavior.

Note

If the CSV data uses another delimiter than ,, it can be specified using the argus-cli customer-networks update --delimiter option.

Using the --format option

The argus-cli customer-networks update --format option takes a comma-separated list of fields expected to be present in the input CSV data.

The valid fields names are address (or Network), description, subnet_mask, zone and location (or LocationShortName). They are case-sensitive.

The default format is address,description, so the following data can be imported without any specification :

10.10.1.0/24,first network
10.10.1.0/24,second network

As an example, the following data can be imported with --format description,address,netmask,zone,location :

first network,10.10.1.0,255.255.255.0,INTERNAL,oslo
second network,10.10.1.0,255.255.255.0,INTERNAL,oslo

Using CSV headers

Alternatively, if the first row of the CSV data is a header, this header can be used by the import command by using the argus-cli customer-networks update --first-line-defines-format option.

Example :

description,address,netmask,zone,location
first network,10.10.1.0,255.255.255.0,INTERNAL,oslo
second network,10.10.1.0,255.255.255.0,INTERNAL,oslo

Updating and deleting networks

By default, the customer-networks update command will only create new networks in argus :

  • existing networks will not be updated, even if the CSV data differs frpm Argus data

  • no existing networks will be deleted

This behavior can be changed using the argus-cli customer-networks update --replace and argus-cli customer-networks update --delete-missing flags :

Warning

As an import using these flags can be destructive, it is recommended to perform a dry run (argus-cli customer-networks update --dry) to ensure the the outcome of the import will be as expected.

running the import non-interactively

By default, the customer-networks update will prompt for confirmation before creating or deleting Argus data.

In order to run the command non-interactively, set the argus-cli customer-networks update --always-yes flag.

Warning

Use with caution if combined with the argus-cli customer-networks update --replace and/or argus-cli customer-networks update --delete-missing flags.