Skip to main content
Alt text

​
Overview

The On-Prem Agent allows you to scan applications, file systems, container images, and source code hosted within your local or private infrastructure. The agent runs securely inside your environment and communicates with the Zero-X Cloud platform to send scan results. This section is intended for: > End Users (Security Analysts)
> DevOps / Platform Engineers

​
End-to-End On-Prem Agent Workflow

1. Create On-Prem Agent data source from UI
2. Generate API Key and download agent bundle
3. Install agent on local infrastructure
4. Verify agent is online
5. Trigger on-prem scans
6. View findings across dashboards and reports

​
Step 1 – Add On-Prem Agent Data Source (End User)

Connectors → Data Source → Add Data Source

​
Steps:

1. Click Add Data Source.
2. Select On-Prem Agent.
3. Enter Agent Name (unique identifier for your host).
4. Click Create.

​
System Actions:

> System creates a new on-prem agent entry.
> System generates a one-time API Key.
> Important: Copy and store the API Key securely. It will not be visible again.
> System provides an Agent Installer Bundle (.zip) for download.

​
Step 2 – On-Prem Agent Installation (DevOps / User)

​
Zero-X Cloud On-Premise Agent Setup

The Zero-X agent is a lightweight background service that: > Sends heartbeats to the Zero-X platform
> Executes security scans locally
> Securely uploads scan results

​
2.1 Prerequisites

> Linux or macOS host (amd64)
> curl and unzip installed
> Network access to Zero-X Cloud platform URL
> Required scanners installed and available in $PATH (e.g., trivy, semgrep)

​
2.2 Installation Steps

​
1. Download Agent Bundle

From the Zero-X Cloud UI, download:
 zerox-agent-installer.zip

​
2. Unzip the Bundle

unzip zerox-agent-installer.zip

​
3. Run Installation Script

Execute the installation script with sudo privileges. sudo ./install-agent.sh <YOUR_API_KEY> <YOUR_ZEROX_PLATFORM_URL>

​
Example:

sudo ./install-agent.sh agent_abcdef1234567890 http://localhost:9002

​
2.3 What the Installation Script Does

> Detects operating system (Linux / macOS)
> Downloads the correct agent binary
> Creates directories:
   - /opt/zerox-agent/ – agent binary
   - /etc/zerox-agent/ – configuration
> Writes environment configuration file:
   - /etc/zerox-agent/.env
> Configures background service:
   - Linux: systemd service
   - macOS: launchd service
> Enables and starts the agent automatically

​
Step 3 – Verify Agent Status

​
Linux (systemd)

sudo systemctl status zerox-agent
sudo journalctl -u zerox-agent -f

​
macOS (launchd)

sudo launchctl list | grep cloud.zerox.agent
log stream --predicate 'process == "zerox-agent"'

​
Expected Result

> Agent service is running
> Heartbeats are sent successfully

​
Step 4 – Agent Online Verification (UI)

Connectors → Data Source

​
Expected Behavior:

> On-Prem Agent status changes to Online
> Host details become visible

​
Step 5 – Trigger On-Prem Scan (End User)

Connectors → New Scan

​
Steps:

1. Click New Scan.
2. Select Target Type: On-Premise Agent.
3. Select Scanner Type as required:
  - File System Scan
  - Container Image Scan
  - SAST Scan
4. Select the Agent / Resource.
5. Enter Scan Target Path (e.g., project directory path).
6. Click Scan Now.

​
Step 6 – View On-Prem Scan Findings

​
Expected Behavior

After scan completion, findings are available across the platform: 1. On-Prem Dashboard
> High-level severity summary:
  - Critical
  - High
  - Medium
  - Low
 2. On-Prem Findings / Vulnerabilities Module
> Detailed vulnerability and security issues
> CVE details, severity, impact, and remediation
 3. Asset-Level View
> Findings mapped to:
  - Servers
  - Hosts
  - IP Addresses
  - Applications
 4. can Results / Scan History
> Full scan execution details
> Timestamp, scan status, and findings