Scanner Configuration Guide

Guide for configuring CyberOptix scanners after deployment.

Overview

After installing the CyberOptix scanner package or deploying a scanner appliance, you must configure the scanner to connect to your CyberOptix organization and integrate with GVM (Greenbone Vulnerability Management) for vulnerability scanning.

Prerequisites

• Scanner deployed (Ubuntu 24.04, RHEL 9.x, or AWS appliance)
• Scanner group created in CyberOptix
• Root or sudo access to scanner
• Scanner link command from CyberOptix

Configuration Steps

Step 1: Update System and Configure User

Ubuntu 24.04:

sudo apt update && sudo apt dist-upgrade -y

RHEL 9.x:

sudo dnf update -y

Add the current user to docker and optix groups:

sudo usermod -aG docker,optix $USER && su $USER

Step 2: Install GVM Tools and Pull Images

Ubuntu 24.04:

Install gvm-tools globally using pipx:

sudo PIPX_HOME=/opt/pipx PIPX_BIN_DIR=/usr/local/bin pipx install gvm-tools

RHEL 9.x:

Install pipx and gvm-tools:

sudo PIPX_HOME=/opt/pipx PIPX_BIN_DIR=/usr/local/bin pipx install gvm-tools

Pull CyberOptix scanner Docker images:

docker compose -f /etc/optix/docker-compose-optix.yml --profile disable pull

Start the Docker services:

docker compose -f /etc/optix/docker-compose-optix.yml up -d

Step 3: Configure GVM Administrator

Set proper file permissions for GVM:

sudo chown optix:optix -R /etc/optix/
sudo chown -R 1001:1001 /etc/optix/.gvm/
sudo chmod 777 -R /etc/optix/.gvm/
sudo chmod 600 /etc/optix/scanner-config.json

Create a strong random password for the GVM admin user:

# Generate a secure password
GVM_PASSWORD=$(openssl rand -base64 32)

# Set the GVM admin password
docker compose -f /etc/optix/docker-compose-optix.yml exec -u gvmd gvmd gvmd --user=admin --new-password=$GVM_PASSWORD

# Display the password (save this securely)
echo "GVM Admin Password: $GVM_PASSWORD"

Update GVM tools configuration:

sudo vim /etc/optix/.config/gvm-tools.conf

Add the following configuration:

[gmp]
username=admin
password=your-gvm-password-here

Secure the configuration file:

sudo chmod 600 /etc/optix/.config/gvm-tools.conf

Step 4: Link Scanner to CyberOptix

Retrieve the scanner link command from CyberOptix:

1. Navigate to Scanners → Scanner Groups
2. Locate your scanner group
3. Click the copy icon to copy the link command

Execute the link command on the scanner:

sudo scanner-link -url https://{API_URL}/ \
  -scanner_group_id {SCANNER_GROUP_ID} \
  -org_id {ORG_ID}

Parameters:

• {API_URL} - Your CyberOptix instance URL (e.g., mycompany-api.cyberoptix.io)
• {SCANNER_GROUP_ID} - Scanner group ID from CyberOptix
• {ORG_ID} - Organization ID from CyberOptix

Step 5: Enable and Start Services

Enable and start all scanner services:

sudo systemctl enable --now \
  scanner-active-discovery.service \
  scanner-client-completed-tasks.service \
  scanner-client-new-tasks.service \
  scanner-task-manager.service \
  scanner-gvm.service

RHEL 9.x only - Configure firewall (if enabled):

sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --reload

Verify Configuration

Check Service Status

Verify all scanner services are running:

sudo systemctl status scanner-active-discovery.service
sudo systemctl status scanner-client-completed-tasks.service
sudo systemctl status scanner-client-new-tasks.service
sudo systemctl status scanner-task-manager.service
sudo systemctl status scanner-gvm.service

All services should show active (running) status.

Check Docker Containers

Verify GVM containers are running:

docker ps

Expected containers:

• gvmd (GVM daemon)
• ospd-openvas (OpenVAS scanner)
• postgres (Database)
• redis (Cache)

View Scanner Logs

Monitor scanner activity:

# Active discovery logs
sudo journalctl -u scanner-active-discovery.service -f

# Task manager logs
sudo journalctl -u scanner-task-manager.service -f

# GVM logs
sudo journalctl -u scanner-gvm.service -f

Service Overview

Configuration Files

Post-Configuration

After successful configuration:

1. Verify scanner appears in CyberOptix scanner group
2. Assign scanner group to zones for automated scanning
3. Monitor initial scans to ensure proper operation
4. Review scan results in CyberOptix platform

GVM Password Management

Initial Password:

• Set during Step 3 of configuration
• Used by scanner services to authenticate with GVM
• Stored in /etc/optix/.config/gvm-tools.conf

Password Rotation:

To change the GVM admin password:

# Generate new password
NEW_PASSWORD=$(openssl rand -base64 32)

# Update GVM password
docker compose -f /etc/optix/docker-compose-optix.yml exec -u gvmd gvmd gvmd --user=admin --new-password=$NEW_PASSWORD

# Update configuration file
sudo vim /etc/optix/.config/gvm-tools.conf

# Restart GVM service
sudo systemctl restart scanner-gvm.service

Docker Compose Management

Stop all scanner containers:

docker compose -f /etc/optix/docker-compose-optix.yml down

Start all scanner containers:

docker compose -f /etc/optix/docker-compose-optix.yml up -d

View container logs:

docker compose -f /etc/optix/docker-compose-optix.yml logs -f

Update scanner images:

docker compose -f /etc/optix/docker-compose-optix.yml pull
docker compose -f /etc/optix/docker-compose-optix.yml up -d

Troubleshooting

RHEL-Specific Issues

SELinux blocking Docker:

If containers fail to start due to SELinux:

# Check for SELinux denials
sudo ausearch -m avc -ts recent

# If needed, set SELinux to permissive for troubleshooting
sudo setenforce 0

# For a permanent fix, create a custom policy or configure container labels

Docker socket permissions:

If you encounter permission errors with Docker:

sudo chmod 666 /var/run/docker.sock
# Or restart the docker service
sudo systemctl restart docker

Next Steps

1. Verify scanner connectivity in CyberOptix platform
2. Assign scanner group to zones
3. Configure scan schedules and parameters
4. Monitor first scan execution
5. Review scan results and findings

Additional Resources

• Scanner Deployment Guide
• Scanner Group Management Guide
• Zone Management Guide
• AWS Appliance Deployment Guide
• GVM Documentation