website/reference/plugins/validator.md

   1 ---
   2 layout: default
   3 title: Validator Plugins
   4 ---
   5 [DDL]: /mcollective/reference/plugins/ddl.html
   6
   7 ## Overview
   8 MCollective provides extensive input data validation to prevent attacks and
   9 injections into your agents preventing attack vectors like Shell Injection
  10 Attacks.
  11
  12 Traditionally we shipped a number of pre-made validator plugins that could be
  13 used in agents and DDL files but you were not capable fo adding your own easily.
  14
  15 As of version 2.2.0 you can write new Validator plugins that allow you to extend
  16 the DDL and Agent validation methods.
  17
  18 ## Writing A New Validator
  19 We'll write a new validator plugin that can validate a string matches valid Exim
  20 message IDs like *1Svk5S-0001AW-I5*.
  21
  22 Validator plugins and their DDL files goes in the libdir in the *validator*
  23 directory on both the servers and the clients.
  24
  25 ### The Ruby Plugin
  26 The basic validator plugin that will validate any data against this regular
  27 expression can be seen here:
  28
  29 {% highlight ruby %}
  30 module MCollective
  31   module Validator
  32     class Exim_msgidValidator
  33       def self.validate(msgid)
  34         Validator.typecheck(msgid, :string)
  35
  36         raise "Not a valid Exim Message ID" unless msgid.match(/(?:[+-]\d{4} )?(?:\[\d+\] )?(\w{6}\-\w{6}\-\w{2})/)
  37       end
  38     end
  39   end
  40 end
  41 {% endhighlight %}
  42
  43 All you need to do is provide a *self.validate* method that takes 1 argument and
  44 do whatever validation you want to do against the input data.
  45
  46 Here we first confirm it is a string and then we do the regular expression match
  47 against that.  Any Exception that gets raised will result in validation failing.
  48
  49 ### The DDL
  50 As with other plugins these plugins need a DDL file, all they support is the
  51 metadata section.
  52
  53 {% highlight ruby %}
  54 metadata    :name        => "Exim Message ID",
  55             :description => "Validates that a string is a Exim Message ID",
  56             :author      => "R.I.Pienaar <rip@devco.net>",
  57             :license     => "ASL 2.0",
  58             :version     => "1.0",
  59             :url         => "http://devco.net/",
  60             :timeout     => 1
  61 {% endhighlight %}
  62
  63 ## Using the Validator in a DDL
  64 You can use the validator in any DDL file, here is a snippet matching an input
  65 using the new *exim_msgid* validator:
  66
  67 {% highlight ruby %}
  68 action "retrymsg", :description => "Retries a specific message" do
  69     display :ok
  70
  71     input :msgid,
  72           :prompt      => "Message ID",
  73           :description => "Valid message id currently in the mail queue",
  74           :type        => :string,
  75           :validation  => :exim_msgid,
  76           :optional    => false,
  77           :maxlength   => 16
  78
  79     output :status,
  80            :description => "Status Message",
  81            :display_as  => "Status"
  82 end
  83 {% endhighlight %}
  84
  85 Note here we are using our new validator to validate the *msgid* input.
  86
  87 ## Using the Validator in an Agent
  88 Agents can also have validation, traditionally this included the normal things
  89 like regular expressions but now here you can also use the validator plugins:
  90
  91 {% highlight ruby %}
  92 action "retrymsg" do
  93   validate :msgid, :exim_msgid
  94
  95   # call out to exim to retry the message
  96 end
  97 {% endhighlight %}
  98
  99 Here we've extended the basic *validate* helper of the RPC Agent with our own
 100 plugin and used it to validate a specific input.
 101
 102 ## Listing available Validators
 103 You can obtain a list of validators using the *plugin* application:
 104
 105 {% highlight ruby %}
 106 % mco plugin doc
 107
 108 Please specify a plugin. Available plugins are:
 109
 110 .
 111 .
 112 .
 113
 114 Validator Plugins:
 115   array                     Validates that a value is included in a list
 116   exim_msgid                Validates that a string is a Exim Message ID
 117   ipv4address               Validates that a value is an ipv4 address
 118   ipv6address               Validates that a value is an ipv6 address
 119   length                    Validates that the length of a string is less or equal to a specified value
 120   regex                     Validates that a string matches a supplied regular expression
 121   shellsafe                 Validates that a string is shellsafe
 122   typecheck                 Validates that a value is of a certain type
 123
 124 {% endhighlight %}
 125
 126 Note our new *exim_msgid* plugin appears in this list.
 127