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:
|
|
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 |
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:
|
| 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:
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:
-
Create a placeholders.csv file under the configs folder and open it.
-
In the first line of the placeholders CSV file enter: config_name;placeholder;placeholder_value;template
- config_name: is the name of the scan file that you want to create
- placeholder: is the placeholder name that you want to replace automatically for each scan file, for example, a username or a password
- placeholder_value: is the actual value that should be used in the created scan files for the placeholder name defined as placeholder.
- template: is the name of the template file you want to use for creating the scan files.
-
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 -
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.
-
Start OC Configurator application and click the General settings tab.
-
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.
-
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:
|
| -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