パターンについて
For collecting data from remote Systems or Devices the Patterns are used to describe how to get information and transforming that to Discovery-Objects. The best way to see which Objects are possible is to generate Host and Device Examples with "Discovery.exe -e".
Pattern Structure
A Pattern is a XML File wich can contain the following Nodes:
ノード | (必須) | 説明 |
---|---|---|
<Version> | A version string for the pattern | |
<PatternID> | A unique string for each pattern | |
<AlternativePattern> | A pattern that will be used instead of that one (e.g. used for PowerShell) | |
<ProcessType> | Discovery-Tool が情報を収集するために続行する実行のタイプを記述します。 All possible Process Types are listed under 1.1. | |
<PatternType> | Describes for which type of Discovery-Object the pattern is responsible. All possible Pattern Types are listed under 1.2. | |
<OrderNr> | It is possible to have multiple Pattern for one Discovery-Object, the order number is used to set in which order the Pattern are executed. (For example you can see in the pattern folder 3 Pattern for Linux Network Interface) | |
<Command> | リモート システムで実行されるコマンドが含まれます。 The command depends on the Process Type examples are listed under 1.1: | |
<Processing> | Discovery-Objects に渡す結果データを処理する C# SourceCode が含まれます。 For more details see Creating Custom Pattern | |
<IgnoreCommandCache> | If set to true, the CommandProvider will not observe the cache. Per default a command result will be stored in the cache and the result of the same command will be read from the cache. The cache is just persistent for a scan session. | |
<RegValue> | WMIRegValue で使用されるコマンドと組み合わせて読み取られるレジストリ変数。 | |
<ApplicationName> | The name of the application that is used to collect extended information for | |
<ContextName> | Optional SNMP Walk context name | |
<WMINamespace> | define an alternative WMI Namespace for the initial command |
Process Types
タイプ | Example Command | Command Result Type | 説明 |
---|---|---|---|
SSHExecute | ifconfig -a | 文字列 | 接続されているリモート UNIX システムで SSH コマンドを実行する |
WMIQuery | SELECT * FROM Win32_OperatingSystem | ManagementObjectCollection | 接続されているリモート Windows システムで WMI クエリを実行する |
WMIExecute | netstat -an | 文字列 | 接続されているリモート Windows システムでコマンドを実行する |
WMIRegValue | <![CDATA[ | The result object can any type of a registry value | WMIRegValue によって、コマンドはレジストリ パスを含み、<RegValue> Node of the Pattern に記述されている値を読み取る。 「Root」は既定で「HKEY_LOCAL_MACHINE\」に設定されるため、コマンドには含めないこと。 結果はレジストリ変数のすべてのバリエーションを含むオブジェクトである。 |
WMIRegValueList | <![CDATA[ | List<string> | WMIRegValueList によって、コマンドはレジストリ パスを含み、レジストリ パスの「subKeys」を返す。 「Root」は既定で「HKEY_LOCAL_MACHINE\」に設定されるため、コマンドには含めないこと。 |
PowerShellExecute | Get-WmiObject win32_computersystem | 文字列 | 接続されているリモート Windows システムで PowerShell コマンドを実行する |
SNMP_GET | 1.3.6.1.4.1.2021.4.5.0;1.3.6.1.4.1.2021.4.6.0 | ExtendedInformation is an object with two attributes: | 指定された MIB に対して SNMP GET コマンドを実行する。 ExtendedInformation のリスト、名前 (MIB) を含む ExtendedInformation、および MIB の値を返す。 |
SNMP_WALK | 1.3.6.1.2.1.2.2.1.2;1.3.6.1.2.1.4.20.1.2 | ExtendedInformation is an object with two attributes: | 指定された MIB に対して SNMP WALK コマンドを実行する。 ExtendedInformation のリスト、名前 (MIB) を含む ExtendedInformation、および MIB の値のリストを返す。 |
Command Result Types
In Discovery 3 version every Pattern Process Type has a Command Result implementation.
Process Type | Command Result Type |
---|---|
WMIQuery | WMIQueryResult |
WMIRegValue | WMIRegValueResult |
WMIRegValueList | WMIRegValueListResult |
WMIExecute | WMIExecuteResult |
PowerShellExecute | PowerShellExecuteResult |
SSHExecute | SSHExecuteResult |
SNMP_GET | SNMPExecuteResult |
SNMP_WALK | SNMPExecuteResult |
VIMObject | VIMCommandResult |
Pattern Types
The pattern type defines which type of Discovery-Object are returning as result from the processing.
Discovery-Object の結果はマージされます。たとえば、Discovery/pattern フォルダーには、複数の HostInfo パターンが表示され、それらはすべてホストの部分的な結果を収集するので、Discovery-Tool が属性をマージします。
タイプ | example Pattern (inlcuded) | 説明 |
---|---|---|
ホスト | Linux_Hostinfo_Hostname.pat Windows_Hostinfo_Hostname_Model.pat | Processing collected data for a Host. HostInfo-Object を処理するパターン関数 (PerformAction)。 |
Deviceinfo | SNMP_Deviceinfo_Default.pat | Processing collected data for a Host or a Device. DeviceInfo-Object を処理するパターン関数 (PerformAction)。 |
ネットワーク | Linux_NetworkInterfaces.pat Windows_NetworkInterfaces.pat | Processing collected data for NetworkInterfaces. 親システムの NetworkInterface-Object を処理するパターン関数 (PerformAction)。 |
CPU | Linux_CPUs.pat Windows_CPUs.pat | Processing collected data for CPUs. 親システムの CPUInfo-Object を処理するパターン関数 (PerformAction)。 |
OS | Linux_OS.pat Windows_OS.pat | Processing collected data for OS. 親システムの OSInfo-Object を処理するパターン関数 (PerformAction)。 |
ファイルシステム | Linux_FileSystem.pat Windows_FileSystem.pat | Processing collected data for FileSystems. 親システムの FileSystemInfo-Object を処理するパターン関数 (PerformAction)。 |
アプリケーション | Linux_Application_RPM.pat Windows_Application_Product.pat | Processing collected data for Applications. 親システムの ApplicationInfo-Object のリストを返すパターン関数 (PerformAction)。 |
Patch | Windows_Patches.pat | Processing collected data for Patches. 親システムの PatchInfo-Object を処理するパターン関数 (PerformAction)。 |
ApplicationService | Windows_ApplicationServices.pat | Processing collected data for ApplicationServices. 親システムの ApplicationServiceInfo-Object を処理するパターン関数 (PerformAction)。 |
OSProductKey | Windows_ProductKey.pat | Processing collected data for License. オペレーティング システムのライセンスを処理するパターン関数 (PerformAction) |
ApplicationProductKey | 例: アプリ プロダクト キー | Processing collected data for License. 親システムのアプリのライセンスを処理するパターン関数 (PerformAction)。 |
ユーザー | Linux_User.pat Windows_User.pat | ユーザーについて収集されたデータの処理。 親システムのユーザーを処理するパターン関数 (PerformAction)。 |
グループ | Linux_Group.pat Windows_Group.pat | グループについて収集されたデータの処理。 親システムのグループを処理するパターン関数 (PerformAction)。 |
ConnectedPeripherie | Windows_Peripherie_USB_Storage.pat | Processing collected data for Extended Informations. 親システムの ExtendedInformation-Object を処理するパターン関数 (PerformAction)。 |
SNMPExtendedValues | SNMP_Deviceinfo_ExtExampleRAM.pat | Processing collected data for Extended Informations. 親システムの ExtendedInformation-Object を処理するパターン関数 (PerformAction)。 |
ConnectedPeripherie | Windows_Peripherie_USB_Storage.pat | Processing collected data for Connected Devices of the parent system. |
HostinfoList | Windows_VBox_VMs.pat Linux_VBox_VMs.pat | Processing collected data for a lis of Virtual Guests 親システムの Host-Object (仮想ゲスト マシンなど) を処理するパターン関数 (PerformAction)。 |
PostProcessing | 事後処理パターンは、すべてのパターン タイプの後に実行され、ホスト/デバイス情報の追加または変更に使用できる HostInfo-Object または DeviceInfo-Object を返すパターン関数 (PerformAction)。 |
Creating custom patterns
For creating a custom pattern navigate to the Discovery/pattern folder. Here you can create a new file (UTF-8) with the ending .pat or you copy and modifying an existing pattern of the Pattern-Type you want. The best practice to develop and test a new pattern is to extract a separate Discover-Tool Instance and setting up a connection to the Host or Device that returning the result data you want to handle with.
次に、「メイン」の HostInfo パターンを除くすべてのパターンを削除します(Linux_Hostinfo_Hostname.pat、Windows_Hostinfo_Hostname_Model.pat、SNMP_Deviceinfo_Default.pat)。Hostname が含まれている「メイン」の HostInfo オブジェクトは必ず必要です。このセットアップでは、他のすべてのパターンの応答を待たずに、新しいパターンを高速テストできます。
Be sure that your new Pattern are containing all required XML-Nodes, the <Processing>-Node containing the C# class to process the result data from the command to a Discovery-Object. The functionality is that the Discovery-Tool reading the C# Source Code that is including the <Processing>-Node and invoking the PerformAction-Method of the PatternExec-Class.
PerformAction Method は必須です。Discovery-Tool は次の 4 オブジェクトを含むオブジェクト配列を使用して、このメソッドを呼び出します。
parameter | object type | description |
---|---|---|
parameters[0] | コマンド結果 | Containing the result of the initial pattern command |
parameters[1] | iProvider | Containing the executing Provider-Class that is connected to the discovering system. このプロバイダーは、必要に応じて他のコマンドを実行するためにパターンで使用されます。 |
parameters[2] | オブジェクト | スキャンの開始時に最初に作成される HostInfo-/Device-オブジェクトを含みます。 |
ホストまたはデバイスへの接続では、 Discovery-Tool で使用するプロバイダーのタイプが 4 つあります。以下では、接続とデータ収集コマンドの実行を処理するプロバイダーについて説明します。
パターン内では、システムからさらに情報が必要な場合に、実際に接続されているプロバイダーを使用して追加のコマンドを実行できます。
SSH プロバイダー
SSH プロバイダー クラスは Linux システムに接続し、Insight のパターンで使用できます。
using Insight.Discovery.ProviderClasses; // Include the ProviderClasses Namespace at the Head of the PatternCode using Insight.Discovery.InfoClasses; // Include the InfoClasses Namespace at the Head of the PatternCode // Casting the connected Provider out of the parameters from the PerformAction-Method SSHProvider ssh = (SSHProvider)parameters[1]; // using the SSH-Provider to execute a command and receiving the result. var result = (SSHExecuteResult)ssh.ExecuteCommand("hostname"); // returning the hostname of a Linux System
たとえば、cast SSHProvider は "Linux_Hostinfo_Hostname.pat" パターンで使います。
WMI プロバイダー
WMI プロバイダー クラスは Windows システムに接続し、Insight のパターンで使用できます。
using Insight.Discovery.ProviderClasses; // Include the ProviderClasses Namespace at the Head of the PatternCode using Insight.Discovery.InfoClasses; // Include the InfoClasses Namespace at the Head of the PatternCode // Casting the connected Provider out of the parameters from the PerformAction-Method WMIProvider wmiProvider = (WMIProvider)parameters[1]; // using the WMI-Provider to read a Registry Value. var result = (WMIRegValueResult)wmiProvider.GetRegistryValue("HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\<Key>", "DisplayName"); // using the WMI-Provider to get a List of all Registry-Sub-Keys. var result = (WMIRegValueListResult)wmiProvider.GetSubKeysFromRegistry("SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\"); //using the WMI-Provider to execute a WMI query receiving the result. var result = (WMIQueryResult)wmiProvider.ExecuteWMIQuery("netstat -an"); //using the WMI-Provider to execute a command and receiving the result. var result = (WMIExecuteResult)wmiProvider.ExecuteWMICommand("netstat -an");
SNMP プロバイダー
SNMP プロバイダー クラスは SNMP デバイスに接続し、Insight のパターンで使用できます。
using Insight.Discovery.ProviderClasses; // Include the ProviderClasses Namespace at the Head of the PatternCode using Insight.Discovery.InfoClasses; // Include the InfoClasses Namespace at the Head of the PatternCode // Casting the connected Provider out of the parameters from the PerformAction-Method SNMPProvider snmp = (SNMPProvider)parameters[1]; // using the SNMP-Provider to execute a SNMPGet command and receiving the results var result = (SNMPExecuteResult)snmp.ExecuteCommand("1.3.6.1.2.1.1.6.0", ScanProcessType.SNMP_GET, true); // using the SNMP-Provider to execute a SNMPWalk command and receiving the results var result = (SNMPExecuteResult)snmp.ExecuteCommand("1.3.6.1.2.1.2.2.1.2", ScanProcessType.SNMP_WALK, true); // using the SNMP-Provider to execute a SNMPWalk command with contextName and receiving the results var result = (SNMPExecuteResult)snmp.ExecuteCommand("1.3.6.1.2.1.2.2.1.2", ScanProcessType.SNMP_WALK, "myContext",true);
VIM プロバイダー
SNMP プロバイダー クラスは VMware ESXi システムに接続し、Insight のパターンで使用できます。
using Insight.Discovery.ProviderClasses; // Include the ProviderClasses Namespace at the Head of the PatternCode using Insight.Discovery.InfoClasses; // Include the InfoClasses Namespace at the Head of the PatternCode // Casting the connected Provider out of the parameters from the PerformAction-Method VIMProvider snmp = (SNMPProvider)parameters[1]; // using the VIM-Provider to execute a command and receiving the results var result = (VIMCommandResult)snmp.ExecuteCommand("HostSystem");
Additional Functions
ImportService
アプリの InstallDate など Discovery-Object の Date 属性を設定する場合は、特定の形式 ("MM/dd/yyyy") にする必要があります。
提供される ImportService.ImportDate メソッドを使って変換を実行できます。
using Insight.Discovery.Tools; // Include the Discovery Tools Namespace at the Head of the PatternCode // using the ImportDate Method to transform the Date string of a result Object discoveryObject.InstallDate = ImportService.Instance.ImportDate("resultDateString"); // The following input formats will be transformed: // "MM/dd/yy", "M/dd/yy", "MM/dd/yyyy", "M/dd/yyyy", "MM/dd/yy", "M/d/yy", "MM/d/yyyy", "M/d/yyyy", "yyyyMMdd", "yyMMdd", "dd.MM.yy", "dd.MM.yyyy", "MMM-dd-yy", "MMM-dd-yyyy", "yyyy-MM-dd"
LogService
If you want to write entrys into the Discovery Logfile you can use the delivered LogService Class.
using Insight.Discovery.Tools; // Include the Discovery Tools Namespace at the Head of the PatternCode // creating a "normal" log entry LogService.Instance.LogNormal("My normal log entry"); // creating a "debug" log entry with additional Exception object try { LogService.Instance.LogDebug("a debug log entry"); // Code that could raise an exception } catch (Exception ex) { LogService.Instance.LogError("Log of an exception", ex); }
Custom Pattern examples
例: SNMP 拡張値
SNMP デバイスの情報を拡張することは可能です。
You must know which OID-Number returning the Value that should be discovered. In the processing script the return value of the OID will be mapped to a ExtendedInformation.
次の例は、異なる RAM 情報を検出するために 3 つの OID を送信しています。
<?xml version="1.0" encoding="utf-8"?> <ScanPattern xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <Version>3.0.1</Version> <PatternID>RIADA-Cust-SNMP-1</PatternID> <OrderNr>0</OrderNr> <ProcessType>SNMP_GET</ProcessType> <PatternType>SNMPExtendedValues</PatternType> <Command> <![CDATA[ 1.3.6.1.4.1.2021.4.5.0;1.3.6.1.4.1.2021.4.6.0;1.3.6.1.4.1.2021.4.11.0 ]]> </Command> <Processing> <![CDATA[ using System; using System.Collections.Generic; using Insight.Discovery.InfoClasses.CommandResult.ResultTypes; using Insight.Discovery.Tools; using Insight.Discovery.InfoClasses; using Insight.Discovery.InfoClasses.CommandResult; namespace Insight.Discovery { public class PatternExec { public void PerformAction(object[] parameters) { DeviceInfo deviceInfo = (DeviceInfo)parameters[2]; if (deviceInfo.ExtendedInformations.IsNullOrEmpty()) deviceInfo.ExtendedInformations = new List<ExtendedInformation>(); try { var commandResult = (SNMPExecuteResult)parameters[0]; commandResult.LogResult(); foreach (KeyValuePair<string, object> item in commandResult) { switch (item.Key) { case "1.3.6.1.4.1.2021.4.5.0": // OID to get available RAM if (item.Value != null) { try { long t = 0; long.TryParse(item.Value.ToString().Replace("\n", "").Trim(), out t); if (t > 0) { deviceInfo.ExtendedInformations.Add(new ExtendedInformation() { Name = "RAM Total", Value = (t / 1024).ToString() }); } } catch { // } } break; case "1.3.6.1.4.1.2021.4.6.0": // OID to get used RAM if (item.Value != null) { try { long t = 0; long.TryParse(item.Value.ToString().Replace("\n", "").Trim(), out t); if (t > 0) { deviceInfo.ExtendedInformations.Add(new ExtendedInformation() { Name = "RAM Used", Value = (t / 1024).ToString() }); } } catch { // } } break; case "1.3.6.1.4.1.2021.4.11.0": // OID to get free RAM if (item.Value != null) { try { long t = 0; long.TryParse(item.Value.ToString().Replace("\n", "").Trim(), out t); if (t > 0) { deviceInfo.ExtendedInformations.Add(new ExtendedInformation() { Name = "RAM Free", Value = (t / 1024).ToString() }); } } catch { // } } break; } } } catch (Exception ex) { LogService.Instance.LogDebug("Error getting Extended SNMP RAM Information.", ex); } } } } ]]> </Processing> </ScanPattern>
例: アプリ プロダクト キー
検出されたライセンス情報をアプリに追加することは可能です。たとえば、ライセンス ファイルが存在することがわかっている場合は、このファイルを読み取るパターンを追加できます。
次の例で、パターンは Linux アプリ「apt」のライセンスキーを含むファイル「lic」を読み取っています。
<?xml version="1.0" encoding="utf-8"?> <!-- © Mindville --> <ScanPattern xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <Version>1.0.1</Version> <PatternID>Mindville-Cust-Linux-AppPK-1</PatternID> <OrderNr>0</OrderNr> <ProcessType>SSHExecute</ProcessType> <PatternType>ApplicationProductKey</PatternType> <ApplicationName>apt</ApplicationName> <Command> <![CDATA[ cat /etc/apt/lic ]]> </Command> <Processing> <![CDATA[ using System; using Insight.Discovery.InfoClasses; using Insight.Discovery.Tools; using Insight.Discovery.InfoClasses.CommandResult.ResultTypes; using System.Collections.Generic; namespace Insight.Discovery { public class PatternExec { public void PerformAction(object[] parameters) { HostInfo hostInfo = (HostInfo) parameters[2]; try { SSHExecuteResult sshExecuteResult = (SSHExecuteResult)parameters[0]; sshExecuteResult.LogResult(); string input = sshExecuteResult; if (input != string.Empty) { if(hostInfo.OS.License == null)hostInfo.OS.License = new LicenseInfo(); hostInfo.OS.License.LicenseKey = input.Trim(); } } catch (Exception ex) { LogService.Instance.LogDebug("Error getting apt product key Information", ex); } } } } ]]> </Processing> </ScanPattern>
例: アプリ拡張情報
任意のオブジェクト タイプの情報を拡張できます。
次の例では、ホスト情報をいくつかの拡張情報で拡張します。
<?xml version="1.0" encoding="utf-8"?> <ScanPattern xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <Version>1.0.1</Version> <PatternID>Mindville-Cust-Linux-OpenPorts-1</PatternID> <OrderNr>700</OrderNr> <ProcessType>SSHExecute</ProcessType> <PatternType>Host</PatternType> <Command> <![CDATA[ netstat -an ]]> </Command> <Processing> <![CDATA[ using System; using System.Collections.Generic; using Insight.Discovery.Tools; using Insight.Discovery.InfoClasses; using Insight.Discovery.InfoClasses.CommandResult.ResultTypes; using Insight.Discovery.Tools.Networking; namespace Insight.Discovery { public class PatternExec { public void PerformAction(object[] parameters) { HostInfo hostInfo = (HostInfo)parameters[2]; try { SSHExecuteResult sshExecuteResult = (SSHExecuteResult)parameters[0]; sshExecuteResult.LogResult(); string input = sshExecuteResult; if (input != string.Empty) { if (hostInfo != null) { string[] lines = input.Split('\n'); ExtendedInformation tcpPortInfo = new ExtendedInformation() { Name = "TCP Ports", Value = string.Empty }; ExtendedInformation udpPortInfo = new ExtendedInformation() { Name = "UDP Ports", Value = string.Empty }; for (int i = 0; i < lines.Length; i++) { if (!string.IsNullOrEmpty(lines[i]) && lines[i].Contains(":") && (lines[i].ToLower().StartsWith("tcp") || lines[i].ToLower().StartsWith("udp"))) { string[] parts = lines[i].TrimReduce().Split(' '); try { for (int x = 0; x < parts.Length; x++) { if (parts[x].Contains("]")) { parts[x] = parts[1].Substring(parts[x].IndexOf("]")); } if (parts[0].ToLower().StartsWith("tcp") && !string.IsNullOrEmpty(parts[x]) && parts[x].Contains(":")) { if (!tcpPortInfo.Value.Contains(parts[x].Split(':')[1])) { tcpPortInfo.Value += parts[x].Split(':')[1] + ","; break; } } if (parts[0].ToLower().StartsWith("udp") && !string.IsNullOrEmpty(parts[x]) && parts[x].Contains(":")) { if (!udpPortInfo.Value.Contains(parts[x].Split(':')[1])) { udpPortInfo.Value += parts[x].Split(':')[1] + ","; break; } } } } catch { // } } } if (hostInfo.ExtendedInformations.IsNullOrEmpty()) hostInfo.ExtendedInformations = new List<ExtendedInformation>(); if (!string.IsNullOrEmpty(tcpPortInfo.Value) && tcpPortInfo.Value.EndsWith(",")) { tcpPortInfo.Value = tcpPortInfo.Value.Substring(0, tcpPortInfo.Value.Length - 1); hostInfo.ExtendedInformations.Add(tcpPortInfo); } if (!string.IsNullOrEmpty(udpPortInfo.Value) && udpPortInfo.Value.EndsWith(",")) { udpPortInfo.Value = udpPortInfo.Value.Substring(0, udpPortInfo.Value.Length - 1); hostInfo.ExtendedInformations.Add(udpPortInfo); } } } } catch (Exception ex) { LogService.Instance.LogDebug("Error getting ReferencedHosts Information", ex); } } } } ]]> </Processing> </ScanPattern>
Modifying patterns
It is possible but not recommend to modify delivered Pattern. If there are any missing Information the best practice is to add a new pattern, the missing Information will be merged to the Discovery-Object. If you are modified a delivered Pattern, you should save that Pattern external to pretend the lose of your change by updating the Discovery-Tool.
When you updating the Discovery-Tool with the updater, the updater will ask you before overwriting the modified Pattern.
Removing patterns
You can disable a pattern file in general:
- go to the Pattern Tab and uncheck the unwanted pattern
You can disable a pattern file for a specific scan range
- got to the Scan Setting an select the pattern files that you don't want to use