Linux - Configuration - Start Rapid7 Insight Agent Service

What the Rapid7 Insight Agent service starter does

This Automox Worklet™ starts the Rapid7 Insight Agent service on Linux endpoints when the ir_agent daemon is stopped or unresponsive. The Worklet first checks whether ir_agent is registered in systemd by running systemctl list-unit-files and grepping for ir_agent. If no matching unit is found, the Worklet exits without modifying anything, so the policy can target a mixed Linux estate where Rapid7 onboarding is still in progress without producing remediation noise on hosts that do not run ir_agent yet.

When the unit is registered, the Worklet evaluates whether the daemon is actually running by piping ps faux through pgrep ir_agent. If the process is found, evaluation passes and no changes are made. If pgrep finds no running ir_agent process, the endpoint is flagged for remediation.

The remediation path runs service ir_agent start. After issuing the start command, the Worklet re-runs the pgrep probe to confirm the daemon came back up. If the process is still absent, the Worklet exits with a non-zero code and the failure surfaces in the Automox activity log for triage.

Why keep the Rapid7 Insight Agent service running on Linux

The Rapid7 Insight Agent is the data source InsightVM and InsightIDR rely on for continuous vulnerability assessment, threat detection, and policy reporting on every Linux host you manage. A handful of common events stop the ir_agent daemon: a kernel update, a maintenance window that was never reversed, an out-of-memory event that kills the process without systemd restarting it, or a Rapid7 self-update that exits in a degraded state. When the daemon stops, the endpoint silently drops off the InsightVM coverage map. The console still lists the host, but the last-seen timestamp ages out and vulnerability data freezes at whatever state it was in when the daemon died.

CIS Benchmarks, NIST 800-53 control SI-4, PCI-DSS 11.5, and SOC 2 CC7.1 all require continuous monitoring evidence, and a stopped agent is an audit gap regardless of whether the underlying host is actually compromised. The Worklet runs systemctl list-unit-files and pgrep ir_agent on every evaluation, treats a missing process as non-compliant, and calls service ir_agent start in the remediation pass before the host disappears from the InsightVM dashboard or stops sending telemetry to InsightIDR. The activity log captures each restart as evidence for continuous monitoring controls.

How Rapid7 Insight Agent service recovery works

1. Evaluation phase: The Worklet runs systemctl list-unit-files and greps for ir_agent to determine whether the agent is registered with systemd. If no unit is found, evaluation exits 0 and remediation is skipped. If the unit is registered, the Worklet pipes ps faux through pgrep ir_agent. The endpoint passes evaluation only when a live ir_agent process is found. A missing process flags the endpoint for remediation.

2. Remediation phase: The Worklet runs service ir_agent start to bring the daemon back up. It then re-runs the pgrep ir_agent probe to confirm the process is alive. On success, the Worklet exits 0 and the next evaluation pass reports the endpoint compliant. On failure, the Worklet exits non-zero and the activity log records the output for triage.

Rapid7 Insight Agent service requirements

• Linux endpoint with the Rapid7 Insight Agent installed and an ir_agent service unit registered with systemd

• systemd-based distribution (Ubuntu 18.04+, RHEL 7+, CentOS 7+, Debian 9+, Amazon Linux 2) with the ir_agent unit visible in systemctl list-unit-files

• pgrep available on the PATH (provided by procps or procps-ng on every supported distribution)

• Root or sudo privileges for the Automox agent, which the default agent context already grants

• Rapid7 InsightVM or InsightIDR tenant reachable from the endpoint on TCP 443 so the restarted agent can re-register

• Optional: enable ir_agent with systemctl enable ir_agent in a companion Worklet so the daemon starts automatically on the next boot after this Worklet restarts it

Expected Rapid7 Insight Agent state after remediation

After a successful remediation, pgrep ir_agent returns a live process ID and the Worklet exits 0. The agent re-registers with the InsightVM tenant within a few minutes, the host's last-seen timestamp in the InsightVM console updates, and queued scan jobs resume against the endpoint. Subsequent Automox policy runs report the endpoint as compliant without applying remediation again, because the evaluation phase finds the daemon already running.

You can verify the change from the host by running systemctl status ir_agent, which should show the service as active (running) with a recent start time. From the Automox console, the activity log records the remediation exit code and the output captured at the time of the run, providing an evidence trail for SOC 2 CC7.1 and PCI-DSS 11.5 continuous monitoring controls.