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. The scanner uses a plugin-based vulnerability scanning engine with Redis for task queuing and OWASP ZAP for DAST (Dynamic Application Security Testing).

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
• License key for vulnerability test synchronization

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 License Key and Pull Docker Images

Install your license key (required for vulnerability test updates):

sudo bash -c 'echo YOUR_LICENSE_KEY > /etc/optix/license.key'
sudo chmod 600 /etc/optix/license.key

Contact [email protected] to obtain a license key if you don't have one.

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: Synchronize Vulnerability Tests

Synchronize vulnerability tests from the CyberOptix rsync server:

sudo /usr/local/bin/sync-vulnerability-tests.sh

This downloads the latest vulnerability test definitions to /var/lib/optix/vulnerability_tests/.

Automated Synchronization:

Enable the sync service timer for automatic updates:

sudo systemctl enable --now optix-sync-tests.timer

Step 4: Set Proper File Permissions

Set proper file permissions for scanner directories:

sudo chown optix:optix -R /etc/optix/
sudo chown optix:optix /var/lib/optix

Step 5: 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} \
  -organization_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

Upon successful linking, the scanner will display "Scanner linked successfully" and save authentication credentials to /etc/optix/scanner-config.json.

Step 6: 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-vm.service

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-vm.service
sudo systemctl status optix-sync-tests.timer

All services should show active (running) status.

Check Docker Containers

Verify Docker containers are running:

docker ps

Expected containers:

• redis (Task queue)
• zaproxy (OWASP ZAP for DAST scanning)

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

# Vulnerability scanner logs
sudo journalctl -u scanner-vm.service -f

# New tasks client logs
sudo journalctl -u scanner-client-new-tasks.service -f

# Completed tasks client logs
sudo journalctl -u scanner-client-completed-tasks.service -f

Service Overview

Architecture Overview

The scanner uses a distributed task-based architecture:

CyberOptix Command Center
        |
        v
scanner-client-new-tasks (fetches tasks)
        |
        v
Redis Queue (NewScannerTasksQueue)
        |
        v
scanner-task-manager (routes by type)
        |
        v
+---------------------------------------+
|                                       |
v                                       v
NmapTasksQueue              NetworkVulnerabilityTasksQueue
|                                       |
v                                       v
scanner-active-discovery                scanner-vm
|                                       |
+---------------------------------------+
        |
        v
Redis Queue (CompletedScannerTasksQueue)
        |
        v
scanner-client-completed-tasks
        |
        v
CyberOptix Command Center

Configuration Files

Scanner Configuration Structure

The /etc/optix/scanner-config.json file contains:

{
  "auth": {
    "auth_url": "https://auth.cyberoptix.io/oauth/token",
    "secret": "client-secret",
    "client_id": "scanner-client-id"
  },
  "base_url": "https://api.cyberoptix.io",
  "scanner_group_id": "uuid",
  "organization_id": "uuid",
  "mode": "running",
  "sentry_io_dsn": ""
}

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

Scanner Mode Management

The scanner supports two operational modes:

Running Mode (default): Scanner actively processes tasks

scanner-cli -mode_running

Maintenance Mode: Scanner pauses task processing

scanner-cli -mode_maintenance

Check scanner version:

scanner-cli -version

Vulnerability Test Synchronization

Manual Sync

Run the sync script manually:

sudo /usr/local/bin/sync-vulnerability-tests.sh

View Sync Logs

cat /var/log/optix/sync.log

Sync Configuration

The sync script connects to the rsync server using your license key:

• Server: rsync://[email protected]/vulnerability_tests
• Local directory: /var/lib/optix/vulnerability_tests
• License file: /etc/optix/license.key

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 --profile disable pull
docker compose -f /etc/optix/docker-compose-optix.yml up -d

Updating the Scanner

Use the built-in update script for safe scanner updates:

sudo /etc/optix/update_scanner.sh

This script:

1. Puts scanner in maintenance mode
2. Waits for running tasks to complete
3. Stops all scanner services
4. Updates packages via apt
5. Pulls latest Docker images
6. Restarts all services
7. Reboots the system

Troubleshooting

Service Won't Start

Check service logs for errors:

sudo journalctl -u scanner-vm.service -n 50 --no-pager

Verify Redis is running:

docker ps | grep redis

Scanner Not Receiving Tasks

1. Check scanner-client-new-tasks service:

   Bash

   sudo systemctl status scanner-client-new-tasks.service

2. Verify scanner configuration:

   Bash

   sudo cat /etc/optix/scanner-config.json | jq .

3. Test connectivity to Command Center:

   Bash

   curl -I https://your-api-url.cyberoptix.io

Vulnerability Tests Not Loading

1. Verify tests are synchronized:

   Bash

   ls -la /var/lib/optix/vulnerability_tests/
   find /var/lib/optix/vulnerability_tests -name "*.yaml" | wc -l

2. Check sync logs:

   Bash

   cat /var/log/optix/sync.log

3. Verify license key:

   Bash

   sudo cat /etc/optix/license.key

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

Redis Connection Issues

If services can't connect to Redis:

# Check Redis container
docker logs $(docker ps -q -f name=redis)

# Verify Redis is listening
netstat -tlnp | grep 6379

# Test Redis connectivity
redis-cli ping

Log Files

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