Assess with agent-based policies

You can conduct secure configuration policy assessments against assets in your environments with the Insight Agent. Whether you’re implementing security best practices or adhering to a specific security compliance framework, the Insight Agent is able to collect asset information without the need for credential management or a corporate network connection. The information collected by the Insight Agent is then sent to InsightVM, once every 24 hours, for assessment.

Working with agent-based policy assessments, at a glance
  1. Enable the agent-based policies and assets you want to be assessed.
  2. Once every 24 hours, InsightVM sends a request to the agents in your environment to collect asset configuration information.
  3. The agent then collects the configuration settings and information on an asset.
  4. The information collected is sent to InsightVM.
  5. InsightVM assesses that information against the policies you have enabled.
  6. InsightVM displays the assessment results on the agent-based policy pages, including any applied override results.

Requirements

Users must be Global Administrators

Agent-Based Policy is currently only accessible to Global Administrators.

The Endpoint Broker must be deployed to your agent assets

The Endpoint Broker must be deployed to your agent assets before you can use the Insight Agent for policy data collection.

If your version of the Insight Agent is not set up for automatic updates and the Endpoint Broker is not already deployed, contact support to arrange a specific time to deploy the Endpoint Broker.

When the Endpoint Broker is successfully deployed you'll see, rapid7_endpoint_broker, a new running process and sub-component of the Insight Agent on your agent assets.

You must adhere to Insight Agent supported systems

Agent-based assessment supports Windows, Linux, and macOS operating systems. For more information on specific versions supported by the Insight Agent, refer to Supported Operating Systems.

Windows PowerShell 5.1 required

If you're a Windows user, you must be running a minimum of Windows PowerShell 5.1 in your environment. If the minimum is not installed, you may experience incorrect assessment results.

Windows PowerShell 5.1 is installed by default on Windows Server version 2016 and higher and Windows client version 10 and higher.

Assessment limitations

At this time, a maximum of 100 agent-based policies can be enabled per organization.

Why use agent-based policies?

Agent-based assessments, when run regularly against an organization’s assets, can quickly identify security misconfigurations and help to reduce the attack surface of your organization.

  • Credentials are not needed for agent-based assessments.
  • An on-premise connection is not required for agent-based assessments, which is especially beneficial for assessing remote assets.

How does it work?

Policy compliance is based on how well assets comply with the rules of each agent-based assessment.

Select from a large library of pre-built configuration baselines and recommendations to monitor the assets in your environment for any compliance deviation. The asset information collected by the agent is assessed against recommendations within each benchmark. In InsightVM, these recommendations are called rules.

Example

The policy CIS Windows 10 Server Benchmark - Level 1 contains 400 rules. One of these rules requires a "password length of 14 characters" and another ensures "account lockout after 5 incorrect password attempts". Each of these rules must pass for the asset to be compliant to the policy.

After enabling an agent-based policy for your assets, InsightVM schedules the agents in your environment to collect configuration information and then assesses your assets once every 24 hours against the selected agent-based policy. The assessment results can then be viewed and adjusted in InsightVM.

Policy report data

The policy reports currently available on the console do not contain agent-based assessment data because reporting for engine-based policies and agent-based policies are separate features.

How updates affect agent-based policies

After a third party publisher updates a policy, and those updates are applied by InsightVM, a new version of the agent-based policy is automatically added and the previous version is deprecated and flagged in the UI. This applies to both the agent-based policies that have not been enabled and those that are currently enabled for organizations. If an agent-based policy was enabled for your organization, the new version of that agent-based policy is automatically enabled to minimize any disruptions you might normally face when transitioning between versions.

Data is retained from the last agent-based assessment

For deprecated and manually disabled agent-based policies, data from the last assessment is only stored for 30 days and cannot be extended.

For enabled agent-based policies, the data displayed and stored is from the most recent assessment results.

Data from previous assessments cannot be recovered:

  • Following a new assessment
  • Beyond the 30 day period after an agent-based policy was deprecated or manually disabled

Enable an agent-based policy

Global Administrator role required

Agent-Based Policy is currently only accessible to Global Administrators.

When you assess a policy, you are actively checking which assets in your environment align with or deviate from the rules outlined in specific configuration standards. You must select and enable each agent-based policy you want your environment to be assessed against.

  1. In the navigation menu, click Policies > Agent-Based Policy.
  2. On the Agent-Based Policy page, on the Available Policies tab, select an agent-based policy you want to assess against.
  3. On the Policy Details page, click Enable to start regularly assessing your environment against the selected agent-based policy.
  4. When prompted, specify the assets you want to assess against the enabled agent-based policy by selecting either:
    • All assets. This applies the policy to all applicable assets that have the Insight Agent installed.
    • Custom scope. This allows you to select and assess specific assets that have the Insight Agent installed. You must use a query to select these assets.
  5. Click Enable.

Manage which assets are being assessed against a specific agent-based policy at any time by clicking Manage Assessment Scope on the Policy Details Page.

Disable an agent-based policy

  1. In the navigation menu, click Policies > Agent-Based Policy.
  2. On the Agent-Based Policy page, on the Enabled Policies tab, select the agent-based policy that you want to disable.
  3. On the Policy Details page, click Disable > Yes, disable it to stop assessing your assets against the selected agent-based policy.
    • When an agent-based policy is disabled, the data from the last assessment is only retained for 30 days.

Create a custom policy

Custom policies allow you to address specific security concerns unique to your organization. To create a custom policy, you can either upload a policy or edit a copy of an existing policy. Refer to Uploading custom SCAP policies for more information on uploading policies. Refer to Custom Policy Builder for more information on editing existing policies.

To upload a custom policy:

  1. On the Agent-Based Policy page, click Manage Custom Policies.

  2. Click Upload Policy.

  3. In the pop-up, select a file to upload. You must upload a ZIP file with a unique name and where the file suffixes are the following:

    • -cpe-dictionary.xml
    • -cpe-oval.xml
    • -oval.xml
    • -xccdf.xml

    It is recommended that you choose a file with a unique name devised from a naming convention to help you identify which policies have been customized for your organization.

  4. Click Upload.

    • If you receive an error message, you must resolve the issue mentioned and repeat these steps for the policy to upload successfully.
    • A spinning image may display during the upload. This is normal and may be due to the number of rules included as the time to complete an upload depends on the policy’s complexity and size.

To customize an existing policy:

  1. On the Agent-Based Policy page, click Manage Custom Policies.
  2. Select a policy that you want to edit.
  3. Click the Copy Policy button to launch the Custom Policy Builder.
  4. Edit the aspects of the policy you want to customize.
  5. Click Save.

After uploading or editing a custom policy, it may take several minutes to finish processing depending on the size of the policy. You can check the state of your custom policy's Status and Agent Compatible in the Manage Custom Policies listing table.

Enable a custom policy

Review custom policies before enabling

With awareness of user access and regular reviews of new policies and audit logs, you can reduce the risk associated with custom policy content. For more information refer to our risks and recommendations page.

Enable custom policies for agent-based assessment by selecting any policy under the Custom Publisher. After a custom policy is enabled for agent-based assessment, only a Global Administrator can edit the custom policy.

  1. In the navigation menu, click Policies > Agent-Based Policy.
  2. On the Agent-Based Policy page, on the Available Policies tab, select a Custom policy that you want to enable for agent-based assessment.
  3. Review the selected custom policy configuration.
  4. On the Policy Details page, click Enable.

If the custom policy meets the requirements for agent-based assessment and is validated successfully, your environment will be regularly assessed against the selected custom policy.

Delete a custom policy

You can delete a custom policy if new versions are available or if you no longer want to assess against a custom policy.

To delete a custom policy:

  1. In the navigation menu, click Policies > Agent-Based Policy.
  2. On the Agent-Based Policy page, click Manage Custom Policies.
  3. Use the Publisher filter to find Custom (Agent-Based) policies.
  4. Select the custom policy that you want to delete.
  5. Click Delete. This action is permanent. Deleted policies cannot be recovered.
    • If you are deleting a custom policy that was enabled for agent-based assessment, your assessment stops and your data is not retained.
    • If you are deleting an engine-based custom policy, deleting from the Manage Custom Policies page does not affect the custom policy on the console. To delete the custom policy permanently, you must delete from the Scan Engine Policy page.

Adjust assessment results

An override can be used to manually change the assessment result of a rule to either passed, failed, or N/A.

Create an override

  1. Click Create Override on the Rule Details table.
  2. In the pop-up, select to create an override for All assets or based on either an IP Range/Netmask/Host Name. To create an override for a singular asset, see Review rule details.
  3. Complete the required fields.
  4. Click Submit and approve.

Delete an override

You may want to delete an override if the overridden status no longer applies, or if you want to create a similar override, but with different parameters.

To delete an override:

  1. From the Rule Details page, click on the overridden rule you want to delete.
  2. Click Delete on the Override details page.

View agent-based assessments

You can view your compliance results in the Available Policies listing table, the Enabled Policy listing table, Policy Details pages, and the various agent-based policy dashboard cards.

You can export agent-based assessment results to CSV from the Policy listing table, Policy Details page, and Rule Details page, and convert them to PDF through the dashboard cards.

View available policies

The Available Policies listing table displays all of the agent-based policies that you can assess within your environment. You can view a specific agent-based policy’s details by clicking on its name:

FeatureDescription
Available Policies ComplianceTracks the total percentage of rules that have successfully passed policy checks against the total number of policy rules.
Filter ResultsNarrow results by platform, publisher, and status.

You can use the Publisher filter to filter by organizations that publish policy benchmarks or your organization's customized policies.

Check the Include Deprecated Policies box to display all policy versions.

You can use the Status filter to filter by assessment data, including whether a policy is assessed. An assessed policy means that the policy has been previously evaluated against your environment.
Review policy details

View agent-based policy rules and assessment results for your enabled agent-based policies on the Policy Details page. This is where you can find an agent-based policy’s full description, its rules, the assets it’s assessing against, and any of its override exceptions:

FeatureDescription
RulesEach policy contains rules that assets are assessed against. You can click on a rule to view its details.

When you assess a policy, you are investigating to see if the assets in your environment comply with the policy’s rules. If an asset meets the configuration standard outlined by individual rules, it is marked as pass. If an asset does not meet the configuration standard for the rule, it is marked as a failure. You can override any assessment result.
AssetsView compliance results and percentage of rules for each asset assessed by a policy. Rule compliance for an asset is measured by how many rules that asset has passed within a policy.
OverridesView the status of rule overrides, their scope, and their expiration date. Learn more about creating and managing overrides.

How updates affect agent-based policies

After a third party publisher updates a policy, and those updates are applied by InsightVM, a new version of the agent-based policy is automatically added and the previous version is deprecated and flagged in the UI. This applies to both the agent-based policies that have not been enabled and those that are currently enabled for organizations. If an agent-based policy was enabled for your organization, the new version of that agent-based policy is automatically enabled to minimize any disruptions you might normally face when transitioning between versions.

Data is retained from the last agent-based assessment

For deprecated and manually disabled agent-based policies, data from the last assessment is only stored for 30 days and cannot be extended.

For enabled agent-based policies, the data displayed and stored is from the most recent assessment results.

Data from previous assessments cannot be recovered:

  • Following a new assessment
  • Beyond the 30 day period after an agent-based policy was deprecated or manually disabled

Review rule details

From the Policy Details Page, you can click on an individual rule to open the Rule Details Page to examine the various details of an individual rule and all assets assessed by that rule.

Click Remediation Details to see the rule’s rationale and the remediation steps that need to be followed in order to apply the rule. Additionally, from here, you can create an override for the rule.

View custom policies

When your custom policy meets the necessary requirements for agent-based assessment, you can view your newly created or edited custom policy in the Manage Custom Policies listing table or in the Available Policies listing table.

The Manage Custom Policies listing table displays all of the policies within your environment and includes custom policy specific UI elements:

FeatureDescription
StatusThe status column reflects the state of your custom policy after uploading or editing.

  • Pending - The policy is currently being processed. Assessment eligibility will be determined soon.
  • Invalid - The policy is ineligible for assessment due to an issue. Ensure that any policies uploaded or edited adhere to the SCAP standard.
  • Valid - The policy can be enabled for assessment.
Agent CompatibleThe agent compatible column refers to a custom policy’s compatibility with the Insight Agent. If a custom policy is not agent compatible you will not be able to use it for agent-based assessments.

For example, a device might have an operating system not currently supported by the Insight Agent. Because the Insight Agent cannot be installed on the device, any custom policies that originate from that device are not eligible for agent-based assessment. This type of policy may still be used for assessments using the Scan Engine. Similarly, a custom policy may be valid but not agent compatible, meaning the policy can only be used in engine-based assessments.

  • Pending - The policy is currently being processed. Agent compatibility will be determined soon.
  • ✔️ - The custom policy can be enabled for agent-based assessment.
  • ✖️ - The custom policy did not meet the necessary requirements for agent-based assessment.
Filter resultsNarrow results by platform or publisher.

You can use the Publisher filter to filter by organizations that publish policy benchmarks such as DISA or CIS. Select Custom (Agent-Based) or Custom (Engine-Based) to view policies your organization has created in the Custom Policy Builder.

Check the Include Deprecated Policies box to display all policy versions.
Agent-Based vs. Engine-Based
  • Agent-Based - is an identifier in the Publisher column that refers to custom policies that were created through the Agent-Based Policy pages.
  • Engine-Based - is an identifier in the Publisher column that refers to custom policies that were created through the Scan Engine Policy page.

    To enable an Engine-Based custom policy for agent-based assessment, you must make a copy of the policy on the Manage Custom Policies page.

View enabled policies

The Enabled Policies listing table displays the agent-based policies that you've enabled for assessment. You can view a specific agent-based policy’s details by clicking on its name in the table.

Review policy details

View agent-based policy rules and assessment results for your enabled agent-based policies on the Policy Details page. This is where you can find an agent-based policy’s full description, its rules, the assets it’s assessing against, and any of its override exceptions:

FeatureDescription
RulesEach policy contains rules that assets are assessed against. You can click on a rule to view its details.

When you assess a policy, you are investigating to see if the assets in your environment comply with the policy’s rules. If an asset meets the configuration standard outlined by individual rules, it is marked as pass. If an asset does not meet the configuration standard for the rule, it is marked as a failure. You can override any assessment result.
AssetsView compliance results and percentage of rules for each asset assessed by a policy. Rule compliance for an asset is measured by how many rules that asset has passed within a policy.
OverridesView the status of rule overrides, their scope, and their expiration date. Learn more about creating and managing overrides.

How updates affect agent-based policies

After a third party publisher updates a policy, and those updates are applied by InsightVM, a new version of the agent-based policy is automatically added and the previous version is deprecated and flagged in the UI. This applies to both the agent-based policies that have not been enabled and those that are currently enabled for organizations. If an agent-based policy was enabled for your organization, the new version of that agent-based policy is automatically enabled to minimize any disruptions you might normally face when transitioning between versions.

Data is retained from the last agent-based assessment

For deprecated and manually disabled agent-based policies, data from the last assessment is only stored for 30 days and cannot be extended.

For enabled agent-based policies, the data displayed and stored is from the most recent assessment results.

Data from previous assessments cannot be recovered:

  • Following a new assessment
  • Beyond the 30 day period after an agent-based policy was deprecated or manually disabled

Review rule details

From the Policy Details Page, you can click on an individual rule to open the Rule Details Page to examine the various details of an individual rule and all assets assessed by that rule.

Click Remediation Details to see the rule’s rationale and the remediation steps that need to be followed in order to apply the rule. Additionally, from here, you can create an override for the rule.

Enabled Policies Compliance tracks the percentage of rules, across all enabled policies, that have a 100% asset compliance score. A rule only scores 100% if all the assets that have been assessed by that rule have a status of pass.

Compliance example

There are 100 total rules in policy A, 400 total rules in policy B, and 300 total rules in policy C, equaling 800 total rules. If only 80 rules have scored 100% (meaning all assets assessed by that rule passed) across the 800 total rules, then the enabled compliance percentage would be 80/800 = 10%.

Display agent-based policies in the dashboard

There are 5 agent-based policy compliance dashboard cards available to organize and display your data. You can view more detailed information for each card by clicking Expand Card.

Dashboard cardDescription
Total Assets Assessed by PolicyDisplays the total number of assessed assets by agent-based policy.
Total Assessed PoliciesDisplays the count of agent-based policies with findings stored.
Asset Compliance by PolicyDisplays asset compliance by an agent-based policy. Select which agent-based policy’s data you want to view in the dropdown.
Least Compliant AssetsPopulates the assets with the least compliance for specific agent-based policies. Select which agent-based policy’s data you want to view in the dropdown.
Rule Compliance by PolicyMeasures the ratio of rules that passed or failed in comparison to the total amount of rules within an agent-based policy. Select to display the percentage of rules that passed or failed.