Skip to content

Smart Policies

Jump to bottom
Adán Sánchez de Pedro Crespo edited this page Aug 2, 2016 · 16 revisions

Smart Policies

Smart Policies are scripts that receive notifications every time a watched file changes. Policies trigger actions such as emailing someone, reverting changes or shutting the system down.

Currently you can write policies in Javascript, CoffeeScript or IcedCoffeeScript.

Policies are Node.js packages downloaded from public git repositories. Anyone can take any available policy, fork it and improve it.

Policies are parameterizable. Each policy package can define customizable "fields" to suit different monitoring needs.

When the watcher starts, it runs every policy inside a sandboxed virtual machine. Such virtual machines run in the background, waiting the watched files to change.

Every time a watched file gets modified, the watcher generates a diff. Such diff is then sent to every one of the modified file's policies.

Ready-to-use policies

  • Mailer: sends an email with the diff between previous version of a file and current one.
  • Backup: backs up a file to a different location every time it gets modified.
  • Rollbacker: rolls modified files back to the previous version.
  • Shutdown: shuts the whole system down.
  • Stamper: embeds your files into the blockchain.
  • Zapier (coming soon): connects your file events to a whole world of apps.

Writing your own policies

Policy package structure

  • main.js / main.coffee / main.iced: Main entry point for the policy script.
  • package.json: Package manifest.
  • LICENSE: (optional)
  • README.md: (optional)

package.json example

{
  "name": "mailer-policy",
  "version": "0.0.1",
  "dependencies": {
    "email": "0.2.6"
  },
  "policy": {
    "language": "coffeescript",
    "params": {
      "from": {
        "type": "email",
        "label": "Sender address",
        "required": true,
        "tip": "The address to show as sender of the email."
      },
      "to": {
        "type": "email",
        "required": true,
        "tip": "The email will be sent to this address."
      },
      "format": {
        "type": "select",
        "label": "Format",
        "options": {     
          "plain": {
            "label": "Plain text"
          },
          "html": {
            "label": "HTML"
          }
        },
        "default": "plain"
      }
    },
    "defaultName": "Email notifications"
  }
}

The policy object is compulsory and must contain the language attribute. Possible values are javascript, coffeescript or icedcoffeescript.

The policy.params defines variables that you can customize when you attach the policy to a watched file. Their values are passed to the policy script's constructor.

The possible attributes under policy.params are:

Attribute Description Required
type Type of field to be shown when configuring this parameter. ✅
label Label (show description) to be shown before this field. ✅
tip Long description or advise on how to fill this field. ❌
default Default value for this attribute. ❌
required Whether this field is compulsory or not. ❌
options (Only if type is select) Object with available options and corresponding labels. E.g.:{ "opt1" : { "label": "First option" }, "opt2" : { "label": "Second option" } } ❌

Parameters field types

The allowed values for type are: text, checkbox, color, date, datetime, datetime-local, email, month, number, password, range, tel, time, url, week and select.

Policy script example

You can name your main class as you prefer as long as you export it by assigning it to module.exports.

Email = require('email').Email

module.exports = class Policy
  constructor : (params) ->
    @file = params.filename
    @from = params.from
    @to = params.to

  receiver : (changes, metadata) =>
    msg = new Email
      from: @from
      to: @to
      subject: """File "#{@file}" has been modified"""
      body: """File "#{@file}" has been modified.
        The changes are:
        #{JSON.stringify changes}
        """
    msg.send()

Receiver payload

The receiver method takes two arguments: changes and metadata.

changes argument

The changes argument receives an Array of different objects representing the diff between previous and current version of the modified file.

Changes example: (This depicts Alice trying to hide a root session and pretend to be Bob)

[
   {
      "type":"ellipsis",
      "size":439
   },
   {
      "type":"fill",
      "start":440,
      "lines":[
         "Jul 14 18:25:10 server: someone : TTY=pts/14 ; PWD=/home/alice ; USER=alice",
         "Jul 14 18:25:10 server: pam_unix: session opened for user alice by (uid=0)"
      ]
   },
   {
      "type":"rem",
      "start":442,
      "lines":[
         "Jul 14 18:25:10 server su[6249]: + /dev/pts/14 root:root",
         "Jul 14 18:25:10 server su[6249]: pam_unix(su:session): session opened for user root by (uid=0)",
      ]
   },
   {
      "type":"add",
      "start":444,
      "lines":[
         "Jul 14 18:25:10 server su[6249]: + /dev/pts/14 bob:bob",
         "Jul 14 18:25:10 server su[6249]: pam_unix(su:session): session opened for user bob by (uid=0)",
      ]
   }
]

Possible values for the type attribute are:

Value Description
ellipsis Represent a certain number of omitted lines which are irrelevant to the diff.
fill Contain a few lines surrounding the changes for helping to contextualize them.
add Contain added lines
rem Contain removed lines
metadata argument

The metadata argument receives an object containing the following keys and values:

Key Description
prev Previous content of the modified file.
cur Current content of the modified file.
Clone this wiki locally