{{indexmenu_n>3}} ===== Compliance XCH API ===== At the moment we support four different API calls for NCCM and compliance: * **nccm_run:** force an NCCM poll * **nccm_submit:** Push a configuration to the NCCM * **cmpl_run:** force a compliance check * **cmpl_report:** retrieve a report for compliance on a policy, node group, shown per policy or per node ==== Forcing an NCCM poll ==== You can also force an NCCM poll through the exchange server. A sample exchange XML call looks like this: The parameters you can send are simple: * **node_name:** the node's hostname. This can be either in the YCE or CMDB database * **fqdn:** the node's fqdn. If no node_name is provided, we try to find the node based on its fqdn, which can be an ip or string. These nodes will be scheduled for an NCCM poll and they will be picked up on the nccmd daemon's next cycle (if load permits). ==== Submit a manual NCCM configuration ==== The configurations are normally retrieved from the nodes (jobs, nccm poll). But sometimes it could be desired to upload a configuration directly into the NCCM. For example when a node configuration cannot be retrieved directly and a NCCM report or Compliance check is required anyway. The ''**nccm_submit**'' API call allows you to create an NCCM entry for a node as the 'latest' configuration. To submit a configuration for a node it must exist as either a CMDB node or as an YCE node. The configuration can be submitted with an optional attribute, ''nccm_polltime'', to insert a manual timestamp of the configuration instead of the current date and time. However, as with GIT and other 'diff' based storage engines, the NCCM cannot process submitted configurations out-of-order. The provided polling timestamps are mostly administrative and the configuration is still considered the 'latest' superseding the previous configuration. The option is useful mostly to submit a series of configurations taken at different historical moments. Their order is NOT verified or enforced although a transaction with an invalid or badly formatted nccm_polltime is rejected. The nccm_polltime must be formatted as "YYYY-MM-DD hh:mm:ss". As the configuration will be embedded in the XML-formatted API call, precautions must be taken to prevent conflicting XML characters in the configuration. Two options exists to achieve this. First the configuration can be **encoded** using HTML codes. The ''<'' and ''>'' will then be encoded as ''<'' and ''>'' respectively and some other characters will be treated likewise. The use of encoding must be explicitly indicated in the request by adding ''xml_decode="yes"'' in the "head" and ''config'' in the "request" part of the API call. This informs the API that the field "config" must be decoded. An example of this call using encoding: asd--cr01001 2022-09-27 09:20:00 config # # This configuration is automatically generated at 2022-06-09 16:59:00 # hostname <asd--cr01001> snmp-server localhost # interface loopback address 127.0.0.1 255.255.255.255 # end The second option is to insert the configuration as **CDATA**. This encapsulates the configuration using the header '''', which informs the XML decoder to ignore any xml characters within this section. The use of CDATA does not require any variables in the API request. The same example using CDATA for the configuration: snmp-server localhost # interface loopback address 127.0.01 # end ]]> The response to these calls: ... ... configuration has '14' lines configuration unchanged, not added to nccm If a configuration was determined as unchanged, the response ''nccm_status'' will say as much. When a new entry is created in the NCCM, the message will read "created new nccm diff config: 65", where the number refers to the Nccm_id where it is stored. The response will also return the node details it used to create the NCCM entry like the fqdn, vendor and domain name. ==== Forcing a Compliance check ==== You can also force a Compliance check through the exchange server. A sample exchange XML call looks like this: The parameters you can send are simple: * **node_name:** the node's hostname. This can be either in the YCE or CMDB database * **fqdn:** the node's fqdn. If no node_name is provided, we try to find the node based on its fqdn, which can be an ip or string. These nodes will be scheduled for compliance and they will be picked up on the nccmd daemon's next cycle (if load permits). ==== Requesting reports ==== You can request reports with the same search filters as you can in the reports form (for more information, refer to the [[menu:cmpl:reports|Reports]] section. A sample request looks like this: * **type:** The report type. Mandatory * 'policies': get results based on policies * 'rules': get results based on rules * **report_template_id:** A report template id. Optional. When a value is provided it will load all filters in that template. Any other parameter values in this request will overwrite them if they exist. Either one of these following is mandatory, to prevent overloading the system * **policy_id:** a policy's ID from the netYCE database * **group_name:** a node group name Additional parameters to set as filters: * **hostname:** A (part of a) hostname of a node. So both "switch1" and "swi" match "switch1". Optional. * **policy_name:** A (part of a) policy name. Optional. * **rule_name:** A (part of a) rule name. Optional. * **vendor_type:** A vendor type. Optional. * **detail_level:** The level of detail to show the report in: * 0: Only only the basic policy or node information * 1: Up to conditions - default * 2: Up to condition details * 3: Up to condition full details - this will return everything * **status:** 1 ("compliant") or 0 ("not compliant"). Optional * **severity:** The string version of the severity as set in the NCCM Lookup. Optional. * **report_summary:** The report summary. Can be part of this string. Optional. A sample return is as follows: