User Tools

Site Tools


guides:reference:compliance:cmpl_xch

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
guides:reference:compliance:cmpl_xch [2020/06/10 10:03]
yspeerte [Forcing an NCCM poll]
guides:reference:compliance:cmpl_xch [2020/06/10 10:03] (current)
yspeerte [Forcing a Compliance check]
Line 1: Line 1:
 +{{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
 +  * **cmpl_run:​** force a compliance check
 +  * **cmpl_report:​** retrieve a report for compliance on a policy, node or policy on a node
 +  * **cmpl_report_raw:​** retrieve a detailed customizable data dump of reports on compliance
 +
 +==== Forcing an NCCM poll ====
 +
 +You can also force an NCCM poll through the exchange server. A sample exchange XML call looks like this:
 +
 +<code xml>
 +<​task>​
 +  <head
 +    userid="​--your login name--"​
 +    passwd="​--your (encrypted) password--"​
 +    task_type="​xml-request"​
 +    task_name="​nccm_run"​
 +  />
 +  <request
 +    hostname="​switch13"​
 +    fqdn="​192.168.60.113"​
 +  />
 +</​task>​
 +</​code>​
 +
 +The parameters you can send are simple:
 +  * **hostname:​** the node's hostname. This can be either in the YCE or CMDB database
 +  * **fqdn:** the node's fqdn. If no hostname 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.
 +
 +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 ''&​lt;''​ and ''&​gt;''​ 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 ''<​xml_decode>​config</​xml_decode>''​ 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:
 +<code xml>
 +<​task>​
 +  <​head ​
 +    userid="​username" ​
 +    passwd="​xxxxxxxxxxxxxx" ​
 +    log_level="​0" ​
 +    task_type="​xml_request" ​
 +    task_name="​nccm_submit" ​
 +    xml_decode="​yes"​ />
 +  <request > 
 +<​nodename>​asd--cr01001</​nodename>​
 +<​xml_decode>​config</​xml_decode>​
 +<​config>​
 +#
 +# This configuration is automatically generated at 2020-06-09 16:59:00
 +#
 +hostname &​lt;​asd--cr01001&​gt;​
 +
 +snmp-server localhost
 +#
 +interface loopback ​
 +  address 127.0.01
 +#
 +end
 +</​config>​
 +  </​request>​
 +</​task>​
 +</​code>​
 +
 +The second option is to insert the configuration as **CDATA**. This encapsulates the configuration using the header ''<​![CDATA[''​ and footer ''​]]>'',​ 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:​
 +<code xml>
 +<​task>​
 +  <​head ​
 +    userid="​username" ​
 +    passwd="​xxxxxxxxxxxxxx" ​
 +    log_level="​0" ​
 +    task_type="​xml_request" ​
 +    task_name="​nccm_submit"​ />
 +  <request nodename="​asd--cr01001">​
 +<​config><​![CDATA[
 +#
 +# This configuration is automatically generated at 2020-06-09 16:59:00
 +#
 +hostname <​asd--cr01001>​
 +
 +snmp-server localhost
 +#
 +interface loopback
 +  address 127.0.01
 +#
 +end
 +]]></​config>​
 +  </​request>​
 +</​task>​
 +</​code> ​
 +
 +The response to these calls:
 +<code xml>
 +<​task>​
 +  <​head>​ ... </​head>​
 +  <​request>​ ... </​request>​
 +  <​response ​
 +    nccm_status="​configuration unchanged, not added to nccm" ​
 +    request_error="​0" ​
 +    request_status="​completed">​
 +    <​log>​configuration has '​14'​ lines</​log>​
 +    <​log>​configuration unchanged, not added to nccm</​log>​
 +    <​nccm_data ​
 +      action="​upload" ​
 +      job_descr="​nccm upload" ​
 +      node_domain="​DOM013400" ​
 +      node_fqdn="​asd--cr01001.acme.com" ​
 +      node_name="​asd--cr01001" ​
 +      node_vendor="​HP_C5" ​
 +      operator="​username" ​
 +      session_type="​mgmt" ​
 +      state="​manual" ​
 +      verbose="​1"/>​
 +  </​response>​
 +</​task>​
 +</​code>​
 +
 +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:
 +
 +<code xml>
 +<​task>​
 +  <head
 +    userid="​--your login name--"​
 +    passwd="​--your (encrypted) password--"​
 +    task_type="​xml-request"​
 +    task_name="​cmpl_run"​
 +  />
 +  <request
 +    hostname="​switch13"​
 +    fqdn="​192.168.60.113"​
 +  />
 +</​task>​
 +</​code>​
 +
 +The parameters you can send are simple:
 +  * **hostname:​** the node's hostname. This can be either in the YCE or CMDB database
 +  * **fqdn:** the node's fqdn. If no hostname 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 a report on a node, policy, or node-policy combination. A sample request looks like this:
 +
 +<code xml>
 +<task response="">​
 +  <head
 +    userid="​--your login name--"​
 +    passwd="​--your (encrypted) password--"​
 +    task_type="​xml-request"​
 +    task_name="​cmpl_report"​
 +  />
 +  <request
 +    hostname="​switch13"​
 +    level="​3"​
 +  />
 +</​task>​
 +</​code>​
 +
 +  * If a **hostname** is specified, this command will return a report of all policies on this node.
 +  * If a **policy id** is specified, this command will return a report of all nodes in this policy.
 +  * If both a **hostname** and **policy id** are specified, this command will return the report of this policy on this node
 +  * If no **hostname** or **policy id** is defined, this report will be empty       
 +
 +**level** indicates the amount of detail returned by the report:
 +  * 0: Only the policies and nodes
 +  * 1: Up to rules
 +  * 2: Up to conditions
 +  * 3: Up to condition details - this will return everything and is the default
 +
 +A sample result looks like this:
 +
 +<code xml>
 +<​task>​
 +  <head abort_on_error="​1"​ error="​0"​ log_level="​0"​ passwd="​U2FsdGVkX18OHVUyLsoaISkoy3agroYMY2EjGRas9vc="​ req_host="​eth0gate.netyce.nl"​ status="​completed"​ task_id="​0511_0051"​ task_level="​2"​ task_name="​cmpl_report"​ task_type="​xml-request"​ userid="​jbosch">​
 +    <​logs>​ </​logs>​
 +  </​head>​
 +  <request hostname="​switch1"​ level="​3"​ request_id="​1">​ </​request>​
 +  <​response request_error="​0"​ request_status="​completed">​
 +    <report message="​Node switch1 is not compliant">​
 +      <policy message="​Policy IOS_policy is not compliant">​
 +        <rule message="​Rule '​banner_check'​ compliance error:">​
 +          <​condition message="​ And statement left leg failed with logic: ( A and ( B and C ) )"> </​condition>​
 +          <​condition message="​ Condition '​A'​ not compliant">​
 +            <​condition_detail message="​ Condition line '​banner exec' in condition '​A'​ not found in block '<​full_config>'​ with path '<​full_config>'"/>​
 +          </​condition>​
 +        </​rule>​
 +        <rule message="​Rule '​vtp_mode'​ compliance error:">​
 +          <​condition message="​ Condition '​A'​ not compliant">​
 +            <​condition_detail message="​ Exclude line 'vtp mode transparent'​ in condition '​A'​ was found in block '<​full_config>'​ with path '<​full_config>'"/>​
 +          </​condition>​
 +        </​rule>​
 +      </​policy>​
 +    </​report>​
 +  </​response>​
 +</​task>​
 +</​code>​
 +
 +==== Requesting raw reports ====
 +
 +In case you want more details than just a report, you can request the raw data from the report database from the API. A sample request looks like this:
 +<code xml>
 +<task response="">​
 +  <head
 +    userid="​--your login name--"​
 +    passwd="​--your (encrypted) password--"​
 +    task_type="​xml-request"​
 +    task_name="​cmpl_report_raw"​
 +  />
 +  <request
 +    report_type="​nodes"​
 +    hostname=""​
 +    policy_id=""​
 +    policy_name=""​
 +    compliance=""​
 +    node_group=""​
 +    polling_group_id=""​
 +    node_model=""​
 +    vendor_type=""​
 +    domain=""​
 +    node_fqdn=""​
 +  />
 +</​task>​
 +</​code>​
 +
 +  * **report_type:​** either '​policies'​ or '​nodes'​. Show reports for policies or for nodes. ​
 +  * **compliance:​** if a policy or node is fully compliant; either '​yes'​ or '​no'​
 +
 +If the report type is '​policies',​ the filters you can specify are:
 +  * **policy_id:​** a policy'​s ID from the netYCE database
 +  * **policy_name:​** a policy'​s name. Supports * and ? wildcard.
 +
 +If the report type is '​nodes',​ the filters you can specify are:
 +  * **hostname:​** the node's hostname. Will also filter partial results, so "​swi"​ matches "​switch1"​.
 +  * **node_group_id:​** a node group id from the netYCE database
 +  * **polling_group_id:​** a polling group id from the netYCE database
 +  * **node_model:​** the node's Node_model attribute, this is a value we pull directly from the node's config
 +  * **domain:** the node's domain
 +  * **node_fqdn:​** the node's fqdn; supports the * and ? wildcard
 +
 +A sample return is as follows:
 +
 +<code xml>
 +<​task>​
 +  <head abort_on_error="​1"​ error="​0"​ log_level="​0"​ passwd="​U2FsdGVkX18wJSfHsTFSThj3Tga8TVl33IAZnx5SuI0="​ req_host="​eth0gate.netyce.nl"​ status="​completed"​ task_id="​0512_0029"​ task_level="​2"​ task_name="​cmpl_report_raw"​ task_type="​xml-request"​ userid="​jbosch">​
 +    <​logs>​ </​logs>​
 +  </​head>​
 +  <request compliance=""​ domain=""​ hostname=""​ node_fqdn=""​ node_group=""​ node_model=""​ policy_id=""​ policy_name=""​ polling_group_id=""​ report_type="​nodes"​ request_id="​1"​ vendor_type="">​ </​request>​
 +  <​response request_error="​0"​ request_status="​completed">​
 +    <reports Compliance="​no"​ Hostname="​clone_switch13"​ Severity="​High"​ Severity_color="#​ff0000">​
 +      <​cmpl_nodes name="​cmpl_nodes">​
 +        <data Cmpl_node_id="​666"​ Compliance="​Compliant"​ Hostname="​clone_switch13"​ Last_change_date="​2020-05-12 10:​00:​40"​ Last_check_date="​2020-05-12 10:​00:​40"​ Nccm_id="​4660"​ Node_scope="​1"​ Policy_group_id="​0"​ Policy_id="​53"​ Policy_name="​IOS_policy"​ Policy_schedule_id="​-1"​ Report_id="​26864"​ Schedule_servers="​yce72_a,​yce72_b"​ Schedule_time="​0000-00-00 00:​00:​00"​ Scheduled_policy_id="​0"​ Scope="​cmdb"​ Server=""​ Severity="​-1"​ Severity_color=""​ Severity_str=""​ Status="​1"​ Timestamp="​2020-05-12 10:​00:​40"/>​
 +        <data Cmpl_node_id="​942"​ Compliance="​Not compliant"​ Hostname="​clone_switch13"​ Last_change_date="​2020-05-12 10:​30:​37"​ Last_check_date="​2020-05-12 10:​30:​45"​ Nccm_id="​4660"​ Node_scope="​1"​ Policy_group_id="​0"​ Policy_id="​57"​ Policy_name="​NEWEST_IOS"​ Policy_schedule_id="​-1"​ Report_id="​27140"​ Schedule_servers="​yce72_a,​yce72_b"​ Schedule_time="​0000-00-00 00:​00:​00"​ Scheduled_policy_id="​0"​ Scope="​cmdb"​ Server=""​ Severity="​1"​ Severity_color="#​cc9977"​ Severity_str="​Medium"​ Status="​0"​ Timestamp="​2020-05-12 10:​30:​45"/>​
 +        <data Cmpl_node_id="​745"​ Compliance="​Not compliant"​ Hostname="​clone_switch13"​ Last_change_date="​2020-05-12 10:​05:​36"​ Last_check_date="​2020-05-12 10:​05:​41"​ Nccm_id="​4660"​ Node_scope="​1"​ Policy_group_id="​0"​ Policy_id="​55"​ Policy_name="​NEW_IOS"​ Policy_schedule_id="​-1"​ Report_id="​26943"​ Schedule_servers="​yce72_a,​yce72_b"​ Schedule_time="​0000-00-00 00:​00:​00"​ Scheduled_policy_id="​0"​ Scope="​cmdb"​ Server=""​ Severity="​3"​ Severity_color="#​ff0000"​ Severity_str="​High"​ Status="​0"​ Timestamp="​2020-05-12 10:​05:​41"/>​
 +      </​cmpl_nodes>​
 +    </​reports>​
 +    <reports Compliance="​no"​ Hostname="​clone_switch14"​ Severity="​High"​ Severity_color="#​ff0000">​
 +      <​cmpl_nodes name="​cmpl_nodes">​
 +        <data Cmpl_node_id="​662"​ Compliance="​Compliant"​ Hostname="​clone_switch14"​ Last_change_date="​2020-05-12 10:​00:​40"​ Last_check_date="​2020-05-12 10:​00:​40"​ Nccm_id="​4666"​ Node_scope="​1"​ Policy_group_id="​0"​ Policy_id="​53"​ Policy_name="​IOS_policy"​ Policy_schedule_id="​-1"​ Report_id="​26860"​ Schedule_servers="​yce72_a,​yce72_b"​ Schedule_time="​0000-00-00 00:​00:​00"​ Scheduled_policy_id="​0"​ Scope="​cmdb"​ Server=""​ Severity="​-1"​ Severity_color=""​ Severity_str=""​ Status="​1"​ Timestamp="​2020-05-12 10:​00:​40"/>​
 +        <data Cmpl_node_id="​950"​ Compliance="​Not compliant"​ Hostname="​clone_switch14"​ Last_change_date="​2020-05-12 10:​30:​37"​ Last_check_date="​2020-05-12 10:​30:​45"​ Nccm_id="​4666"​ Node_scope="​1"​ Policy_group_id="​0"​ Policy_id="​57"​ Policy_name="​NEWEST_IOS"​ Policy_schedule_id="​-1"​ Report_id="​27148"​ Schedule_servers="​yce72_a,​yce72_b"​ Schedule_time="​0000-00-00 00:​00:​00"​ Scheduled_policy_id="​0"​ Scope="​cmdb"​ Server=""​ Severity="​1"​ Severity_color="#​cc9977"​ Severity_str="​Medium"​ Status="​0"​ Timestamp="​2020-05-12 10:​30:​45"/>​
 +        <data Cmpl_node_id="​741"​ Compliance="​Not compliant"​ Hostname="​clone_switch14"​ Last_change_date="​2020-05-12 10:​05:​36"​ Last_check_date="​2020-05-12 10:​05:​41"​ Nccm_id="​4666"​ Node_scope="​1"​ Policy_group_id="​0"​ Policy_id="​55"​ Policy_name="​NEW_IOS"​ Policy_schedule_id="​-1"​ Report_id="​26939"​ Schedule_servers="​yce72_a,​yce72_b"​ Schedule_time="​0000-00-00 00:​00:​00"​ Scheduled_policy_id="​0"​ Scope="​cmdb"​ Server=""​ Severity="​3"​ Severity_color="#​ff0000"​ Severity_str="​High"​ Status="​0"​ Timestamp="​2020-05-12 10:​05:​41"/>​
 +      </​cmpl_nodes>​
 +    </​reports>​
 +  </​response>​
 +</​task>​
 +</​code>​
  
guides/reference/compliance/cmpl_xch.txt ยท Last modified: 2020/06/10 10:03 by yspeerte