User Tools

Site Tools


Sidebar

NetYCE Documentation



guides:reference:compliance:cmpl_xch

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 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:

<task>
  <head
    userid="--your login name--"
    passwd="--your (encrypted) password--"
    task_type="xml_request"
    task_name="nccm_run"
  />
  <request
    node_name="switch13"
    fqdn="192.168.60.113"
  />
</task>

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.

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:

<task>
  <head 
    userid="username" 
    passwd="xxxxxxxxxxxxxx" 
    log_level="0" 
    task_type="xml_request" 
    task_name="nccm_submit" 
    xml_decode="yes" />
  <request > 
<node_name>asd--cr01001</node_name>
<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>

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:

<task>
  <head 
    userid="username" 
    passwd="xxxxxxxxxxxxxx" 
    log_level="0" 
    task_type="xml_request" 
    task_name="nccm_submit" />
  <request node_name="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>

The response to these calls:

<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>

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:

<task>
  <head
    userid="--your login name--"
    passwd="--your (encrypted) password--"
    task_type="xml_request"
    task_name="cmpl_run"
  />
  <request
    node_name="switch13"
    fqdn="192.168.60.113"
  />
</task>

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 a report on a node, policy, or node-policy combination. A sample request looks like this:

<task response="">
  <head
    userid="--your login name--"
    passwd="--your (encrypted) password--"
    task_type="xml_request"
    task_name="cmpl_report"
  />
  <request
    node_name="switch13"
    level="3"
  />
</task>
  • If a node_name 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 node_name and policy_id are specified, this command will return the report of this policy on this node
  • If no node_name 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:

<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 node_name="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>

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:

<task response="">
  <head
    userid="--your login name--"
    passwd="--your (encrypted) password--"
    task_type="xml_request"
    task_name="cmpl_report_raw"
  />
  <request
    report_type="nodes"
    node_name=""
    policy_id=""
    policy_name=""
    compliance=""
    node_group_id=""
    polling_group_id=""
    node_model=""
    vendor_type=""
    domain=""
    node_fqdn=""
  />
</task>
  • 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:

  • node_name: 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
  • vendor_type the vendor type of the node

A sample return is as follows:

<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_id="" 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>
guides/reference/compliance/cmpl_xch.txt · Last modified: 2020/10/26 15:09 by bdorlandt