opensecret 0.0.9925 → 0.0.9949

data/lib/usecase/docker/README.md

@@ -0,0 +1,146 @@
+
+# safe jenkins <command>
+
+
+### safe jenkins post [aws|docker|git] <<jenkins-host-url>> | introduction
+
+Use **`safe jenkins post`** to inject both your **AWS IAM User** and **docker login/password** credentials into your Jenkins 2.0 continuous integration portal reachable by the **jenkins host url** given in the 4th parameter of the safe command.
+
+---
+
+## safe jenkins post | prerequisite
+
+Before you can inject credentials into jenkins using **`safe jenkins post`** you must
+
+- be logged into your safe
+- have opened the appropriate chapter/verse
+- have put the required credential key/value pairs into the safe
+- have the jenkins service up and running
+
+After the post (to jenkins), your continuous integration jobs will be able to access the credential values via their IDs as stated in the below table.
+
+---
+
+## safe jenkins post aws | key names table
+
+As credentials are WORO (write once, read often), safe makes the reading part very very easy (and secure) so your effort is frontloaded.
+
+| Safe Key    | Jenkins Credential IDs | Environment Variable  | Description                                              |
+|:-----------:|:----------------------:|:--------------------- |:-------------------------------------------------------- |
+| @access.key | safe.aws.access.key    | AWS_ACCESS_KEY_ID     | The AWS IAM user's access key credential.                |
+| @secret.key | safe.aws.secret.key    | AWS_SECRET_ACCESS_KEY | The AWS IAM user's secret key credential.                |
+| region.key  | safe.aws.region.key    | AWS_REGION            | The AWS region key that your Jenkins service points to.  |
+
+So you can see that by convention, safe expects the credential keys in the safe to be named a particular way, and likewise, you can be assured of the IDs it gives those credentials when posted to Jenkins.
+
+
+## safe jenkins post | credentials lifecycle
+
+The life of the credentials begins when you create an  IAM user and record its access and secret keys. Then
+
+- you login to safe and store the 3 keys and their values
+- safe jenkins post will read the values and post them to Jenkins
+- Jenkins stores the values in conjunction with the Jenkins Credential IDs
+- pipeline jobs ask Jenkins to put the Credential ID values against environment variables
+- tools like Terraform and AwsCli use the environment variables to work in the cloud
+
+
+## Jenkinsfile | Usage in Pipeline Jobs
+
+Here is a pipeline declaration within a Jenkinsfile that asks Jenkins to put the credential values in its secrets store into the stated environment variables.
+
+    environment
+    {
+        AWS_ACCESS_KEY_ID     = credentials( 'safe.aws.access.key' )
+        AWS_SECRET_ACCESS_KEY = credentials( 'safe.aws.secret.key' )
+        AWS_REGION            = credentials( 'safe.aws.region.key' )
+    }
+
+After **`safe jenkins post aws`** you can **click into the Credentials item in the Jenkins main menu** to assure yourself that the credentials have indeed been properly injected.
+
+---
+
+## How to Write AWS Credentials into your Safe
+
+In order to **`safe terraform apply`** or **`safe jenkins post aws <<jenkins-host-url>>`** or `safe visit` you must first put those ubiquitous IAM programmatic user credentials into your safe.
+
+    $ safe login joebloggs.com                  # open the book
+
+    $ safe open iam dev.s3.reader               # open chapter and verse
+    $ safe put @access.key ABCD1234EFGH5678     # Put IAM access key in safe
+    $ safe put @secret.key xyzabcd1234efgh5678  # Put IAM secret key in safe
+    $ safe put region.key eu-west-3             # infrastructure in Paris
+
+    $ safe open iam canary.admin                # open chapter and verse
+    $ safe put @access.key 4321DCBA8765WXYZ     # Put IAM access key in safe
+    $ safe put @secret.key 5678uvwx4321abcd9876 # Put IAM secret key in safe
+    $ safe put region.key eu-west-1             # infrastructure in Dublin
+
+    $ safe logout
+
+
+---
+
+
+## How to write DockerHub Credentials into your Safe
+
+#### safe jenkins post docker https://jenkins.example.com
+
+Before you can issue a **`safe jenkins post docker http://localhost:8080`** you must insert your docker login credentials in the form of a docker.username and @docker.password into your safe. Remember that any key starting with the `@ sign` tells the safe to keep it a secret like when you issue a **`safe show`** command.
+
+    $ safe login joebloggs.com         # open the book
+    $ safe open docker production      # at the docker (for production) chapter and verse
+    $ safe put docker.username admin   # Put the Docker repository login docker.username into the safe
+    $ safe put @docker.password s3cr3t # Put the Docker repository login @docker.password into the safe
+    $ safe logout
+
+When docker credentials are injected into a Jenkins service the safe will expect to find **lines** at the open chapter and verse location with key names **`docker.username`** and **`@docker.password`**.
+
+The safe promises to inject credentials with an ID of **safe.docker.login.id** so any jenkins jobs that need to use the docker login docker.username and password must specify this ID when talking to the Jenkins credentials service.
+
+
+### DockerHub Credentials Inject Response
+
+Here is an example of posting dockerhub credentials into a Jenkins service running on the local machine.
+
+``` bash
+safe jenkins post docker http://localhost:8080
+```
+
+If successful safe provides a polite response detailing what just happened.
+
+```
+ - Jenkins Host Url : http://localhost:8080/credentials/store/system/domain/_/createCredentials
+ -   Credentials ID : safe.docker.login.id
+ -  Inject Username : devops4me
+ - So what is this? : The docker repository login credentials in the shape of a username and password.
+
+  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
+                                 Dload  Upload   Total   Spent    Left  Speed
+100   428    0     0  100   428      0  47555 --:--:-- --:--:-- --:--:-- 47555
+```
+
+---
+
+
+## safe integrations | we need your help
+
+**You can help to extend safe's integrations.**
+
+By design - safe integrations are simple to write. They primarily integrate with producers and consumers. To deliver efficacy to devops engineers safe will endeavour to
+
+- **send** credentials to **downstream consumers** and
+- **receive** credentials from **upstream producers**
+
+safe needs pull requests from the devops community and it promises to always strive to keep the task of writing an integration extremely simple.
+
+### integrations | what giving takes?
+
+Currently, writing an integration entails delivering 3 or 4 artifacts which are
+
+- 1 simple Ruby class
+- 1 README.md documenting the command structure, the prerequisites and the expected outcome
+- 1 class containing unit tests
+- (optionaly) an INI file if many configuration and facts are involved
+
+Giving doesn't take much so roll up your sleeves (or frocks) and get writing.

data/lib/usecase/docker/docker.rb

@@ -0,0 +1,49 @@
+#!/usr/bin/ruby
+	
+module OpenSecret
+
+    # This docker use case handles the ...
+    #
+    #     safe docker login
+    #     safe docker logout
+
+    class Docker < UseCase
+
+        # The command which currently must be login, logout or
+        # an empty string.
+        attr_writer :command
+
+        def execute
+
+            return unless ops_key_exists?
+            master_db = get_master_database()
+            return if unopened_envelope?( master_db )
+
+            # Get the open chapter identifier (id).
+            # Decide whether chapter already exists.
+            # Then get (or instantiate) the chapter's hash data structure
+            chapter_id = ENVELOPE_KEY_PREFIX + master_db[ ENV_PATH ]
+            verse_id = master_db[ KEY_PATH ]
+            chapter_exists = OpenKey::KeyApi.db_envelope_exists?( master_db[ chapter_id ] )
+
+            # Unlock the chapter data structure by supplying
+            # key/value mini-dictionary breadcrumbs sitting
+            # within the master database at the section labelled
+            # envelope@<<actual_chapter_id>>.
+            chapter_data = OpenKey::KeyDb.from_json( OpenKey::KeyApi.content_unlock( master_db[ chapter_id ] ) )
+
+            key_value_dictionary = chapter_data[ verse_id ]
+            docker_username = key_value_dictionary[ "docker.username" ]
+            docker_password = key_value_dictionary[ "@docker.password" ]
+            docker_login_cmd = "docker login --username #{docker_username} --password #{docker_password} 2>/dev/null"
+            docker_logout_cmd = "docker logout"
+            docker_cmd = @command.eql?( "logout" ) ? docker_logout_cmd : docker_login_cmd
+            system docker_cmd
+
+        end
+
+
+    end
+
+
+end

data/lib/usecase/edit/README.md

@@ -0,0 +1,43 @@
+
+### safe put | safe delete | safe copy | safe paste
+
+# edit use cases | copy | paste | delete
+
+The edit use cases create, delete and update the credentials and configuration inside your safe.
+
+## Common Usage
+
+Typically you login to a book, open a chapter and verse, then you put **`key/value`** pairs, known as **lines**.
+
+```
+safe login joe@home
+
+# -- -------------------------------------------------- -- #
+# -- Create chapter (email) and verse <<email-address>> -- #
+# -- -------------------------------------------------- -- #
+safe open email joebloggs@gmail.com
+
+# -- ---------------------------- -- #
+# -- Populate it with credentials -- #
+# -- ---------------------------- -- #
+safe put gmail.id joebloggs
+safe put @password s3cr3et
+safe put recovery.phone 07500875278
+
+# -- ----------------------------------------------- -- #
+# -- Now copy and then paste a line (key/value pair) -- #
+# -- ----------------------------------------------- -- #
+safe copy recovery.phone
+safe open email joe@ywork.com
+safe paste
+```
+
+## editing behaviour
+
+**These use cases are intuitive and behave almost like what you would expect.** The safe ethos is for commands to behave according to which of the 5 levels you are at.
+
+
+| Command          | Verse                         | Chapter                          | Book                            |
+|:---------------- |:----------------------------- |:-------------------------------- |:------------------------------- |
+| safe copy <<id>> | Copy one of the verse's lines | Copy one of the chapter's verses | Copy one of the book's chapters |
+| safe copy        | Copy all of the verse's lines | Copy all of the chapter's verses | Copy all of the book's chapters |

data/lib/usecase/edit/delete.rb

@@ -0,0 +1,46 @@
+#!/usr/bin/ruby
+	
+module OpenSecret
+
+  # The <b>delete use case</b> delete's one or more of the safe's entities.
+  #
+  # - at <tt>verse</tt> level - it can delete one or more lines
+  # - at <tt>chapter</tt> level - it can delete one or more verses
+  # - at <tt>book</tt> level - it can delete one or more chapters
+  # - at <tt>safe</tt> level - it can delete one book
+  #
+  class DeleteMe < UseCase
+
+    attr_writer :entity_id
+
+    # Deletion that currently expects an open chapter and verse and always
+    # wants to delete only one line (key/value pair).
+    def execute
+
+      return unless ops_key_exists?
+      master_db = OpenKey::KeyApi.read_master_db()
+      return if unopened_envelope?( master_db )
+
+      chapter_id = ENVELOPE_KEY_PREFIX + master_db[ ENV_PATH ]
+      chapter_exists = OpenKey::KeyApi.db_envelope_exists?( master_db[ chapter_id ] )
+      chapter_data = OpenKey::KeyDb.from_json( OpenKey::KeyApi.content_unlock( master_db[ chapter_id ] ) ) if chapter_exists
+      chapter_data = OpenKey::KeyDb.new() unless chapter_exists
+
+      content_hdr = create_header()
+      master_db[ chapter_id ] = {} unless chapter_exists
+      verse_id = master_db[ KEY_PATH ]
+
+      chapter_data.delete_entry( verse_id, @entity_id )
+      chapter_data.delete_entry( verse_id, "#{FILE_KEY_PREFIX}#{@entity_id}" )
+
+      OpenKey::KeyApi.content_lock( master_db[ chapter_id ], chapter_data.to_json, content_hdr )
+      OpenKey::KeyApi.write_master_db( content_hdr, master_db )
+      Show.new.flow_of_events
+
+    end
+
+
+  end
+
+
+end

data/lib/usecase/export.rb

@@ -0,0 +1,40 @@
+#!/usr/bin/ruby
+
+module OpenSecret
+
+  # Export the entire book if no chapter and verse is specified (achieved with a safe close),
+  # or the chapter if only the chapter is open (safe shut or safe open <<chapter>>, or the
+  # mini-dictionary at the verse if both chapter and verse are open.
+  class Export < UseCase
+
+    def get_chapter_data( chapter_key )
+      return OpenKey::KeyDb.from_json( OpenKey::KeyApi.content_unlock( chapter_key ) )
+    end
+
+    def execute
+
+      return unless ops_key_exists?
+      master_db = OpenKey::KeyApi.read_master_db()
+
+      return if unopened_envelope?( master_db )
+
+      chapter_id = ENVELOPE_KEY_PREFIX + master_db[ ENV_PATH ]
+      has_chapter = OpenKey::KeyApi.db_envelope_exists?( master_db[ chapter_id ] )
+
+      unless has_chapter
+        puts "{}"
+        return
+      end
+
+      chapter_data = get_chapter_data( master_db[ chapter_id ] )
+      puts JSON.pretty_generate( chapter_data )
+
+      return
+
+    end
+
+
+  end
+
+
+end

data/lib/usecase/files/README.md

@@ -0,0 +1,37 @@
+
+# safe file | ingest and eject files
+
+You ingest a file with **safe file** and then **safe eject** will output that file into the present working directory.
+
+If safe detects during an eject, that a file already exists with the same name - it backs it up with a timestamp before ejecting and clobbering the existing file.
+
+```bash
+safe open <<chapter-name>> <<verse-name>>
+safe file <<keyname>> <</path/to/private-key.pem>>
+safe eject <<keyname>>
+safe show
+```
+
+To pull in 3 certificate oriented files for Kubernetes one could use these commands.
+
+```bash
+safe open production kubernetes
+safe file kubernetes.cert ~/.kubectl/kube.prod.cert.pem
+safe file kubernetes.ca.cert ~/.kubectl/kube.prod.ca.cert.pem
+safe file kubernetes.key ~/.kubectl/kube.prod.key.pem
+cd /tmp
+safe eject
+```
+
+The safe ingests the files and spits them out whenever you so desire.
+**Binary files** are supported and can be safely pulled in with <tt>safe file</tt> and ejected at any point in the future.
+
+## remote (external) files
+
+The **local filesystem** is the most common, but by no means the only file storage location. You can read from and write to
+
+- a zip file **`zip://`**
+- an S3 filesystem **`s3://`**
+- SSH locations **`<<user>>@<<hostname>>:/path/to/file`**
+- a git repository **`git@github.com`**
+- a **google drive** store

data/lib/usecase/files/eject.rb

@@ -0,0 +1,56 @@
+#!/usr/bin/ruby
+	
+module OpenSecret
+
+  # The <b>eject use case</b> writes (or overwrites) a file or files.
+  # Files are always ejected into the present working directory. If an
+  # overwrite is detected a backup is taken of the about to be clobbered
+  # file.
+  #
+  # If a keyname is provided then only the file against that key is ejected.
+  # No keyname will eject every file in the opened chapter and verse.
+  class Eject < UseCase
+
+    attr_writer :file_key
+
+    # Files are always ejected into the present working directory and any
+    # about to be clobbered files are backed up with a timestamp.
+    #
+    # If a keyname is provided then only the file against that key is ejected.
+    # No keyname will eject every file in the opened chapter and verse.
+    def execute
+
+      return unless ops_key_exists?
+      master_db = get_master_database()
+      return if unopened_envelope?( master_db )
+      chapter_id = ENVELOPE_KEY_PREFIX + master_db[ ENV_PATH ]
+      verse_id = master_db[ KEY_PATH ]
+      chapter_data = OpenKey::KeyDb.from_json( OpenKey::KeyApi.content_unlock( master_db[ chapter_id ] ) )
+
+      base64_content = chapter_data[ verse_id ][ "#{FILE_KEY_PREFIX}#{@file_key}" ][ FILE_CONTENT_KEY ]
+      simple_filename = chapter_data[ verse_id ][ "#{FILE_KEY_PREFIX}#{@file_key}" ][ FILE_NAME_KEY ]
+      file_full_path = File.join( Dir.pwd, simple_filename )
+      backup_filename = OpenKey::KeyNow.yyjjj_hhmm_sst() + "-" + simple_filename
+      backup_file_path = File.join( Dir.pwd, backup_filename )
+      will_clobber = File.file?( file_full_path )
+
+      File.write( backup_file_path, File.read( file_full_path ) ) if will_clobber
+      ::File.write( file_full_path, Base64.urlsafe_decode64( base64_content ) )
+
+      puts ""
+      puts "File successfully ejected from safe into current directory."
+      puts ""
+      puts "Clobbered File = #{backup_filename}" if will_clobber
+      puts "Current Directory = #{Dir.pwd}"
+      puts "Ejected Filename = #{simple_filename}"
+      puts "Chapter and Verse = #{master_db[ENV_PATH]}:#{verse_id}"
+      puts "Ejected File Key = #{@file_key}"
+      puts ""
+
+    end
+
+
+  end
+
+
+end

data/lib/usecase/files/file_me.rb

@@ -0,0 +1,78 @@
+#!/usr/bin/ruby
+	
+module OpenSecret
+
+  # The <b>file use case</b> pulls a file in from either an accessible filesystem
+  # or from a remote http, https, git, S3, GoogleDrive and/or ssh source.
+  #
+  # The @file_url is the most common parameter given to this use case.
+  class FileMe < UseCase
+
+    attr_writer :file_key, :file_url
+
+    # There are 3 maps involved in the implementation and they are all (or in part) retrieved and/or
+    # created as necessary. They are
+    #
+    # - the current chapter as a map
+    # - the current verse as a map
+    # - the file's keyname as a map
+    #
+    # Once the maps have been found and/or created if necessary the file's keyname map is either
+    # populated or amended with the following data.
+    #
+    # - filename | {UseCase::FILE_NAME_KEY} | the file's simple name
+    # - content64 | {UseCase::FILE_CONTENT_KEY} | the file's base64 content
+    def execute
+
+      return unless ops_key_exists?
+      master_db = OpenKey::KeyApi.read_master_db()
+      return if unopened_envelope?( master_db )
+
+      chapter_id = ENVELOPE_KEY_PREFIX + master_db[ ENV_PATH ]
+      chapter_exists = OpenKey::KeyApi.db_envelope_exists?( master_db[ chapter_id ] )
+      chapter_data = OpenKey::KeyDb.from_json( OpenKey::KeyApi.content_unlock( master_db[ chapter_id ] ) ) if chapter_exists
+      chapter_data = OpenKey::KeyDb.new() unless chapter_exists
+
+      content_hdr = create_header()
+      master_db[ chapter_id ] = {} unless chapter_exists
+      verse_id = master_db[ KEY_PATH ]
+
+      file_full_path = ::File.absolute_path( @file_url )
+      file_base_name = ::File.basename( file_full_path )
+      file_content64 = Base64.urlsafe_encode64( ::File.read( file_full_path ) )
+
+      log.info(x) { "Key name of the file to ingest => #{@file_key}" }
+      log.info(x) { "Ingesting file at path => #{file_full_path}" }
+      log.info(x) { "The name of the file to ingest is => #{file_base_name}" }
+      log.info(x) { "Size of base64 file content => [#{file_content64.length}]" }
+
+      chapter_data.create_map_entry( verse_id, "#{FILE_KEY_PREFIX}#{@file_key}", FILE_NAME_KEY, file_base_name )
+      chapter_data.create_map_entry( verse_id, "#{FILE_KEY_PREFIX}#{@file_key}", FILE_CONTENT_KEY, file_content64 )
+
+      OpenKey::KeyApi.content_lock( master_db[ chapter_id ], chapter_data.to_json, content_hdr )
+      OpenKey::KeyApi.write_master_db( content_hdr, master_db )
+
+      Show.new.flow_of_events
+
+    end
+
+
+    private
+
+
+    # Perform pre-conditional validations in preparation to executing the main flow
+    # of events for this use case. This method may throw the below exceptions.
+    #
+    # @raise [SafeDirNotConfigured] if the safe's url has not been configured
+    # @raise [EmailAddrNotConfigured] if the email address has not been configured
+    # @raise [StoreUrlNotConfigured] if the crypt store url is not configured
+    def pre_validation
+
+
+    end
+
+
+  end
+
+
+end