Agent Attributes for InsightVM

You can configure each of your Insight Agents with custom attributes that InsightVM will import as asset tags. This attribute functionality allows you to label and group your deployed agents in InsightVM in ways that are meaningful to your organization. Attribute configuration and assignment can take place either during an Insight Agent command line installation or at a later time by modifying the attribute.json file in each agent installation directory.

Attribute character requirements

Your custom attributes can contain the following characters:

  • Upper and lowercase alphabetical characters (A-Z, a-z)
  • Numbers (0-9)
  • Underscores _
  • Dashes -
  • Equal signs =

How to configure attributes during an Insight Agent installation

Command line installation required

Attribute configuration and assignment during Insight Agent installations is only supported with the command line installation method.

If you want to configure and assign attributes to Insight Agents at install time, you can do so by modifying the standard installation command with the additional formatting shown in the following operating system examples. If you want to specify multiple attributes at the same time, separate each attribute name with a comma.

Mac and Linux

For Mac and Linux assets, modify the standard install command with the --attributes option. List your attributes inside the quotation marks:

1
sudo ./agent_installer.sh install_start --attributes "attribute1,attribute2,attribute3,attribute4"

Windows

For Windows assets, modify the standard install command with the CUSTOMATTRIBUTES option. List your attributes inside the quotation marks:

1
msiexec /i agentinstaller-x86_x64.msi CUSTOMATTRIBUTES="attribute1,attribute2,attribute3,attribute4"

How to configure attributes using attribute.json

You can also configure and assign new attributes or update existing attribute associations for an asset by modifying its attribute.json file in the Insight Agent installation directory. The Insight Agent installer creates this file for you automatically if you elect to assign attributes during the initial installation. By default, this file is placed in the following locations according to the asset's operating system:

  • Mac and Linux - /opt/rapid7/ir_agent/components/insight_agent/common/attribute.json
  • Windows - C:\Program Files\Rapid7\Insight Agent\components\insight_agent\common\attribute.json

What if my Insight Agent installation directory doesn't have this file?

If you didn't configure any attributes during the installation phase described earlier, you are free to create the attribute.json manually and fill in any attributes as needed. Take care to place the file in the correct directory according to your asset's operating system or InsightVM will not be able to import the attributes defined by the file.

Attribute update characteristics

InsightVM will take action on updates in attribute.json as necessary whenever the Insight Agent sends assessment data to the Insight Platform according to its normal communication schedule:

  • If new attributes are defined in attribute.json, InsightVM will import these as new tags and associate them with the asset.
  • If previously defined attributes are removed from attribute.json, InsightVM will disassociate the corresponding tags from the asset.
    • InsightVM will never delete asset tags from the Security Console in response to changes in attribute.json. If you wish to delete asset tags entirely, you must do so manually.

Example attribute.json structure

The following example shows how each of your attribute.json files must be formatted:

json
1
{
2
"attributes": "attribute1,attribute2,attribute3,attribute4"
3
}

Note that multiple attributes are separated with commas in the same manner as the command line installation method.

What if my attribute.json file has a "version" key in it?

attribute.json files that were generated during the installation of the Insight Agent include a version key with a baseline value. This key-value pair is not used during an InsightVM import process, so feel free to ignore it.