Troubleshoot a Plugin

If you’re experiencing issues with a plugin, follow the steps below to diagnose and troubleshoot your problem efficiently.

Table of Contents

Use these quick links to get the help you need.

Find Plugin Information

Plugin information can be found both in InsightConnect and in the vendor’s own documentation. Every plugin has a “Plugin Details” panel that contains the plugin version number, lists of triggers and actions, help documentation, and the technical spec.

Find this information in the following locations:

  • Plugin selection panel during step creation
  • “Plugins” page under “Settings”

A plugin’s “Help” section will often contain links to the vendor’s API documentation. Reading the vendor’s documentation can help you troubleshoot plugin issues outside of InsightConnect.

General Troubleshooting

First try these steps to identify and resolve the issue. Have a copy of the error message ready.

Update Plugins

Make sure the plugin is up to date. Automatic update notices appear on the “Plugins” page under "Settings." To update all plugins, click the link in the notification.

Check Connections

If the plugin version is up-to-date, test any connections for the plugin to make sure these are configured correctly in InsightConnect and that the credentials or parameters you use are current in their respective plugins. Whenever you update or change keys or passwords for your integrations, remember to update them for your connections as well.

Check Triggers

To find out if a trigger is causing errors, visit the “Triggers” page under “Settings.” Review any triggers with an orange “Error” status, and click View under the three-dot options menu for that trigger to see the logs.

Locate Errors from the UI

When a job fails, you can check the output logs or any artifacts for errors. On the “All Output” tab for a failed job, you can view every step’s Input, Output, logs, and any errors that occurred.

Follow these steps to find out what caused the job to fail:

  1. On the “Artifacts” tab, look for any error-specific artifacts. These often provide next steps for resolving the issue.
  2. On the “All Output” page of a job, look at any steps in error. These steps will have an “Error” tab instead of “Output.”
  3. Click on the Input tab for any steps with errors. Check that the input values for the job are correct, or at least expected.
  4. Click on the Log tab to see error messages.

Many error messages will have error codes or provide additional context. Use this information when searching for help online, in documentation, or when contacting Rapid7 support.

Search Vendor Documentation

Review the plugin’s API documentation and search for the error message. Plugin vendors often provide troubleshooting information.

To find vendor information in InsightConnect:

  1. Navigate to the details page for the plugin you’re working on. You can find this in the workflow builder by clicking the down arrow button on a plugin when choosing a plugin for a step, then clicking on the Plugin Docs button. Alternatively, you can view plugin details for all installed plugins from the “Plugins” page under “Settings.”
  2. Click on the Help tab in the plugin details panel.
  3. Check the “About” and “Connection” sections for any links to vendor documentation. Alternatively, you can run a web search for the name of your plugin with the string API documentation. This search will often yield a variety of resources to help you troubleshoot your needs, but the vendor’s own documentation is a good place to look first.

Common Issues

Plugin Actions Cannot Connect to External Resources

If you encounter the following problems with InsightConnect actions, it means the plugins cannot connect to external resources:

  • DNS resolution failures for hosts you define in plugin connections
  • Continued connection timeout after updating connections to rule out DNS

To troubleshoot connection problems between your host network and plugin Docker containers from the command line:

  1. SSH into your orchestrator virtual machine from your local machine.
  2. Test connectivity to an external host by running curl https://www.rapid7.com.
  3. Generate a list of all containers currently running on the orchestrator by running sudo docker ps.
  4. Connect to a bash shell in a container currently experiencing the connectivity issue by running sudo docker exec -i -t <container name> /bin/bash. Replace the <container name> variable with the name of one of the containers from the list generated in step 3.
  5. Once inside the container, run the same curl command from step 2: curl https://www.rapid7.com.
  6. If this command returns “curl: (7) Failed to connect to www.rapid7.com port 443: Operation timed out” , test the curl command with an IP address instead. To get an IP address to test, exit the container and run nslookup www.rapid7.com within the orchestrator virtual machine. Run the docker command from step 4 with the same container name, then run the curl command with the IP address you just obtained. The command should look like curl -k https://192.168.1.1:1234/, with the numerical values of the IP address substituted with the one you received from the nslookup command.
  7. If the curl command succeeds with the IP address method, navigate to the container’s DNS settings. These are stored in the /etc/resolv.conf file.
  8. Exit the container.
  9. Run sudo sysctl -a | grep forward. In the command output, check that the following fields are all set to 1. Correctly set values should look like:
 
1
net.ipv4.conf.all.forwarding = 1
2
net.ipv4.conf.default.forwarding = 1
3
net.ipv4.conf.docker0.forwarding = 1
4
net.ipv4.conf.ens32.forwarding = 1
5
net.ipv4.conf.lo.forwarding = 1
6
net.ipv4.ip_forward = 1

Note that the interface number ens32 may be different on your host. 10. If any of the above fields have different values (0 instead of 1), run the following commands to configure IPv4 forwarding for your orchestrator.

Configure IPv4 Forwarding
1
# Get the primary interface name for the host and use it to configure forwarding correctly
2
export ORCH_PRIMARY_INTERFACE=$(ip link | awk -F": " '$0 !~ "lo|vir|docker|veth|wl|^[^0-9]"{print $2;getline}')
3


4
# Apply at runtime
5
sudo sh -c 'sysctl -w net.ipv4.conf.$1.forwarding=1' -- "$ORCH_PRIMARY_INTERFACE"
6
sudo sysctl -w net.ipv4.conf.all.forwarding=1
7
sudo sysctl -w net.ipv4.conf.default.forwarding=1
8
sudo sysctl -w net.ipv4.conf.docker0.forwarding=1
9
sudo sysctl -w net.ipv4.conf.lo.forwarding=1
10
sudo sysctl -w net.ipv4.ip_forward=1
11


12
# Continue configuration
13
sudo sh -c 'echo "net.ipv4.conf.$1.forwarding = 1" >> /etc/sysctl.d/99-sysctl.conf' -- "$ORCH_PRIMARY_INTERFACE"
14
sudo sh -c 'echo "net.ipv4.conf.all.forwarding = 1" >> /etc/sysctl.d/99-sysctl.conf'
15
sudo sh -c 'echo "net.ipv4.conf.default.forwarding = 1" >> /etc/sysctl.d/99-sysctl.conf'
16
sudo sh -c 'echo "net.ipv4.conf.docker0.forwarding = 1" >> /etc/sysctl.d/99-sysctl.conf'
17
sudo sh -c 'echo "net.ipv4.conf.lo.forwarding = 1" >> /etc/sysctl.d/99-sysctl.conf'
18
sudo sh -c 'echo "net.ipv4.ip_forward = 1" >> /etc/sysctl.d/99-sysctl.conf'
  1. Restart the orchestrator with the command systemctl restart rapid7-orchestrator (or the command shortcut, orch-restart) to save and apply the new configurations.
  2. Exit the orchestrator virtual machine and sign into your InsightConnect account..
  3. Re-run the workflow that previously exhibited issues. The action that failed to connect to external resources should now work properly.

Contact Support

If the problem persists after you try the previous recommendations, prepare the following details and submit them to our support team.

Provide as many of the following details as you are able to:

  • Error message, copy-pasted from the UI
  • Screenshots of the error
  • Plugin version number
  • Step input/output, with nonsensitive info only
  • Orchestrator information