Add/Edit a device

Adds a device to AFA, or edits the device configuration for a device already managed by AFA.

Resource details

Resource Name:

/api/v1/devices/

Request Methods:

  • POST - adds a device
  • PUT - edits a device

Request URL Parameters:

Parameter

Required

Type

Description
body

Mandatory

String

Data in JSON format that specifies the values for all parameters applicable to the brand of the added or edited device.

For more details, see Request parameters by brand.

addChildren

Optional

Boolean

True - managed devices are automatically added. (Default)

False - managed devices are not added unless specified explicitly.

testMode

Optional

Boolean

True - used as a test run without actually adding or editing the device specified. Returns all parameters that would have been sent by the request.

False (default) - performs the actual request.

Response:

Code

Description
200

Operation completed successfully

400

Bad request, with one of the following error messages:

  • ALREADY_EXISTS. Specified device not found in AFA.
  • SCHEME_ERROR. Failed to load the device schema.
  • Validation Error. API values are not valid according to the device schema.
  • Not Found. Relevant when editing a device configuration, if the specified device is not found in AFA.

401

Unauthorized

403

Non-admin user

Request example - edit device

curl --location --request PUT 'https://docker:7443/afa/api/v1/devices/' \ --header 'Content-Type: application/json' \ --header 'Accept: */*' \ --header 'Cookie: PHPSESSID=r9psihhnjebng2oovhv268odh1' \ --data-raw '{ "display_name": "myUpdatedNSC", "name": "fw_10_20_13_1", "host_name": "10.20.13.1", "user_name": "admin", "passwd": "algosec", "collector": "Central Manager", "baseline_profile": "JuniperNetscreenProfile", "vrouters": "yes", "con": "SSH", "ssh_port": "", "log_collection_mode": "extensive", "collect_log": "yes", "collect_log_from": "nsm", "log_host_name": "10.0.0.2", "log_user_name": "root", "log_passwd": "algosec", "collect_log_from_adt": "nsm", "log_host_name_adt": "10.0.0.1", "log_user_name_adt": "root", "log_passwd_adt": "algosec", "additional_fw_ids": "1.1.1.1:2.2.2.2:ServerName", "log_collection_frequency": "20", "active_change": "yes", "monitoring": "no", "set_user_permissions": "no", "password_fields": "passwd:log_passwd:log_passwd_adt", "FW_TYPE": "FW_NSC" }'

Response example - edit device 

{
				"httpStatus": "200",
				"message": "Successfully modified \"myUpdatedNSC\"",
				"LogData": "",
				"fw_name": "fw_10_20_13_1",
				"syslog_restart_needed": false,
				"not_supported_audit_from_clm": false,
				"set_user_permissions": false
			}

Back to top

Request parameters by brand

The following tables list the parameters valid for each brand recognized by AFA. In the tables, click each parameter name to jump to more details.

Required Parameter
Mandatory
Optional
Required Parameter
Mandatory
Optional
Required Parameter
Mandatory
Optional
Required Parameter
Mandatory
Optional

For managed devices parameters, see Check Point Provider 1 managed device parameters.

Required Parameter

Mandatory
Optional
Required Parameter
Mandatory

Optional
Required Parameter
Mandatory
Optional
Required Parameter
Mandatory
Optional
Required Parameter
Mandatory
Optional
Required Parameter
Mandatory
Optional
Required Parameter
Mandatory
Optional
Required Parameter
Mandatory
Optional

Note: Starred parameters are technically listed as optional. However, adding a Firepower device without it's childrens' credentials will cause analysis to fail.

Required Parameter
Mandatory
Optional
Required Parameter
Mandatory
Optional
Required Parameter
Mandatory
Optional
Required Parameter
Mandatory
Optional
Required Parameter
Mandatory
Optional
Required Parameter
Mandatory

Optional
Required Parameter
Mandatory
Optional
Required Parameter
Mandatory
Optional
Required Parameter
Mandatory
Optional
Required Parameter

Mandatory
Optional
Required Parameter
Mandatory
Optional
Required Parameter
Mandatory
Optional
Required Parameter
Mandatory
Optional
Required Parameter
Mandatory
Optional
Required Parameter
Mandatory
Optional

Request parameters for device from file

The following table lists parameters for devices created from file.

Required Parameter
Mandatory
Optional

Device parameter details

The following table lists all the parameters used by /api/v1/devices/ GET, POST and PUT methods. All of the listed values are formatted as Strings, unless otherwise indicated.

Note: By default, parameter values for child objects are automatically imported into your REST API call. This functionality is controlled by the addChildren parameter.

Parameter

Description
active_change

Licenses ActiveChange capabilities for the domain.

Possible values:

  • yes
  • no (default)
additional_fw_ids

Additional device identifiers.
AFA can use multiple IP addresses or hostnames to identify this device when parsing logs, in addition to the default host.
Allow_Auto_Implementation

Possible values:

  • yes
  • no (default)
arrFWs/do_log_analysis

Configures whether to perform log analysis on child devices in the array.
arrFWs/FW_baseline_profile

The default baseline profile for the child device in the array.
arrFWs/FW_display_name

Display name of the child device in the array.
arrFWs/FW_epasswd

Password used for advanced mode for the child device in the array. Relevant for Cisco routers only.
arrFWs/FW_host_name

Host name of the child device in the array.
arrFWs/FW_NAME

Name of the child device in the array.
arrFWs/FW_os

Operating system of the child device in the array.
arrFWs/FW_passwd

Password to access the child device in the array.
arrFWs/FW_user_name

Username to access the child device in the array.

arrFWs/FWDefined

Determines whether the child device in the array is defined.

Possible values:

  • yes
  • no
arrFWs/FWLogAnalysis

Determines whether log analysis is enabled for the child device in the array.

Possible values:

  • yes
  • no
arrFWs/FWLogCollectMode

The log collection mode defined for the child device in the array.

Possible values:

  • none
  • standard
  • extensive
arrFWs/FWName

The unique AFA name for the child device in the array.
arrFWs/FWOrigName

The original named as defined in the child device in the array.
arrFWs/FWParent

The name of the child device's parent in the array.
arrFWs/IS_ENABLED

Determines whether the child device in the array is enabled.

Possible values:

  • yes
  • no
arrFWs/log_collection_mode

Mode of log collection.

Possible values:

  • none
  • standard
  • extensive
arrFWs/LOGSERVER

The name of the log server for the child device in the array.
arrFWs/RM_NAME

The name of the ASMS system node that collects data for the child device in the array.

Default value: Central Manager
Auto_Tree_Update_Enabled

Allows monitor to auto update the device tree if new VRFs are found on monitor

aws_access_key_id

AWS access key ID.
aws_assume_role

Set of temporary security credentials you can use to access AWS resources that you might not normally have access to
aws_resource_name

Amazon Resource Name (ARN).
aws_secret_access_key

AWS secret access key.
aws_specific_region

AWS region.
azure_client_id

Azure app client ID (Application ID).
azure_client_key

Client secret key.
azure_subscription_id

GUID that identifies your subscription.
azure_tenant_id

GUID that identifies the Azure Active Directory instance.
baseline_profile

The default baseline profile for the device.
brand

Device brand, for devices that don't have a specific FW_TYPE parameter value.

Possible values:

  • aws - Amazon Web Services (AWS) EC2.
  • azure - Azure.
  • pv1 - Check Point Provider 1.
  • cma - Check Point Smart Center.
  • ciscoaci - Cisco Application Centric Infrastructure (ACI).
  • pix - Cisco ASA.
  • firepower - Cisco Firepower.
  • ciscoise - Cisco Identity Services Engine (ISE).
  • ios - Cisco IOS.
  • nexus - Cisco Nexus Router.
  • file - Device from file.
  • f5bigip_afm - F5 BIG-IP LTM and AFM.
  • fortigate - Fortinet Fortigate.
  • fortimanager - Fortinet Fortimanager.
  • nsc - Juniper Netscreen.
  • space_security_director - Juniper Space.
  • junos - Juniper SRX.
  • paloalto - Palo Alto firewall.
  • panorama - Palo Alto Panorama.
  • nsx - VMWare NSX.
CKP_R80_or_higher

Relevant for Check Point Provider 1 and SmartCenter.

Possible values:

  • 1 - device will be connected to CKP Manager R80 or higher.
  • 0 - device will not be connected to CKP Manager R80 or higher.
CMA

Comma-separated list of the Check Point Smart Center names.
CMA_HOST

Comma-separated list of the Check Point Smart Center IP addresses.

collect_log

Enable log collection.

Possible values:

  • yes
  • no
collect_log_from

Log server type for traffic logs.

Possible values:

  • (blank) - no log collection.
  • syslog - syslog NG Server.
  • nsm - Juniper NSM - relevant only for NetScreen devices.
collect_log_from_adt

Log server type for audit logs.

Possible values:

  • (blank) - no log collection.
  • syslog - syslog NG Server.
  • nsm - Juniper NSM - relevant only for NetScreen devices.
collector

Name of the ASMS system node that collects data from the device.

Possible values:

  • Central Manager (Default)
  • <name of the collector>
communication

Relevant for all SSH Direct devices.

Possible values: cpstat
con

Type of connection.

Possible values for most relevant brands:

  • SSH (Default)
  • telnet

For Cisco ASA, additional possible values include:

  • SSH(3des)
  • SSH(des)

For Fortigate Fortimanager, possible values include only:

  • ssh
  • rest
device_UID

The device's unique ID.*
display_name

Display name of the device.
enable_user_name

Username used for advanced mode. Relevant for Cisco routers only.
epasswd

Password used for advanced mode. Relevant for Cisco routers only.
existingFile

Relevant for Device From File.

Enables an existing file in the Algosec file system to be specified as the data source.

File must be located in /home/afa/algosec/fwfiles
fetched_devices

The device's children, in a comma-separated list of the fetched_device objects.*
fetched_devices/device_domain

The ID of the fetched device's domain.*

Value: 0
fetched_devices/device_group

The ID of the fetched device's group.*
fetched_devices/device_id

The fetched device's ID.*
fetched_devices/device_UID

The fetched device's unique ID.*
fetched_devices/display_name

The fetched device's display name.*
fetched_devices/FW_baseline_profile

The name of the baseline profile associated with the fetched devices.
fetched_devices/FW_epasswd

Password used for advanced mode for the fetched device. Relevant for Cisco routers only.
fetched_devices/FW_host_name

The host name of a fetched device.
fetched_devices/FW_NAME

The fetched device's name.
fetched_devices/FW_os

The fetched device's operating system.
fetched_devices/FW_passwd

The password used to access the fetched device.
fetched_devices/FW_user_name

The username used to access the fetched device.
fetched_devices/host_name

The host name of the fetched device, as defined in the device itself.*
fetched_devices/log_collection_mode

Mode of log collection for the fetched device.*

Possible values:

  • none
  • standard
  • extensive
fetched_devices/name

The fetched device's unique name, as defined in AFA.*
fetched_devices/original_name

The original name for the fetched device, as defined in the device itself.*
fetched_devices/RM_NAME

The ASMS system node that collects data from the fetched device.

Default value: Central Manager
fetched_devices/serial_num

The fetched device's serial number.*
fetched_devices/syslogIdentifiers

Comma-separated list of the fetched device's syslog servers.*
fileSource

Enables a file to be uploaded to add or edit a device from a file.

Possible value: Absolute path to the file you want to upload, including the file name.

These files are stored in the /home/afa/algosec/fwfiles/ directory.

For example: /home/afa/algosec/fwfiles/myCiscoASA.zip
full_analysis

Enable policy analysis.

Possible values:

  • no - default and recommended value for routers with no ACLs.
  • yes
FW_TYPE

Device type, for devices that don't have a brand parameter.

Possible values:

  • CMA - Check Point Smart Center
  • FW_FILE - Device from file
  • FW_IOS - Cisco IOS routers
  • FW_NSC - Juniper Netscreen
  • FW_NSM - Juniper NSM
  • FW_PIX - Cisco ASA
  • PV1 - Check Point Multi-Domain Security Management

Note: All other devices do not need a specific value for this parameter.

Set the brand parameter value instead.

GenerateACL

Determines whether FireFlow can generate CLI recommendations and push them to the device via ActiveChange.

Possible values:

  • yes
  • no (Default)
host_name

Host name of the device.

Note: For cloud devices, use the name defined for the device in AFA.
learning_mode

Determines whether Learning Mode is enabled.

Possible values:

  • yes. Learning Mode is enabled.
  • no (Default)

Note: Learning Mode marks all traffic from the firewall as blocked, without actually blocking traffic.

This enables you to better understand that traffic that flows through the firewall, enabling you to optimize your rules to support your business needs.
log_collection_frequency

Sets how often the log is collected.

Value in minutes.

Default = 60
log_collection_mode

Mode of log collection for the child device.

Possible values:

  • none
  • standard
  • extensive

Note: For Cisco firewalls, if only hit-counters are required (and no traffic logs), set to 'none'.
log_host_name

Host name of the traffic log server.
log_host_name_adt

Host name of the ADT Syslog server. Required for configuring a Syslog server for the first time.

Default: localhost
log_passwd

Password to connect to the traffic log server.
log_passwd_adt

Password to connect to the audit log server.
log_user_name

Username to connect to the traffic log server.
log_user_name_adt

Username to connect to the audit log server.
monitoring

Sets if the device is monitored.

Possible values:

  • yes
  • no (default)
MS_epasswd

Password used for advanced mode for the device.
MS_host_name

Host name of the device.
MS_os

Operating system of the device.
MS_passwd

Password to access the device.
MS_user_name

Username to access the device.
name

Tree name of the device.

Relevant only for device edit (PUT).

Note: This is not the name displayed in the tree. Get this name using another API.

For details, see Get details for a specified device or Get a list of devices.
number_of_allowed_encryption_keys

Relevant for all SSH Direct devices.

Controls how many SSH keys are stored for the device to avoid known_host issues.

Possible values:

  • unlimited - default
  • 1
  • 2
original_name

The device's original name, as defined in the device itself.
passwd

Password of user.
rest_port

The device's REST connection port number.
route_collection

The device's routing information collection method.

Possible values:

  • automatic (Default)
  • static

Note: If you have manually edited the device's routing table, use the static value together with filename of the static URT file.

Use this parameter together with the static_urt_filename parameter.

rules_view

Determines the type of rules view used in ASMS.

Possible values:

  • CLI

  • ASDM. Use together with the Intelligent Policy Tuner and to display unused objects within rules.

Note: ASDM is supported even if you manage the Cisco firewall from the command line.
secondary_host_ip

Allows allocation of a secondary IP for the management platform. If the primary IP is not accessible after several attempts, the secondary IP is accessed.
selected_devices

Key and value list of child devices you want to add to AFA.

Use a list of a device names with empty key values.

For example:

"selected_devices": {

 "Lion_New": {},

 "vSRX-Neptune": {},

 "vSRX-Uranus": {}

}

Note: If you are working with a management devices, you must add the child devices even if you are making no changes to those children. Children that are not listed in this value will not be added to AFA.
fetched_device/host-name

The fetched device's host name.

Use the APIs listed in Get data on managed devices to get these values.
SelectedCMA

List of Smart Centers that are managed by MDLM.
separate_vrfs

Determines whether VRF separation is enabled.

Relevant for Cisco routers only.

Possible values:

  • yes (default and recommended)
  • no
ssh_port

The port used to connect via SSH.
static_urt_filename

The name of the file that contains static routing data.

Use this parameter together with the route_collection parameter.
syslog-server-identifier

The ID of the device's syslog server.
user_name

Name of user used to access the device.
vrouters

Determines whether to display virtual routers in the device tree and network map for the device.

Back to top