v0.1.7: Added the cloudflare_threat_control LWRP

Based off an initial work by Adrien Siebert (https://github.com/asiebert)

This LWRP allows to manage Cloudflare's threat control services

Also adapted the Vagrantfile to make it possible to use Chef-Zero instead of solo.
However, I'll need to switch to Test-KItchen pretty soon as the vagrant-chef-zero
plugin is going to be deprecated pretty soon.

Author: wk8

.gitignore

@@ -1 +1,4 @@
 /.vagrant
+/.bundle
+/vendor
+/.zero-knife.rb

Berksfile.lock

@@ -4,4 +4,4 @@ DEPENDENCIES
     metadata: true
 
 GRAPH
-  cloudflare (0.1.6)
+  cloudflare (0.1.7)

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 This file is used to list changes made in each version of cloudflare.
 
+## 0.1.7:
+
+* Added the `threat_control` LWRP allowing to whitelist or blacklist IPs on CloudFlare (see https://support.cloudflare.com/hc/en-us/articles/200171266-How-do-I-block-or-trust-visitors-in-Threat-Control-)
+
 ## 0.1.6:
 
 * Added the `shared_A_record` attribute to the LWRP to make it possible to have several A records with the same name (aka DNS load balancing)

README.md

@@ -1,7 +1,7 @@
 Description
 ===========
 
-This Chef! cookbook defines one LWRP that you can easily use in your own cookbook to create and delete Cloudflare DNS records.
+This Chef! cookbook defines one LWRP that you can easily use in your own cookbook to create and delete Cloudflare DNS records and manage your threat control services.
 
 It is built on top of B4k3r's Ruby wrapper for the Cloudflare API. (https://github.com/B4k3r/cloudflare)
 
@@ -27,6 +27,8 @@ There also are a number of optional node attributes:
 
 Those attributes come in especially handy if you have a number of servers and get throttled by Cloudflare's API limits.
 
+A couple of threat-control-related attributes are explained in the "`threat_control` Resource" section below.
+
 Usage
 =====
 
@@ -64,10 +66,43 @@ Another example:
 
 would delete the `server_name.example.com` record from your Cloudflare account.
 
+`threat_control` Resource
+-------------------------
+CloudFlare's threat control can be used to whitelist or blacklist IPs hitting your domains going through their network.
+cf. [CloudFlare FAQ - How do I block or trust visitors in Threat Control?](https://support.cloudflare.com/hc/en-us/articles/200171266-How-do-I-block-or-trust-visitors-in-Threat-Control-)
+
+Attribute:
+
+* `ip` (optional): the IP you want to white/blacklist (defaults to `node.ipaddress`)
+
+Actions: `:whitelist`, `:blacklist`, `:remove_ip`
+Should be self-explanatory, the latter one being used to remove a white/blacklisted IP from their respective list.
+Note that the default action is `:nothing`!
+
+Examples:
+
+    cloudflare_threat_control 'whitelist_current_server' do
+      action :whitelist
+    end
+
+    cloudflare_threat_control 'shall_we_trust_this?' do
+      ip '208.73.210.203'
+      action :blacklist
+    end
+
+A word on how this LWRP works: we don't want to have Chef hit Cloudflare's API every time it runs, for Cloudflare's API usage thresholds are pretty low. The thing is, unlike DNS records (for which we can query a DNS server instead of the API), there's no way to double-check the current status without making API calls.
+To get around this, this LWRP caches the current status (and trusts that the cached information is valid) for a while, which is reasonable if your Chef recipe is the only way this should ever be modified in your setup. The cache's validity is controlled by the `['cloudflare']['threat_control']['cache_duration']` node attribute, which defaults to 1 day. Note this attribute expects this duration in days, but does accept floats (so you can set it to `1.0 / 24.0` to reduce it to one hour).
+
+If you happen to have few enough servers that you don't care about Cloudflare's API usage thresholds, or if you really want your recipe to make calls to the API at every run, you can set the `['cloudflare']['threat_control']['disable_cache']` node attribute to `true` (defaults to `false`).
+
+A caveat worth noting with this resource is that [Cloudflare's API](https://www.cloudflare.com/docs/client-api.html) as of today (08/18/14) offers no way to check the current status of a given IP w.r.t threat control settings, nor does it give any information when making a call to set an IP's status regarding its previous status. As a result, _this resource will be marked as updated whenever an API call is made, even if the status wasn't actually changed_.
+
+Note that you can't use the cache with Chef solo, as there's nowhere to save the information to. [Chef-zero](https://github.com/opscode/chef-zero) will do nicely though if you don't have a Chef server around.
+
 Example recipe
 ==============
 
-You can have a look at the `cloudflare::example` recipe for examples on how to use the LWRPs.
+You can have a look at the `cloudflare::example` recipe for examples on how to use the DNS-related LWRPs.
 
 You can also test my cookbook with Vagrant (see the 'Vagrant' section below).
 
@@ -85,10 +120,14 @@ You also need to define 3 environment variables to be able to use my Vagrantfile
 You can do so by typing e.g. `export CLOUDFLARE_EMAIL='[email protected]'` and so on in your shell.
 
 Be aware that the example recipe will then proceed to create a few DNS records on that DNS zone with your credentials, so use with caution! That being said, all said records will start with 'cl-cb-test-' so they have little chance of clonflicting with exisiting records on your account.
+Also, it does white-black list a couple of private IP addresses.
 
 You can also easily clean up the test records created that way by running `CLOUDFLARE_CLEANUP=1 vagrant provision`.
 
-Then playing with this cookbook should be as easy as running `bundle install && vagrant up`!
+Then playing with this cookbook should be as easy as running `bundle install --path vendor/bundle && vagrant up`!
+
+Note that if you want to test/do stuff on the caching mechanism for the threat control LWRP, you'll need to use Chef-zero. For now this project uses the [Vagrant-Chef-Zero](https://github.com/andrewgross/vagrant-chef-zero) plugin, but we'll soon migrate to Test Kitchen.
+To use the Chef-Zero plugin, simply install it, the Vagrantfile will pick it up automatically.
 
 Contributing & Feedback
 =======================
@@ -99,6 +138,9 @@ Feel free to reach me at <[email protected]>
 Changes
 =======
 
+* 0.1.7 (Aug 18, 2014)
+    * Added the `threat_control` LWRP allowing to whitelist or blacklist IPs on CloudFlare (see https://support.cloudflare.com/hc/en-us/articles/200171266-How-do-I-block-or-trust-visitors-in-Threat-Control-)
+
 * 0.1.6 (Jul 9, 2014)
     * Added the `shared_A_record` attribute to the LWRP to make it possible to have several A records with the same name (aka DNS load balancing)
     * Properly updating LWRP states when an action has been performed
@@ -124,3 +166,8 @@ Changes
 
 * 0.1.0 (Oct 3, 2013)
     * Initial release
+
+Contributors
+============
+
+* [Adrien Siebert](https://github.com/asiebert)

Vagrantfile

@@ -21,13 +21,26 @@ Vagrant.configure(VAGRANTFILE_API_VERSION) do |config|
 
   config.berkshelf.enabled = true
 
-  config.vm.provision :chef_solo do |chef|
+  # we use chef-zero instead of solo if the plugin is available
+  # that makes it easy to test the caching mechanism for the
+  # threat_control resource
+  if Vagrant.has_plugin? 'vagrant-chef-zero'
+    provisioner = :chef_client
+  else
+    provisioner = :chef_solo
+  end
+
+  config.vm.provision provisioner do |chef|
     chef.json = {
       'cloudflare' => {
         'credentials' => {
           'email' => CLOUDFLARE_EMAIL,
           'api_key' => CLOUDFLARE_API_KEY
         },
+        'threat_control' => {
+          # one minute, to be able to test quickly
+          'cache_duration' => 1.0 / (24.0 * 60.0)
+        },
         'example_zone' => CLOUDFLARE_ZONE,
         'debug' => true
       }

attributes/default.rb

@@ -16,3 +16,16 @@
 # If you set the attribute above to true, that's the DNS server we're going
 # to ask - defaults to Cloudflare's main public DNS server
 default['cloudflare']['DNS_server'] = 'ns.cloudflare.com'
+
+
+# Interval during which the threat control caching in node's attributes remains valid
+# In days, as a float
+default['cloudflare']['threat_control']['cache_duration'] = 1.0
+# If set to true, we won't care about the cached information - be aware that will
+# result in quite a lot of API calls (one per resource and per chef run)
+default['cloudflare']['threat_control']['disable_cache'] = false
+
+# Do not edit this manually, this is where this cookbook caches the threat-control
+# statuses
+# For the record, it maps IPs to a hash with the 'status' and 'datetime' keys
+default['cloudflare']['threat_control']['status_cache'] = {}

libraries/provider.rb

@@ -0,0 +1,19 @@
+class Chef::Provider
+
+  # this needs to be done at run time, not compile time
+  def load_cloudflare_cookbook_gems
+    return if defined? @@cloudflare_cookbook_gems_loaded
+
+    chef_gem 'cloudflare' do
+      action :nothing
+      version '2.0.1' # TODO update to latest 2.0.2
+    end.run_action(:install, :immediately)
+
+    require 'resolv'
+    require 'cloudflare'
+    require 'date'
+
+    @@cloudflare_cookbook_gems_loaded = true
+  end
+
+end

metadata.json

@@ -4,4 +4,4 @@
 license          'unlicense'
 description      'Registers your server with Cloudflare\'s DNS service'
 long_description IO.read(File.join(File.dirname(__FILE__), 'README.md'))
-version          '0.1.6'
+version          '0.1.7'

metadata.rb

@@ -39,18 +39,3 @@
     Chef::Log.info "No DNS record named #{new_resource.complete_url} found, can't delete"
   end
 end
-
-private
-
-# this needs to be done at run time, not compile time
-def load_cloudflare_cookbook_gems
-  return if defined? @@cloudflare_cookbook_gems_loaded
-
-  chef_gem 'cloudflare' do
-    action :nothing
-    version '2.0.1'
-  end.run_action(:install, :immediately)
-  require 'resolv'
-  require 'cloudflare'
-  @@cloudflare_cookbook_gems_loaded = true
-end

providers/dns_record.rb

@@ -0,0 +1,69 @@
+action :whitelist do
+  action_for_status :whitelist
+end
+
+action :blacklist do
+  action_for_status :blacklist
+end
+
+action :remove_ip do
+  action_for_status :remove_ip
+end
+
+private
+
+# it's the same logic for all the actions, so let's DRY that up
+def action_for_status status
+  load_cloudflare_cookbook_gems
+  ip = new_resource.ip
+
+  if trust_cache? && status_from_cache(ip) == status
+    Chef::Log.info "[CF] Cache says that #{ip} is already in status #{status}, nothing to do"
+  else
+    # we need to make the actual call to the API
+    new_resource.set_status status
+    Chef::Log.info "[CF] #{ip}'s threat control was succesfully set to #{status}"
+
+    # no harm in caching even if the cache isn't used
+    set_cache ip, status
+
+    # as noted in the README, we can't know whether the status
+    # really was updated with Cloudflare, so...
+    new_resource.updated_by_last_action true
+  end
+end
+
+# we trust the cache iff it's not disabled and we're not running chef-solo
+def trust_cache?
+  !node['cloudflare']['threat_control']['disable_cache'] \
+    && !Chef::Config[:solo]
+end
+
+# returns the cache's status for that IP
+# if the cache is stale, it removes that entry
+# and returns `:none`
+def status_from_cache ip
+  clean_cache
+  node['cloudflare']['threat_control']['status_cache'].fetch(ip)['status'].to_sym
+rescue KeyError
+  # not found
+  :none
+end
+
+def is_stale? str_datetime
+  DateTime.now > DateTime.strptime(str_datetime) + node['cloudflare']['threat_control']['cache_duration']
+end
+
+def set_cache ip, status
+  node.normal['cloudflare']['threat_control']['status_cache'][ip] = {
+    'datetime' => DateTime.now.strftime,
+    'status' => status
+  }
+end
+
+# we clean the whole cache every time we use it
+# might look a tad inefficient, but keeps code simple
+# and avoids lingering obsolete values
+def clean_cache
+  node.normal['cloudflare']['threat_control']['status_cache'].reject! { |ip, data| is_stale? data['datetime'] }
+end

providers/threat_control.rb

@@ -8,3 +8,10 @@
     action :delete
   end
 end
+
+['172.20.126.126', '172.20.127.127'].each do |ip|
+  cloudflare_threat_control "remove-threat-control-#{ip}" do
+    ip ip
+    action :remove_ip
+  end
+end

recipes/example-cleanup.rb

@@ -76,3 +76,17 @@
   content 'getchef.com'
   record_name "#{prefix}-conflicting-CNAME"
 end
+
+##
+## Threat control testing
+##
+
+cloudflare_threat_control 'whitelist_test_server_a' do
+  ip '172.20.126.126'
+  action :whitelist
+end
+
+cloudflare_threat_control 'blacklist_test_server_b' do
+  ip '172.20.127.127'
+  action :blacklist
+end

recipes/example.rb

@@ -4,7 +4,7 @@
 attribute :name, :name_attribute => true, :kind_of => String, :required => true
 attribute :record_name, :kind_of => [String, FalseClass], :default => false
 attribute :zone, :kind_of => String, :required => true
-attribute :content, :kind_of => [String, FalseClass], :default => false
+attribute :content, :kind_of => String, :default => node.ipaddress
 attribute :type, :kind_of => String, :equal_to => ['A', 'CNAME'], :default => 'A'
 attribute :ttl, :kind_of => Fixnum, :default => 1
 attribute :shared_A_record, :kind_of => [TrueClass, FalseClass], :default => false
@@ -92,13 +92,6 @@ def zone *args
   old_zone *args
 end
 
-alias_method :old_content, :content
-def content *args
-  # we default to the node's ipaddress if no content was explicitely given
-  @content = node.ipaddress if !@content
-  old_content *args
-end
-
 def shared_A_record?
   type == 'A' && shared_A_record
 end

resources/dns_record.rb

@@ -0,0 +1,11 @@
+actions :whitelist, :blacklist, :remove_ip
+default_action :nothing
+
+attribute :ip, :kind_of => String, :default => node.ipaddress
+
+def set_status status
+  response = node.cloudflare_client.send status, ip
+  if response['result'] != 'success'
+    Chef::Application.fatal! "Unable to set threat control status to #{status} for ip #{ip} : Cloudflare's API returned #{response}"
+  end
+end