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

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 configuration command with the --attributes option. List your attributes inside the quotation marks:

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

Windows

For Windows assets, modify the standard install command with the CUSTOMATTRIBUTES option. Substitute <installerType> with x86_64 for most Windows architectures or arm64 for Windows ARM64 and list your attributes inside the quotation marks:

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

How to configure attributes using attributes.json

You can also configure and assign new attributes or update existing attribute associations for an asset by modifying its attributes.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/attributes.json
• Windows - C:\Program Files\Rapid7\Insight Agent\components\insight_agent\common\attributes.json

Attribute update characteristics

InsightVM will take action on updates in attributes.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 attributes.json, InsightVM will import these as new tags and associate them with the asset.
• If previously defined attributes are removed from attributes.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 attributes.json. If you wish to delete asset tags entirely, you must do so manually.

Example attributes.json structure

The following example shows how each of your attributes.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.