Build your own ACC-V Inventory module (Check Definition)

[Kim Rasmussen]

Use Case

When using Agent Client Collector you most likely will need to enhance the data collected. By default the data collected is handled by the Enhanced Discovery Check definition coming with ACC-V.

This KB will show how to build a discovery extension that gets the Windows Build Number and add it to a custom field called u_os_build_number .

The use case will be using OSQuery to get the OS data. (The Query we will be using is already defined in the Allow-List

NOTE: This guide assumes that the custom field u_os_build_number has been added to the cmdb_ci_computer table before setting up the module.

Step By Step

TLDR

To expand the discovery using ACC-V you need:

- A Check Definition that can get the the new data

- A Check Type that can handle the return data and store it in the Database

- A policy to schedule the Check

- Potentially add a White-Listing of the script/OSQuery that gets the data.

all steps are documented in detail here: https://docs.servicenow.com/bundle/tokyo-it-operations-management/page/product/agent-client-collecto...

 

Create a Check Type

The key to building the extension is handling the return data. This is done by a Check type that will read and store the data that is returned from the ACC-V execution. 

First thing you need to do is to define a Check type:

1. In the sn_agent_check_type.list table create a new record, give it a name and use a script like this :

/*******
*
*  Retrive and set a new Discovered value based on a OSQuery Check definition for a Agent Client Collector.
*  Fields populated:
*    - OS Build Numeer
*
********/
for (var index = 0; index < checkResults.length; index++) {
	var check  = checkResults[index]["check"];
	if (check) {
		gs.info("OSQUERY-I-OK Custom OSQuery result recieved: " + JSON.stringify(check));
		
		//Get CI object
		var ci = new GlideRecord("cmdb_ci_computer");
		ci.get('sys_id', check.ci_id);
		
		if (ci.name) {
			var out = JSON.stringify(check["output"]);
			gs.info("OSQUERY-I-OK CI found " + ci.name + " content: " + out);
			var outObj = JSON.parse(check["output"]);
			var sOsName = outObj[0].name;
			var sOsBuild = outObj[0].build;
			gs.info("OSQUERY-I-OK CI: " + ci.name + " OS Build: " + sOsBuild);
			//gs.info("OSQUERY-I-OK CI: " + ci.name + " OS Name: " + sOsName);
			//ci.setValue("short_description","OSQuery OS Name: " + sOsName);
			ci.setValue("u_os_build_number", sOsBuild);
			ci.update();
		} else {
			gs.error("OSQUERY-E-NOCI CI not found"  + check.client);	
		}
	} else {
		gs.error("OSQUERY-E-Empty no check result found");	
	}
}

Remember the name of the Check type.

Create the Check Definition

Once the Check Type is defines you need a check definition that define the way of querying the end-device.  This could be done with scripts, commands or with the build in OSQuery (https://osquery.io/). ACC-V uses OSQuery for other data detection, and is maintained by the Agent. 

The good thing is that there is a predefined Check Definition to run OSQuery (util.osquery.agent) that you can take inspiration from.

This will build a generic Check definition using a parameter for the actual query, but you can also hardcode it in the check it self.

1. Navigate to Agent Client Connector -> Configuration -> Check Definitions
2. Create new - This example named it : Generic OSQuery check - as we will build it to be reused.
3. Select the Check Type you created above.
4. Command should be something like (Note that it will take the query as a parameter) :

   osqueryi --logger_min_status 1 --json "{{.labels.params_query}}"​

5. Interval - set it as 60 while you test, but you should set it 86400 - Once a day.
6. If you like to test the Check Definition, then you need a command in the parameter e.g.: 

   select * from uptime

7. Save.
8. Optionally use the Test Check , and select an Agent.

The Check could look like this :

Create Policy

To schedule the Check you need to create a Policy that also will contain the right OSQuery for the parameter created above.

The simple OSQuery to get the Windows build would be:

select build from os_version

But by default is a wider query already defined in the Default allow list on the Agents so it makes it easier to use that:

select * from os_version

To define the policy:

1. Navigate to Agent Client Connector -> Configuration -> Policies
2. Create New and give it a name.
3. create a filter for the computers you like to inventory
   
4. Add the check from above
   
5. Save
6. Modify the parameter on the check by clicking the check definition bellow and change the parameter from:

   select * from uptime

   TO

   select * from os_version

   Like this
   
7. Save

The System has now scheduled a new check that will be executed at the Agent, that then returns the data in the ECC Queue, and being handled by the Check Type to store the data in the right table.

[Kim Rasmussen]

I have updated the check for CI to ensure better error handling if CI has been removed.

[karlis_peterson]

@Kim Rasmussen - awesome post! 

[Will Hallam]

I notice you're writing directly to the computer record -- it should be possible to send the check data through IRE as well, right?

[Kim Rasmussen]

@Will Hallam Yes essentially you could do anything with the collected data, just add it in the section :

	if (ci.name) {
		var outObj = JSON.parse(check["output"]);
		..
		..
	} else {

You have the collected data in the check array, retrieved above into the outObj object. And the CI data in the GlideRecord ci

Publishing the data through IRE and MultiSource will require some more code, which is not a bad topic for another ITOM Community article 👍.  

[Manisha Yadav]

Hi Kim,

Very well explained.
I have followed the same steps and able to achieve data retrieval but issue is i want Computer description (as customer is storing Asset tag value in computer description)

However i have tried many classes and methods but unable to get that. Any idea on that?

Thanks for the help.

[Chatarina Lyth]

@Manisha Yadav 

You will find the computer description here: "select Description from Win32_OperatingSystem"

[Steven Parker]

I am trying to follow this, but hung up on the Create a Check Type script.

In the TestCheck - OSQuery [Windows] check definition, I created a test osquery with the below query to pull a given data field from the registry.

"SELECT data FROM registry WHERE key = 'HKEY_LOCAL_MACHINE\SOFTWARE\Immunet Protect' AND name = 'guid'"

The test works fine, but I am a little at a loss with how to incorporate it into a new Check Type/Definition.  I am trying to populate the "u_secure_endpoint_guid" field we created on the cmdb_ci_computer table.

How can I modify that Check Type above to work with pulling data from the regsitry?

UPDATE:

So I created a check type and made a check definition, and resolved my Allow List error I was getting by adding the plugins osquery and acc-visibility-modules to the Check Definition....now onto creating the policy next.