Microsoft System Center Configuration Manager (SCCM)

You can use your Microsoft System Center Configuration Manager (SCCM) tool to mass deploy the Insight Agent to collections of Windows assets in your organization. This article guides you through this configuration and deployment procedure.

This procedure requires the following configuration steps:

Create a Device Collection

Before you can mass deploy the agent, you need to create a Device Collection in SCCM that specifies which of your Windows assets will be included in the package distribution.

To create a Device Collection in SCCM:

  1. In your SCCM interface, click the Assets and Compliance tab on your left navigation menu.
  2. Expand the Overview dropdown and click Devices. Verify that all your intended assets are online and reachable. The online state is indicated by a green check mark over the device icon.
  3. After verifying that all your intended assets are online, right-click Device Collections in the left navigation menu and click Create Device Collection.
  4. Give your Device Collection a name and a comment to describe its function.
  5. Click Browse next to "Limiting collection" to determine which systems are available to choose from. Generally, you will select the All Systems option, but choose whichever is suitable according to your needs. Click OK and Next to advance to the "Membership Rules" step.
  6. Click Add Rule to determine how the Device Collection will add new members according to your organizational requirements. Possible options include Direct Rule, Query Rule, Include Collections, and Exclude Collections. Click Next when finished.
  7. Verify that all your intended devices are included by the rule or rules you configured for the Device Collection. Close the wizard when your Device Collection completes successfully.

Create an Application

Now that your Device Collection is in place, you need to create the Application that will hold the Insight Agent installer.

To create an Application for the Insight Agent installer in SCCM:

  1. In your SCCM interface, click the Software Library tab on your left navigation menu.
  2. Expand the Overview dropdown, then expand the Application Management dropdown. Right-click Applications and click Create Application.
  3. Give your Application a name and a comment to describe its function.
  4. Click Browse next to "Installation program" to locate the Insight Agent .msi that you intend to push to target assets in your Device Collection. Note that the .msi (and any necessary configuration files if you elect to deploy using the certificate package edition of the Insight Agent installer) must be on a network share that your server can access.

CUSTOMCONFIGPATH function

For this SCCM deployment procedure, the CUSTOMCONFIGPATH assignment is always required, whether you elect to deploy with the certificate package installer or the token installer.

When used with the certificate package installer, CUSTOMCONFIGPATH tells the .msi where to look for the configuration files that it needs to complete the installation. These configuration files must already be in a location that the installer can reference when it executes.

When used with the token-based installer, CUSTOMCONFIGPATH tells the .msi where to save the configuration files after it downloads them from the Insight Platform. The installer then pulls the files from this location during the installation process. After the installation completes, the directory specified in CUSTOMCONFIGPATH is no longer required.

We recommend you use a writable directory that exists on all endpoints, such as C:\Windows\Temp, for <target-save-path-for-dependencies> when installing using the token method.

  1. After locating the .msi, modify the Installation program field according to one of the following examples, depending on whether you intend to deploy with the certificate package or the token installer, and whether you’d like to include connectivity test reports.
  2. In the command, specify this information where indicated:
    • <installerType> - Specify x86_64 for most Windows architectures, or arm64 for Windows ARM64.
    • <token> - If necessary, substitute with your generated agent installer token.
    • <target-directory-for-dependencies> - Specify the necessary file path, as described in the previous step and callout.

Certificate package installer

 
1
msiexec /i "agentInstaller<installerType>.msi" /q CUSTOMCONFIGPATH=<target-directory-for-dependencies>

Token installer

 
1
msiexec /i "agentInstaller<installerType>.msi" CUSTOMTOKEN=<token> CUSTOMCONFIGPATH=<target-save-path-for-dependencies>

Installation with connectivity test reports

Use either of these options if you want connectivity test reports to let you know whether the Insight Agent was able to connect to the platform.

Certificate package installer

 
1
msiexec /i "agentInstaller<installerType>.msi" CUSTOMCONFIGPATH=<target-directory-for-dependencies> REPORTPATH=<path-for-report-generation> RUNALLTESTS=[true]

Token installer

 
1
msiexec /i "agentInstaller-<installerType>.msi" CUSTOMTOKEN=<token> CUSTOMCONFIGPATH=<target-save-path-for-dependencies> REPORTPATH=<path-for-report-generation> RUNALLTESTS=[true]

Notes on installation with connectivity test reports

The REPORTPATH must be set and be world writable in order for the tests to run.

RUNALLTESTS is optional. If it’s empty, testing stops at the first location where all test cases passed, and a test report is only generated if all tests failed. If it’s not empty, all tests run for all configured collectors and a test report is generated if any host fails any of the tests.

The name for each test report is <fqdn of host>-<timestamp when report is created>. Each entry in the report starts with a line of "-------------". After this, each line consists of the test name (either Socket Connect, or TLS Socket Connect), and a result (PASS or FAIL). If any test fails the line will have a "->" followed by a technically detailed message to help you identify and troubleshoot issues.

Token vs. certificate package installation

Unlike the certificate package installer (which requires that the configuration files be present in the network share with the installer .msi), the token installer uses your unique token to download the necessary configuration files directly from the Insight Platform at install time.

  1. Click through the remaining steps of the Application wizard with no changes.

Distribute the Application

Now that you’ve configured an Application that contains the Insight Agent installer, you’re ready to distribute it to a Distribution Point. In SCCM, the Distribution Point hosts the Application that you intend to deploy to the assets in your Device Collection.

To distribute your Application:

  1. Right-click your Application and click Distribute Content. The "Distribute Content Wizard" window displays.
  2. In the "Content Destination" step, click Add and select Distribution Point.
  3. Select at least one server that will host your Application.
  4. Click through the remaining steps of the distribution wizard with no changes.
  5. Before proceeding to the next step, check the status of the distribution by clicking on the Monitoring tab on your left navigation menu.
  6. Navigate to Overview > Distribution Status > Content Status and double-click on your Application to check its progress.

Complete distribution before deployment

Make sure your Application has completed its distribution before proceeding to the deployment phase.

Deploy the Application

After the distribution of your Application completes successfully, you can deploy the Application to the assets in your Device Collection.

To deploy the Application:

  1. Right-click your Application and click Deploy. The "Deploy Software Wizard" window displays.
  2. Click Browse next to "Collection" to select the Device Collection that you configured earlier. Click Next.
  3. In the "Deployment Settings" step, set the deployment purpose as needed:
    • Available - The program will appear in the SCCM Software Center of the target PC, but will not install until the user clicks Install.
    • Required - The program will install without any action from the user.
  4. Click through the remaining steps of the deployment wizard with no changes.

The assets in your Device Collection will have the Insight Agent available for installation according the refresh cycle of their respective SCCM Software Center. Depending on the deployment settings selected earlier, the installation will take place automatically or will require user action.

Check Agent Installation Status

Finally, verify that the agent was installed correctly on your target assets. You can determine this by checking the service list on each machine to see if the agent service is present and running.

To verify that the agent was installed correctly:

  1. On one of your target assets, click Start > Run.
  2. Enter services.msc and click OK.
  3. Check that the Rapid7 Insight Agent service is present and running.
  4. Browse to Program Files\Rapid7\Insight Agent\components\bootstrap\common\ssl and verify that the three necessary certificate files are present.