Creating Asset Tags using Groovy

Document created by Qualys Documentation Employee on Jul 6, 2015
Version 1Show Document
  • View in full screen mode

Groovy is a programming language for the Java platform. You can write a Groovy script and insert it into a tag rule in order to tag assets automatically. For example, tag hosts that have certain ports open, or tag hosts when the results of a QID contain a specific string of text. Jump directly to Groovy rule examples.

 

 

Let's take a quick look at Groovy code

With this code, we'll tag hosts that take more than 30 minutes to scan.

groovy_sample_code.png

Each line in the code above is a unique command or comment:

  • Lines that start with "//" are comments. For example, the first line is a comment:

// Skip testing on non-hosts.

  • All other lines are commands. For example, the second line is a command:

if(asset.getAssetType()!=Asset.AssetType.HOST) return false;

  • The "asset" variable is a special variable. It is the current asset (host asset, web application, scanner) being tested.
  • The "return" command is a special command. It returns a value, either "true" or "false". A "true" value will apply the tag, while a "false" value will remove, or not apply the tag.

 

 

A few things to consider

  • Skip inapplicable assets - You must include this command at the top of your script to tag hosts only and skip all other asset types. This is necessary to optimize performance.

if(asset.getAssetType()!=Asset.AssetType.HOST) return false;

 

 

Groovy rule examples

 

Here are some ways you can use Groovy to tag your hosts. Learn how to apply these rules to tags.

 

Tag assets that have another tag

With this rule we'll tag assets that already have the tag “HIGH Risk”. (Note - This rule can be used to tag other types of assets like web applications, but you'll need to remove the first line of code to do this.)

 

if(asset.getAssetType()!=Asset.AssetType.HOST) return false;
return asset.hasTag("HIGH Risk");

 

Tag assets that do NOT have another tag

With this rule we'll tag assets that are not tagged with HIGH, MED or LOW risk tags in order to keep track of assets that have not been scored yet.

 

if(asset.getAssetType()!=Asset.AssetType.HOST) return false;

return !asset.hasTag("HIGH Risk") && !asset.hasTag("MED Risk") && !asset.hasTag("LOW Risk");

 

Tag assets that do not have an Operating System detected

With this rule we'll tag assets where the Operating System is null.

 

if(asset.getAssetType()!=Asset.AssetType.HOST) return false;
return asset.getOperatingSystem()==null || asset.getOperatingSystem().trim().length()<=0;

 

Tag assets with certain vulnerability severity levels

With this rule we'll tag assets that have vulnerabilities with severity levels 3, 4 or 5.

 

if(asset.getAssetType()!=Asset.AssetType.HOST) return false;
return asset.hasVulnsWithSeverity(3,4,5)

 

Tag assets with certain software

With this rule we'll tag assets that have software with “Microsoft” in the name.

 

if(asset.getAssetType()!=Asset.AssetType.HOST) return false;
return asset.hasSoftwareByName("Microsoft")

 

Tag assets with certain QIDs

With this rule we'll tag assets that have QID 22000 or QID 45239.

 

if(asset.getAssetType()!=Asset.AssetType.HOST) return false;
return asset.hasAnyVuln([22000,45239])

 

Tag assets with ALL specified ports open

With this rule we'll tag assets with port 22 and port 8080 open.

 

if(asset.getAssetType()!=Asset.AssetType.HOST) return false;
return asset.hasAllPortsOpen([22,8080])

 

Tag assets with ANY specified port open

With this rule we'll tag assets with port 22 or port 8080 open.

 

if(asset.getAssetType()!=Asset.AssetType.HOST) return false;
return asset.hasAnyPortsOpen([22,8080])

 

Obtain results for a QID and tag assets with specific text in results (hasVulnWithResults)

With this rule we'll tag assets with QID 90464 where the results contain “Detected through MSRPC Interface”.

 

if(asset.getAssetType()!=Asset.AssetType.HOST) return false;
return asset.hasVulnWithResults(90464,"Detected through MSRPC Interface");

 

Obtain results for a QID and tag assets with specific text in results (resultsForQid)

 

Important - Please note the "L" after the QID in the examples below. The L is required. Also, be sure to include the question mark in "?.contains" to make your rule as efficient as possible.

 

With this rule we'll tag assets with QID 42017 where the results contain “Service name: Remote”.

 

if(asset.getAssetType()!=Asset.AssetType.HOST) return false;
return asset.resultsForQid(42017L)?.contains("Service name: Remote");

 

With this rule we'll tag assets with QID 70004 where the results contain “ABC” or "XYZ".

 

if(asset.getAssetType()!=Asset.AssetType.HOST) return false;
return asset.resultsForQid(70004L)?.contains("ABC") | |

asset.resultsForQid(70004L)?.contains("XYZ");


 

 

How do I create tags with these rules?

 

AM_icon.pngFrom the Asset Management (AM) application, go to Tags > New Tag. Choose Groovy Scriptlet from the Rule Engine list (under Tag Rule) and enter your rule text. Then save your tag.

 

In this example, we'll tag hosts that have vulnerabilities with severity level 4 or 5.

 

groovy_rule_sample.png

 

Want to create tags using the API? No problem. Use the Create Tag API (https://<baseurl>/qps/rest/2.0/create/am/tag) and specify the Groovy rule text in the POST data. Check out this example.

 

Request:

curl -u "USERNAME:PASSWORD" -H "Content-type: text/xml" -X "POST" --data-binary @-"https://qualysapi.qualys.com/qps/rest/2.0/create/am/tag" < file.xml

 

Note: “file.xml” contains the request POST data.

Request POST data (file.xml):

<?xml version="1.0" encoding="UTF-8" ?>

<ServiceRequest>

   <data>

       <Tag>

           <name>groovy-hasVulnsWithSeverity</name>

           <ruleType>GROOVY</ruleType>

           <ruleText>if(asset.getAssetType()!=Asset.AssetType.HOST) return false;

return asset.hasVulnsWithSeverity(4,5)</ruleText>

        </Tag>

   </data>

</ServiceRequest>

Response:

<?xml version="1.0" encoding="UTF-8"?>

<ServiceResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:noNamespaceSchemaLocation="https://qualysapi.qualys.com/qps/xsd/2.0/am/tag.xsd">

<responseCode>SUCCESS</responseCode>

<count>1</count>

<data>

   <Tag>

     <id>1896021</id>

     <name>groovy-hasVulnsWithSeverity</name>

     <created>2015-06-30T21:24:04Z</created>

     <modified>2015-06-30T21:24:04Z</modified>

     <ruleText>if(asset.getAssetType()!=Asset.AssetType.HOST) return false;

return asset.hasVulnsWithSeverity(4,5)</ruleText>

     <ruleType>GROOVY</ruleType>

     <children>

       <list/>

     </children>

   </Tag>

</data>

</ServiceResponse>

3 people found this helpful

Attachments

    Outcomes