Discover Certificates from Server

Before you begin

Ensure the following before attempting to discover a certificate from a particular server device through AppViewX:

Server devices should be added in AppViewX.
The device should be in Managed state.

Request Structure


Endpoint:	/certificate/discovery/instance
Type:	POST
Sample URL:	`https://<IP/HostName/TenantName>:<GWPORT>/avxapi/certificate/discovery/instance?gwsource=external` To understand the elements of the sample URL, click here.
Headers
Content-Type:	application/json

Table 1. Input Parameters
Name	Description
sessionId `Header`	(Mandatory) Session Id received after login. Type: String Constraint: Required if username and password are not provided.
username `Header`	(Mandatory) AppViewX login username. Type: String Constraint: Required if sessionId is not provided.
password `Header`	(Mandatory) AppViewX login password. Type: String Constraint: Required if sessionId is not provided.
Content-Type `Header`	(Mandatory) Specifies the nature of the data in the payload. Type: String Constraint: Value of the parameter should be ‘application/json’
gwsource `Query`	(Mandatory) Source from which the request is triggered. (E.g. external) Type: String
Payload `Body`	Contains all the parameters to be sent in the request body for the post request. Type: Payload

Payload

Table 2. Payload
Name	Description
discoveryType	(Mandatory) Type of the discovery. Type: String Possible values:: ONDEMAND, SCHEDULED
name	(Mandatory) Name of the discovery instance to be created. Type: String
description	(Optional) Description of the discovery request. Type: String
groupName	(Mandatory) Specifies the group under which the discovered certificate needs to be tagged. Type: String Constraint: Not mandatory if the field rbacRuleProcessRequired is true
source	(Mandatory) Source of the certificates. Type: String Possible values:: Server
certStatus	(Mandatory) Specifies the certificate status to be maintained in the inventory after discovering the certificates. Type: String Possible values:: Managed, Monitored, or None. If "None", then certificates will not be moved to certificate inventory.
targetList	(Mandatory) Name of the devices where the certificates need to be discovered. Type: List of String Constraint: Device names which are added already need to be specified.
coolingPeriod	(Mandatory) Indicates whether the discovery is sequential or parallel. 0 is for sequential, whereas 1< indicates parallel. Type: Integer
associatedRule	(Optional) Name of the rule to be associated with the discovered certificates. Type: String Constraint: Rule name which is added already need to be specified.
rbacRuleProcessRequired	(Optional) Determines whether Rbac rule process is required. Type: Boolean (true or false) Constraint: If "true", then new certificates will be tagged under the group specified in the rule.

Response Structure

Response returns string of type application/json with the following body parameters:

Table 3. Parameters
Name	Description
response	Contains the response attributes for the enrollment request. Type: Object
discoveryName `response`	Name of the discovery request created. Type: String
message `response`	Success message of the action or failure description in case of error. Type: String
message	Success message or failure description in case of error. Type: String
appStatusCode	Application specific status code for the response. It is a non-null for failure response. Type: String
tags	Additional information in case of a failure response. Type: Object
header	HTTP headers associated with the response. Type: Object

Status Codes


HTTP Code	appStatusCode	Response Message
202 Accepted	NA	Discovery history details added successfully with discovery id<value>, and discovery operation has been triggered.
401 Unauthorized	AVX_GW_003	Authentication failed, reason - Invalid Credentials. Remediation: Ensure that valid username and password or valid sessionId is provided as header parameters.
400 Bad Request	MANDATORY_FIELD_MISSING	Mandatory field is missing or invalid - <<field name>> Remediation: Ensure that a valid value is provided for the <<field name>> field in the request.
400 Bad Request	INVALID_REQUEST	Target list not found. Remediation: Ensure that a valid value is provided for the targetList field in the request.
400 Bad Request	MSG_DISC_HISTORY_UNIQUE_NAME	Discovery name already exists. Please specify different Discovery name. Remediation: Provide a different Discovery name.
417 Expectation failed	GROUP_NOT_FOUND	Specified certificate group is not found. Remediation: Ensure that valid value is provided for the groupName section in the request.
417 Expectation failed	FIELD_VALUE_INVALID	Cooling period should be 0 or greater than 1. Remediation: Provide a correct value in the field coolingPeriod.
417 Expectation failed	FIELD_VALUE_INVALID	Discovery Type should be ONDEMAND or SCHEDULED. Remediation: Provide a correct value in the field discoveryType.
500 Internal Server Error	avx-common-011	Error while processing.

Sample Request/Response

Sample Request

 {
 "discoveryType": "ONDEMAND",
 "name": "ServerDiscovery",
 "description": "Discovery from server devices",
 "source": "SERVER",
 "coolingPeriod": "5",
 "associatedRule": "RevokedCertExclusion",
 "certStatus": "MANAGED",
 "rbacRuleProcessRequired": false,
 "groupName": "Default",
 "targetList": [
 "ApacheLinux"
 ]
 }

Sample Response

 {
 "response": {
 "discoveryName": "ServerDiscovery",
 "message": "Discovery history details added successfully with discovery id 605dc592c0bb5b1924e6851f, and discovery operation has been triggered."
 },
 "message": "Discovery history details added successfully with discovery id 605dc592c0bb5b1924e6851f, and discovery operation has been triggered.",
 "appStatusCode": null,
 "tags": {},
 "headers": null
 }

References

Understanding the sample URL

IP/HostName/TenantName: Replace with the actual IP address, hostname, or tenant name based on the specific configuration in AppViewX.
- IP: A unique identifier assigned to each device connected to a computer network that uses the Internet Protocol for communication
  The IP address will be included in the endpoint URL for an on-prem deployment.
- HostName: A human-readable label assigned to a device (host) on a network
  The hostname will be included in the endpoint URL for an on-prem deployment.
- TenantName: An identifier label for a tenant given to indicate which tenant's data the API request will access/modify
  The tenant name will be included in the endpoint URL for a SaaS deployment.
GWPORT: AppViewX gateway port
A gateway port refers to a network port through which data is sent and received to communicate with a gateway in an on-prem deployment.
Example: 31443
avxapi: Path parameter value (static) that is part of the endpoint's URL
Endpoint: Endpoint of the API, for example: execute-hook
gwsource: Source or origin of a gateway, for example: external.