Linux - Software Lifecycle - Install Rapid7 Insight Agent

What the Rapid7 Insight Agent deployer does

This Automox Worklet™ deploys the Rapid7 Insight Agent to Linux endpoints. The Worklet reads the endpoint architecture from uname -m, downloads the matching installer shell script from Rapid7 (saved locally as agent_installer-x86_64.sh or agent_installer-arm64.sh), makes it executable, and runs it with the install_start subcommand. The agent payload lands under /opt/rapid7/ir_agent/ and runs continuously as the ir_agent systemd service.

Registration uses your Rapid7 user token, passed to install_start via the --token argument so the installer can attach the endpoint to your Insight platform tenant. The Worklet pulls that token from a Shared Secret named rapid7_token at runtime rather than hard-coding it, so the same Worklet can ship to every Linux endpoint in your fleet without exposing the token in the script body, build logs, or Automox activity output.

If the rapid7_token secret is missing, the Worklet exits with a non-zero status and writes a stderr message to Automox Activity before attempting any download, so a misconfigured policy fails fast instead of leaving a partial install behind.

Why deploy the Rapid7 Insight Agent through Automox

Unmanaged Linux endpoints slow down vulnerability programs. A developer laptop, a build host racked in a colo, and an ARM64 instance in a remote office all need the same Insight Agent before InsightVM can report on them. Until the agent is installed and the ir_agent service is reporting, those endpoints do not appear in dashboards, do not raise alerts on newly disclosed CVEs, and do not show up in the live vulnerability view the security team triages against. The path from purchasing Rapid7 Insight to useful coverage is largely an agent-deployment problem.

Apply this Worklet to the Linux server and developer workstation device groups so the Rapid7 Insight Agent installer runs on x86_64 and ARM64 hosts with the same Shared Secret and the same systemd handoff. CIS Benchmarks and NIST 800-53 control families CA-7 and RA-5 expect continuous monitoring; binding the policy to the Automox-managed Linux device group extends that coverage without an SSH session per host.

How the Rapid7 agent deployment works

1. Evaluation phase: The script runs systemctl status ir_agent followed by systemctl is-active --quiet ir_agent to determine whether the Insight Agent service is registered and running. If the service is active, the endpoint is marked compliant. If the service is inactive but the /opt/rapid7/ir_agent directory already exists, the Worklet treats the endpoint as compliant and does not reinstall, leaving the existing agent state for manual review. Only endpoints with no agent directory at all are flagged for remediation.

2. Remediation phase: The script first checks that the rapid7_token Shared Secret is set and exits with a stderr message if it is not. It then reads uname -m, selects the x86_64 or ARM64 installer URL from us.storage.endpoint.ingress.rapid7.com, downloads it with curl -L into the working directory as agent_installer-x86_64.sh or agent_installer-arm64.sh, and runs chmod +x against the file. The installer is invoked with install_start --token "$rapid7_token" so Rapid7 can register the endpoint against your Insight platform tenant. After the installer exits, the Worklet re-runs the ir_agent service check and verifies that /opt/rapid7/ir_agent/ir_agent exists on disk; either failure produces a non-zero exit and a triage message in Automox Activity.

Insight Agent deployment requirements

• Active Rapid7 Insight tenant with a valid user token generated from the Insight platform

• Rapid7 user token added to the policy as an Automox Secrets Management variable named rapid7_token (the script reads $rapid7_token by name and exits if it is empty)

• Linux endpoint running x86_64 or ARM64 (aarch64) on a Rapid7-supported distribution such as RHEL, CentOS, Rocky, Alma, Oracle Linux, Ubuntu, Debian, or Amazon Linux

• systemd as the init system; the ir_agent service is registered and managed via systemctl

• curl available on the endpoint for fetching the installer script from Rapid7

• Outbound HTTPS reachability from the endpoint to us.storage.endpoint.ingress.rapid7.com (the installer URL the script targets) and to your Insight platform tenant for registration

• Sufficient free space under /opt for the agent install plus working data

• Root execution context for the Automox agent (the default execution context already satisfies this; the installer writes under /opt and registers a systemd unit)

Expected state after Insight Agent deployment

After remediation, /opt/rapid7/ir_agent/ir_agent is present on the endpoint, the ir_agent systemd unit is active, and the endpoint appears in the Rapid7 Insight platform asset inventory with its hostname, OS, and architecture populated. Subsequent Automox evaluations against the same endpoint exit 0 without re-running the installer, because the ir_agent service check already returns active.

Validate the deployment with two checks. Run systemctl status ir_agent on the endpoint and confirm the service is active (running) and that /opt/rapid7/ir_agent/ir_agent exists on disk. Open the Rapid7 Insight console, navigate to Assets, and confirm the endpoint reports a recent heartbeat with a populated vulnerability assessment. From that point on, Insight Agent telemetry flows to InsightVM and any companion Insight products (InsightIDR, InsightAppSec) without further intervention, and newly disclosed CVEs surface against the endpoint at the cadence configured in your Rapid7 policy.