Scan Files

Introduction

Scan files tab section is the most important section regarding configuring your OC Scanners. A scan file contains encrypted information about:

• Target machines (the IP addresses, domains, and credentials)
• Access parameters for hypervisors (VMware, Nutanix, Hyper-V, OpenStack)
• Other configuration details

OC Scanner decrypts the information, reads it, and then starts the scan. Depending on the scanner deployment approach, the naming of scan files follow some conventions:

• Agent-based scanner approach: The naming of the scan file is up to you. You can choose any name. In the case of using only one agent-based scan file, we recommend naming it simply agent. If you have multiple agent-based scan files, we recommend the naming convention of starting with agent_ and entering a self-explanatory ending.
• Agentless single scanner approach: The naming of the scan file is up to you. You can choose any name. We recommend using self-explanatory, no whitespaces, and no special characters (except the underline, point, and dash sign) for the naming. For instance, you could name the scan file SPLA_Environment.
• Agentless multiple scanners approach: The naming of the scan files must follow a convention. The naming of a scan file needs to be either the FQDN (fully qualified domain name), Computer name, or IP address of the machine where OC Scanner is getting deployed. For instance, if the FQDN name of the OC Scanner deployed server is my.customer.com, then the scan file should be named as well my.customer.com. The reason for this convention is, that the scan files in this deployment approach are not copied with OC Scanner on the machine, instead, they are stored centrally in the OC Configurator API server under the configs folder. To know for OC Scanner which scan file it needs to pick up for the scan, it makes an API request to the OC Configurator API server to ask for its related scan file, which is always up to date. If you make later modifications on the scan file over the OC Configurator, you will not need to copy paste that scan file to the OC Scanner machine, because the OC Scanner will always pick up the latest version of its scan file over the API from the OC Configurator.

Scan File Creation

Creating a scan file is done by clicking the button Create new scan file. This action will open a window, with the following fields:

Name	Enter here the name of the scan file. Depending on your deployment approach, you will need to follow some conventions (see Introduction section of Scan files).
Description	This field is optional and additionally useful for searching scan files in the scan files list.
Make remote scan	This checkbox is only used for the agentless multiple scanners approach and only created one time. Once the checkbox is set, the Name field gets disabled with the name remote. Because in the agentless multiple scanners approach the scan files of OC Scanners are not deployed with the OC Scanners. They are always stored in the OC Configurator API server under the configs folder. Instead, the remote scan file is deployed with OC Scanners together. The remote scan file stores basically the URL information of the OC Configurator API server, which OC Scanner needs to know to pick up its original scan file over the API.

 

Scan File Configuration

To configure a scan file, you can double-click the scan file from the list or select and right-click it and click in the context menu open. In the context menu, you have also the following additional options:

• Renaming the scan file
• Making a copy of the scan file
• Deleting the scan file

Once you open a scan file, the configuration can start. Keep in mind, that you can configure within one scan file many things, as scanning a domain, connecting to a vCenter, etc. A scan file is not limited only to one specific task. Also, keep in mind that a scan file is always representing an OC Scanner.

Servers tab

In the Servers tab, you add scan scopes to the target directly. Directly means, the scanner will try to connect to the target machines defined in the scan scope and try to login to the machines with the given credentials to read out the relevant inventory information such as the installed applications, the number of cores, etc.

You can add multiple scan scopes to the list. Each scan scope is scanned with its defined credentials.

Adding a scan scope

Click the Add button, which will open a window, with the following fields:

Credentials	If you have created credential templates in the Default credentials section, those credentials would be selectable in the dropdown field. If one credential template is selected from the list the Username and Password fields are getting prefilled and disabled. If there are no credentials in the list, the custom value is selected, which means simply you can enter the credentials directly in the Username and Password fields, which is the most used approach.
Label	This field is very helpful to describe which scan scope, network, or domain you are going to scan. You can enter any name into this field. We recommend using self-explanatory names. If you, for instance, want to define a domain as the scan scope, the name of the domain or any other readable label would be a good approach.
IP address / FQDN	This field actually defines the scan scope. It is very powerful and flexible. You can enter: a single IP address a range of IP addresses, for example, 10.0.0.0/24 or 10.0.0.23-10.0.0.65 IP addresses separated by commas, for example, 10.0.0.2,10.0.0.10,10.0.0.20-10.0.0.50 FQDN name of a machine (usually used when scanning Domain Members over a Domain Controller) Note: The defined IP addresses or FQDN in the scan scope don’t need to be reachable or accessible over the network from the OC Configurator server, they only need to be reachable and accessible from the server where OC Scanner will be deployed.
Username and Password fields	In these fields, enter the username and password to access the target machines defined in the scan scope.
Scan domain over Domain Controller	This checkbox is depending on what you entered in the IP address / FQDN field. If you want to scan domain members over the Domain Controller, then you need to enter the IP address or FQDN name of the Domain Controller in the IP address / FQDN field and check this checkbox. If you are going to scan an AD domain, then we recommend entering the FQDN name of the Domain Controller in the scan scope and setting this checkbox to ON.

After the fields are filled, you can click to Add button. That will save the scan scope into the list and immediately open another window, the modifying window. This window is similar to the previous one but has more options to configure specific parts of the scan scope. The fields from the previous window are already prefilled.

Modifying a scan scope

All created scan scopes are listed in the Servers tab. To modify a scan scope, you can double-click the entry in the list or select and right-click it and click in the context menu Edit. In the context menu, you have also the following additional options:

• Copying the scan scope
• Deleting the scan scope

Once you open a scan scope, you can configure more precisely what to scan and make other configurations.

In the General settings tab, the following additional configurations are possible:

Scan over DC	This is the same field as the Scan domain over Domain Controller checkbox from the adding a scan scope window. If this option is ON the AD member machines will be scanned over the Domain Controller.
Scan over AD forest	Set this switcher to ON to scan the entire AD forest (including multiple AD domains/subdomains).
Scan only servers	Set this switcher to ON to scan only Windows server operating systems, avoid workstations, laptops, etc.
Scan only LDAP on DC	This option allows you to only execute LDAP queries on the AD without scanning the Domain Controller machine itself. If this option is combined with Scan over DC, then the Domain Controller itself will not be scanned, but the members in the AD will.
Set OU…	This option is only available as a button when Scan over DC is switched to ON. Click this button to define the organizational units (OUs) in the Active Directory that contains the machines you’d like to scan or exclude from the scan. Enter per each line the full distinguished name of an OU in the following format: CN=ABC,OU=Server,OU=SPLA,DC=customer,DC=local
Advanced options	In the Advanced options section you have the following possibilities: Excluding or Including target machines defined in the scan scope. The Including option doesn’t add new target machines into the scan scope, it only scans the included target machines which are already defined in the scan scope. DCs for consideration allows you to define on which AD domain controllers OC Scanner is allowed to scan the Active Directory. The order of entering the DC’s is important, as OC Scanner will try to scan the first one first, if no success, then it will try the second one, etc. until one of the defined DC’s is successfully scanned. Use token groups to detect ad group membership option can be used in specific scenarios when some user-group relation cannot be discovered in an ordinary way. Be aware that this can have an impact on performance, and cause a high load during the scan. The Disable AD connection option is to disable the scanning of the Active Directory. Normally, if OC Scanner is scanning AD machines, a connection to the Active Directory of the Domain Controller is made to get further information about the AD member machine. In cases to prevent that, you can switch this option to ON. This option is usually used when AD Domain credentials/required network connectivity are missing. Be aware that AD user-related information of the given AD target machine will be missing if this option is set to ON.
Customers	You have the possibility to add a customer to the defined scan scope. The customer could be your end customer or an internal organization in your company. The entered name here is the official name, which is also later displayed in the OC Reporter web application in the Customers section. You have also the possibility to add customers in OC Reporter directly without adding them here. Follow this guideline to decide either to add the customer name in OC Configurator or in OC Reporter: If the scan scope belongs only to one customer, then you can add that customer in this section in OC Configurator. For instance, your scan scope is to scan a domain, and this domain belongs only to one customer, you can add the customer name here, the same is if you are scanning an IP range and all machines within this range belong to one customer. If in the scan scope multiple customers are represented, we recommend leaving this Customers section empty and manage the customers directly over the OC Reporter web application. To add a customer in this section, click the add button and enter the name of the customer in the Customer name field. You can ignore the other fields, they are deprecated. You have in fact the possibility to add multiple customers here, but only the first one will be used for the assignment to the scan scope.

 

In the User settings tab, you can define user-related configurations. For instance, the SQL Server Standard application can be licensed per Core or per User in SPLA. If you license the SQL Server Standard applications always per Core, you have here the possibility to disable scanning users, who could access the SQL Server Standard application. That will increase the scan performance of OC Scanner. For the other server applications, we highly recommend keeping the switch to ON for scanning users. Even if in your environment those applications are not used, keep the switch to ON, if by mistake one time the applications get installed, OC Scanner will discover and send an alert.

The Desktop Applications section in the User settings tab manages configurations for Terminal Server desktop applications such as Office Standard, Visio, Projects, etc. OC Scanner has an Auto detection option which is set to ON per default. This option allows OC Scanner to automatically figure out which users can access the Terminal Servers over RDP and which applications can be executed by the users on those servers. If you use AppLocker or NTFS permissions to prevent certain users to start certain desktop applications on Terminal Servers, you can set those options to ON, OC Scanner will read out the set permissions and based on them set the user licenses. If you are using Citrix for letting users access Terminal Servers, set that option to ON. OC Scanner will then instead of reading the RDS users on the Terminal Servers directly, check the Citrix settings to figure out which users can access which Terminal Servers.

In very complex scenarios, or if you want to map custom applications with users, you can also map manually applications to users through AD groups, OU, etc. Click the button add in the Desktop Applications section and select from the predefined applications list or enter your custom desktop application name and map it to an AD group, OU, or another possible option.

In the Asset settings tab, similar to the User settings tab, you can define asset (server, computer) related configurations.

Hypervisors tab

In the Hypervisors tab, you have the possibility to connect to different hypervisors over their specific APIs to get information that is not able to collect over the direct scan, such as the relation between a Virtual Machine and its Host, or which Hosts are in which Clusters or Datacenters, etc. OC Scanner is able to read information by following hypervisors:

• VMware
• Hyper-V
• Nutanix
• OpenStack
• RedHat
• Citrix
• KVM
• Proxmox
• CloudStack
• etc.

Each of the hypervisors has its own settings. You can add multiple hypervisors as long as OC Scanner can reach them from its deployed server.

Cloud tab

The Cloud tab is currently in the Beta stage. The idea is to allow OC Scanner to connect to different Cloud vendor APIs to get relevant information. Following Cloud vendors are supported:

• Azure

Settings tab

In the Settings tab of the scan file, you have the possibility to overwrite some general values. Usually, all OC Scanners send data back to the same workspace ID of OC Reporter web application. But you have the possibility to change that behavior on the scan file level. If you want OC Scanner to send the data to another workspace ID, enter here the ID of that specific workspace. If OC Workspace-ID field is empty, OC Scanner will send the data to the default defined Workspace-ID in the global General settings tab.

The Send data to API Url option is mainly used for agent-based OC Scanners. Because agent-based OC Scanners have no remote scan file deployed with them, they need to know to which OC Configurator API server they need to send the inventoried data. If you set this option to ON, OC Scanner will send the scanned data to the URL defined in the global General settings tab in the Other settings section in API Url field.

The Don’t keep generated CSV files option allows you to control whether OC Scanner should save the inventoried data as CSV files in its own Reports folder or not. This option is usually set to ON for the agent-based OC Scanners, not to keep any CSV files on OC Scanner deployed machines. For the agentless multiple scanners approach, the option can be controlled over the remote scan file.

Scheduler tab

In the Scheduler tab of a scan file, you can define in which iterations OC Scanner should scan the defined scan scope. Once you configured the scheduler, you need to start OC Scanner the first time manually, so it can create its own scheduled task. OC Scanner will create a scheduled task with the name octopus_cloud_scanner_task

The Remote Scan File

The special remote scan file is used for the agentless multiple scanners approach because in this approach the original scan files of the deployed OC Scanners are never deployed together with the OC Scanner, instead, they are always stored on OC Configurator API server under the configs folder. For the agentless multiple scanners approach only the remote scan file is deployed with OC Scanner.

The remote scan file has the following fields:

API Url	Enter in this field the URL of OC Configurator API, e.g. https://[oc-configurator-api-server-address]/Service.svc. The agentless OC Scanners will then know from which OC Configurator API server they need to get their original scan file and to which OC Configurator API server they need to send the inventoried data.
Configs folder	Usually, the original scan files of OC Scanners are stored in the configs folder of OC Configurator API server, but you have the possibility to store the scan files also in subfolders. In such cases, you would need in each subfolder a separate OC Configurator application to manage the scan files in those subfolders. In this field, you can enter in which subfolder OC Scanner should search for its own scan file. This field is very rarely used, that’s why most of the time kept empty.
Store secret key locally	The remote scan file is communicating with private/public RSA keys to OC Configurator API server. The private secret key is usually saved in the remote scan file itself. If you set this option to ON, the private RSA key will be stored locally in the ScannerID section of the Windows key container and deleted from the remote scan file.
Send reports to API	If this option is set to ON, OC Scanner will send the inventoried data to OC Configurator API server. Otherwise, you would need to copy the inventoried CSV files manually to OC Configurator API server.
Don’t keep generated CSV files	This option allows you to control whether the OC Scanner should save the inventoried data as CSV files in its own Reports folder or not. This option is usually set to ON, not to keep any CSV files on OC Scanner deployed machines.

 

Special Configurations

There are some special configurations possible with OC Configurator.

Scan Files Created Over A Template

If you have to create many scan files that follow the same pattern, you can use a template. With a template scan file, you can generate all other scan files by replacing current values with the actual values needed. To use a template the following steps needs to be done:

1. Create a placeholders.csv file under the configs folder and open it.

2. In the first line of the placeholders CSV file enter: config_name;placeholder;placeholder_value;template

   1. config_name:  is the name of the scan file that you want to create
   2. placeholder: is the placeholder name that you want to replace automatically for each scan file, for example, a username or a password
   3. placeholder_value: is the actual value that should be used in the created scan files for the placeholder name defined as placeholder.
   4. template: is the name of the template file you want to use for creating the scan files.

3. Using the actual values, add as many lines as you need. For instance, the content of your placeholders.csv file could look like this:

   config_name;placeholder;placeholder_value;template
   ScanFile1.cfg;{username};Username1;_TemplateA.cfg
   ScanFile1.cfg;{customer};Customer ABC;_TemplateA.cfg
   ScanFile2.cfg;{username};Username2;_TemplateA.cfg
   ScanFile2.cfg;{customer};Customer XYZ;_TemplateA.cf
   

4. Copy the placeholders.csv file to the same folder that contains the OC Configurator application. If the CSV file is is not in the same folder, you won’t see the appropriate options in OC Configurator.

5. Start OC Configurator application and click the General settings tab.

6. There, you will see a new option available called Template config. Click the Create button next to it and the scan files are going to be created through the placeholders.csv file.

7. The scan file generator will replace the placeholders (such as {username}, {customer}, etc.) in the _TemplateA.cfg template scan file (btw. you can name the template scan file as you like) into their placeholder values defined in the placeholders.csv and generate the defined scan files. In our example above, it will generate two scan files with the names ScanFile1.cfg and ScanFile2.cfg. OC Configurator will create as many scan files as many unique config_name are defined in the placeholders.csv file.

Command Line

OC Configurator allows executing some actions over the command-line.

Creating a scan file

This option is used for the automated creation of scan files by using the OC Configurator application over the command line, or over scripts. When OC Configurator is executed by double-click, it starts its GUI for the regular graphical configuration. However, the same OctopusConfigurator.exe can be executed without GUI, over the command line, but has limitations. Below is a list of possible execution arguments:

Argument	Required	Description
-h or -help	no	Prints in the logs folder of the OC Configurator in the log file all available options.
-ScanFileName	yes	Name of the scan file you want to create.
-ScanDescription	no	Description of the scan file
-ConfPassword	yes	The password of the OC Configurator
-Address	no	IP address / FQDN of the scan scope. The same possibilities are available as in the GUI.
-Username	no	Username for accessing the defined scan scope.
-Password	no	Password for accessing the defined scan scope.
-DomainScan	no	Is it a Scan over DC? Same as in the GUI. Value can be yes or no. The default value is no.
-Customer	no	Enter the customer name to be assigned to the defined scan scope.

Note:

• Arguments are case insensitive.
• All output messages are logged in the log file, and not in the command line.
• Providing a scan file name, which already exists in OC Configurator, will update the previously created scan file.

Example 1

When only required arguments are provided (-ScanFileName and -ConfPassword), OC Configurator will create a scan file with an empty scan scope. The created scan file can be configured further over the GUI of OC Configurator. Open the command line and enter the following command:

OctopusConfigurator.exe -ScanFileName testScanFile -ConfPassword mysecrectpassword

Example 2

In this example, all arguments are provided and we define a scan over the Domain Controller:

OctopusConfigurator.exe -ScanFileName testScanFile -ScanDescription “this is my scan file” -ConfPassword mysecretpassword -Address 10.0.0.1 -Username Administrator -Password adminPass -DomainScan yes -Customer “Customer ABC”

Adding Hypervisor In Scan File

You can add hypervisors into the scan file.

Argument	Required	Description
-ScanFileName	yes	Name of the scan file
-ConfPassword	yes	The password of the OC Configurator
-ScanType	yes	Which hypervisor configuration should be set up. You can choose between the following values: vCenter hyperv nutanix openStack redHat citrix kvm proxmox cloudStack
-Label	yes	A name for the hypervisor entry in the scan file.
-Address	yes	The IP or DNS address of the hypervisor to access.
-Username	yes	The username to access the hypervisor.
-Password	yes	The password to access the hypervisor.
-Customer	no	Customer name which will be assigned to the scanned hypervisor entries.
-HypervisorDelete	no	The argument to delete the hypervisor entry from the scan file. Available values are yes and no. The default value is no.

 

Example 1

To create a hypervisor scan scope into an existing scan file, you can use the following command:

OctopusConfigurator.exe -ScanFileName testScanFile -ConfPassword mysecretpassword -ScanType vCenter -Label "vCenter Name" -Address "11.22.33.44" -Username userNameVCenter -Password secretvcenterpassword -Customer "Customer ABC"

Example 2

To delete a hypervisor scan scope entry, use the following command:

OctopusConfigurator.exe -ScanFileName testScanFile -ConfPassword mysecretpassword -ScanType vCenter -Label "vCenter Name" -HypervisorDelete yes

Note: To be able to delete a hypervisor scan scope entry from a scan file, it is required to have a label defined.

 

Adding Default Credentials

You can add or update default credentials for scan configuration over Powershell using Powershell secure string as a password.

Argument	Required	Description
-ConfPassword	yes	The password of the OC Configurator
-DefaultCredLabel	yes	Name of the default credentials
-DefaultCredUser	yes	Username
-DefaultCredPassword	yes	Password

 

Adding Scheduled Task

You can add a scheduled task into a scan file.

Argument	Required	Description
-ScanFileName	yes	Name of the existing scan file
-ConfPassword	yes	The password of the OC Configurator
-DisableScheduledTask	no	Disable scheduled task
-UseSystemAccount	no	Use a system account for scheduled task.
-TaskRepeatPeriod	no	Repeat period for scheduled task: never, once, daily, weekly, monthly
-DayOfWeek	no	Day when the task will be scheduled if it is set to weekly (monday - sunday).
-TaskTime	no	Time at which task will be executed (12:01…)
-ScheduleUsername	no	The username to run the task.
-SchedulePassword	no	The password to run the task.
-ScheduleTaskCreatorUsername	no	The username to create a task.
-ScheduleTaskCreatorPassword	no	The password to create a task.

 

Example 1

To create a scheduled task into an existing scan file, you can use the following command:

OctopusConfigurator.exe -ScanFileName testScanFile -ConfPassword mysecretpassword -TaskTime 20:01 -TaskRepeatPeriod weekly -DayOfWeek monday

Example 2

To create a scheduled task into a non-existing scan file with adding server configuration, you can use the following command:

OctopusConfigurator.exe -ScanFileName testScanFile -ConfPassword mysecretpassword -TaskTime 20:01 -TaskRepeatPeriod weekly -DayOfWeek monday -Customer TestCustomer

Example 3

To create a server combined scheduled task into an non-existing scan file with adding server configuration, you can use the following command:

OctopusConfigurator.exe -ScanFileName testScanFile -ConfPassword mysecretpassword -TaskTime 20:01 -TaskRepeatPeriod weekly -DayOfWeek monday -ScheduleUsername scheduleUsername -SchedulePassword schedulePassword -ScheduleTaskCreatorUsername scheduleCreator -ScheduleTaskCreatorPassword scheduleCreatorPassword -Address 10.0.0.1 -Username Administrator -Password adminPass -DomainScan yes -Customer “Customer ABC”

 

Adding sending data to API

You can add or update the send data to API settings.

Argument	Required	Description
-ScanFileName	yes	Name of the existing scan file
-ConfPassword	yes	The password of the OC Configurator
-SendDataToApi	no	Sets configuration setting for sending data to API.

 

Example 1

To add sending data to API in existing scan file, you can use the following command:

OctopusConfigurator.exe -ScanFileName testScanFile -ConfPassword mysecretpassword -SendDataToApi yes