VersionOps Documentation

Quick Start

Get started with VersionOps in just a few minutes:

Key Concepts

VersionOps Agent

The VersionOps Agent is a lightweight daemon that runs on your Linux servers to automatically discover installed applications and report their versions.

Agent Installation

# Download the binary
wget https://github.com/versionops-platform/versionops-agent/releases/latest/download/versionops-agent-linux-amd64

# Install
sudo mv versionops-agent-linux-amd64 /usr/local/bin/versionops-agent
sudo chmod +x /usr/local/bin/versionops-agent

# Configure
sudo versionops-agent config --backend=https://api.versionops.com --token=YOUR_SERVICE_TOKEN

# Install systemd service
sudo versionops-agent install

# Start the agent
sudo systemctl enable --now versionops-agent

Agent Configuration

Configuration is stored in /etc/versionops/agent.conf (JSON format):

{
  "backend_url": "https://api.versionops.com",
  "token": "your-service-token",
  "interval": 300,
  "log_level": "INFO"
}

# Set backend URL
sudo versionops-agent config --backend=https://api.versionops.com

# Set service token
sudo versionops-agent config --token=YOUR_TOKEN

# Set reporting interval (seconds)
sudo versionops-agent config --interval=300

# View current configuration
sudo versionops-agent config --show

Systemd Service

After running versionops-agent install, the service is managed via systemd:

# Start the agent
sudo systemctl start versionops-agent

# Stop the agent
sudo systemctl stop versionops-agent

# Restart the agent
sudo systemctl restart versionops-agent

# View status
sudo systemctl status versionops-agent

# View logs
sudo journalctl -u versionops-agent -f

System Requirements

Supported Operating Systems

Supported Architectures

• x86_64 (amd64) — Standard 64-bit Intel/AMD processors
• ARM64 (aarch64) — AWS Graviton, Apple Silicon (via Linux VMs), Raspberry Pi 4+

Windows Support

Minimum Requirements

Agent Commands

Inventory Management

VersionOps automatically discovers and tracks all software installed on your hosts. The dashboard provides a centralized view of your entire infrastructure.

• Host Overview — See all your servers with OS info, IP addresses, and last seen time
• Application List — Browse all detected applications with current versions
• Search & Filter — Quickly find specific hosts or applications
• Export — Download inventory data in CSV or JSON format

Version Tracking

Track software versions across your infrastructure and get notified about available updates.

• Version History — See when versions changed on each host
• Latest Versions — Compare installed versions with latest releases from GitHub and Repology
• Update Recommendations — Get smart recommendations for patch, minor, and major updates
• Custom Sources — Configure custom version sources for internal applications

Alerts & CVE Detection

Stay informed about security vulnerabilities and outdated software with automated alerts.

• CVE Monitoring — Automatic detection of known vulnerabilities
• Notification Rules — Configure alerts via email, Slack, or webhooks
• Severity Levels — Prioritize based on CVSS scores
• Remediation Guidance — Get upgrade paths for vulnerable packages

npm Dependency Monitoring (Projects)

Monitor npm packages and Node.js dependencies across your projects. VersionOps scans your package.json and package-lock.json files to track dependencies and detect security vulnerabilities.

Key Features

• Project-based Monitoring — Create projects to track npm dependencies separately from host inventory
• package.json Import — Upload or sync package.json files directly from your repositories
• package-lock.json Support — Full transitive dependency analysis from lockfiles
• Multiple Vulnerability Sources — Scans against OSV (Open Source Vulnerabilities) and GitHub Advisory Database
• Semver-aware Recommendations — Get patch, minor, and major update suggestions following semantic versioning
• CI/CD Webhook — Trigger scans from your build pipelines with a single API call

package.json vs package-lock.json

Getting Started with npm Monitoring

Background Processing

All dependency imports are processed in the background. This means:

• Large projects with hundreds of dependencies import smoothly
• Progress is shown in the UI while import is running
• You can navigate away and return later to see results
• CVE scanning starts automatically after import completes

Security Hub & Container Scanning

The Security Hub provides a unified view of vulnerabilities across your entire stack — container images, Infrastructure as Code, Kubernetes manifests, and application dependencies. Powered by Trivy, the industry-leading open-source vulnerability scanner.

Key Features

• Unified Dashboard — Aggregated vulnerability overview across all scan sources in one place
• Container Image Tracking — Add images to your inventory and enable auto-scanning on a configurable schedule (1–168 hours)
• Severity Breakdown — Every scan result includes Critical, High, Medium, and Low counts with CVSS scores
• IaC Formats — Supports Terraform (.tf), CloudFormation (YAML/JSON), Dockerfiles, Kubernetes manifests, and Helm charts
• Remediation Guidance — Each finding includes the fixed version, file path, line number, and resolution steps
• Scan History & Trends — Track vulnerability counts over time with 7/30/90 day trend analytics
• Security Notifications — Get alerted via Slack, Email, Telegram, Discord, MS Teams, or PagerDuty when scans find vulnerabilities above your severity threshold

Supported IaC Formats

Private Container Registries

Scan private container images from any Docker V2-compatible registry. VersionOps stores your registry credentials securely (encrypted at rest with AES-256) and automatically applies them when scanning private images.

Supported Registries

Key Features

• Automatic Credential Resolution — VersionOps matches image URLs to configured registries and applies credentials automatically
• Cloud-Native Token Management — For AWS ECR, GCP, and Azure, short-lived tokens are refreshed automatically
• Connection Testing — Verify credentials before saving with one-click test
• Encrypted Storage — All credentials encrypted at rest, masked in API responses
• Audit Trail — Every credential operation is logged for compliance
• SSRF Protection — Connection tests block requests to internal network addresses

Troubleshooting