Windows scan

The Windows scan module is a Windows application program (.exe) that runs in user context and - with default configuration - produces an output file (scan file) per invocation.

The scan file is a compressed .xml file which contains information that is later imported into the central OctoSAM Inventory database.

Minimum impact philosophy

The scan module was designed to give you maximum flexibility on how to deploy it in your network and to minimize the impact on your existing configuration and management tools.

Octoscan2 can happily run in parallel with all your established management tools.

The scan process uses only standard mechanisms provided by the Windows environment. The scan module works completely disconnected from the central server. There is no communication between the server and the scan module, which makes it easy to install the scanner even in complex organizations with high security requirements.

Another benefit of this architecture is that you don’t have to license your database server for each scanned Machine in the network as you typically have to with connected agents.

The scanner executable, Octoscan2.exe is entirely self-contained. There are no dependencies on external libraries or runtime environments other than the Windows operating system itself.

Info

Octosoft AG digitally signs the Octoscan2 executable. Depending on your environment and security requirements, you might want to sign Octoscan2.exe with your own code security certificate.

Also, there is no communication with the end user or visible activity on the user’s desktop. On the other hand, the scanner does not attempt to hide itself from the system tools such as task monitor. It’s just an ordinary windows application running in the logged-on user context.

Open file format

The produced scan file is a compressed .XML file which is human readable and can be transformed through XML tools if required.

Tip

The provided Octodump utility can be used to decompress .scan files into human readable .xml files or to compress scan.xml files into .scan files. The .scan file can also be decompressed using a standard ZIP tool such as 7-zip.

Scanner source license

The source code of the scanner can be licensed for local modifications or in environments with very high security requirements.

Custom registry and file scanning can be implemented through configuration and/or custom versions of the scanner. Contact us with your specific requirements.

Supported operating systems

Octoscan2 Version	Minimum Windows Version Required
1.9.6	Windows XP / Windows Server 2003
1.9.7	Windows Vista / Windows Server 2008
1.9.8	Windows 7 SP1 / Windows Server 2008 SP2 or 2008 R2 SP1
1.11.0 and later	Windows 7 SP1 / Windows Server 2012

Choosing the output folder

The output folder for scan files should be on a system powerful enough to accept the potentially large number of generated scan files at peak logon time.

If possible, the folder should be on a highly available system (cluster).

Tip

The output folder is best placed in a subdirectory on the same share from which the scanner gets started. When using GPO to start the scanner, using the same share handles all possible network failures gracefully without user impact. If the scanner is started from a network location different to the configured OutputFolder, you have to make sure that the network is up and running before starting OctoScan2.

Network prerequisites

For best results, all machines in your network should have synchronized clocks. Otherwise date and time information in the inventory can be unreliable.

Installing Octoscan2

Publish Octoscan2 to the network

You are completely free on how to make Octoscan2 available on the network. Either use a global share visible to all Users and Machines (recommended) or publish it to several locations depending on your network topology or security requirements.

Warning

Its important to make sure that Octoscan2.exe and octoscan.config are read-only for all users and cannot be overwritten except by the OctoSAM Inventory administrator. All parts of the Path must be readable by the executing user. Due to a bug in Windows 7, NTFS bypass traverse checking is not supported for starting Octoscan2.

Warning

When you install the scanner locally on your windows machines using any type software management system, do not install it in %ProgramFiles%/OctoSoft or a subfolder of that. You may risk conflicts with other Octosoft tools in the future.

Start Octoscan2 at user logon

Good practice for starting Octoscan2 for all users and machines in your network is to place a call to Octoscan.exe in your login script or define a group policy to start the executable at logon.

Tip

This forum thread provides information about how to Setup GPO and Security Zones

See Chapter “Push Installation” on how to handle mobile Machines that do not frequently log on to the corporate network.

Server scans

On Servers, some features can only be scanned if the scanner runs in elevated Administrator user context:

• UAL usage data from WMI (Windows Server 2012 or newer)
• UAL overview data from WMI (Windows Server 2012 or newer)
• Hyper-V information (Windows Server 2012 or newer)
• Cluster information (Windows Server 2008 or newer)

If you need this information, you have to make sure that the scanner runs with Administrator permission from time to time.

Tip

A proven way to start the scanner on servers with admin rights is to schedule a Scheduled Task via Group Policy.

Collect the generated .scan files

Octoscan2 writes its compressed output file (the scan file) to a folder you specify via the OutputFolder parameter in the configuration file.

The filename consists of a GUID to make sure that each generated scan file name is unique and does not get overwritten by other scans.

Most convenient configuration is to have all scan files written to a globally visible share, where they are directly processed by the Import Service. But again, you are free to use any method for collecting scan files and make them available to the OctoSAM Inventory Import Service.

You can also use the OctoSAM Inventory Replication Service to collect scan files from a set of remote locations.

Warning

All Users must have write permissions to their configured OutputFolder. For security reasons you might want to configure different OutputFolder settings for different user or machine groups. You can do this by using conditional configuration in your configuration file, by using multiple configuration files, or through environment variable expansion within the configuration file.

Using advanced NTFS access right configuration, you can also configure a drop only folder where files can be written but not read or modified once they are written, see: http://sysadmin1138.net/mt/blog/2009/10/filesystem-drop-boxes-on-ntfs.shtml

Command line options

% Octoscan2 options

/clean

Immediately clean all local traces of Octoscan2, regardless of any settings in the configuration file. This removes all local files and registry settings.

/f

Force an immediate full scan, regardless of any settings in the configuration file.

/keep

Together with /show: keep the window open even if Octoscan2 would exit based on the current configuration.

/q

Gracefully end an active Octoscan2 scan process running in the background. This option can be used to stop Octoscan2 when Metering is enabled.

/show

Show the program window during operation

/reveal

Show the program window of the active Octoscan2 scan process running in the background. This option can be used to inspect status messages of a running Octoscan2

/tag:tag

Allows to specify a tag name that is stored in the .scan file and can later be used to identify the invoker of the scanner.

% Octoscan2.exe /tag:startedfromgpo1

For example, if you invoke octoscan2 from multiple policies, you can specify the policy name here. This lets you identify which policy caused the scan.

/x

Disable exception handling code on program level. Used for debugging only.

Metering mode

If Metering is not enabled, Octoscan2 exits after producing the scan file. On the other hand, in metering mode, the scanner needs to be active during the whole user session. At startup, a scan file is produced as usual, including summarized metering information gathered in the previous session.

Metering Information is stored locally on the computer until the next invocation of Octoscan2.

Immediate metering mode

In Immediate Metering Mode, Octoscan2 will periodically write an immediate metering file which can be imported instead of saving metering locally for the next scan. This can be used in terminal server and Citrix farms if there is a high probability that the user will not work on the same server within a reasonable time or where the Servers are periodically reset.

Warning

Immediate Metering Mode can only be used when the output is written to a central share and can be overwritten from the the scanned system/user. Upload of .scan files to a web server via Upload configuration is not supported in immediate mode.

Upgrade Octoscan2

If you want to update Octoscan2 on a central share, Windows will most likely block the update because of open file handles, especially if software metering is active. Usually, it's not a problem to close the open file handles from the server side if you update outside peak hours. The script

% close_octoscan2_handles.ps1

provided in Support/Install/Scripts closes just the handles to Octoscan2.exe leaving other open file handles to the share intact.

Octoscan2.exe specifies the IMAGE_FILE_NET_RUN_FROM_SWAP flag. This means that the executable is copied fully to the local swap space and does not depend on the network availability once it is started. So far we have not seen any problems with closing the file handles for updating the executable.

Depending on your configuration, Octoscan2.exe may also be running on the local server, possibly under other user accounts too. close_octoscan2_handles.ps1 also stops theses instances of Octoscan2.exe.

Octoscan2 also provides a scheme for updating the scanner without having to close handles, see this Forum article.

Push installation

Why push installation

If your environment has mobile PCs that do not frequently log on to the domain, you can configure a local installation of Octoscan2 for metering information to be more accurate. When you use the Push Installation feature, Octoscan2 installs and updates itself locally on the machine at first scan or when the original Octoscan2.exe file gets modified on the network share.

Octoscan2 then configures itself to start whenever the user logs on to the system.

Push Install only makes sense together with Metering enabled and ImmediateMeteringOut set to false in most cases.

Warning

Push Installation may trigger alerts in your anti-virus software. Test carefully and configure the appropriate rules in your anti-virus software before using this feature.

In the Octoscan.config file specify:

PushLocal=true
Metering=true
ImmediateMeteringOutput=false

Warning

Try to avoid the PushLocal setting if it is not really needed. If you can differentiate between connected and mobile devices, enable PushLocal only on the mobile devices using conditional expressions.

PushLocal considerably complicates your setup. Do not set it to true before you have all connected devices scanning reliably for a week or so.

How push installation works

The first time Octoscan2 is started with PushLocal set to true, it will copy itself locally to the machine into the user's AppData/Local/Octosoft/Octoscan2 folder. This local copy will start at every user logon through the 'Run' registry setting. If the network is not available, the scanner will just write its metering information to the AppData/Local/Octopus folder.

If the network becomes available and Octoscan2 is started from the network share, it will stop the already running local instance of Octosan2, update its local copy if needed, and finally include the accumulated metering data into the freshly generated .scan file.

Understanding .scan files

Using octodump.exe

Octodump is a utility to decompress .scan files into their .xml format. It works on the current directory and processes all scan files found. The generated .xml files have the same timestamp information as the .scan file so that you can still sort the files or find out what files are newest to the system. Octodump can also be used to compress a .scan.xml file into the .scan format.

Alternatively most zip utilities should be able to decompress the .scan file.

Getting summarized .scan file information

Call Octodump with the /s option to generate a summary over multiple .scan files. The output is in .csv format, so that you can easily analyze it further in Excel or any text editor. Octodump uses its own internal parser to read the contents of the .scan file so that you can also analyze partial files or otherwise malformed files.

Analyzing .scan files

environment section

Shows basic information about the environment of the scan.

octoscan section

Here you can find the build info for the Octoscan2 process that actually generated the file and the full path to the configuration file used for this scan.

octoscan_config section

In this section, you find the configuration parameter values that were set after evaluating the configuration file. Three parameters that cannot be set through configuration are:

DoHardwareScan
DoSoftwareScan
DoUalScan

These parameters indicate if hardware, software or UAL scans are to be performed, considering the configuration, scan period settings and timestamp value on the current machine.

The configuration file

Location and filename

The default configuration file must be named octoscan.config and must be located in the same directory as Octoscan2.exe.

You can specify alternate configuration files by setting the environment variable OCTOSCAN_CONFIG before calling Octoscan2.exe

Protect your config files

Make sure that Octoscan2.exe and octoscan.config are read-only for all users and cannot be overwritten except by the OctoSAM Inventory administrator.

Configuration file format

The configuration file consists of one configuration assignment statement per line. The general syntax is:

<ConfigurationParameter> = <Value>

Comments can be specified by a leading semicolon or hash character.

Boolean parameters can be specified using 1, true or yes for True, 0, false, or no for False. Use double quotes for string values that contain whitespace.

Running without configuration file

If you start octoscan2.exe without a configuration file, all parameters are set to their default values. The OutputFolder parameter will be set to ‘.’ (the current working directory). Note that if you start Octoscan2.exe without configuration from a GPO or login script, you have to make sure the current directory is set to the desired output folder.

Sample configuration file

#
# octoscan2 sample configuration file
#
OutputFolder = \\myserver\OctoSAM$\data
#
# metering (requires metering option)
#
Metering = true
#

Conditions

Simple if / else / end if statements allow for more flexible configuration. The configuration is parsed top down, evaluating the conditional statements.

# scan at every logon
ScanPeriod = 0
# except when logged on remotely through rdp or ica/citrix
# in that case scan only every 10 days.
if remotesession
    ScanPeriod = 240
end if

Conditional statements can be nested:

# scan WMI
ScanHardwareInfo = true
# do not scan WMI when logged on remotely through citrx
if remotesession
    ScanHardwareInfo = false
    # except when the session name starts with ICA-XYZ
    if match string %SESSIONNAME% ICA[-]XYZ.*
         ScanHardwareInfo = true
    end if
end if

The configuration parser is quite simple to keep the size of the scanner executable as tiny as possible. For example there are no logical operators on conditions. You can nest conditional statements but be careful to keep the configuration as straight-forward as possible as nested conditions can be hard to understand.

The same configuration variable can be assigned multiple times. The value at the end of the configuration parse wins.

Environment variables

You can use references to Windows Environment variables anywhere in the configuration file except for the starting comment character. For example you could provide the Output Folder path in an environment variable and configure

# use enviroment variable %MYGROUP% to build variable folder names
#
OutputFolder = \\myserver\OctoSAM_%MYGROUP%

Info

Since Octoscan2 is a 32bit application, you see the Environment form a 32bit view. To see the 32bit Environment use the 32bit version of cmd.exe at %WinDir%\SysWow64\cmd.exe

ProgramFiles environment variable

Octoscan2 is a 32bit application to support both 32bit and 64bit Windows installations. When referencing Environment Variables such as %ProgramFiles% in the configuration, be aware that they point to different filesystem locations for 32bit processes.

In addition to this, Octoscan2 unifies process paths for 32-bit and 64-bit and always reports %ProgramFiles% in process signatures. If a program is installed both as 32 and 64bit version on the same machine, only one installation may be reported in some cases.

Configuration parameters

AlternateScanner

Name	Type	DefaultValue
AlternateScanner	String	"" (empty)
If set, Octoscan will replace itself with the configured alternate scanner.
This can be used to run a new version of the scanner only on a subset of machines, or for canary testing together with the canary conditional.

AppendComputerDomainNameToOutputFolder

Name	Type	DefaultValue
AppendComputerDomainNameToOutputFolder	Boolean	false

If true, Octoscan adds the computer’s domain name to the OutputFolderPath. This can be used in a multi-domain environment to get .scan files into different directories per domain. If the directory does not exist on disc, it will be created if possible.

Cleanup

Name	Type	DefaultValue
Cleanup	Boolean	false

If set to true, Octoscan2 will clean up all traces on the system. Use this setting in case you plan to end scanning your environment and want to clean up. Leave the invocation logic for Octoscan2 (GPO, Login Scripts etc.) in place long enough to clean most systems.

Info

If Cleanup is set to true, all other configuration parameters are ignored.

ImmediateMeteringOutput

Name	Type	DefaultValue
ImmediateMeteringOutput	Boolean	false

If true and Metering is also set to true, Octoscan2 will periodically write metering data into a .scax file which can be imported into the database. This setting is most commonly used in a terminal server or Citrix setting, where sessions are recycled and there is no possibility to persist a metering information file.

Info

If ImmediateMeteringOutput is set, the scanner needs to be able to overwrite existing files on the directory specified by ImmediateMeteringOutputFolder. This is slightly different from the standard, where the scanner always creates a new file.

Info

Upload to a web server is not supported if ImmediateMeteringOutput is set to true.

ImmediateMeteringOutputFolder

Name	Type	DefaultValue
ImmediateMeteringOutputFolder	String	Value of OutputFolder

Can be used to set a special folder for immediate metering files.

Metering

Name	Type	DefaultValue
Metering	Boolean	false

If true, Octoscan2 will report software usage metering information. Setting this Parameter to true will cause octoscan2 to stay resident during the user session and to periodically scan for programs executed under the current user credentials.

MeteringUseRoamingAppDataFolder

Name	Type	DefaultValue
MeteringUseRoamingAppDataFolder	Boolean	false

If true, Octoscan2 will use the roaming profile to store metering data between invocations. Use this parameter if the local profile gets reset frequently, for example in some terminal server environments.

# use roaming profile on citrix farms
if icasession
   MeteringUseRoamingAppDataFolder=true
end if

OutputFolder

Name	Type	DefaultValue
OutputFolder	String	"." (the current working directory)

Indicates where Octoscan2 should write its output file.

OutputFolder=\\centralserver\OctoSAM$\Data

The last directory in the path will be created if it does not exist and if the parent folder’s permissions allow creation of subdirectories. This is especially useful, if your configuration uses Variables such as:

OutputFolder=\\centralserver\OctoSAM$\Data\%USERDOMAIN%

PushLocal

Name	Type	DefaultValue
PushLocal	Bool	false

If true, Octoscan2 will install itself locally on the scanned computer and will start metering whenever the user logs in.

Info

PushLocal is ignored if Metering is false.

Info

Avoid PushLocal for machines that are always on the network. For example Kiosk systems or desktops. If you can tell desktops from laptops via the computer name, use a match machine condition to disable PushLocal.

Warning

Do not specify PushLocal if you install Octoscan2 locally on a machine by other means than starting it from a file share. For example if you distribute the scanner with Microsoft Intune or another managment system. In this case your installation routine must take care to configure automatic startup of Octoscan2 on the target machine. Use PushLocal only in the scenario where the scanner gets started from a central file share.

Warning

Using PushLocal may trigger your Antivirus system. Make sure you whitelist octoscan2.exe before configuring PushLocal and test thoroughly on a limited set of machines.

Scan

Name	Type	DefaultValue
Scan	Bool	true

If set to false, Octoscan2 will not generate a .scan file at all.

ScanSecurityInfo

Name	Type	DefaultValue
ScanSecurityInfo	Bool	false

If true, Octoscan2 will report the security groups the current user belongs to. Currently, OctoSAM Inventory does not use this information and does not import it into the database.

ScanHardwareInfo

Name	Type	DefaultValue
ScanHardwareInfo	Bool	true for workstations true for servers if run with administrator privilege false for servers if run with ordinary user rights

If true, Octoscan2 will report WMI information.

# scan WMI
ScanHardwareInfo = true
# do not scan WMI when logged on remotely through citrx
if remotesession
   ScanHardwareInfo = false
   # except when the session name starts with ICA-XYZ
   if match string %SESSIONNAME% ICA[-]XYZ.*
       ScanHardwareInfo = true
   end if
end if

Some server configuration settings can only be scanned as Administrator. Therefore it’s best to not scan the Hardware & Configuration information if Octoscan2 is not running with Administrator privileges. The setting can be set to true to force Hardware scan on servers for all users, but results might be inconsistent.

ScanProcess

Name	Type	DefaultValue
ScanProcess	Bool	false

If true, Octoscan2 will scan the process table once during scan and report metering data for the processes that are running, even if Metering is turned off. For example, java detection can be improved when java processes are detected on servers even if we do not want software metering. If Metering is turned on anyway, the setting affects only the WMI Scan of Win32_Process.

Info

ScanProcess also causes additional WMI scan for Win32_Process if WMI scanning is enabled via ScanHardware parameter.

Warning

To be able to import the data into the database, the METERING license option must be enabled. Activating this option results in incomplete Metering data for the affected systems. Metering queries will show only minimal usage data per scan for the found processes.

ScanUalDeviceAccess

Name	Type	DefaultValue
ScanUalDeviceAccess	Bool	true

If true (the default), Octoscan2 will report UAL Device Access statistics on supported systems if the scanner runs with administrator permissions. If set to false, no UAL Device Access statistics logs be scanned. Note that scanning the UAL logs can take quite some time depending on the amount of available data.

ScanUalUserAccess

Name	Type	DefaultValue
ScanUalUserAccess	Bool	true

If true (the default), Octoscan2 will report UAL User Access statistics on supported systems if the scanner runs with administrator permissions. If set to false, no UAL User Access logs will be scanned. Note that scanning the UAL logs can take quite some time depending on the amount of available data.

ScanVisualStudioSetupApi

Name	Type	DefaultValue
ScanVisualStudioSetupApi	Bool	true

If set to the default value of true, Octoscan2 will call into the Microsoft Visual Studio Setup Configuration API to report installed Visual Studio versions and instances. The scan does not add much overhead and almost no overhead if no Visual Studio is detected - so its recommended to keep this scan enabled unless you experience a problem on a specific machine.

Upload Parameters

Octoscan2 supports uploading of generated .scan files to a running upload server on Windows or octopus-resty on Linux. If upload is configured, Octoscan2 will first write the .scan files to a local folder and will try to upload to the specified host(s) later on. If Metering is enabled, Octoscan2 will continue to periodically try to upload the files. Octosoft provides upload server applications for Windows based on .NET and for Linux based on openresty.

Info

The recommended default settings are to use https and verify the server certificate during upload. For a secure configuration you need to specify the UploadHosts setting only. Most other upload settings are here to work around configuration problems and are generally not recommended in production.

Info

If Upload is configured, Octoscan2 will ignore the OutputFolder setting.

Warning

If Upload is configured, Immediate Metering mode is not supported. For scanning Citrix / Terminal Server software usage you need to provide a share where the .scan and .scax files can be written to.

UploadHosts

Name	Type	DefaultValue
UploadHosts	String	"" (empty)

A space-separated list of upload hosts to where to upload the generated .scan file.

Info

If the specified hosts can be reached with IPv6, Windows will prefer IPv6 over IPv4. There is currently no way to change that without potential side-effects for other applications on the same machine.

UploadPath

Name	Type	DefaultValue
UploadPath	String	"/upload/"

Path on the upload web hosts to where the upload will be posted.

Info

The same path is used on all configured hosts. You cannot configure different paths per host.

UploadNoProxy

Name	Type	DefaultValue
UploadNoProxy	Boolean	false

If set to true, the upload ignores any proxy settings. The default is to respect the configured proxy settings for the current user context.

This option is available after Octoscan2 1.10.4.120.

UploadInsecure

Name	Type	DefaultValue
UploadInsecure	Boolean	false

If set to true, Octoscan2 does not test the server certificate. The default is to connect only to a host which presents a valid certificate.

UploadPlainHttp

Name	Type	DefaultValue
UploadPlainHttp	Boolean	false

If set to true, uploads over plain http are allowed. The default is to always use https.

UploadPort

Name	Type	DefaultValue
UploadPort	Integer	443

Port to use on the upload web host.

Info

Transfer is using the https protocol regardless of the specified port unless UploadPlainHttp is set to true

Advanced Parameters

These settings should not be used unless advised by Octosoft support.

HardwareScanPeriod

Name	Type	DefaultValue
HardwareScanPeriod	Integer (hours)	0

Specify the minimum time between two hardware and configuration (WMI) scans in hours. If Octoscan2 is restarted within this period of time, no hardware information is scanned to the .scan file produced. Do not use this setting unless advised by Octosoft support. Not scanning at every logon leads to incomplete history information in some inventory data such as IP address history.

OfflineScan

Name	Type	DefaultValue
OfflineScan	Boolean	false

This parameter must be set to true if Octoscan2 is called by the OctoSAM Inventory Offline Scan module (OctoOffline.exe). See OctoSAM Inventory Offline Scan Configuration Guide for more information about offline scans.

ScanDelay

Name	Type	DefaultValue
ScanDelay	Integer (seconds)	0

The initial system scan is delayed for the specified number of seconds after configuration initialization start. This parameter can be used to delay the scan until after logon script is complete and/or software installations have been processed.

Debugging parameters

AppendMachineNameToScanFileName

Name	Type	DefaultValue
AppendMachineNameToScanFileName	Boolean	false

In some rare cases Octoscan2 may terminate without writing any information to the compressed scan file. This usually indicates a serious problem with the system configuration of affected machines. Adding the machine name to the scan file name may help identify affected systems.

FlushLevel

Name	Type	DefaultValue
FlushLevel	Integer	1

If set to 1, Octoscan2 flushes the collected basic information to the scan file before attempting to perform the software or hardware scan. Setting this parameter to a low value leads to smaller scan files but in case of errors you have potentially less information in the scan file.

FlushLevel	Behavior
0	Produces the smallest .scan files but no information is written if Octoscan2 terminates prematurely
1 (default)	Basic information such machine and user names is flushed to the .scan file as early as possible
2	Flush after each logical block of information
3	Flush after each sub block
4-7	Reserved for debugging
8	Flush on every embedded comment message
9	Flush after every XML element
10	Flush after every line
11	Additional debugging information about the progress of WMI scan

Setting FlushLevel to 0 results in the smallest scan files, but should be used only after you have the scanner running stable with no corrupt scan files for a while.

Info

Regardless of the FlushLevel setting, Octoscan2 tries to flush its buffer when it encounters an error condition.

FlushLevel can also be set through local registry parameters. In that case, the maximum FlushLevel defined will be applied.

Info

If octoscan2 encounters an error during processing it writes an <error> element to the compressed output and tries to flush the output file. This behavior leads to the situation that the last line in the decompressed .xml file is an <error> element. The error message does not have to be related to the real cause of the incomplete .scan file, it’s just the last bit that got written to the file because octoscan2 flushes its buffers whenever it writes an <error> element to the .scan file.

Conditional statements

administrator

True if the scanner runs with Administrator permissions. If UAC is active, this condition is true only if the process actually runs in the elevated administrator mode. If you run the scanner manually from a desktop, you usually need to start it with “Run as Administrator” option.

canary percentage

True if a random generated number between 1 and 100 is lower than the defined percentage. This conditional allows to canary test new settings on a small percentage of scans.

if canary 5
    AlternateScanner=\\server\OctoSAM$\alt_bin\octoscan2.exe
end if

This configuration starts the alternate scanner .exe on approx. 5 percent of all scans.

embedded

True if on an embedded version of Windows.

if embedded
   Metering = false
end if

exists file path

True if the specified file or folder name exists.

if exists file C:\programme\myapp\test.exe
    Metering = false
end if

icasession

True if Octoscan2 is called in a XenDesktop Session

#
# no wmi scan if called through a citrix session login
# in this case we are interested in the Metering data (even if on server).
#
if icasession
    ScanHardwareInfo = false
    Metering = true
    ImmediateMeteringOutput = true
end if

The following example shows an approach to detect Citrix environments:

#
# example to detect citrix environments.
# note that XenDesktop does not set the remote indicator.
#
if remotesession
    if icasession
        # this is XenApp over ICA
    else
        # standard rdp session (can also be XenApp if RDP is used to connect)
    end if
else
    if icasession
        # this is XenDesktop over ICA
    else
        # this is ordinary desktop
    end if
end if

localsession

True if Octoscan2 is called from the local console. Exact opposite of remotesession.

match machine regex

True if the current machine name (NETBIOS name, lower-case ) matches the specified regular expression.

#
# do not scan if computer name starts with ‘STAFF-‘
#
if match machine staff-.*
    Scan = false
end if

match machinedomain regex

True if the current machine domain name (NETBIOS name, lower-case) matches the specified regular expression.

match user regex

True if the current user name (SAMAccount name, lower-case) matches the specified regular expression.

match upn regex

True if the current UserPrincipalName matches the specified regular expression.

This option is available after Octoscan2 1.10.4.120.

Info

Be aware that the UPN may not always be set depending on your network/security configuration.

match userdomain regex

True if the current user domain name (NETBIOS name, lower-case) matches the specified regular expression.

match string string regex

True if the supplied string matches (lower-case) the specified regular expression. Can be used to test values of environment variables for example.

if match string %USERDOMAIN% (devdomain|testdomain)
    Metering = false
end if

match tag regex

(New in OctoSAM 1.10.8.61) True if the tag specified using the /tag: option on the command-line matches the specified regular expression. Note that the match is case sensitive.

Useful for example in a scenario, where you have different group policies and use the /tag: option to indicate which policy started the scanner.

minmajor, minminor, minbuild

True if the operating system version is greater or equal to the configured value. See MSDN Documentation on OSVERSIONINFOEX for more information.

if minmajor 10
    # meter on windows 10 / Server 2016 only
    Metering = true
end if

Deprecated

These conditions are deprecated. Please do not use them for new configurations. They will be removed in a future version of Octoscan2.

remotesession

True if Octoscan2 is called through a remote session, either RDP or ICA.

server

True if on a server operating system

terminalservices

True if terminal services are installed

ualcapable

True if the operating system supports User Access Logging.

workstation

True if on a workstation operating system

wow64

True if Octoscan2 runs on a 64 bit OS.

Message statement

The message statement allows to send a message to the output window. This can be used to trace complex nested conditions.

if match machine staging-.*
    message "scan disabled for staging machines"
    Scan = false
endif

Java file system scan

By default Octoscan2 already uses a variety of methods to find installed Java runtimes. For example we inspect the Path, the Java Registry and well known locations for standard installations. However, many software products include their private copy of Java or some users copy a private version of java on their machine without installing.

Octoscan2 allows to scan parts of the filesystem for java executables.

Multiple JavaFileSystemScan commands can be used in a configuration.

Examples

Scan ProgramFiles directories and subdirectories for Java runtimes that come as part from applications

JavaFileSystemScan programfiles

this is equivalent to:

JavaFileSystemScan %ProgramFiles%
if wow64
    # file scan 64-bit programs on 64 bit windows
   JavaFileSystemScan %ProgramW6432%
end if

Scan all local filesystems

JavaFilesystemScan local

Scan the System Drive

JavaFilesystemScan %SystemDrive%\

Scan C: and D: drive if they exist

JavaFileSystemScan C:\
JavaFileSystemScan D:\

Scan all local filesystems on all machines except for fs001 and fs002. Scan only drives c: and d: on these.

if match machine fs001|fs002
    # do not scan large local volumes on these file servers
    JavaFileSystemScan C:\
    JavaFileSystemScan D:\
else
    JavaFileSystemScan local
end if

In complex settings or for special tests, you may want to reset already configured scans before you configure new scans

# complex logic here
if ....

end if

# all fine and dandy but for this special machines we want to configure something completely different:

if match machine s0422
    JavaFileSystemScan clear
    JavaFileSystemScan c:/my_special_folder
end if

Warning

Scanning large file systems can put considerable stress on your machines. Exclude your file server volumes or other big data volumes from the scan.

Info

For performance reasons, the Java filesystem scan does not descend into some directories. The following directories and their subdirectories are not scanned:

• .git
• .nuget
• .vs
• .vscode
• /google/chrome
• /local/microsoft/teams
• /local/microsoft/vault
• /local/microsoft/windows
• /local/mozilla/firefox
• /local/nuget
• /microsoft/edge
• /octosoft/octosam
• /windows/assembly
• /windows/fonts
• /windows/logs
• /windows/system32
• /windows/systemapps
• site-packages
• Windows
• WinSXS
• WTx64

Custom file scan

Octoscan2 supports scanning of custom file metadata with the following statement

FileScan <class> <path>

Multiple FileScan statements can be used in a configuration file together with conditions. The scanned information appears under Hardware % & Configuration (WMI Tables).

Example

FileScan X_CustomConfig "c:/CustomConfig/*.ini"

Info

Note that by convention, custom class names start with X_

Since the custom file scan uses the same data structures as WMI (Hardware & Configuration), custom file scan is only done when ScanHardwareInfo is set to true.

Custom file signature scan

Octoscan2 supports scanning of custom files metadata, version and digital certificate info with the following statement

FileSignatureScan <path> [recurse]

Multiple FileSignatureScan statements can be used in a configuration file together with conditions. The scanned information appears as static file: software signature. In case of java .exes an additional java: signature gets generated. This can be useful when a site has a well known installation directory for a site-specific packages that do not conform to the standard installation conventions.

Use file scanning only as a last resort if the package does not leave any other detectable traces on the system. The OctoSAM software catalog does not use file: signatures. These signatures can only be used with custom packages.

The file signature scan is done whenever a software scan is initiated. The user must have read permissions on the files and folders that are to be scanned.

Optional Windows file wildcards are only supported in the filename, the last part of the specified path.

Examples

FileSignatureScan "c:/my application/myprogram.exe"
FileSignatureScan "%ProgramFiles%/my other application/myotherprogram.exe"

Detects site specific executables at a well-known location.

FileSignatureScan c:/mypackages/mypackage/*.exe

Detects all .exe files in the directory c:/mypackages/mypackage

FileSignatureScan c:/mypackages/mypackage/*.dll     recurse

Detects all .dll files in c:/maypackages/maypackage and subdirectories

# file scan 32-bit programs on 32 or 64 bit windows
FileSignatureScan "%ProgramFiles%/*.exe" recurse
# file scan 64-bit programs on 64 bit windows
if wow64
    FileSignatureScan "%ProgramW6432%/*.exe" recurse
end if

Scans all .exe files in the programs folders for 32 and 64 bit Windows.

Warning

Be careful when you use the the recurse option. Recursing into a large directory structure can take a lot of time, stresses the scanned system and can potentially generate a considerable amount of data. Use recursive form only as a last resort if you do not know the folder structure of the product in advance.

Info

You may use signature rewriting to move more fields than just the filename and version into the signature. For example you can move the Publisher from the version resource or from a digital certificate to the signature.

Info

Since octoscan2 is a 32-bit program, you see the filesystem from a 32-bit view. Some parts of Octoscan2 such as usage metering unify the 32/64 view. Therefore you may see slightly different paths if you scan within %ProgramFiles% or other regions of the filesystem that are sensitive to the 32/64 bit differences.

Custom registry scan

Octoscan2 supports inventory of Registry keys with the following statement

RegistryScan <class> <instance> <path> [32|64]

Multiple RegistryScan statements can be used. Class and instance define where a particular scan appears in the Hardware and Configuration tree. The class name should begin with X_ to avoid clashes with future versions of OctoSAM Inventory.

Path can start with HKCU or HKLM for the current user or local machine hives.

The last optional parameter specifies if the 32bit or the 64bit part of the Registry should be scanned. If not set, Octoscan2 will search 32bit first and 64bit only if nothing found in the 32bit part.

Examples

RegistryScan X_IvoSoftClassicShell ClassicShell "HKLM/SOFTWARE/IvoSoft/ClassicShell"
RegistryScan X_AdobeFlash Flash32 "HKLM/SOFTWARE/Adobe/FlashPlayer" 32
RegistryScan X_AdobeFlash Flash64 "HKLM/SOFTWARE/Adobe/FlashPlayer" 64

Info

The class/instance logic implies that you should use the same class name only for keys that have the same range of Registry value names. Some Registry hives are the same for 32 and 64 bit based access. Since the custom Registry scan uses the same data structures as WMI (Hardware & Configuration), custom Registry scan is only done when ScanHardwareInfo is set to true.

On Servers, this is per default only the case if the scanner was started with effective Administrator rights.

Resetting cumulative scan configurations

Configuration settings RegistryScan, FileScan, FileSignatureScanand JavaFileSystemScanare cumulative. If multiple statements are encountered while parsing the configuration file, each configured location is added for scanning. Sometimes the configuration logic can be made simpler by resetting already encountered configuration statements. Therefore, these settings support specifying clear as first argument to clear earlier configurations.

For example, you may have some rather complex JavaFileSystemScan configuration and want to change that configuration for just a couple of specific machines:

if .....
    .... complex logic with multiple JavaFileSignatureScan settings
end if

# special Java scan for thismachine and thatmachine (regardless of prior scan configuration that may also apply)
if match machine thismachine|thatmachine
  JavaFileSystemScan clear
  JavaFileSystemScan c:\
end if

Regular expressions

Starting with OctoSAM 1.10.5.48, octoscan2 uses the standard c++ regex library (std::regex). This makes regex matches in the configuration file much more powerful and better aligned with the .net regex syntax that is used in most parts of OctoSAM.

Info

When testing patterns with Regex Buddy, select std::regex (Visual c++ 2017-2022), case insensitive.

Offline scan

OctoSAM Inventory Offline Scan can be used to scan systems that are not part of your network or that are not part of your Active Directory or NDS.

Using the offline scan tool allows you to have these disconnected machines in your OctoSAM Inventory database. The Organization can also be set offline, so that the machine appears in the correct organization in the inventory.

Offline Scan is configured to run from USB sticks or removable discs. Due to the disconnected architecture of the whole OctoSAM Inventory scanning process, an offline scan does not differ significantly from a connected scan invoked by GPO or similar.

OctoOffline.exe

OctoOffline is a small program that provides an easy way to interactively start the standard scanner Octoscan2.exe.

With OctoOffline you can also manually enter values for the Description and CustomField1 / CustomField2 attributes of the OctoSAM Inventory Machine Object

Preparation and configuration

Required programs

Before you start, make sure that you have the newest versions of Octoscan2.exe and OctoOffline.exe Both executables are delivered with the OctoSAM Inventory Support Files archive.

Configure Octoscan.config file

For offline scans, the Octoscan2 configuration parameter OfflineScan must be set to true.

;
; Octoscan2 Sample Config for Offline Scans
;
OfflineScan=1
ScanPeriod=0
HardwareScanPeriod=0
ScanHardwareInfo=1
Metering=0
OutputFolder=.\scanfiles

These are the minimum required settings for offline scans. For obvious reasons, metering cannot be activated for offline scans. Note that in this example the .scan files are written to a subfolder, which must exist. See Octoscan2 Configuration Guide for more information about configuring Octoscan2.

Configure Organizations.csv file

Generate a .csv file through OctoSAM Inventory GUI -> Setup -> Organization -> Grid Context Menu -> Export.

OctoOffline expects the file in the format ;. Contents of “Name” will be written to the .scan File.

Info

It is strongly advised, that you configure your organization structure before starting offline scans. If no organizations.csv file is found, organization "Unknown" will be selected and it may be cumbersome to map the machines to the correct organization after import.

OctoOffline.ini

This file persists local settings of the offline tool. If the file does not exist the settings dialog will be shown at start.

Running OctoOffline

If you run OctoOffline for the first time, you are asked for your name.

The value entered is used to supply a default value for the Notes field of the machine object. Enter the desired information and click Scan!

After a short while a Message Box will indicate that the scan could be performed.

Verify that a new .scan file has been written to the configured Output Directory. In our example setup to the subdirectory “scanfiles”.

Configure AUTORUN.INF

[autorun]
OPEN=octooffline.exe
ICON=octooffline.exe
ACTION=octooffline.exe

Note, however that AutoPlay is often disabled for USB Sticks. Still it’s cool to see the OctoScan Icon.

Prevent scan operator from running Octoscan2.exe directly

It’s a good idea to set Octoscan2.EXE as a hidden file. Octoscan2 detects, when it is run directly in offline mode and displays a warning.

Importing the offline scan files

Copy the generated .scan files to your ordinary Import folder.

Troubleshooting

No .scan file gets produced:

Check if Octoscan2 is already running in Metering mode on the machine. If that is the case, use Octoscan2 /q to stop the background instance of Octoscan2.

In general, systems that are scanned regularly via GPO or similar means should not at the same time be scanned with the offline scanner.

Verify the .scan File:

Use octodump.exe to generate a readable .xml File:

Understanding .scan files

Using octodump.exe

Octodump is a utility to decompress .scan files into their .xml format. It works in the current directory and processes all scan files found. The generated .xml files have the same timestamp information as the .scan file so that you can still sort the files or find out what files are newest to the system. Octodump can also be used to compress a .scan.xml file into the .scan format.

Alternatively most zip utilities should also be able to decompress the .scan file.

Getting summarized .scan file information

Call Octodump with the /s option to generate a summary over multiple .scan files. The output is in .csv format, so that you can easily analyze it further in Excel or any text editor. Octodump uses its own internal parser to read the contents of the .scan file so that you can also analyze partial files or otherwise malformed files.

Analyzing .scan files

environment section

Shows basic information about the environment of the scan.

octoscan section

Here you can find the build info for the Octoscan2 process that actually generated the file and the full path to the configuration file used for this scan.

octoscan_config section

In this section, you find the configuration parameter values that were set after evaluating the configuration file. Three parameters that cannot be set through configuration are:

DoHardwareScan
DoSoftwareScan
DoUalScan

These parameters indicate if hardware, software or UAL scans are to be performed, considering the configuration, scan period settings and timestamp value on the current machine.

Troubleshooting

Corrupt .scan files

The Import Service rejects .scan files that are not well-formed.

Corrupt .scan files usually indicate one of the following problems:

• Octoscan2 was killed before it could write the compressed output file. For example some methods of writing a logon script with VB Script may lead to this problem. When the login script ends, all processes started from the script are also killed.
• There are access permission problems for parts of the registry or the WMI service is not started
• The network connection between the scanned Machine and the network share was not stable.

Things you can try to get more information:

• Use octodump -s to get a summary over multiple .scan files. This option also parses partial .scan files that cannot be processed by an XML parser.

• De-compress partial files using Octodump and check the information at the beginning of the file.

  • Sometimes the problem might only occur on a certain machine or a group of machines.
  • Check OS version information
  • Remote session / Citrix ICA session
• Try increasing the FlushLevel parameter to find out where Octoscan2 errs out.
• Try setting either the ScanHardwareInfo or ScanSoftwareInfo to false.
• As a last resort, try setting AppendMachineNameToScanFileName to true to find out what machines lead to the problem.

Changes made to scanned systems

Care has been taken to minimize the impact of the scanning module on scanned systems. However, for optimized functionality, Octoscan2 must maintain a limited amount of per-user state information on each inspected system.

All information is kept in a human-readable format. The registry settings and the local metering state file can safely be removed anytime. In the worst case, some metering information may be lost.

Registry key for scan state information: (roaming)

HKEY_CURRENT_USER\SOFTWARE\Octosoft\Octoscan

Registry key for starting a push-installed octoscan2: (roaming)

HKEY_CURRENT_USER\CurrentUser\SOFTWARE\Microsoft\Windows\CurrentVersion\Run\Octoscan2

Metering state file location: (non-roaming)

Local Appdata\Octosoft\Octoscan2\%COMPUTERNAME%_metering.txt

Local copy of Octoscan2 when push install is configured: (non-roaming)

Local Appdata\Octosoft\Octoscan2\Octoscan2.exe

Locally cached scan files when using http base upload: (non-roaming)

Local Appdata\Octosoft\Octoscan2\*.sca?

Locally stored trace files if tracing is active: (non-roaming)

Local Appdata\Octosoft\Octoscan2\Trace_*.log

Cleanup

Before removing Octoscan2 from an environment, set the Cleanup configuration parameter to true and let the scanner run for a month until it has removed its traces from most systems.

Using local settings

Octoscan2 supports local overriding of some of the configuration switches. This can be useful if you are testing an installation or experiencing problems on a particular machine.

Use the provided OctoscanSettings.Exe utility to override settings.

These local registry settings override the configuration through the config file or command-line options. For the FlushLevel setting, Octoscan2 will use the max. Value of all configurations found.

Info

You can set local settings either on the current user or for all users on the system if you have local administrator rights.

Options

You can set the following options in the local registry, which override settings from the config file:

Show windows during scan

if set, the scanner window will show during the scan. This is equivalent to specifying /show on the command-line of octoscan2.

Keep window open after scan

if set, the scanner window will stay open after the scan. This is equivalent to specifying /keep on the command-line of octoscan2.

Detailed trace

Octoscan2 will write a detailed trace file

Flush level

Override the configured flush level

Wait

Wait time in milliseconds before starting the scan. You can set this to a reasonable amount of time if you suspect timing issues on a machine.

Disable software scan

Do not scan the software inventory. Temporarily set this flag to confirm a problem with the software scan.

Disable WMI scan

Do not scan WMI regardless of the configuration in the .config file. Temporarily set this flag if you suspect a problem with WMI.

Disable usage metering

Do not meter software usage. Override the configured metering settings for this user or machine.

Disable immediate metering output

Do not perform immediate metering output. Can be set if you suspect a problem with immediate metering output on terminal servers.

Disable UAL scan

Do not scan the User Access Log

Disable Hyper-V scan

Do not scan Hyper-V configuration

Disable push local

Do not perform a push local installation for this user and/or machine.

Disable java filesystem scan

Do not scan the filesystem for Java installations

Write trace file

Write a trace fie OctscanSettings.exe can also be used to enable tracing for a specific user or all users on a machine. If the Write Trace option is enabled, Octoscan2 writes a daily trace file to local AppData (non-roaming). The trace files are kept until the option is disabled again.

Scanned information

Machine and operating system information

For detailed information, see the database model documentation (Machine table)

User information

For detailed information, see the database model (User table)

User device affinity and logon history

Information about user-to-device relations.

User local security group membership (optional)

Octoscan2 can scan the user's membership in local groups. This information is currently not stored in the inventory database.

Software information

Windows installer registry

All information from the Windows installer registry.

Windows AppStore

Information about Apps installed from the AppStore.

SWID files

SWID Files are copied entirely and can be investigated in the database.

Product-specific detection logic

Octoscan2 contains product-specific logic to detect some of the more complex products like:

• Microsoft SQL Server Instance information
• Sharepoint
• Internet Explorer Versions
• Microsoft Visual Studio
• Microsoft Office Click 2 Run
• Java Runtime and JDK
• ORACLE_HOME configuration
• Oracle Database Servers

Filesystem scan (optional)

Octoscan2 can be configured to scan parts of the filesystem. The OctoSAM software discovery process does not use filesystem information. The filesystem scan can be helpful if OctoSAM is the main inventory scanner, but some connected systems require filesystem information.

Software metering (optional)

Software Metering scans all running processes per user.

Custom registry scan

Octoscan2 can be configured to collect site-specific registry information.

Custom file metadata scan

Octoscan2 can be configured to collect metadata (Creation, LastAccess, LastModification, Size) about specified files and folders.

APP-V

The following APP-V WMI classes get scanned

• AppvClientApplication,
• AppvClientAsset
• AppvClientConnectionGroup
• AppvClientPackage
• AppvPublishingServer
• WMI_Extension

User Access Logging (optional, capable systems only)The following User Access Logging classes get scanned:

• MsftUal_Admin
• MsftUal_SystemId
• MsftUal_Overview
• MsftUal_UserAccess
• MsftUal_DeviceAccess

Hyper-V

Octoscan2 scans the host and guest side of Windows virtual machines. The following Hyper-V classes get scanned on Hyper-V hosts:

• Msvm_ComputerSystem

VMware

Octoscan2 detects the guest parameters of VMware.

Hardware and configuration

WMI classes

For detailed information, see Microsoft documentation:](https://msdn.microsoft.com/en-us/library/aa394554(v=vs.85).aspx)

The following WMI Classes get scanned:

• Win32_BaseBoard
• Win32_BIOS
• Win32_ComputerSystem
• Win32_ComputerSystemProduct
• Win32_DesktopMonitor
• Win32_DisplayConfiguration
• Win32_LogicalDisk
• Win32_NetworkAdapter
• Win32_PhysicalMemory
• Win32_NetworkAdapterConfiguration
• Win32_DiskDrive
• Win32_Battery
• Win32_PortableBattery
• Win32_Printer
• Win32_TCPIPPrinterPort
• Win32_Processor
• Win32_PNPEntity
• Win32_Share
• Win32_PrinterShare
• Win32_SystemEnclosure
• Win32_SoundDevice
• Win32_USBController
• Win32_USBControllerDevice
• Win32_USBHub
• Win32_VideoController
• Win32_PointingDevice
• Win32_OperatingSystem
• Win32_SerialPort
• Win32_ParallelPort
• Win32_Service
• Win32_OptionalFeature (installed features only)
• WmiMonitorID