3 title: Validator Plugins
5 [DDL]: /mcollective/reference/plugins/ddl.html
8 MCollective provides extensive input data validation to prevent attacks and
9 injections into your agents preventing attack vectors like Shell Injection
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.
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.
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*.
22 Validator plugins and their DDL files goes in the libdir in the *validator*
23 directory on both the servers and the clients.
26 The basic validator plugin that will validate any data against this regular
27 expression can be seen here:
32 class Exim_msgidValidator
33 def self.validate(msgid)
34 Validator.typecheck(msgid, :string)
36 raise "Not a valid Exim Message ID" unless msgid.match(/(?:[+-]\d{4} )?(?:\[\d+\] )?(\w{6}\-\w{6}\-\w{2})/)
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.
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.
50 As with other plugins these plugins need a DDL file, all they support is the
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",
59 :url => "http://devco.net/",
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:
68 action "retrymsg", :description => "Retries a specific message" do
72 :prompt => "Message ID",
73 :description => "Valid message id currently in the mail queue",
75 :validation => :exim_msgid,
80 :description => "Status Message",
81 :display_as => "Status"
85 Note here we are using our new validator to validate the *msgid* input.
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:
93 validate :msgid, :exim_msgid
95 # call out to exim to retry the message
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.
102 ## Listing available Validators
103 You can obtain a list of validators using the *plugin* application:
108 Please specify a plugin. Available plugins are:
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
126 Note our new *exim_msgid* plugin appears in this list.