conjur-api 2.4.0 → 2.5.1

data/.gitignore

@@ -17,3 +17,5 @@ test/tmp
 test/version_tmp
 tmp
 .kateproject.d
+.rvmrc
+

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2012 Rafał Rzepecki
+Copyright (c) 2012 Conjur Inc
 
 MIT License
 

data/Rakefile

@@ -3,7 +3,9 @@ require "bundler/gem_tasks"
 
 begin
   require 'rspec/core/rake_task'
-  RSpec::Core::RakeTask.new(:spec)
+  RSpec::Core::RakeTask.new(:spec) do |t|
+    t.rspec_opts = '--order rand'
+  end
 rescue LoadError
   $stderr.puts "RSpec Rake tasks not available in environment #{ENV['RACK_ENV']}"
 end

data/conjur-api.gemspec

@@ -3,10 +3,11 @@ require File.expand_path('../lib/conjur-api/version', __FILE__)
 
 Gem::Specification.new do |gem|
   gem.authors       = ["Rafa\305\202 Rzepecki","Kevin Gilpin"]
-  gem.email         = ["divided.mind@gmail.com","kevin.gilpin@inscitiv.com"]
+  gem.email         = ["divided.mind@gmail.com","kgilpin@conjur.net"]
   gem.description   = %q{Conjur API}
   gem.summary       = %q{Conjur API}
   gem.homepage      = ""
+  gem.license       = "MIT"
 
   gem.files         = `git ls-files`.split($\) + Dir['build_number']
   gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
@@ -23,4 +24,5 @@ Gem::Specification.new do |gem|
   gem.add_development_dependency 'rspec'
   gem.add_development_dependency 'webmock'
   gem.add_development_dependency 'ci_reporter'
+  gem.add_development_dependency 'simplecov'
 end

data/lib/conjur-api/version.rb

@@ -1,6 +1,6 @@
 module Conjur
   class API
-    VERSION = "2.4.0"
+    VERSION = "2.5.1"
     # Note: when bumping major version, please remove compatibility code in role#grant_to
   end
 end

data/lib/conjur/has_id.rb

@@ -5,7 +5,7 @@ module Conjur
     end
   
     def id
-      path_components[-1]
+      path_components[2..-1].join('/')
     end    
   end
 end

data/lib/conjur/log.rb

@@ -1,40 +1,20 @@
-# Logging mechanism borrowed from rest-client
+require 'logger'
+
 module Conjur
   # You can also configure logging by the environment variable CONJURAPI_LOG.
   def self.log= log
     @@log = create_log log
   end
 
-  # Create a log that respond to << like a logger
-  # param can be 'stdout', 'stderr', a string (then we will log to that file) or a logger (then we return it)
   def self.create_log param
     if param
       if param.is_a? String
         if param == 'stdout'
-          stdout_logger = Class.new do
-            def << obj
-              STDOUT.write obj
-            end
-          end
-          stdout_logger.new
+          Logger.new $stdout
         elsif param == 'stderr'
-          stderr_logger = Class.new do
-            def << obj
-              STDERR.write obj
-            end
-          end
-          stderr_logger.new
+          Logger.new $stderr
         else
-          file_logger = Class.new do
-            attr_writer :target_file
-
-            def << obj
-              File.open(@target_file, 'a') { |f| f.write obj }
-            end
-          end
-          logger = file_logger.new
-          logger.target_file = param
-          logger
+          Logger.new param
         end
       else
         param
@@ -49,4 +29,4 @@ module Conjur
   def self.log # :nodoc:
     @@env_log || @@log
   end
-end
+end

data/lib/conjur/resource.rb

@@ -35,7 +35,7 @@ module Conjur
           logger << " with options #{options.to_json}"
         end
       end
-      super.delete(options)
+      super options
     end
 
     def permit(privilege, role, options = {})
@@ -62,6 +62,15 @@ module Conjur
         self["?deny&privilege=#{query_escape p}&role=#{query_escape role}"].post(options)
       end
     end
+
+    # True if the logged-in role, or a role specified using the acting-as option, has the
+    # specified +privilege+ on this resource.
+    def permitted?(privilege, options = {})
+      self["?check&privilege=#{query_escape privilege}"].get(options)
+      true
+    rescue RestClient::ResourceNotFound
+      false
+    end
     
     protected
     

data/manual/asset/about.markdown

@@ -0,0 +1,12 @@
+Asset
+=====
+
+Implements a domain-specific permission modeling concept. Assets combine functionality of roles, resources, and other assets
+together into unified APIs.
+
+Assets commonly perform the following functions:
+
+* **containment** An asset can contain other assets, such as an environment which contains variables or a deployment which contains hosts.
+Assets can be collected and re-combined arbitrarily.
+* **role management** Container assets can define roles which manage permissions on child assets. 
+

data/manual/asset/members.add.markdown

@@ -0,0 +1,52 @@
+Asset#members#add
+=================
+
+A common purpose of an asset is to manage access to a collection of "child" assets. Permissions on child assets are granted
+via roles defined on the parent asset.
+
+For example, consider an Environment asset which contains a number of child Variables:
+
+```
+Environment[e1]
+  - variables
+    - Variable[v1]
+    - Variable[v2]
+    - Variable[v3]
+```
+
+The Environment may define a role "use_variable" and permit "read" and "execute" on each variable by the "use_variable" role. 
+Therefore, granting the "use_variable" role to another role "r1" will permit r1 to read and execute each variable.
+
+Examples
+--------
+
+### Command Line
+
+```bash
+$ conjur asset:create environment `conjur id:create`
+{
+  "id": "9yxa80",
+  <snip>
+}
+$ conjur host:create
+{
+  "id": "9bfqx5",
+  <snip>
+}
+$ conjur environment:variables:create 9yxa80 test-var test text/plain "the-value"
+Variable created
+$ conjur asset:show environment 9yxa80
+{
+  "id": "9yxa80",
+  "variables": {
+    "test-var": "he2e00"
+  },
+  <snip>
+}
+$ conjur resource:check variable he2e00 host:9bfqx5 execute
+false
+$ conjur asset:members:add environment 9yxa80 use_variable host:9bfqx5
+Membership granted
+$ conjur resource:check variable he2e00 host:9bfqx5 execute
+true
+```

data/manual/asset/show.markdown

@@ -0,0 +1,50 @@
+Asset#show
+==========
+
+Display an asset as JSON.
+
+The Conjur `jsonfield` utility can be used to pluck JSON values.
+
+Examples
+--------
+
+### Command Line
+
+#### Create and show an environment
+
+```bash
+$ id=`conjur id:create`
+$ e=`conjur asset:create environment $id`
+$ conjur asset:show environment id
+{
+  "id": "0y3s00",
+  "variables": {
+  },
+  "userid": "kgilpin",
+  "ownerid": "sandbox:user:kgilpin",
+  "resource_identifier": "sandbox:environment:0y3s00"
+}
+```
+#### Create and show a host
+
+```bash
+$ hostid=`conjur host:create | jsonfield id`
+$ conjur asset:show host $hostid
+{
+  "id": "g7hytz",
+  "userid": "kgilpin",
+  "created_at": "2013-07-09T21:10:06+00:00",
+  "ownerid": "sandbox:user:kgilpin",
+  "roleid": "sandbox:host:g7hytz",
+  "resource_identifier": "sandbox:host:g7hytz"
+}
+```
+
+#### Attempt to show a non-existant asset.
+
+```bash
+$ conjur asset:show host foo
+error: 404 Resource Not Found
+$ echo $?
+1
+```

data/manual/group/about.markdown

@@ -0,0 +1,6 @@
+Group
+=====
+
+A group represents a collection of other roles (users, groups, hosts, generic roles, etc). Essentially
+it is just a role whose `kind` is "group".
+

data/manual/group/create.markdown

@@ -0,0 +1,20 @@
+Group#create
+============
+
+A group is created from an identifier. The identifier should be unique.
+
+Example
+-------
+
+### Command Line
+
+```bash
+$ conjur group:create `conjur id:create`
+Created https://core-sandbox-conjur.herokuapp.com/groups/5zjys0
+```
+
+### API
+
+```ruby
+conjur.create_group SecureRandom.uuid
+```

data/manual/host/about.markdown

@@ -0,0 +1,23 @@
+Host
+====
+
+A host represents a non-human user. VMs, processes, and jobs are all commonly represented as Hosts.
+
+Attributes
+----------
+
+* **username** the host username is composed of the word 'host' composed with the host identifier. For example, "host/i-bbe231db"
+* **api_key** each host is assigned an API key, just like a human user
+
+Like a human User, a Host can authenticate with Conjur and perform actions.
+
+Roles
+-----
+
+On creation, the host creates a Conjur role to represent itself. The role kind is 'host'.
+
+Resources
+---------
+
+On creation, the host creates a Conjur resource to represent itself. 
+

data/manual/host/create.markdown

@@ -0,0 +1,34 @@
+Host#create
+===========
+
+A host is created with an identifier. The identifier must be unique.
+It can be assigned, or it can be generated by Conjur. 
+
+When the host is created, the `api_key` field is included in the JSON response.
+
+Host#show does not include the `api_key`.
+
+Example
+-------
+
+```bash
+$ conjur host:create
+{
+  "id": "8y2p5w",
+  "userid": "kgilpin",
+  "created_at": "2013-07-09T21:12:57+00:00",
+  "ownerid": "sandbox:user:kgilpin",
+  "roleid": "sandbox:host:8y2p5w",
+  "resource_identifier": "sandbox:host:8y2p5w",
+  "api_key": "vj98ne10ar6vvmwrjt02ryfj6924a4vkch6yqcw292v9p12sv1rd"
+}
+$ conjur asset:show host 8y2p5w
+{
+  "id": "8y2p5w",
+  "userid": "kgilpin",
+  "created_at": "2013-07-09T21:12:57+00:00",
+  "ownerid": "sandbox:user:kgilpin",
+  "roleid": "sandbox:host:8y2p5w",
+  "resource_identifier": "sandbox:host:8y2p5w"
+}
+```

data/manual/host/enroll.markdown

@@ -0,0 +1,21 @@
+Host#enroll
+===========
+
+Returns a unique URL which, when fetched, returns a shell command which will login
+the host with Conjur.
+
+Example
+-------
+
+```bash
+$ conjur host:enroll vaz7qg
+https://core-sandbox-conjur.herokuapp.com/hosts/enroll?key=7fxt_HiRfOodA3J6wh5s2X9a6gm-b-wkPmF0g-HOPYo=
+On the target host, please execute the following command:
+curl -L https://core-sandbox-conjur.herokuapp.com/hosts/enroll?key=7fxt_HiRfOodA3J6wh5s2X9a6gm-b-wkPmF0g-HOPYo= | bash
+$ curl -L https://core-sandbox-conjur.herokuapp.com/hosts/enroll?key=7fxt_HiRfOodA3J6wh5s2X9a6gm-b-wkPmF0g-HOPYo=
+#!/bin/sh
+set -e
+
+conjur authn:login -u host/vaz7qg -p 39c63b3d5bc372de1c100feec852e05f747bc9eb
+```
+

data/manual/resource/about.markdown

@@ -0,0 +1,11 @@
+Resource
+========
+
+A resource is an entity on which permissions are assigned. 
+
+Resources are partitioned into "kinds", such as "group", "host",
+"file", "environment", "variable", etc. 
+
+Resources are not frequently used directly. Instead, higher-level "assets" such as Host, Group, User,
+Variable provide more intuitive functionality. For example, Assets often combine role and resource
+functionality together.

data/manual/resource/create.markdown

@@ -0,0 +1,29 @@
+Resource#create
+===============
+
+A resource is composed of a `kind` and `identifier`. The `kind`
+indicates the semantic purpose of the resource, the identifier identifies
+it uniquely within the kind. 
+
+Example
+-------
+
+### Command Line
+
+```bash
+$ conjur resource:create food bacon
+{
+  "id": {
+    "account": "sandbox",
+    "kind": "food",
+    "id": "bacon"
+  },
+  "owner": {
+    "account": "sandbox",
+    "id": "user:kgilpin"
+  },
+  "permissions": [
+
+  ]
+}
+```

data/manual/resource/deny.markdown

@@ -0,0 +1,23 @@
+Resource#deny
+=============
+
+Removes a specific permission on a resource from a role. 
+
+The owner of a resource always has all permissions on the resource, even if specific permissions
+are denied.
+
+Example
+-------
+
+### Command Line
+
+```bash
+$ conjur resource:permit food bacon host:a4yta8 fry
+Permission granted
+$ conjur resource:check food bacon host:a4yta8 fry
+true
+$ conjur resource:deny food bacon host:a4yta8 fry
+Permission revoked
+$ conjur resource:check food bacon host:a4yta8 fry
+false
+```

data/manual/resource/permit.markdown

@@ -0,0 +1,35 @@
+Resource#permit
+===============
+
+Gives a specific permission on a resource to a role. 
+
+Example
+-------
+
+### Command Line
+
+```bash
+$ conjur host:create
+<snip>
+$ conjur resource:permit food bacon host:a4yta8 fry
+Permission granted
+$ conjur resource:check food bacon host:a4yta8 fry
+true
+$ conjur resource:check food bacon host:a4yta8 bake
+false
+$ conjur resource:permitted_roles food bacon fry
+[
+  {
+    "id": {
+      "account": "sandbox",
+      "id": "user:kgilpin"
+    }
+  },
+  {
+    "id": {
+      "account": "sandbox",
+      "id": "host:a4yta8"
+    }
+  }
+]
+```