The DriftGuard REST API

Overview

When it comes to adding Dimensions and Collection Point definitions in DriftGuard, there are several ways it can be done. Dimensions can be added one-by-one via the Dimensions screen, and Collection Points via the Snapshot Browser. Or the Maintenance Spreadsheet could be downloaded to add multiple Dimensions at once, and then again to add multiple Collection Points. However, if you do have a large number of Dimensions and/or Collection Points to add, or you wish to configure them automatically in response to new hosts/applications being deployed, another option is to leverage the DriftGuard REST API.

APIs

A full list of available DriftGuard APIs can be found in the DriftGuard documentation, however, those required to create Dimensions and Collection Points include the following:

Adding a Host:

http://<DriftGuard host>/drift/Rest/RegisterHost?host=<host alias>&tagprop-10-HostName=<host name>

Adding an Environment:

http://<DriftGuard host>/drift/Rest/RegisterDimensionValue?dimensionName=Environments 
&dimensionValue=<environment>&tagprop-10-EnvShortName=<environment short name>

Adding an Asset:

http://<DriftGuard host>/drift/Rest/RegisterDimensionValue?dimensionName=Assets 
&dimensionValue=<asset name>&tagprop-10-EnvShortName=<asset short name>

Adding a Collection Point

http://<DriftGuard host>/drift/Rest/Register?name=<collection name>&path=<collection path>&host=<host alias>&ruleSet=<rule set>&dimensionName=Assets&dimensionValue=<asset >&dimensionName=Environments&dimensionValue=<environment>

Browser Method

If the API in question is being called from a browser session where the user is already logged into DriftGuard, then it is simply a matter of populating the correct values in the relevant API and submitting. For example, to create a Host with the alias of “soa_server_1” and a tag of “soa.proddomain.com”, the REST API URL would appear similar to the following:

http://<DriftGuard host>/drift/Rest/RegisterHost?host=soa_server_1&tagprop-10-HostName=soa.proddomain.com

Were this to be submitted in a browser session where the user is already logged into DriftGuard, the following success response would be received:

<?xml version="1.0" encoding="UTF-8"?>
<dynamicResult>
	<errors />
	<fieldName />
	<id>57</id>
	<messages />
	<name />
	<objectsToUpdate />
	<operation>CREATE</operation>
	<parentId />
	<type>Host</type>
	<url />
</dynamicResult>

And a review of the Hosts Dimension and Tags screen would show the following:

Command-line Method

The real power of the REST APIs becomes apparent, however, when calling them from the command line. In order to use this method, it is best done via a script as it is first necessary to create a session cookie to be used by the subsequent API calls, and it also makes it easier to make use of loops and conditional statements.

To create the cookie and write it to a file, a command similar to the following command can be used:

curl -k "http://<DriftGuard host>/drift/j_spring_security_check" -H 'Content-Type: application/x-www-form-urlencoded' --data 'j_username=<user name>&j_password=<password>' -b cookies.txt -c cookies.txt -L -s > /dev/null 2>&1

A full script that reads an input file with hosts listed on separate lines, and creates a Host dimension and Collection Point for each, might appear as follows:

#!/bin/bash

driftguard="/drift"

while IFS= read -r line
do
  host=$(echo $line)

  # create cookie
  curl -k "${driftguard}/j_spring_security_check" -H 'Content-Type: application/x-www-form-urlencoded' --data 'j_username=&j_password=' -b cookies.txt -c cookies.txt -L -s > /dev/null 2>&1

  # create Dimensions
  curl "${driftguard}/Rest/RegisterHost?host=${host}&tagprop-10-HostName=${host}" -b cookies.txt -c cookies.txt

  # create Collection Point (assumes pre-existence of soa Asset and dev Environment)
  name=${host}_soa
  path=/oracle/app/dev/soa/environments/soa_domain/
  target_host=${host}
  ruleset=WLS+Domain+Home
  asset=soa
  env=dev
  curl "${driftguard}/Rest/Register?name=${name}&path=${path}&host=${target_host}
&ruleSet=${ruleset}&dimensionName=Assets&dimensionValue=${asset}&dimensionName=Environments&dimensionValue=${env}" -b cookies.txt -c cookies.txt

  # cleanup
  rm cookies.txt
done < [host file]

Use-case

An example of a recent use-case where the command-line method was put to work was the provisioning of some DriftGuard training environments. A number of training environments were built, however, in order to test them, each required a Collection Point to be defined. Rather than logging into them one-by-one and manually creating the necessary Dimensions and Collection Points, a script was put together that used the REST APIs to do the job. A manual process that would ordinarily have taken an hour or more was quickly replaced by a script that did the job in less than a minute.

Summary

Ultimately, the DriftGuard REST API is simply another tool in the arsenal that helps you to manage Configuration Drift within your environments. The possibilities provided by combining the DriftGuard REST API with the power of custom scripting are myriad and limited only by what you can conceive. The API might not always be the best tool to reach for, but sometimes it will be. It will certainly make configuration, and more importantly automation, a lot easier in the right situation.