With version 1.1 ProcDOT introduces a fully fledged plugin engine which has been specifically developed to cover a maximum area of possibilities whilst keeping the development/creation of plugins as simple as possible.
In this respect the plugin developer is free to choose if she wants to base her plugin on
This already tremendous freedom can be achieved by the use of a pretty uncommon way of providing arguments and receiving results:
Besides this ProcDOT's plugin engine generally supports multiple types of plugins:
At startup ProcDOT scans the (relative) subdirectory "plugins" for available plugins. Each plugins' config will then be verified if it matches the OS, the architecture, if the actual plugin file is available, and the plugin type specifics are consistent. I any of these checks fails the plugin will be automatically deactivated for the current run.
A ProcDOT plugin always consists of two parts:
The plugin descriptor file is used to tell ProcDOT all the details about how to handle the actual plugin file. This is especially necessary as ProcDOT supports multiple platforms as well as to give the plugin developer more flexibility in her decision which techniques to use.
Furthermore the plugin descriptor file must have the extension ".pdp" which stands for ProcDOT Plugin. Though being the perfect abbreviation I decided to not use ".pdf" as extension - the reason should be kind of obvious. ;-)
A plugin descriptor file is a simple INI file (preference file).
Here is an example of a typical plugin descriptor file:
Name = Test Plugin
Author = chrisu
Version = 1.0
Type = ContextMenuItemForGraph
Architecture = Windows32BitExe
File = test.exe
Priority = 9
RunHidden = 0
RunExclusively = 1
CanOverrideOtherPlugins = 0
CanOverrideProcDot = 0
The following table explains any of the supported keynames and how they should be used:
| Keyname | Description | Possible values | Supported plugin types |
| Name | Specifies the name of the plugin. | [Ascii] | all |
| Author | Specifies the name of the author. | [Ascii] | all |
| Description | Specifies a description for the plugin. | [Ascii] | all |
| Version | Specifies the version of the plugin. | [Ascii] | all |
| Type |
Specifies the type of the plugin. Currently 3 types are supported: |
ContextMenuItemForGraph |
all |
| Architecture | Specifies the architecture the plugin was developed for. | Linux32BitExe Linux32BitSo Linux64BitExe Linux64BitSo LinuxShellScript Windows32BitDll Windows32BitExe Windows64BitDll Windows64BitExe WindowsBatchScript |
all |
| File | Specifies the file to be used as the actual plugin. | [Filename] | all |
| Priority | Specifies the position of the actual plugin in case of multiple matching plugins from 1 to 9 with 1 being the highest priority and 9 being the lowest. | 1 - 9 | all |
| RunHidden | Tells ProcDOT to run the actual plugin hidden hennce preventing any windows from popping up. (1 = True, 0 = False) | 1 / 0 | all |
| RunExclusively | Tells ProcDOT to not run any other non-exclusive plugin in parallel to this one. (1 = True, 0 = False) | 1 / 0 | all |
| CanOverrideOtherPlugins | Specifies that if the actual plugin exits with a return code of 1 any other plugin being in the queue waiting to run will be skipped. (1 = True, 0 = False) | 1 / 0 | all |
| CanOverrideProcDot | Specifies that if the actual plugin exits with a return code of 1 any following builtin functionality of ProcDOT will be skipped. (1 = True, 0 = False) | 1 / 0 | all |
| CanBeVerified |
Specifies that this plugin can also be called in verification mode (Environmentvariable PROCDOTPLUGIN_VerificationRun) to decide if it's able to handle the hovered node or situation. (1 = True, 0 = False) |
1 / 0 | all |
|
Event or Events |
Specifies the event (or events seperated with colons) for which the actual plugin shall be registered for as an event handler. | BeforeLeftClickOnGraph BeforeLeftDblClickOnGraph BeforeMiddleClickOnGraph BeforeMiddleDblClickOnGraph BeforeRightClickOnGraph BeforeRightDblClickOnGraph AfterLeftClickOnGraph AfterLeftDblClickOnGraph AfterMiddleClickOnGraph AfterMiddleDblClickOnGraph AfterRightClickOnGraph AfterRightDblClickOnGraph BeforeRefresh AfterRefresh BeforeProcmonButtonClick AfterProcmonButtonClick BeforeWindumpButtonClick AfterWindumpButtonClick BeforeLauncherButtonClick AfterLauncherButtonClick BeforeSwitchToFrameMode AfterSwitchToFrameMode BeforeSwitchToNormalMode AfterSwitchToNormalMode BeforeTimelineFirstFrame AfterTimelineFirstFrame BeforeTimelinePreviousFrame AfterTimelinePreviousFrame BeforeTimelineNextFrame AfterTimelineNextFrame BeforeTimelineLastFrame AfterTimelineLastFrame BeforeTimelinePlayAnimation AfterTimelinePlayAnimation BeforeTimelineStopAnimation AfterTimelineStopAnimation |
EventHandler |
First of all the effective/actual plugin file has to match the architecture configured in the corresponding plugin descriptor file. If not, it will get automatically deactivated during the verification step on startup of ProcDOT.
As already mentioned any plugin receives necessary informations and data from ProcDOT via environment variables. The following table explains all of the currently available environment variables:
| Variable (with heading "PROCDOTPLUGIN_") | Description | Example value(s) | Supported plugin types |
| AnimationMode | Indicates if ProcDOT's currently in animation mode. | 1 | all |
| AnimationMode_CurrentFrame | Provides the current frame number if in animation mode. | 45 | all |
| AnimationMode_CurrentFrame_StatusMessage | Provides the current frames status message as shown in the GUI. | Process "IEXPLORE.EXE" (PID: 768) receives a HTTP response from "members.a1.net" (80.75.46.215) | all |
| AnimationMode_CurrentFrame_Timestamp | Provides the current frames timestamp as a progressive double. | 1.5056724 | all |
| AnimationMode_CurrentFrame_TimestampOriginalString | Provides the current frames original timestamp. | 23:05:04,6506963 | all |
| AnimationMode_CurrentFrame_TimestampString | Provides the current frames timestamp as it's shown in the GUI. | 00:00:01,5056724 23:05:04,6506963 |
all |
| Architecture | Value of plugin descriptor file. | Windows32BitExe | all |
| Author | Value of plugin descriptor file. | chrisu | all |
| CurrentNode_color | Line color of the node. | black | ContextMenuItemForGraph EventHandler |
| CurrentNode_Details_CommandLine | Commandline of the process if the node is a process. | "C:\WINDOWS\system32\rundll32.exe" Shell32.dll,Control_RunDLL C:\DOKUME~1\winxp\LOKALE~1\Temp\wPwRz3y.exe | ContextMenuItemForGraph EventHandler |
| CurrentNode_Details_Domain | Domain name of the server if the node is a server. | suppototalreg.biz | ContextMenuItemForGraph EventHandler |
| CurrentNode_Details_FirstCreateTime | Timestamp of the first monitored create of the file if the node is a file. | 11:30:27,7797512 | ContextMenuItemForGraph EventHandler |
| CurrentNode_Details_FirstDeleteTime | Timestamp of the first monitored delete of the file if the node is a file. | 11:30:27,7797512 | ContextMenuItemForGraph EventHandler |
| CurrentNode_Details_FirstReadTime | Timestamp of the first monitored read from the file/registry key if the node is a file/registry key. | 11:30:27,7797512 | ContextMenuItemForGraph EventHandler |
| CurrentNode_Details_FirstWriteTime | Timestamp of the first monitored write to the file/registry key if the node is a file/registry key. | 11:30:27,7797512 | ContextMenuItemForGraph EventHandler |
| CurrentNode_Details_FullPath | Fully qualified path of the file/registry-value/process if the node is a file/registry-value/process. | C:\Dokumente und Einstellungen\winxp\Lokale Einstellungen\Temp\383000.dat | ContextMenuItemForGraph EventHandler |
| CurrentNode_Details_IP-Address | Ip address of the server if the node is a server. | 185.6.80.51 | ContextMenuItemForGraph EventHandler |
| CurrentNode_Details_LastCreateTime | Timestamp of the last monitored create of the file if the node is a file. | 11:30:27,7797512 | ContextMenuItemForGraph EventHandler |
| CurrentNode_Details_LastDeleteTime | Timestamp of the last monitored delete of the file if the node is a file. | 11:30:27,7797512 | ContextMenuItemForGraph EventHandler |
| CurrentNode_Details_LastReadTime | Timestamp of the last monitored read from the file/registry key if the node is a file/registry key. | 11:30:27,7797512 | ContextMenuItemForGraph EventHandler |
| CurrentNode_Details_LastWriteTime | Timestamp of the last monitored write to the file/registry key if the node is a file/registry key. | 11:30:27,7797512 | ContextMenuItemForGraph EventHandler |
| CurrentNode_Details_Main | States that the underlying thread is the main thread of its process if the node is a thread. | Yes | ContextMenuItemForGraph EventHandler |
| CurrentNode_Details_Name | Pathless name of the file/registry-value/process if the node is a file/registry-value/process. |
GoogleUpdate.exe |
ContextMenuItemForGraph EventHandler |
| CurrentNode_Details_OnlyInPCAP | States that the underlying server did not leave any tracks in the Process Monitor logs if the node is a server. | No | ContextMenuItemForGraph EventHandler |
| CurrentNode_Details_ParentPID | Process ID (PID) of the process that created the underlying process/thread if the node is a process/thread. | 2136-n8 | ContextMenuItemForGraph EventHandler |
| CurrentNode_Details_ParentTID | Thread ID (TID) of the thread that created the underlying process/thread if the node is a process/thread. | 2140 | ContextMenuItemForGraph EventHandler |
|
CurrentNode_Details_Path |
Path (without the name of the actual entry) of the file/registry-value/process if the node is a file/registry-value/process. | C:\Dokumente und Einstellungen\winxp\Lokale Einstellungen\Temp\ HKCU\Software\Microsoft\Windows\CurrentVersion\Explorer\Shell Folders\ C:\WINDOWS\system32\ |
ContextMenuItemForGraph EventHandler |
| CurrentNode_Details_PID | Process ID (PID) of the process if the node is a process | 2156-n9 | ContextMenuItemForGraph EventHandler |
| CurrentNode_Details_Relevant | States that the underlying item (node) was (automatically) designated as relevant. | Yes | ContextMenuItemForGraph EventHandler |
| CurrentNode_Details_RelevantBecauseOfProcmonLines | Lists the line number(s) of the Process Monitor event(s) that made the underlying item (node) relevant. | 122119 | ContextMenuItemForGraph EventHandler |
| CurrentNode_Details_StartTime | Start time of the process/thread if the node is a process/thread. | 11:30:19,9147767 | ContextMenuItemForGraph EventHandler |
| CurrentNode_Details_StopTime | Stop time of the process/thread if the node is a process/thread. | 11:30:20,1441645 | ContextMenuItemForGraph EventHandler |
| CurrentNode_Details_Threads | Number of detected (in terms of Process Monitor events) threads belonging to the underlying process if the node is a process. Threads designated as being relevant are summed up in the brackets. | 2 (1 relevant) | ContextMenuItemForGraph EventHandler |
| CurrentNode_Details_TID | The thread ID (TID) of the thread if the node is a thread. | 2160 | ContextMenuItemForGraph EventHandler |
| CurrentNode_fillcolor | Background color of the node. | black | ContextMenuItemForGraph EventHandler |
| CurrentNode_height | 0.5 | ContextMenuItemForGraph EventHandler | |
| CurrentNode_label | Label (caption) of the node. | 2160 GoogleUpdate.exe [6]\nrundll32.exe\n(PID: 2156) [4]\nsuppototalreg.biz\n185.6.80.51 |
ContextMenuItemForGraph EventHandler |
| CurrentNode_name | ProcDOT internal node ID. Can be used to determine the type/meaning of the node. |
FILE:C:\\WINDOWS\\system32\\abcd.exe |
ContextMenuItemForGraph EventHandler |
| CurrentNode_shape | Geometrical shape of the node. | box | ContextMenuItemForGraph EventHandler |
| CurrentNode_style | Style of the node. | filled | ContextMenuItemForGraph EventHandler |
| CurrentNode_width | 1.1234 | ContextMenuItemForGraph EventHandler | |
| CurrentNode_x | 21.208 | ContextMenuItemForGraph EventHandler | |
| CurrentNode_y | 24.25 | ContextMenuItemForGraph EventHandler | |
| Event | Value of plugin descriptor file. | BeforeMiddleClickOnGraph | EventHandler |
| GraphFileDetails | Detail informations for each node. | C:\Users\chrisu\AppData\Local\Temp\procdot.dot.procdot | all |
| GraphFileDot | The DOT file generated by the second executable of ProcDOT called "procmon2dot". | C:\Users\chrisu\AppData\Local\Temp\procdot.dot | all |
| GraphFilePng (DEPRECATED with plugin engine V1.1) | The graph image in PNG format generated by Graphviz' "dot" binary. | C:\Users\chrisu\AppData\Local\Temp\procdot.png | all |
| GraphFileTxt | The graph layout in TXT format generated by Graphviz' "dot" binary. | C:\Users\chrisu\AppData\Local\Temp\procdot.txt | all |
| Name | Value of plugin descriptor file. | Test Plugin | all |
| Path2DotExecutable | Path to dot-executable as set in ProcDOT's options. | C:\Program Files (x86)\Graphviz\bin\dot.exe dot |
all |
| Path2WindumpExecutable | Path to windump/tcpdump-executable as set in ProcDOT's options. |
C:\Users\chrisu\GlobalTools\WinDump.exe |
all |
| PluginEngineVersion | The version of the pluginengine currently in use. | 1.0 | all |
| PluginsPath | Full qualified path to plugins folder. | C:\Users\me\Documents\procdot\trunk\plugins\ | all |
| ProcmonFile | The content of the according text box. | C:\Users\chrisu\Downloads\procmon-aggressive.csv C:\Users\chrisu\Downloads\procmon-aggressive.pml |
all |
| ProcmonFileCsv | The content of the according text box if the extension is ".CSV". | C:\Users\chrisu\Downloads\procmon-aggressive.csv | all |
| ProcmonFilePml | The content of the according text box if the extension is ".PML". | C:\Users\chrisu\Downloads\procmon-aggressive.pml | all |
| ResultXML | Full qualified path of the plugin result file based on XML format interpreted by ProcDOT. | C:\Users\chrisu\AppData\Local\Temp\PBTEMP.11200.19969.tmp | all |
| ResultTXT | Full qualified path of the plugin result file based on TXT format interpreted by ProcDOT. | C:\Users\chrisu\AppData\Local\Temp\PBTEMP.11200.19970.tmp | all |
| ResultCSV | Full qualified path of the plugin result file based on CSV format interpreted by ProcDOT. | C:\Users\chrisu\AppData\Local\Temp\PBTEMP.11200.19971.tmp | all |
| ResultIMG | Full qualified path of the plugin result file based on PNG, JPEG, or BMP interpreted by ProcDOT. | C:\Users\chrisu\AppData\Local\Temp\PBTEMP.11200.19972.tmp | all |
| SessionFile | Full qualified path of the session file (.pd). | C:\Users\chrisu\.procdot\test.pd | all |
| SessionSavePending | A flag telling if the session has been modified and is waiting for saving. |
1 |
all |
| Type | Value of plugin descriptor file. | ContextMenuItemForGraph EventHandler MainMenuItem |
all |
| Version | Value of plugin descriptor file. | 1.0 | all |
| VerificationRun | Exists and has the value "1" if the current run is (only) for verification purposes. | 1 | all |
| WindumpFile | The content of the according text box. | C:\Users\chrisu\Downloads\windump-aggressive.pcap C:\Users\chrisu\Downloads\windump-aggressive.txt |
all |
| WindumpFilePcap | The content of the according text box if the extension is ".PCAP". | C:\Users\chrisu\Downloads\windump-aggressive.pcap | all |
| WindumpFileTxt | The content of the according text box if the extension is ".TXT". | C:\Users\chrisu\Downloads\windump-aggressive.txt | all |
A plugin can always return an exit code. Especially, exit codes are used in the context of the already mentioned CanOverride attributes.
Return codes:
Besides that a plugin dealing with a table of data can take advantage of ProcDOT's builtin data-table handling capabilities.
This specifically applies to ...
So if you like to do so all your plugin needs to do is to write its output data to one of the result files specified by the environment variable "PROCDOTPLUGIN_Result...". The last part of the name of the variable stands for the format the file is supposed to take. After plugin execution ends ProcDOT will check all of these result files for existence to furthermore call the apropriate output handler.
In this respect ProcDOT is currently aware of 4 formats/types:
Here's an exemplary template of how list-oriented output data is supposedto like in XML format:
<procdot-plugin-output>
<list title="test1" message="test2" submitmessage="test3" statestorename="test4">
<head>
<column width="150">Key</column>
<column width="*">Value</column>
</head>
<body>
<row style="color:red;background-color:yellow">
<column>Key1</column>
<column style="color:red">Value1</column>
</row>
<row>
<column>Key2</column>
<column style="color:green">Value2</column>
</row>
<row>
<column>Key3</column>
<column style="color:blue">Value3</column>
</row>
</body>
</list>
</procdot-plugin-output>
As for the style definitions the following attributes are supported:
In this respect the following color values are currently supported:
If you prefer the CSV format to the XML format for list-oriented output data then here's what your result needs to look like to achieve nearly the same result (just without styling) as the above example:
"Key","Value"
"150","*"
"Key1","Value1"
"Key2","Value2"
"Key3","Value3"
And if you also like to use styling to achieve the identical result like the XML example this is what it needs:
"Key","Value"
"150","*"
{{color:red;background-color:yellow}}"Key1","{color:red}Value1"
"Key2","{color:green}Value2"
"Key3","{color:blue}Value3"
Free form text (TXT) without any styling will be displayed as is. However, if you need the text being styled (colors) in any way here's what it's supposed to look like:
{{{style-id:default;color:black;style-id:one;color:red;style-id:two;color:white;background-color:black}}}This is some free form text!
This line <one>contains</one> some styling.
Here's another line with <two>styling</two>.
No more styling here!
As you can see the style-definition - the stylesheet - must be provided at the beginning (actually with the first character!).
Styles are defined sequentially with each style-id attribute starting a new style definition followed by the actual attributes (like the ones already introduced with the XML template).
The very first style is supposed to be the default style definition which is used for any not specifically styled text.
To use your defined styles you only have to embed the according text into <styledefinitionname>...</styledefinitionname> just like in the example.
Please note that use of styles cannot be nested!
As for image-oriented (IMG) output data you just have to store your image (as you would normally do) in the result file PROCDOTPLUGIN_ResultIMG.