REST API Utilization Guide
Guide Overview
Genian NAC provides REST APIs to enable provision of endpoint information, creation of policies/objects, and configuration changes for integration with other devices or systems.
This guide is written based on V5.0 and aims to provide guidance on requirements, authentication methods, and key APIs for utilizing Genian NAC's REST API.
Prerequisites
Genian NAC Utilization Prerequisites
Authentication is required to call the REST API from external devices to Genian NAC. Select an API authentication method between 'API Key' or 'API Service Account' and generate its value.
- API Key
- The API Key method involves generating an API key for an integration account and attaching the API Key every time Genian NAC's API is called.
- It can be generated and used separately for each account. The permission for the call is dependent on the permissions of that account.
- For more details, please refer to Mutual Authentication Method using API Key.
- API Service Account
- The API Service Account method involves creating and using a separate account for integration.
- Unlike the API-Key method, which attaches an API-Key to each call, this is implemented as a single unit, performing functions after logging into Genian NAC with the API Service Account.
- This method is advantageous when implementing a single function, rather than fragmentary functions for simple information verification, by also implementing a Log-off procedure.
- API Service Accounts cannot be used as accounts for Web Console access.
- For more details, please refer to Mutual Authentication Method using API Service Account.
Networking Prerequisites
The REST API provided by Genian NAC connects using the HTTPS protocol (TCP/8443).
TCP/8443 port is the same as the Web Console access port. Therefore, if settings for Genian NAC Web Console access are already applied in firewalls, etc., no additional work is required.
Mutual Authentication Method for API Utilization
To utilize the REST API with security ensured between Genian NAC and the integrated device, mutual authentication must be performed first.
Genian NAC provides two authentication methods (API Key, API Service Account). Utilizing the REST API requires a Request URL statement or curl command.
For curl creation and testing methods, please refer to Reference - API Utility Tool: Swagger.
Note
- API calls via curl are possible in Ubuntu Terminal, Windows Command, etc.
- When making API calls using curl, if an SSL error occurs (for untrusted certificates), please apply by adding the k option (set to not verify SSL for the URL). (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 method using an API Key allows you to call and use the API through a pre-agreed Key value.
An API Key is generated for each administrator account and calls the API with the same permissions as the account.
Warning
- Please be careful as system information may be exposed if the API Key is leaked. It is also recommended to change it periodically for security.
- Step 1. Generate API Key
- After accessing Genian NAC Web Console, click Management > User menu
- Click the Administrator Account that will use the API Key
- Go to Basic Information > Login Settings > API Key item
- Click the Generate New Key button to generate an API Key for that account
- Step 2. Authentication using API Key
- In the curl you intend to use, at the end of the API Path, enter the generated API Key like ?apiKey={003def2d-4326-4a40-8372-e7806ce5950f}
- Proceed with API call test 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
- The REST API uses the "?" delimiter to separate the Request URL and Get Parameter part. If more than one delimiter is used after the end of the Request URL, it will not be recognized correctly.
- When using the REST API, if another Parameter value exists in the Get Parameter, adding apiKey using "&" at the end of the value will make it work correctly.
- 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 authentication method using an API service account is to add and use a dedicated account for utilizing the API.
- Step 1. Create Service Role
- As service role creation requires separate management related to system security, please request API Service Role (Permission) creation, and a technical support representative will guide you separately.
- Step 2. Grant Service Role to Account for API Service
- After accessing Genian NAC Web Console, click Management > User menu
- Click the Account to be used as an API service account
- Go to Basic Information > Basic Settings > Management Role item
- Grant the API Service Role permission that was created through the creation request
- Step 3. Configure IP Pattern or URL Pattern
- Click the Account granted API Service Role permission
- Go to Basic Information > Settings by Management Role > Trusted Connection Settings item
- Configure patterns for IP or URL that are allowed to call the API
Warning
- Since security issues may occur, Subnet and Range settings are not allowed when configuring IP patterns.
- Step 4. Authentication using API Service Account
- Proceed with API call test using curl (API service account can be called without an 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 }]"
Key APIs
Key API items for integration with Genian NAC include NODES, TAGS, USERS, LOGS, NODEGROUPS, CVES, etc., and their respective contents are as follows:
NODES API
Genian NAC defines a node as a device or endpoint with an IP and MAC.
Nodes are automatically registered when they connect to the network segment managed by NAC or through an agent installed on the node.
Key APIs related to nodes are as follows:
| Description | Type | API Path | Main Purpose |
|---|---|---|---|
| Retrieve full node list and information | GET | /nodes | Retrieve full node list and information for the purpose of obtaining node IP and nodeId to perform specific node information retrieval and tag assignment/removal. |
| Retrieve specific IP node information | GET | /nodes/{ip}/managementscope | Used for the purpose of obtaining nodeId value for a specific IP received to perform tag assignment and removal on that node. |
| Assign tag to specific node | POST | /nodes/{nodeId}/tags | Used for the purpose of performing network isolation by assigning a blocking tag to a specific node deemed a threat node. |
| Remove tag from specific node | DELETE | /nodes/{nodeId}/tags | Used for the purpose of allowing network entry by removing a blocking tag from a specific node deemed safe. |
| Retrieve detailed information of specific node | GET | /nodes/{nodeId}/information/{catgry} | Used for the purpose of obtaining a list of open ports for a specific node for port management. |
Example of retrieving full node list and information
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"
Example of retrieving specific IP node information
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"
Example of assigning tag to specific node
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\": \"\" }]"
Example of removing tag from specific node
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\"]"
Example of retrieving detailed information of specific node
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 can use tags to classify nodes/users. (Default Tags include TRUSTED, THREAT, GUEST, and can be modified or added.)
Tags are used to differentiate node groups when applying NAC enforcement policies through integration with external devices.
Key APIs related to tags are as follows:
| Description | Type | API Path | Main Purpose |
|---|---|---|---|
| Retrieve tag list | GET | /tags | Retrieve tag information for the purpose of obtaining tag ID or name information to perform tag assignment and removal on nodes and user IDs. |
| Create tag | POST | /tags | Used for the purpose of creating a tag when the tag item that the administrator intends to grant to a node or user ID does not exist in Genian NAC. |
Example of retrieving tag list
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"
Example of creating tag
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\": \"테스트 태그\", \"np_periodtype\": 0, \"np_period\": \"\", \"np_periodexpire\": \"\", \"np_adminroles\": \"\", \"np_color\": \"\", \"np_static\": 0}"
USERS API
Users in Genian NAC refer to user and department information created by the administrator or through DB synchronization.
Key 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 | Retrieve tag ID or name information for the purpose of retrieving the list of tags applied to a specific user ID to assign and remove tags. |
| Assign tag to specific user ID | POST | /users/{userId}/tags | Used for the purpose of performing network isolation by assigning a blocking tag to a specific unauthorized user ID. |
| Remove tag from specific user ID | DELETE | /users/{userId}/tags | Used for the purpose of allowing network entry by removing a blocking tag from a specific authorized user ID. |
Example of retrieving tag list applied to specific user ID
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"
Example of assigning tag to specific user ID
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\": \"\" }]"
Example of removing tag from specific user ID
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
Audit logs in Genian NAC refer to all logs of events occurring in systems, devices, etc., and are stored internally on the log server.
Key APIs related to logs are as follows:
| Description | Type | API Path | Main Purpose |
|---|---|---|---|
| Retrieve audit logs | GET | /logs | Retrieve Genian NAC's audit logs for the purpose of utilizing them in creating dashboards and event status. |
Example of retrieving audit logs
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's policies are divided into node policies and enforcement policies, and node groups are required for policy application.
Key APIs related to node groups are as follows:
| Description | Type | API Path | Main Purpose |
|---|---|---|---|
| Retrieve node group list | GET | /nodegroups | Retrieve the list of node groups created in Genian NAC for the purpose of utilizing them in creating dashboards and security operation reports. |
Example of retrieving node group list
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"
CVES API
Genian NAC provides information on publicly known information security vulnerabilities and exposures for each node.
Key APIs related to CVEs are as follows:
| Description | Type | API Path | Main Purpose |
|---|---|---|---|
| Retrieve node's CVE history | GET | /cves | Retrieve the node's CVE history from Genian NAC for the purpose of performing network isolation on risky nodes. |
Example of retrieving node's CVE history
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 the HTTP Status Codes used in the REST API.
| Code | Descriptions | Detailed Descriptions |
|---|---|---|
| 200 | Successful operation | Request processed successfully |
| 206 | Partial Content | Indicates that a range-specified request received the requested range of content. |
| 400 | Bad Request | Client's request syntax is incorrect |
| 401 | Unauthorized | Informs that HTTP authentication information is required for request processing. Access is denied. |
| 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 could not be found. |
| 406 | Not Acceptable | Indicates that there is no appropriate content for the client's request. |
| 412 | Precondition Failed | Informs that a precondition in the client's header is not appropriate for the server's precondition. |
| 416 | Range Not Satisfiable | The specified range requested in the Range header field cannot be satisfied. |
| 500 | Internal Server Error | An error occurred on the server while processing the client's request. |
Reference - API Utility Tool: Swagger
Genian NAC provides Swagger (http://swagger.io/) to help you utilize the API.
Swagger provides REST API information and testing tools through a web page.
- Step 1. Access Swagger
- First access the Web Console with Genian NAC administrator account
- While logged in, enter https://{Policy Server IP}:8443/mc2/swagger/index.html in the address bar for second access
- Confirm Swagger access
- Step 2. Test using Swagger
- Select the API you wish to use, then click the Try It out button on the right side of that API's window
- In the Parameters section, enter the Description value and Example Value in the Body
- Click the Execute button below
- In the Responses section, confirm the curl and Request URL values (It operates normally when the Code value in the Server response item is 200.)
Note
- Content Type uses JSON and 'application/json;charset=UTF-8' is the standard. (If the format is different, the font may appear corrupted.)