Plugins¶
Plugins are the best way to extend the Octopus server with custom functionality. You can write own plugins or to use the existing ones.
Execution of Plugins¶
Plugins are invoked via HTTP POST requests. The body of the request message contains the plugin’s configuration in JSON format. It includes information about how to execute the plugin (required by all plugins) and additional settings for the plugin (dependent on the specific plugin). For example
{
"plugin": <name of the plugin>
"class": <class implementing the IPlugin interface>,
"settings": <JSON object containing plugin specific settings>
}
The configuration file is used by the executeplugin command of the Octopus server, which loads and executes the plugin. The POST request can be issued using curl
cat plugin.json | curl -d @- http://localhost:2480/executeplugin/
where plugin.json contains the configuration.
The Function Export Plugin¶
The function export plugin can be used to export database content at function level. Functions consist of a function node, basic blocks and instruction nodes along with edges between those nodes. It is possible to export functions as a whole or only parts of a function, e.g., the control flow graph.
Configuration¶
The plugins configuration file contains the following data:
{
"plugin": "functionexport.jar",
"class": "bjoern.plugins.functionexporter.FunctionExportPlugin",
"settings": {
"database": <database name>,
"format": "dot"|"graphml"|"gml",
"destination": "<output directory>,
"threads": <number of threads to use>,
"nodes": <JSON array of node types>,
"edges": <JSON array of edge types>
}
}
Note
Edges are only exported if the head and the tail is exported as well.
Example¶
To extract the control flow graphs of all functions of a database named ls you can start with the settings below:
{
"plugin": "functionexport.jar",
"class": "bjoern.plugins.functionexporter.FunctionExportPlugin",
"settings": {
"database": "ls",
"format": "dot",
"destination": "some/path/you/like",
"threads": "4",
"nodes": ["BB"],
"edges": ["CFLOW_ALWAYS", "CFLOW_TRUE", "CFLOW_FALSE"]
}
}
The Instruction Linker Plugin¶
The instruction linker plugin connects the instructions of a function accordingly to the execution order and the flow of control. This is useful to obtain control flow information at the level of instructions as opposed to basic blocks.
Configuration¶
The plugins configuration file contains the following data:
{
"plugin": "instructionlinker.jar",
"class": "bjoern.plugins.instructionlinker.InstructionLinkerPlugin",
"settings": {
"database": <database name>,
}
}
Writing Plugins¶
All plugins must implement the IPlugin interface (octopus.server.components.pluginInterface.IPlugin). The interface specifies the following four methods:
Method | Description |
---|---|
configure | This method is used to configure the plugin. The only argument passed to this method is the JSON object specified by the settings attribute of the configuration file. |
execute | This method contains the main code of the plugin. |
beforeExecution | This method is called before the execution of the plugin. |
afterExecution | This method is called after the execution of the plugin. |
The methods are invoked in the following order: configure, beforeExecution, execute, afterExecution.
Most plugins will require access to some database. The class OrientGraphConnectionPlugin (bjoern.pluginlib.OrientGraphConnectionPlugin) implements the IPlugin interface and opens a connection to a graph database in beforeExecution. The connection is closed in afterExecution. The name of the database is read in configure, the corresponding attribute must be named database. The class OrientGraphConnectionPlugin provides two additional methods to acquire a graph instance: `getGraphInstance and getNoTxGraphInstance for non-transactional graphs and transactional graphs, respectively.
Note
If you override any other method of the IPlugin interface, make sure you don’t forget to call super.