conjur-api 5.3.8.pre.319 → 5.4.0

data/lib/conjur/escape.rb

@@ -0,0 +1,129 @@
+#
+# Copyright (C) 2013-2017 Conjur Inc
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy of
+# this software and associated documentation files (the "Software"), to deal in
+# the Software without restriction, including without limitation the rights to
+# use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+# the Software, and to permit persons to whom the Software is furnished to do so,
+# subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+# FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+# IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+# CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#
+module Conjur
+
+  # Provides helpers for escaping url components.
+  #
+  # The helpers are added as both class and isntance methods.
+  module Escape
+    module ClassMethods
+      # URL escape the entire string.  This is essentially the same as calling `CGI.escape str`,
+      # and then substituting `%20` for `+`.
+      #
+      # @example
+      #   fully_escape 'foo/bar@baz'
+      #   # => "foo%2Fbar%40baz"
+      #
+      # @example
+      #   fully_escape 'test/Domain Controllers'
+      #   # => "test%2FDomain%20Controllers"
+      #
+      # @param [String] str the string to escape
+      # @return [String] the escaped string
+      def fully_escape(str)
+        # CGI escape uses + for spaces, which our services don't support :-(
+        # We just gsub it.
+        CGI.escape(str.to_s).gsub('+', '%20')
+      end
+
+
+      # Escape a URI path component.
+      #
+      # This method simply calls {Conjur::Escape::ClassMethods#path_or_query_escape}.
+      #
+      # @param [String] str the string to escape
+      # @return [String] the escaped string
+      # @see Conjur::Escape::ClassMethods#path_or_query_escape
+      def path_escape(str)
+        path_or_query_escape str
+      end
+
+      # Escape a URI query value.
+      #
+      # This method simply calls {Conjur::Escape::ClassMethods#path_or_query_escape}.
+      #
+      # @param [String] str the string to escape
+      # @return [String] the escaped string
+      # @see Conjur::Escape::ClassMethods#path_or_query_escape
+      def query_escape(str)
+        path_or_query_escape str
+      end
+
+      # Escape a path or query value.
+      #
+      # This method is *similar* to `URI.escape`, but it has several important differences:
+      #   * If a falsey value is given, the string `"false"` is returned.
+      #   * If the value given responds to `#id`, the value returned by `str.id` is escaped instead.
+      #   * The value is escaped without modifying `':'` or `'/'`.
+      #
+      # @param [String, FalseClass, NilClass, #id] str the value to escape
+      # @return [String] the value escaped as described
+      def path_or_query_escape(str)
+        return "false" unless str
+        str = str.id if str.respond_to?(:id)
+        # Leave colons and forward slashes alone
+        require 'addressable/uri'
+        Addressable::URI.encode(str.to_s)
+      end
+    end
+
+    # @api private
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    # URL escape the entire string.  This is essentially the same as calling `CGI.escape str`.
+    #
+    # @example
+    #   fully_escape 'foo/bar@baz'
+    #   # => "foo%2Fbar%40baz"
+    #
+    # @param [String] str the string to escape
+    # @return [String] the escaped string
+    # @see Conjur::Escape::ClassMethods#fully_escape
+    def fully_escape(str)
+      self.class.fully_escape str
+    end
+
+    # Escape a URI path component.
+    #
+    # This method simply calls {Conjur::Escape::ClassMethods#path_or_query_escape}.
+    #
+    # @param [String] str the string to escape
+    # @return [String] the escaped string
+    # @see Conjur::Escape::ClassMethods#path_or_query_escape
+    def path_escape(str)
+      self.class.path_escape str
+    end
+
+
+    # Escape a URI query value.
+    #
+    # This method simply calls {Conjur::Escape::ClassMethods#path_or_query_escape}.
+    #
+    # @param [String] str the string to escape
+    # @return [String] the escaped string
+    # @see Conjur::Escape::ClassMethods#path_or_query_escape
+    def query_escape(str)
+      self.class.query_escape str
+    end
+  end
+end

data/lib/conjur/exceptions.rb

@@ -0,0 +1,4 @@
+module Conjur
+  class FeatureNotAvailable < StandardError
+  end
+end

data/lib/conjur/group.rb

@@ -0,0 +1,41 @@
+# Copyright 2013-2017 Conjur Inc.
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy of
+# this software and associated documentation files (the "Software"), to deal in
+# the Software without restriction, including without limitation the rights to
+# use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+# the Software, and to permit persons to whom the Software is furnished to do so,
+# subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+# FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+# IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+# CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#
+module Conjur
+
+  # A Conjur Group represents a collection of Conjur Users, Groups and Layers.
+  #
+  class Group < BaseObject
+    include ActsAsRolsource
+
+    # Get the group's gidnumber, which can be used by LDAP and SSH login, among other things.
+    #
+    # @return [Fixnum] the gidnumber
+    # @raise [RestClient::Forbidden] if you don't have permission to `show` the group.
+    def gidnumber
+      parser_for(:group_gidnumber, group_attributes)
+    end
+
+    private
+
+    def group_attributes
+      @group_attributes ||= url_for(:group_attributes, credentials, self, id)
+    end
+  end
+end

data/lib/conjur/has_attributes.rb

@@ -0,0 +1,98 @@
+#
+# Copyright 2013-2017 Conjur Inc
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy of
+# this software and associated documentation files (the "Software"), to deal in
+# the Software without restriction, including without limitation the rights to
+# use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+# the Software, and to permit persons to whom the Software is furnished to do so,
+# subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+# FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+# IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+# CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#
+module Conjur
+  # Many Conjur assets have key-value attributes.  Although these should generally be accessed via
+  # methods on specific asset classes (for example, {Conjur::Resource#owner}), the are available as
+  # a `Hash` on all types supporting attributes.
+  module HasAttributes
+    class << self
+
+      # @api private
+      def annotation_value annotations, name
+        (annotations.find{|a| a['name'] == name} || {})['value']
+      end
+    end
+
+    def as_json options={}
+      result = super(options)
+      if @attributes
+        result.merge!(@attributes.as_json(options))
+      end
+      result
+    end
+    
+    def to_s
+      to_json.to_s
+    end
+
+    # @api private
+    # Set the attributes for this Resource.
+    # @param [Hash] attributes new attributes for the object.
+    # @return [Hash] the new attributes
+    def attributes=(attributes); @attributes = attributes; end
+
+    # Get the attributes for this asset. This is an immutable Hash, unless the attributes
+    # are changed via policy update.
+    #
+    # @return [Hash] the asset's attributes.
+    def attributes
+      return @attributes if @attributes
+      fetch
+    end
+
+    # Call a block that will perform actions that might change the asset's attributes.
+    # No matter what happens in the block, this method ensures that the cached attributes
+    # will be invalidated.
+    #
+    # @note this is mainly used internally, but included in the public api for completeness.
+    #
+    # @return [void]
+    def invalidate(&block)
+      yield
+    ensure
+      @attributes = nil
+    end
+
+    def annotations
+      Hash[(attributes['annotations']||{}).collect {|e| [e['name'],e['value']]}]
+    end
+    
+    protected
+
+    def annotation_value name
+      annotations[name]
+    end
+
+    # @api private
+    # Fetch the attributes, overwriting any current ones.
+    def fetch
+      @attributes ||= fetch_attributes
+    end
+
+    # @api private
+    def fetch_attributes
+      cache_key = Conjur.cache_key username, url_for(:resources_resource, credentials, id).url
+      Conjur.cache.fetch_attributes cache_key do
+        JSON.parse(url_for(:resources_resource, credentials, id).get.body)
+      end
+    end
+  end
+end

data/lib/conjur/host.rb

@@ -0,0 +1,27 @@
+#
+# Copyright 2013-2017 Conjur Inc
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy of
+# this software and associated documentation files (the "Software"), to deal in
+# the Software without restriction, including without limitation the rights to
+# use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+# the Software, and to permit persons to whom the Software is furnished to do so,
+# subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+# FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+# IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+# CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#
+module Conjur
+  # This class represents a Conjur Host. Hosts are created in Conjur policy, or with
+  # {Conjur::HostFactory}.
+  class Host < BaseObject
+    include ActsAsUser
+  end
+end

data/lib/conjur/host_factory.rb

@@ -0,0 +1,75 @@
+#
+# Copyright 2013-2017 Conjur Inc
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy of
+# this software and associated documentation files (the "Software"), to deal in
+# the Software without restriction, including without limitation the rights to
+# use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+# the Software, and to permit persons to whom the Software is furnished to do so,
+# subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+# FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+# IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+# CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#
+require 'conjur/host_factory_token'
+
+module Conjur
+  # A Host Factory is a way to allow clients to create Conjur hosts without giving them
+  # any other access to Conjur.
+  #
+  # Each Host Factory can have 0 or more tokens, each of which is a random string that
+  # has an associated expiration and optional CIDR restriction. A user or machine who has
+  # a host factory token can use it to create new hosts, or to rotate the API keys of 
+  # existing hosts.
+  #
+  # @see API#host_factory_create_host
+  # @see HostFactoryToken
+  class HostFactory < BaseObject
+    include ActsAsRolsource
+    
+    # Create one or more host factory tokens. Each token can be used to create
+    # hosts, using {API#host_factory_create_host}. 
+    #
+    # @param expiration [Time] the future time at which the token will stop working.
+    # @param count [Integer] the number of (identical) tokens to create (default: 1).
+    # @param cidr [String] a CIDR restriction on the usage of the token.
+    # @return [Array<HostFactoryToken>] the token or tokens.
+    def create_tokens expiration, count: 1, cidr: nil
+      options = {}
+      options[:expiration] = expiration.iso8601
+      options[:host_factory] = id
+      options[:count] = count
+      options[:cidr] = cidr if cidr
+      response = JSON.parse url_for(:host_factory_create_tokens, credentials, id).post(options)
+      response.map do |data|
+        HostFactoryToken.new data, credentials
+      end
+    end
+    
+    # Create a new token.
+    #
+    # @see #create_tokens
+    def create_token expiration, cidr: nil
+      create_tokens(expiration, cidr: cidr).first
+    end
+
+    # Enumerate the tokens on the host factory.
+    #
+    # @return [Array<HostFactoryToken>] the token or tokens.
+    def tokens
+      # Tokens list is not returned by +show+ if the caller doesn't have permission
+      return nil unless self.attributes['tokens']
+
+      self.attributes['tokens'].collect do |data|
+        HostFactoryToken.new data, credentials
+      end
+    end
+  end
+end

data/lib/conjur/host_factory_token.rb

@@ -0,0 +1,78 @@
+#
+# Copyright 2013-2017 Conjur Inc
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy of
+# this software and associated documentation files (the "Software"), to deal in
+# the Software without restriction, including without limitation the rights to
+# use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+# the Software, and to permit persons to whom the Software is furnished to do so,
+# subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+# FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+# IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+# CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#
+module Conjur
+  class HostFactoryToken
+    def initialize data, credentials
+      @data = data
+      @credentials = credentials
+    end
+    
+    # Convert the object to JSON.
+    #
+    # Fields:
+    #
+    # * token
+    # * expiration
+    # * cidr
+    def to_json(options = {})
+      { token: token, expiration: expiration, cidr: cidr }
+    end
+  
+    # Format the token as a string, using JSON format.
+    def to_s
+      to_json.to_s
+    end
+  
+    # Gets the token string.
+    #
+    # @return [String]
+    def token
+      @data['token']
+    end    
+    
+    # Gets the expiration.
+    #
+    # @return [DateTime]
+    def expiration
+      DateTime.iso8601(@data['expiration'])
+    end
+    
+    # Gets the CIDR restriction.
+    #
+    # @return [String]
+    def cidr
+      @data['cidr']
+    end
+
+    # Revokes the token, after which it cannot be used any more.
+    def revoke
+      Conjur::API.revoke_host_factory_token @credentials, token
+    end
+
+    def ==(other)
+      other.class == self.class &&
+        other.token == self.token &&
+        other.expiration == self.expiration &&
+        other.cidr == self.cidr
+    end
+
+  end
+end

data/lib/conjur/id.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+# Copyright 2013-2018 CyberArk Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require 'conjur/escape'
+
+module Conjur
+  # Encapsulates a Conjur id, which consists of account, kind, and identifier.
+  class Id
+    include Conjur::Escape
+
+    attr_reader :id
+
+    def initialize id
+      @id = Id.normalize id
+    end
+
+    # The organization account, obtained from the first component of the id.
+    def account; id.split(':', 3)[0]; end
+    # The object kind, obtained from the second component of the id.
+    def kind; id.split(':', 3)[1]; end
+    # The object identifier, obtained from the third component of the id. The
+    # identifier must be unique within the `account` and `kind`.
+    def identifier; id.split(':', 3)[2]; end
+    
+    # Defines id equivalence using the string representation.
+    def == other
+      if other.is_a?(String)
+        to_s == other
+      else
+        super
+      end
+    end
+
+    # @return [String] the id string.
+    def as_json options={}
+      @id
+    end
+
+    # Splits the id into 3 components, and then joins them with a forward-slash `/`.
+    def to_url_path
+      id.split(':', 3)
+        .map(&method(:fully_escape))
+        .join('/')
+    end
+    
+    # @return [String] the id string
+    def to_s
+      id
+    end
+
+    def self.normalize id
+      Array(id).join(':').tap do |id|
+        raise ArgumentError, "id must be fully qualified: #{id}" \
+          unless id =~ /.*:.*:.*/
+      end
+    end
+  end
+end

data/lib/conjur/layer.rb

@@ -0,0 +1,9 @@
+module Conjur
+
+  # A Conjur Layer is a type of role whose members are Conjur Hosts. The hosts inherit
+  # permissions from the layer. Automatic roles on the layer can also be used to manage
+  # SSH permissions to the hosts.
+  class Layer < BaseObject
+    include ActsAsRolsource
+  end
+end

data/lib/conjur/log.rb

@@ -0,0 +1,72 @@
+#
+# Copyright 2013-2017 Conjur Inc
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy of
+# this software and associated documentation files (the "Software"), to deal in
+# the Software without restriction, including without limitation the rights to
+# use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+# the Software, and to permit persons to whom the Software is furnished to do so,
+# subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+# FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+# IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+# CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#
+require 'logger'
+
+module Conjur
+  # Assign a Logger for use by Conjur API methods.  This method accepts
+  # several argument forms:
+  # * The strings 'stdout' and 'stderr' cause log messages to be sent to the corresponding stream.
+  # * Other stings are treated as paths and will cause log messages to be sent to those files.
+  # * A `Logger` instance will be used as is.
+  #
+  # Note that the logger specified by the `CONJURAPI_LOG` environment variable will override
+  # the value set here.
+  #
+  # @param [String, Logger,nil] log the new logger to use
+  # @return [void]
+  def self.log= log
+    @@log = create_log log
+  end
+
+  # @api private
+  # Create a log from a String or Logger param
+  #
+  # @param [String, Logger, nil] param the value to create the logger from
+  # @return Logger
+  def self.create_log param
+    if param
+      if param.is_a? String
+        if param == 'stdout'
+          Logger.new $stdout
+        elsif param == 'stderr'
+          Logger.new $stderr
+        else
+          Logger.new param
+        end
+      else
+        param
+      end
+    end
+  end
+
+  @@env_log = create_log ENV['CONJURAPI_LOG']
+
+  @@log = nil
+
+  # @api private
+  # @note this method may return nil if no log has been set, so you **must** check the value
+  # before attempting to use the logger.
+  #
+  # You should consider using {Conjur::LogSource} instead.
+  def self.log
+    @@env_log || @@log
+  end
+end

data/lib/conjur/log_source.rb

@@ -0,0 +1,60 @@
+#
+# Copyright 2013-2017 Conjur Inc
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy of
+# this software and associated documentation files (the "Software"), to deal in
+# the Software without restriction, including without limitation the rights to
+# use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+# the Software, and to permit persons to whom the Software is furnished to do so,
+# subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+# FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+# COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+# IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+# CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+#
+module Conjur
+  # This module provides logging support for actions taken by the Conjur API.
+  #
+  # @example
+  #     class Example
+  #       include LogSource
+  #
+  #       def something_interesting param
+  #         log{|l| l << "doing something interesting with #{param}"}
+  #
+  #         # Do something interesting...
+  #       end
+  #
+  #     end
+  #     # ...
+  #
+  #     Example.new.something_interesting 'foo'
+  #     # will log:
+  #     # [admin] doing something interesting with foo
+  #
+  module LogSource
+    # Yield a logger to the block.  You should use the `<<` method to write to the
+    # logger so that you don't send newlines or formatting.  The block will only be called
+    # if {Conjur.log} is not nil.
+    #
+    # The log format is `"[<username>]<messages logged in block>\n"`.
+    #
+    # @yieldparam [#<<] logger a logger to write messages
+    # @return [void]
+    def log(&block)
+      if Conjur.log
+        Conjur.log << "["
+        Conjur.log << username
+        Conjur.log << "] "
+        yield Conjur.log
+        Conjur.log << "\n"
+      end
+    end
+  end
+end