Library msrpcperformance
This module is designed to parse the PERF_DATA_BLOCK structure, which is
stored in the registry under HKEY_PERFORMANCE_DATA. By querying this structure, you can
get a whole lot of information about what's going on.
To use this from a script, see get_performance_data, it is the only
"public" function in this module.
My primary sources of information were:
- This 1996 journal by Matt Pietrek: <http://www.microsoft.com/msj/archive/S271.aspx>
- The followup article: <http://www.microsoft.com/msj/archive/S2A9.aspx>
- The WinPerf.h header file
And my primary inspiration was PsTools, specifically, pstasklist.exe.
Author:
| Ron Bowes <ron@skullsecurity.net> |
Copyright© Same as Nmap--See http://nmap.org/book/man-legal.html
Source: http://nmap.org/svn/nselib/msrpcperformance.lua
Functions
| get_performance_data (host, objects) |
Retrieve the parsed performance data from the given host for the requested object values. To get a list of possible
object values, leave 'objects' blank and look at |
| parse_perf_counter (data, pos, counter_definition) |
Parse the actual counter value. This is a fairly simple function, it takes a counter definition and pulls out data based on it. |
| parse_perf_counter_block (data, pos) |
Parse a PERF_COUNTER_BLOCK structure. From Microsoft's documentation: |
| parse_perf_counter_definition (data, pos) |
Parse a PERF_COUNTER_DEFINITION structure. From Microsoft's documentation: |
| parse_perf_data_block (data, pos) |
Parses a PERF_DATA_BLOCK, which has the following definition (from "WinPerf.h" on Visual Studio 8): |
| parse_perf_instance_definition (data, pos) |
Parse a PERF_INSTANCE_DEFINITION structure. From Microsoft's documentation: |
| parse_perf_object_type (data, pos) |
Parse a PERF_OBJECT_TYPE structure. From Microsoft's documentation: |
| parse_perf_title_database (data, pos) |
Parses the title database, which is a series of null-terminated string pairs. |
Functions
- get_performance_data (host, objects)
-
Retrieve the parsed performance data from the given host for the requested object values. To get a list of possible object values, leave 'objects' blank and look at
result['title_database']-- it'll contain a list of indexes that can be looked up. These indexes are passed as a string or as a series of space-separated strings (eg, "230" for "Process" and "238" for "Process" and "Processor").Parameters
- host: The host object
- objects: [optional] The space-separated list of object numbers to retrieve. Default: only retrieve the database.
- parse_perf_counter (data, pos, counter_definition)
-
Parse the actual counter value. This is a fairly simple function, it takes a counter definition and pulls out data based on it.
Note: I don't think this is doing the 8-byte values right, I suspect that they're supposed to be doubles.
Parameters
- data: The data being processed.
-
pos:
The position within
data. - counter_definition: The matching counter_definition.
Return value:
(status, pos, result) The status (true if successful), the new position indata(or an error message), and a table representing the datatype, if any. - parse_perf_counter_block (data, pos)
-
Parse a PERF_COUNTER_BLOCK structure. From Microsoft's documentation:
typedef struct _PERF_COUNTER_BLOCK { DWORD ByteLength; // Length in bytes of this structure, // including the following counters } PERF_COUNTER_BLOCK, *PPERF_COUNTER_BLOCK;Parameters
- data: The data being processed.
-
pos:
The position within
data.
Return value:
(status, pos, result) The status (true if successful), the new position indata(or an error message), and a table representing the datatype, if any. - parse_perf_counter_definition (data, pos)
-
Parse a PERF_COUNTER_DEFINITION structure. From Microsoft's documentation:
// There is one of the following for each of the // PERF_OBJECT_TYPE.NumCounters. The Unicode names in this structure MUST // come from a message file. typedef struct _PERF_COUNTER_DEFINITION { DWORD ByteLength; // Length in bytes of this structure DWORD CounterNameTitleIndex; // Index of Counter name into // Title Database #ifdef _WIN64 DWORD CounterNameTitle; #else LPWSTR CounterNameTitle; // Initially NULL, for use by // analysis program to point to // retrieved title string #endif DWORD CounterHelpTitleIndex; // Index of Counter Help into // Title Database #ifdef _WIN64 DWORD CounterHelpTitle; #else LPWSTR CounterHelpTitle; // Initially NULL, for use by // analysis program to point to // retrieved title string #endif LONG DefaultScale; // Power of 10 by which to scale // chart line if vertical axis is 100 // 0 ==> 1, 1 ==> 10, -1 ==>1/10, etc. DWORD DetailLevel; // Counter level of detail (for // controlling display complexity) DWORD CounterType; // Type of counter DWORD CounterSize; // Size of counter in bytes DWORD CounterOffset; // Offset from the start of the // PERF_COUNTER_BLOCK to the first // byte of this counter } PERF_COUNTER_DEFINITION, *PPERF_COUNTER_DEFINITION;Parameters
- data: The data being processed.
-
pos:
The position within
data.
Return value:
(status, pos, result) The status (true if successful), the new position indata(or an error message), and a table representing the datatype, if any. - parse_perf_data_block (data, pos)
-
Parses a PERF_DATA_BLOCK, which has the following definition (from "WinPerf.h" on Visual Studio 8):
typedef struct _PERF_DATA_BLOCK { WCHAR Signature[4]; // Signature: Unicode "PERF" DWORD LittleEndian; // 0 = Big Endian, 1 = Little Endian DWORD Version; // Version of these data structures // starting at 1 DWORD Revision; // Revision of these data structures // starting at 0 for each Version DWORD TotalByteLength; // Total length of data block DWORD HeaderLength; // Length of this structure DWORD NumObjectTypes; // Number of types of objects // being reported LONG DefaultObject; // Object Title Index of default // object to display when data from // this system is retrieved (-1 = // none, but this is not expected to // be used) SYSTEMTIME SystemTime; // Time at the system under // measurement LARGE_INTEGER PerfTime; // Performance counter value // at the system under measurement LARGE_INTEGER PerfFreq; // Performance counter frequency // at the system under measurement LARGE_INTEGER PerfTime100nSec; // Performance counter time in 100 nsec // units at the system under measurement DWORD SystemNameLength; // Length of the system name DWORD SystemNameOffset; // Offset, from beginning of this // structure, to name of system // being measured } PERF_DATA_BLOCK, *PPERF_DATA_BLOCK;Parameters
- data: The data being processed.
-
pos:
The position within
data.
Return value:
(status, pos, result) The status (true if successful), the new position indata(or an error message), and a table representing the datatype, if any. - parse_perf_instance_definition (data, pos)
-
Parse a PERF_INSTANCE_DEFINITION structure. From Microsoft's documentation:
// If (PERF_DATA_BLOCK.NumInstances >= 0) then there will be // PERF_DATA_BLOCK.NumInstances of a (PERF_INSTANCE_DEFINITION // followed by a PERF_COUNTER_BLOCK followed by the counter data fields) // for each instance. // // If (PERF_DATA_BLOCK.NumInstances < 0) then the counter definition // strucutre above will be followed by only a PERF_COUNTER_BLOCK and the // counter data for that COUNTER. typedef struct _PERF_INSTANCE_DEFINITION { DWORD ByteLength; // Length in bytes of this structure, // including the subsequent name DWORD ParentObjectTitleIndex; // Title Index to name of "parent" // object (e.g., if thread, then // process is parent object type); // if logical drive, the physical // drive is parent object type DWORD ParentObjectInstance; // Index to instance of parent object // type which is the parent of this // instance. LONG UniqueID; // A unique ID used instead of // matching the name to identify // this instance, -1 = none DWORD NameOffset; // Offset from beginning of // this struct to the Unicode name // of this instance DWORD NameLength; // Length in bytes of name; 0 = none // this length includes the characters // in the string plus the size of the // terminating NULL char. It does not // include any additional pad bytes to // correct structure alignment } PERF_INSTANCE_DEFINITION, *PPERF_INSTANCE_DEFINITION;Parameters
- data: The data being processed.
-
pos:
The position within
data.
Return value:
(status, pos, result) The status (true if successful), the new position indata(or an error message), and a table representing the datatype, if any. - parse_perf_object_type (data, pos)
-
Parse a PERF_OBJECT_TYPE structure. From Microsoft's documentation:
// // The _PERF_DATA_BLOCK structure is followed by NumObjectTypes of // data sections, one for each type of object measured. Each object // type section begins with a _PERF_OBJECT_TYPE structure. // typedef struct _PERF_OBJECT_TYPE { DWORD TotalByteLength; // Length of this object definition // including this structure, the // counter definitions, and the // instance definitions and the // counter blocks for each instance: // This is the offset from this // structure to the next object, if // any DWORD DefinitionLength; // Length of object definition, // which includes this structure // and the counter definition // structures for this object: this // is the offset of the first // instance or of the counters // for this object if there is // no instance DWORD HeaderLength; // Length of this structure: this // is the offset to the first // counter definition for this // object DWORD ObjectNameTitleIndex; // Index to name in Title Database #ifdef _WIN64 DWORD ObjectNameTitle; // Should use this as an offset #else LPWSTR ObjectNameTitle; // Initially NULL, for use by // analysis program to point to // retrieved title string #endif DWORD ObjectHelpTitleIndex; // Index to Help in Title Database #ifdef _WIN64 DWORD ObjectHelpTitle; // Should use this as an offset #else LPWSTR ObjectHelpTitle; // Initially NULL, for use by // analysis program to point to // retrieved title string #endif DWORD DetailLevel; // Object level of detail (for // controlling display complexity); // will be min of detail levels // for all this object's counters DWORD NumCounters; // Number of counters in each // counter block (one counter // block per instance) LONG DefaultCounter; // Default counter to display when // this object is selected, index // starting at 0 (-1 = none, but // this is not expected to be used) LONG NumInstances; // Number of object instances // for which counters are being // returned from the system under // measurement. If the object defined // will never have any instance data // structures (PERF_INSTANCE_DEFINITION) // then this value should be -1, if the // object can have 0 or more instances, // but has none present, then this // should be 0, otherwise this field // contains the number of instances of // this counter. DWORD CodePage; // 0 if instance strings are in // UNICODE, else the Code Page of // the instance names LARGE_INTEGER PerfTime; // Sample Time in "Object" units // LARGE_INTEGER PerfFreq; // Frequency of "Object" units in // counts per second. } PERF_OBJECT_TYPE, *PPERF_OBJECT_TYPE;Parameters
- data: The data being processed.
-
pos:
The position within
data.
Return value:
(status, pos, result) The status (true if successful), the new position indata(or an error message), and a table representing the datatype, if any. - parse_perf_title_database (data, pos)
-
Parses the title database, which is a series of null-terminated string pairs.
Parameters
- data: The data being processed.
-
pos:
The position within
data.
Return value:
(status, pos, result) The status (true if successful), the new position indata(or an error message), and a table representing the datatype, if any.