REST API Usage Guide

Guide Overview

Genian NAC 6.0 provides REST API for integration with other devices or systems, enabling terminal information provision, policy/object creation, and configuration changes.

This guide is written based on V5.0 and aims to provide guidance on requirements, authentication methods, and major APIs for utilizing Genian NAC 6.0's REST API.

You can watch the REST API usage guide video on YouTube.

Prerequisites

Genian NAC 6.0 Prerequisites

External devices require authentication to call REST API to Genian NAC 6.0. You can choose between 'API Key' or 'API Service Account' authentication methods and generate the corresponding values.

API Key

• The API Key method generates an API key for the integration account and attaches the API-Key each time when calling Genian NAC 6.0's API.

• It can be generated and used separately for each account. The call permissions are dependent on the account's permissions.

• For detailed information, please refer to Mutual Authentication Method using API Key.

API Service Account

• The API Service Account method creates and uses a separate account for integration.

• Unlike the API-Key method that attaches an API-Key for each call, this method is implemented as a single unit that logs into Genian NAC 6.0 with the API service account and performs functions.

• This method is advantageous when implementing as a single function rather than fragmentary functions for simple information checking, as it includes the log-off procedure.

• API Service Accounts cannot be used as Web console access accounts.

• For detailed information, please refer to Mutual Authentication Method using API Service Account.

Networking Prerequisites

The REST API provided by Genian NAC 6.0 uses the https protocol (TCP/8443) for connection.

TCP/8443 port is the same as the Web console access port. Therefore, if firewall settings for Genian NAC 6.0 Web console access are already applied, no additional work is required.

Mutual Authentication Methods for API Usage

To utilize REST API with security ensured between Genian NAC 6.0 and integration target devices, mutual authentication must be performed first.

Genian NAC 6.0 provides two authentication methods (API Key, API Service Account), and Request URL statements or curl commands are required to utilize REST API.

For curl generation and testing methods, please refer to Reference - API Tool Provision: Swagger.

Note

• API calls through curl are possible in Ubuntu Terminal, Windows Command, etc.

• When using curl for API calls, if SSL errors occur (in case of untrusted certificates), add the k option (to disable SSL verification for URLs) to apply. (Option change: -X -> -kX)

  • Example: curl -X POST https://{Policy Server IP}/mc2/rest/{API Path} --> curl -kX POST https://{Policy Server IP}/mc2/rest/{API Path}

Mutual Authentication Method using API Key

The API Key method allows API calls using a pre-agreed Key value.

API Keys are generated for each administrator account and call APIs with the same permissions as the account.

Warning

• If the API Key is leaked, system information may be exposed, so please be careful. It is also recommended to change it periodically for security.

Step 1. API Key Generation

1. Access Genian NAC 6.0 Web console and click Management > Users menu

2. Click the administrator account to use the API Key

3. Navigate to Basic Information > Login Settings > API Key section

4. Click Generate New Key button to generate the API Key for the account

Step 2. Authentication using API Key

1. In the curl you want to use, enter the generated API Key like ?apiKey={003def2d-4326-4a40-8372-e7806ce5950f} at the end of the API Path

2. Test API calls using curl

• curl example

  curl -kX POST "https://192.168.100.253:8443/mc2/rest/nodes?apiKey={003def2d-4326-4a40-8372-e7806ce5950f}"
  -H "accept: application/json;charset=UTF-8" -H "Content-Type: application/json;charset=UTF-8"
  -d "[ { \"nl_ipstr\": \"100.100.100.101\", \"nl_mac\": \"00:00:00:00:00:00\", \"nl_sensornid\": \"\", \"nl_genidev\": 0, \"doNotDeleteNode\": true }]"
  

Note

• REST API uses "?" separator to distinguish between Request URL and Get Parameter parts. If more than two separators are used after the Request URL ends, it will not be recognized properly.

• When using REST API, if other Parameter values exist in Get Parameter, adding apiKey using "&" at the end of the value will work properly.

  • Example: curl -kX GET "https://192.168.100.253:8443/mc2/rest/tags?page=1&pageSize=30&apiKey={912fae69-b454-4608-bf4b-fa142353b463}" -H "accept: application/json;charset=UTF-8"

Mutual Authentication Method using API Service Account

The API Service Account authentication method adds a dedicated account for API usage.

Step 1. Service Role Creation

1. Since service role creation requires separate management related to system security, please request API Service Role (Permission) creation, and our technical support team will provide separate guidance.

Step 2. Assign Service Role to API Service Account

1. Access Genian NAC 6.0 Web console and click Management > Users menu

2. Click the account to use as API Service Account

3. Navigate to Basic Information > Basic Settings > Management Role section

4. Assign the API Service Role permission created through the request

Step 3. IP Pattern or URL Pattern Configuration

1. Click the account with API Service Role permission assigned

2. Navigate to Basic Information > Management Role Settings > Trusted Connection Settings section

3. Configure patterns for IP or URL that will allow API calls

Warning

• Due to potential security issues, Subnet and Range settings are not possible when configuring IP patterns.

Step 4. Authentication using API Service Account

1. Test API calls using curl (API Service Account can be called without API Key)

• curl example

  curl -kX POST "https://192.168.100.253:8443/mc2/rest/nodes"
  -H "accept: application/json;charset=UTF-8" -H "Content-Type: application/json;charset=UTF-8"
  -d "[ { \"nl_ipstr\": \"100.100.100.102\", \"nl_mac\": \"11:11:11:11:11:11\", \"nl_sensornid\": \"\", \"nl_genidev\": 0, \"doNotDeleteNode\": true }]"
  

Main APIs

The main API items for integration with Genian NAC 6.0 include NODES, TAGS, USERS, LOGS, NODEGROUPS, CVES, etc., and their contents are as follows.

NODES API

In Genian NAC 6.0, a Node refers to a device or endpoint that has an IP and MAC address.

Nodes are automatically registered when they connect to network segments managed by NAC 6.0 or through agents installed on the nodes.

The main APIs related to nodes are as follows.

Description	Type	API Path	Main Purpose
Retrieve all node list and information	GET	/nodes	To retrieve node IP and nodeId for performing tag assignment and removal on specific nodes, retrieve all node list and information.
Retrieve node information for specific IP	GET	/nodes/{ip}/managementscope	To obtain nodeId value for a specific IP received for tag assignment and removal on specific nodes.
Assign tag to specific node	POST	/nodes/{nodeId}/tags	To perform network isolation by assigning blocking tags to specific nodes judged as threat nodes.
Remove tag from specific node	DELETE	/nodes/{nodeId}/tags	To allow network access by removing blocking tags from specific nodes judged as safe.
Retrieve detailed information of specific node	GET	/nodes/{nodeId}/information/{catgry}	To obtain open port list of specific nodes for port management.

• Retrieve all node list and information example

  curl -kX GET "https://192.168.100.100:8443/mc2/rest/nodes?page=1&pageSize=30&view=node&nid=All
  &apiKey={912fae69-b454-4608-bf4b-fa142353b463}" -H "accept: application/json;charset=UTF-8"
  

• Retrieve node information for specific IP example

  curl -kX GET "https://192.168.100.100:8443/mc2/rest/nodes/192.168.100.200/managementscope
  ?apiKey={912fae69-b454-4608-bf4b-fa142353b463}" -H "accept: application/json;charset=UTF-8"
  

• Assign tag to specific node example

  curl -kX POST "https://192.168.100.100:8443/mc2/rest/nodes/974bc18c-2cf9-103a-8002-2cf05d0cf498-c0649e1c
  /tags?apiKey={912fae69-b454-4608-bf4b-fa142353b463}" -H "accept: application/json;charset=UTF-8"
  -H "Content-Type: application/json;charset=UTF-8" -d "[ { \"id\": \"\", \"name\": \"test_tag\",
  \"description\": \"\", \"startDate\": \"\", \"expireDate\": \"\", \"periodType\": \"\", \"expiryPeriod\": \"\" }]"
  

• Remove tag from specific node example

  curl -kX DELETE "https://192.168.100.100:8443/mc2/rest/nodes/974bc18c-2cf9-103a-8002-2cf05d0cf498-c0649e1c
  /tags?apiKey={912fae69-b454-4608-bf4b-fa142353b463}" -H "accept: application/json;charset=UTF-8"
  -H "Content-Type: application/json;charset=UTF-8" -d "[ \"5\"]"
  

• Retrieve detailed information of specific node example

  curl -kX GET "https://192.168.100.100:8443/mc2/rest/nodes/974bc18c-2cf9-103a-8002-2cf05d0cf498-c0649e1c
  /information/CAT_NETINFO?apiKey={912fae69-b454-4608-bf4b-fa142353b463}" -H "accept: application/json;charset=UTF-8"
  

TAGS API

Genian NAC 6.0 can use Tags to classify nodes/users. (Default Tags include TRUSTED, THREAT, GUEST, which can be modified and added.)

Tags are used to distinguish node groups when applying NAC 6.0 control policies through integration from external devices.

The main APIs related to tags are as follows.

Description	Type	API Path	Main Purpose
Retrieve tag list	GET	/tags	To obtain tag id or name information for performing tag assignment and removal on nodes and user IDs, retrieve tag information.
Create tag	POST	/tags	Used when the tag items that administrators want to assign to nodes or user IDs do not exist in Genian NAC 6.0, for tag creation purposes.

• Retrieve tag list example

  curl -kX GET "https://192.168.100.100:8443/mc2/rest/tags?page=1&pageSize=30&apiKey={912fae69-b454-4608-bf4b-fa142353b463}"
  -H "accept: application/json;charset=UTF-8"
  

• Create tag example

  curl -kX POST "https://192.168.100.100:8443/mc2/rest/tags?apiKey={912fae69-b454-4608-bf4b-fa142353b463}"
  -H "accept: application/json;charset=UTF-8" -H "Content-Type: application/json;charset=UTF-8"
  -d "{ \"np_idx\": 0, \"np_name\": \"test_tag\", \"np_desc\": \"Test Tag\", \"np_periodtype\": 0,
  \"np_period\": \"\", \"np_periodexpire\": \"\", \"np_adminroles\": \"\", \"np_color\": \"\", \"np_static\": 0}"
  

USERS API

Users in Genian NAC 6.0 refer to users and department information created by administrators or through DB synchronization.

The main APIs related to users are as follows.

Description	Type	API Path	Main Purpose
Retrieve tag list applied to specific user ID	GET	/users/{userId}/tags	To retrieve tag id or name information for tag assignment and removal, retrieve the list of tags applied to specific user IDs.
Assign tag to specific user ID	POST	/users/{userId}/tags	To perform network isolation by assigning blocking tags to unauthorized specific user IDs.
Remove tag from specific user ID	DELETE	/users/{userId}/tags	To allow network access by removing blocking tags from authorized specific user IDs.

• Retrieve tag list applied to specific user ID example

  curl -kX GET "https://192.168.100.100:8443/mc2/rest/users/test1/tags?apiKey={912fae69-b454-4608-bf4b-fa142353b463}"
  -H "accept: application/json;charset=UTF-8"
  

• Assign tag to specific user ID example

  curl -kX POST "https://192.168.100.100:8443/mc2/rest/users/test1/tags?apiKey={912fae69-b454-4608-bf4b-fa142353b463}"
  -H "accept: application/json;charset=UTF-8" -H "Content-Type: application/json;charset=UTF-8"
  -d "[ { \"id\": \"\", \"name\": \"test_tag\", \"description\": \"\", \"startDate\": \"\",
  \"expireDate\": \"\", \"periodType\": \"\", \"expiryPeriod\": \"\" }]"
  

• Remove tag from specific user ID example

  curl -kX DELETE "https://192.168.100.100:8443/mc2/rest/users/test1/tags?apiKey={912fae69-b454-4608-bf4b-fa142353b463}"
  -H "accept: application/json;charset=UTF-8" -H "Content-Type: application/json;charset=UTF-8" -d "[ \"5\"]"
  

LOGS API

In Genian NAC 6.0, audit logs refer to all logs for events that occur in systems, devices, etc., and are stored in its own log server.

The main APIs related to logs are as follows.

Description	Type	API Path	Main Purpose
Retrieve audit logs	GET	/logs	To retrieve Genian NAC 6.0's audit logs for dashboard and event status creation purposes.

• Retrieve audit logs example

  curl -kX GET "https://192.168.100.100:8443/mc2/rest/logs?page=1&pageSize=30&logschema=auditlog&periodType=custom
  &apiKey={912fae69-b454-4608-bf4bfa142353b463}"-H "accept: application/json;charset=UTF-8"
  

NODEGROUPS API

Genian NAC 6.0's policies are divided into node policies and control policies, and node groups are required for policy application.

The main APIs related to node groups are as follows.

Description	Type	API Path	Main Purpose
Retrieve node group list	GET	/nodegroups	To retrieve the list of node groups created in Genian NAC 6.0 for dashboard and security operation report creation purposes.
Retrieve specific node group	GET	/nodegroups/{id}	To retrieve detailed information and filter conditions of a specific node group.
Retrieve node group filters	GET	/nodegroups/{id}/filters	To retrieve only the filter conditions of a specific node group.
Add node group filters	POST	/nodegroups/{id}/filters	To add new filter conditions to a specific node group.
Delete node group filters	DELETE	/nodegroups/{id}/filters	To delete filter conditions from a specific node group.
Retrieve favorite node groups	GET	/nodegroups/favorite	To retrieve the list of node groups set as favorites by the user.
Create node group	POST	/nodegroups	To create a new node group.
Update node group	PUT	/nodegroups/{id}	To modify information of an existing node group.
Delete node group	DELETE	/nodegroups/{id}	To delete an existing node group.

• Retrieve node group list example

  curl -kX GET "https://192.168.100.100:8443/mc2/rest/nodegroups?page=1&pageSize=30&
  apiKey={912fae69-b454-4608-bf4b-fa142353b463}" -H "accept: application/json;charset=UTF-8"
  

• Retrieve specific node group example

  curl -kX GET "https://192.168.100.100:8443/mc2/rest/nodegroups/1?apiKey={912fae69-b454-4608-bf4b-fa142353b463}"
  -H "accept: application/json;charset=UTF-8"
  

• Retrieve node group filters example

  curl -kX GET "https://192.168.100.100:8443/mc2/rest/nodegroups/1/filters?apiKey={912fae69-b454-4608-bf4b-fa142353b463}"
  -H "accept: application/json;charset=UTF-8"
  

• Add node group filters example

  curl -kX POST "https://192.168.100.100:8443/mc2/rest/nodegroups/1/filters?apiKey={912fae69-b454-4608-bf4b-fa142353b463}"
  -H "accept: application/json;charset=UTF-8" -H "Content-Type: application/json;charset=UTF-8"
  -d "[{\"ft_item\":\"IP\",\"fo_type\":\"eq\",\"ft_value\":\"192.168.1.100\"}]"
  

• Delete node group filters example

  curl -kX DELETE "https://192.168.100.100:8443/mc2/rest/nodegroups/1/filters?apiKey={912fae69-b454-4608-bf4b-fa142353b463}"
  -H "accept: application/json;charset=UTF-8" -H "Content-Type: application/json;charset=UTF-8"
  -d "[{\"ft_item\":\"IP\",\"fo_type\":\"eq\",\"ft_value\":\"192.168.1.100\"}]"
  

• Retrieve favorite node groups example

  curl -kX GET "https://192.168.100.100:8443/mc2/rest/nodegroups/favorite?apiKey={912fae69-b454-4608-bf4b-fa142353b463}"
  -H "accept: application/json;charset=UTF-8"
  

• Create node group example

  curl -kX POST "https://192.168.100.100:8443/mc2/rest/nodegroups?apiKey={912fae69-b454-4608-bf4b-fa142353b463}"
  -H "accept: application/json;charset=UTF-8" -H "Content-Type: application/json;charset=UTF-8"
  -d "{\"subj_name\":\"test_group\",\"subj_desc\":\"Test Group\",\"subj_type\":\"NODE\",\"subj_mode\":1,\"filterList\":[{\"ft_item\":\"IP\",\"fo_type\":\"eq\",\"ft_value\":\"192.168.1.0/24\"}]}"
  

• Update node group example

  curl -kX PUT "https://192.168.100.100:8443/mc2/rest/nodegroups/1?apiKey={912fae69-b454-4608-bf4b-fa142353b463}"
  -H "accept: application/json;charset=UTF-8" -H "Content-Type: application/json;charset=UTF-8"
  -d "{\"subj_id\":\"1\",\"subj_name\":\"updated_group\",\"subj_desc\":\"Updated Group\",\"subj_type\":\"NODE\",\"subj_mode\":1,\"filterList\":[{\"ft_item\":\"IP\",\"fo_type\":\"eq\",\"ft_value\":\"192.168.2.0/24\"}]}"
  

• Partial update node group example (using fieldsToUpdate parameter)

  curl -kX PUT "https://192.168.100.100:8443/mc2/rest/nodegroups/1?fieldsToUpdate=subj_name,subj_desc&apiKey={912fae69-b454-4608-bf4b-fa142353b463}"
  -H "accept: application/json;charset=UTF-8" -H "Content-Type: application/json;charset=UTF-8"
  -d "{\"subj_id\":\"1\",\"subj_name\":\"updated_group\",\"subj_desc\":\"Updated Group\"}"
  

Note

The fieldsToUpdate parameter is used when selectively updating specific fields of a node group. When specifying comma-separated field names in this parameter, only those fields are updated while the remaining fields maintain their existing values. Example: fieldsToUpdate=subj_name,subj_desc

• Delete node group example

  curl -kX DELETE "https://192.168.100.100:8443/mc2/rest/nodegroups/1?apiKey={912fae69-b454-4608-bf4b-fa142353b463}"
  -H "accept: application/json;charset=UTF-8"
  

CVES API

Genian NAC 6.0 provides information about publicly known information security vulnerabilities and exposures for each node.

The main APIs related to CVES are as follows.

Description	Type	API Path	Main Purpose
Retrieve node CVE history	GET	/cves	To retrieve node CVE history from Genian NAC 6.0 for performing network isolation on threat nodes.

• Retrieve node CVE history example

  curl -kX GET "https://192.168.100.100:8443/mc2/rest/cves?page=1&pageSize=30
  &apiKey={912fae69-b454-4608-bf4b-fa142353b463}" -H "accept: application/json;charset=UTF-8"
  

RESPONSES CODE

The table below shows HTTP Status Codes used in REST API.

Code	Descriptions	Detailed Descriptions
200	Successful operation	Request processed normally
206	Partial Content	When Range is specified in the request, indicates that the request was received for the specified range only.
400	Bad Request	Client request syntax is incorrect
401	Unauthorized	Indicates that HTTP authentication information is required for request processing. Blocks access.
403	Forbidden	Access forbidden response. Response when blocking Directory Listing requests and Web console access, etc.
404	Not Found	The resource requested by the client does not exist on the server. Means the requested URL cannot be found
406	Not Acceptable	Means there is no appropriate content for the client request
412	Precondition Failed	Indicates that the precondition in the client's header is not appropriate for the server's precondition
416	Range Not Satisfiable	Cannot satisfy the specified range requested in the Range header field.
500	Internal Server Error	An error occurred while the server was processing the client request

Reference - API Tool Provision: Swagger

Genian NAC 6.0 provides Swagger(http://swagger.io/) to help with API utilization.

Swagger provides REST API information and testing tools through web pages.

Step 1. Swagger Access

1. First access to Genian NAC 6.0 Web console with administrator account

2. After login, enter the Swagger URL in the address bar for second access

   • On-premises: https://{Policy Server IP}:8443/mc2/swagger/index.html

   • Cloud: https://{Policy Server FQDN}/mc2/swagger/index.html (port 443)

3. Confirm Swagger access

Step 2. Testing using Swagger

1. Select the API you want to use, then click the Try It out button on the right side of the API window

2. Enter Description values in the Parameters section and Example Value values in the Body

3. Click the Execute button below

4. Check curl and Request URL values in the Responses section (Normal operation when Code value is 200 in Server response section)

Note

• Content Type uses JSON and 'application/json;charset=UTF-8' is the standard. (If the format is different, fonts may appear damaged.)