Plugins

A plugin is a piece of code used to help wordpot in processing and analyzing incoming requests.

How it works: a plugin register itself to one or more hooks which are points triggered by incoming requests. When a hook is triggered it puts in execution every plugin attached to it.

Disclaimer

This feature is to be considered in beta. Please report bugs and drop suggestions to the issue page.

Hooks

There are 4 hooks:

1. themes: is the hook wich is triggered when a theme probe is detected
2. plugins: is the hook which is triggered when a plugin probe is detected
3. admin: is the hook which is triggered when a a probe against the wp-admin/ directory is detected
4. commons: is the hook which is triggered whenever there is a request for a page/file in the main Wordpress directory (index.php, readme.html, wp-login.php, etc)

Plugin Structure

A plugin is made of two file (same name, different extensions):

• plugin.py is where the code lives
• plugin.ini is the plugin configuration file

To be installed both of the above files should be placed inside the wordpot/plugins/ directory.

The basic structure of a plugin.py is:

from wordpot.plugins_manager import BasePlugin

class Plugin(BasePlugin):
    def run(self, **kwargs):
        # code here
        return {}

Input arguments

Depending on the hooks linked the run() function receives as input different arguments:

• themes:
• request which contain details about the request
• theme which contain the theme that has been probed
• subpath which contain the path inside the directory of the theme that has been probed
• plugins:
• request which contain details about the request
• plugin which contain the plugin that has been probed
• subpath which contain the path inside the directory of the plugin that has been probed
• admin:
• request which contain details about the request
• subpath which contain the path inside the admin directory that has been probed
• commons:
• request which contain details about the request
• file which contain the name of the file probed
• ext which contain the extension of the file probed

You are free to parse input arguments as you wish, for example:

# Store input arguments
args = {}
for k, v in kwargs.iteritems():
    args[k] = v

Return informations

The main function must always return a dict, even empty. This dict might be used to pass informations back to the hook which will use them to redirect the request to a certain template or to interact with the main logger.

Every hook can understand the followings:

• log which should contain a message to log trough the main logger
• template which should contain the name of a template (e.g. dummy.html) to which we want to redirect the request to
• template_vars a dictionary of vars to be passed to the template

An example code:

# Result dict to return
res = {}
res['template_vars'] = {}

# CODE HERE

res['log'] = 'this plugin is awesome!'
res['template'] = 'dummy.html'
res['template_vars']['var1'] = 'Value var1'
res['template_vars']['var2'] = 'Value var2'

return res

Configuration

The last component of a plugin is its configuration file which contains general informations and a list of hooks to use:

[plugin]
name            = Plugin Name 
author          = John Doe <j@mailinator.com>
link            = http://jdoe.com/my-plugins/
description     = This plugin is useless and ugly
version         = 1.0
hooks           = commons, themes, plugins, admin

Example plugin

This is the plugin actually used to detect timthumb probes.

timthumb.py:

from wordpot.plugins_manager import BasePlugin
import re

TIMTHUMB_RE     = re.compile('[tim]*thumb|uploadify', re.I)

class Plugin(BasePlugin):
    def run(self, **kwargs):
        # Result dict to return
        res = {}
        
        # Store input arguments
        args = {}
        for k, v in kwargs.iteritems():
            args[k] = v

        # Logic
        if TIMTHUMB_RE.search(args['subpath']) is not None:
            # Message to log
            log = '%s probed for timthumb: %s' % (args['request'].remote_addr, args['subpath'])
            res['log'] = log

            # Template to render
            res['template'] = 'timthumb.html'

        return res

timthumb.ini:

[plugin]
name            = Timthumb Detector 
author          = Gianluca Brindisi <g@brindi.si>
link            = http://brindi.si/g/
description     = detects if a request was probing for timthumb
version         = 1.0
hooks           = plugins, themes