opensecret 0.0.9925 → 0.0.9949

data/lib/configs/README.md

@@ -0,0 +1,58 @@
+
+# Modifying Safe's Behaviour | 4 Configuration Scopes
+
+Safe's behaviour can (by default) be modified in a manner that is scoped in 4 ways. Configuration directives can alter behaviour within
+
+1. a **book global** scope
+2. a **machine local** scope
+3. a **shell session** scope and
+4. a **machine global** scope
+
+The scoping concept is similar to Git's --local and --global but it works in a different way.
+
+
+## 1. Book Global Scope
+
+Directives issued against a safe book **"feel local"** but are global in that the behaviour persists on every machine that works with the book.
+
+Git's --local is different because cloning the repository on another machine wipe's out the directives. With safe the directives continue to alter behaviour even when the book is cloned and/or used on another machine.
+
+
+## 2. Machine Local Scope
+
+This is similar to Git's --global directive which affects all repositories owned by a user on a given machine.
+
+Directives with a machine local scope **can influence the behaviour** of every Safe book one logs into on a machine. Move to another machine and the behaviour becomes unstuck.
+
+== Configuration Directive Precedence
+
+Note the sentence **can influence behaviour** as opposed to **will influence behaviour**.
+
+If a directive with a book global scope says "Yes" and the same directive exists but says "No" with machine local scope the "Yes" wins out.
+
+A book global directive overrides its machine local twin.
+
+
+## 3. Shell Session Scope
+
+The self explanatory **shell session scoped** directives override their siblings be they book global or machine local.
+
+Alas, their elevated privileges are countered by relatively short lifespans. Shell session directives only last until either a logout is issued or the shell session comes to an end.
+
+
+## 4. Default | Machine Global Scope
+
+Did you notice only **one (1) user** is affected by directives with a machine local scope as long as it isn't overriden.
+
+Directives with a **machine global scope** are the **default** and are set during an install or upgrade.
+
+They can potentially affect **every user and every safe book**. Even though their longevity is undisputed, their precedence is the lowest when going head to head with their 3 siblings.
+
+## The Naked Eye
+
+Directives with a book global scope **aren't visible to the naked eye**. They are encrypted within the master safe database and thus protected from prying eyes.
+
+The other 3 directive types exist in plain text
+
+- either where the gem is **installed** (machine global scope)
+- or in the INI file in **.safe** off the user's home directory

data/lib/extension/file.rb

@@ -3,6 +3,73 @@
 # Reopen the core ruby File class and add the below methods to it.
 class File
 
+    # Get the full filepath of a sister file that potentially lives
+    # in the same directory that the leaf class is executing from and
+    # has the same name as the leaf class but a different extension.
+    #
+    # == Usage
+    #
+    # If class OpenFoo:Bar extends class OpenFoo:Baz and we are looking
+    # for an INI file in the folder that OpenFoo:Bar lives in we can
+    # call this method within OpenFoo:Baz like this.
+    #
+    #   ini_filepath = sister_filepath( "ini", :execute )
+    #   # => /var/lib/gems/2.5.0/gems/fooey-0.2.99/lib/barry/bazzy/bar.ini
+    #
+    # == Common Implementation
+    #
+    # Object orientation scuppers the commonly used technique which
+    # derives the path from __FILE__
+    #
+    #    class_directory = File.dirname( __FILE__ )
+    #    leaf_class_name = self.class.name.split(":").last.downcase
+    #    sister_filepath = File.join ( class_directory, "#{leaf_class_name}.#{extension}" )
+    #
+    # With object orientation - running the above code within the
+    # abstracted (parent) class would produce a resultant filepath
+    # based on the folder the parent class is in rather than the
+    # extended "concrete" class.
+    #
+    # == Value Proposition
+    #
+    # You can call this method from the parent (abstract) class and it
+    # will still correctly return the path to the potential sister file
+    # living in the directory that the leaf class sits in.
+    #
+    # Put differently - this extension method allows code executing in
+    # the parent class to correctly pinpoint a file in the directory of
+    # the leaf class be it in the same or a different folder.
+    #
+    # @param caller
+    #     the calling class object usually passed in using <tt>self</tt>
+    #
+    # @param extension
+    #     the extension of a sister file that carries the same simple
+    #     (downcased) name of the leaf class of this method's caller.
+    #
+    #     Omit the (segregating) period character when providing this
+    #     extension parameter.
+    #
+    # @param method_symbol
+    #     the method name in symbolic form of any method defined in
+    #     the leaf class even if the method overrides one of the same
+    #     name in the parent class.
+    #
+    # @return the filepath of a potential sister file living in the same
+    #         directory as the class, bearing the same (downcased) name
+    #         as the class with the specified extension.
+    def self.sister_filepath caller, extension, method_symbol
+
+      leaf_classname = caller.class.name.split(":").last.downcase
+      execute_method = caller.method( method_symbol )
+      leaf_classpath = execute_method.source_location.first
+      leaf_directory = File.dirname( leaf_classpath )
+      lower_filename = "#{leaf_classname}.#{extension}"
+      return File.join( leaf_directory, lower_filename )
+
+    end
+
+
   # This method adds (logging its own contents) behaviour to
   # the standard library {File} class. If this File points to
   # a directory - that folder's single level content files are

data/lib/extension/string.rb

@@ -11,6 +11,16 @@
 # other parameter objects, like arrays and hashes).
 class String
 
+    ## ################################################
+    ## ################################################
+    ## ################################################
+    ## ################################################
+    ## https://www.di-mgt.com.au/cryptokeys.html
+    ## ################################################
+    ## ################################################
+    ## ################################################
+    ## ################################################
+    ## ################################################
 
   # Encrypt this string with the parameter symmetric encryption/decryption key
   # and then return the Base64 (block mode) encoded result.

data/lib/factbase/facts.opensecret.io.ini

@@ -27,6 +27,7 @@ session.file    =  ops.session.configuration.ini
 prompt.1        =  Enter a Robust Password
 prompt.2        =  Re-enter that Password
 
+
 [open]
 
 open.name       =  session

data/lib/interprete.rb

@@ -5,18 +5,21 @@ require "session/time.stamp"
 require "logging/gem.logging"
 require "session/require.gem"
 
+
 # Include the logger mixins so that every class can enjoy "import free"
 # logging through pointers to the (extended) log behaviour.
 include OpenLogger
 
+
 # This standard out sync command flushes text destined for STDOUT immediately,
 # without waiting either for a full cache or script completion.
 $stdout.sync = true
 
+
 # Recursively require all gems that are either in or under the directory
 # that this code is executing from. Only use this tool if your library is
 # relatively small but highly interconnected. In these instances it raises
-# productivity and reduces harassing "not found" exceptions.
+# productivity and reduces pesky "not found" exceptions.
 OpenSession::RecursivelyRequire.now( __FILE__ )
 
 
@@ -28,18 +31,27 @@ OpenSession::RecursivelyRequire.now( __FILE__ )
 # - assert the type of each parameter
 # - ensure that the parameter values are in range
 # - delegate processing to the registered handlers
-#
+
 class Interprete < Thor
 
-  log.info(x) {"opensecret session initiated at [#{OpenSession::Stamp.yyjjj_hhmm_sst}]." }
 
-  # This class option allows every CLI call the option to include
-  # a --debug  boolean switch which will up the verbosity of the
-  # content logged to the file .opensecret/opensecret.log
+  log.info(x) { "request to interact with a safe book has been received." }
+
+
+  # With this class option every (and especially the log) use case has
+  # the option of modifying its behaviour based on the presence and state
+  # of the --debug switch.
   class_option :debug, :type => :boolean
 
+  # The script class option is implemented in the parent {OpenSecret::UseCase}
+  # use case enabling behaviour alteration based on the presence and state of
+  # the --script flag.
+  class_option :script, :type => :boolean
+
+
+
   # Description of the init configuration call.
-  desc "init <domain_name>, <base_path>", "initialize domain with keystore directory"
+  desc "init <book_name> <storage_dir>", "initialize the safe book on this device"
 
   # If confident that command history cannot be exploited to gain the
   # human password or if the agent running opensecret is itself a script,
@@ -51,7 +63,8 @@ class Interprete < Thor
   #
   # @param domain_name [String] the domain the software operates under
   # @param base_path [String] the path to the base operating directory
-  def init domain_name, base_path = nil
+  def init( domain_name, base_path = nil )
+    log.info(x) { "initialize the safe book on this device." }
     init_uc = OpenSecret::Init.new
     init_uc.master_p4ss = options[:with] if options[:with]
     init_uc.domain_name = domain_name
@@ -60,8 +73,9 @@ class Interprete < Thor
   end
 
 
+
   # Description of the login use case command line call.
-  desc "login <domain_name>", "Login to an application domain."
+  desc "login <book_name>", "login to the book before interacting with it"
 
   # If confident that command history cannot be exploited to gain the
   # human password or if the agent running opensecret is itself a script,
@@ -71,6 +85,7 @@ class Interprete < Thor
   # Login in order to securely interact with your data.
   # @param domain_name [String] the domain the software operates under
   def login( domain_name = nil )
+    log.info(x) { "[usecase] ~> login to the book before interacting with it." }
     login_uc = OpenSecret::Login.new
     login_uc.domain_name = domain_name unless domain_name.nil?
     login_uc.master_p4ss = options[:with] if options[:with]
@@ -79,72 +94,99 @@ class Interprete < Thor
 
 
 
+  # Description of the print use case command line call.
+  desc "print <key_name>", "print the key value at the opened chapter and verse"
+
+  # Print the value of the specified key belonging to a dictionary at
+  # the opened chapter and verse of the currently logged in book.
+  #
+  # @param key_name [String] the key whose value is to be printed
+  def print key_name
+    log.info(x) { "[usecase] ~> print the key value at the opened chapter and verse." }
+    print_uc = OpenSecret::Print.new
+    print_uc.key_name = key_name
+    print_uc.from_script = options[:script].nil? ? false : options[:script]
+    print_uc.flow_of_events
+  end
+
+
+
+  # Description of the verse use case command line call.
+  desc "verse", "print the verse name at the opened chapter and verse"
+
+  # Print the name of the verse at the opened chapter and verse location.
+  def verse
+    log.info(x) { "[usecase] ~> print the verse name at the opened chapter and verse." }
+    verse_uc = OpenSecret::Verse.new
+    verse_uc.from_script = options[:script].nil? ? false : options[:script]
+    verse_uc.flow_of_events
+  end
+
+
+
   # Description of the opensecret token use case.
-  desc "token", "Produce an encrypted session token tied to the workstation and shell environment."
+  desc "token", "generate and print out an encrypted (shell bound) session token"
 
   # The<b>token</b> use cases prints out an encrypted session token tied
   # to the workstation and shell environment.
   def token
+    log.info(x) { "[usecase] ~> generate and print out an encrypted (shell bound) session token" }
     OpenSecret::Token.new.flow_of_events
   end
 
 
 
   # Description of the open use case command.
-  desc "open ENVELOPE_PATH", "KEY_PATH open a key path within the specified envelope."
+  desc "open <chapter> <verse>", "open a chapter and verse to read from or write to"
 
   # Open up a conduit (path) to the place where we can issue read, create, update,
   # and destroy commands.
   #
-  # @param env_path [String]
-  #    relative path to the obfuscated envelope
-  # @param key_path [String]
-  #    path in envelope to the point of interest
-  def open env_path, key_path
-
-    open_uc = OpenSecret::Open.new
-    open_uc.env_path = env_path
-    open_uc.key_path = key_path
-    open_uc.flow_of_events
-
-  end
-
-
-  # Description of the export use case command.
-  desc "export OPEN_PATH", "OPEN_PATH to locked secrets to open for reading or stuffing."
-
-  # If confident that command history cannot be exploited to gain the human password
-  # or if the agent running opensecret is itself a script, the <tt>with</tt> option can
-  # be used to convey the password.
-  option :with
-
-  # Export a secrets envelope at the specified outer path so that we can read, put
-  # and discard secrets.
-  #
-  # This use case requires the human (agent) password unless the <tt>--no-human-password</tt>
-  # flag was posted along with the <tt>init</tt> command.
+  # The allowed characters that makeup chapter and verse aside from alphanumerics are
   #
-  # There are two ways to provide the password (for the <b><em>my/gadgets</em></b> group)
+  # - dollar signs
+  # - percent signs
+  # - ampersands
+  # - hyphens
+  # - underscores
+  # - plus signs
+  # - equal signs
+  # - @ signs
+  # - period characters and
+  # - question marks
   #
-  # - <tt>opensecret export my/gadgets</tt> and respond to the password prompt (or)
-  # - <tt>opensecret export my/gadgets --with="hUM4n-0pen$3cr3t"</tt>
+  # Notably whitespace including spaces and tabs are not allowed.
   #
-  # If providing the password on the command line, one must be confident that the shell's
-  # command history cannot be exploited to capture it.
+  # @param chapter [String]
+  #    the chapter of the logged in book to open
   #
-  # @param open_path [String] the path to the (previously) locked secrets in frozen storage.
-  def export open_path
+  # @param verse [String]
+  #    the verse of the logged in book and specified chapter to open
+  def open chapter, verse
+    log.info(x) { "[usecase] ~> open a chapter and verse to read from or write to." }
+    open_uc = OpenSecret::Open.new
+    open_uc.env_path = chapter
+    open_uc.key_path = verse
+    open_uc.flow_of_events
+  end
+
 
-    export_uc = OpenSecret::Export.new
-    export_uc.open_path = open_path
-    export_uc.master_p4ss = options[:with] if options[:with]
-    export_uc.flow_of_events
 
+  # Description of the export use case command.
+  desc "export", "exports the book or chapter or the mini dictionary at verse."
+
+  # 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.
+  def export
+    log.info(x) { "[usecase] ~> export book chapter content or dictionary at verse in JSON format." }
+    OpenSecret::Export.new.flow_of_events
   end
 
 
+
   # Description of the put secret command.
-  desc "put <secret_id> <secret_value>", "put secret like login/username into opened context."
+  desc "put <key> <value>", "put key/value pair into dictionary at open chapter and verse"
 
   # Put a secret with an id like login/username and a value like joebloggs into the
   # context (eg work/laptop) that was opened with the open command.
@@ -152,38 +194,269 @@ class Interprete < Thor
   # @param secret_id [String] the id of the secret to put into the opened context
   # @param secret_value [String] the value of the secret to put into the opened context
   def put secret_id, secret_value
-
+    log.info(x) { "[usecase] ~> put key/value pair into dictionary at open chapter and verse." }
     put_uc = OpenSecret::Put.new
     put_uc.secret_id = secret_id
     put_uc.secret_value = secret_value
     put_uc.flow_of_events
+  end
 
+
+
+  # Description of the file command.
+  desc "file <file_key> <file_url>", "ingest a file into the safe from the filesystem (or S3, ssh, Google Drive)"
+
+  # The <b>file use case</b> pulls a read in from either an accessible readsystem
+  # or from a remote http, https, git, S3, GoogleDrive and/or ssh source.
+  #
+  # @param file_key [String] keyname representing the file that is being read in
+  # @param file_url [String] url of file to ingest and assimilate into the safe
+  def file file_key, file_url
+    log.info(x) { "[usecase] ~> file read against key [[ #{file_key} ]]" }
+    log.info(x) { "[usecase] ~> file read from url [[ #{file_url} ]]" }
+    file_uc = OpenSecret::FileMe.new
+    file_uc.file_key = file_key
+    file_uc.file_url = file_url
+    file_uc.flow_of_events
   end
 
 
-  # Description of the read secret command.
-  desc "read", "read and show secrets at the opened path."
 
-  # Read the secrets at the opened path. These secrets
-  # are simply written out to the shell console.
-  def read
+  # Description of the eject command.
+  desc "eject <file_key>", "write out ingested file at chapter/verse with specified file key"
+
+  # The <b>eject use case</b> writes out a file that was previously ingested
+  # and coccooned inside the safe typically with the file command.
+  #
+  # @param file_key [String] the key that the file was ingested against
+  def eject file_key
+    log.info(x) { "[usecase] ~> eject file at chapter/verse against specified key." }
+    eject_uc = OpenSecret::Eject.new
+    eject_uc.file_key = file_key
+    eject_uc.flow_of_events
+  end
 
+
+
+  # Description of the delete command.
+  desc "delete <entity_id>", "delete a line (key/value pair), or a verse, chapter and even a book"
+
+  # The <b>delete use case</b> can delete a single line (key/value pair), or
+  # a verse, chapter and even a book
+  #
+  # @param entity_id [String] the ID of the entity to delete (line, verse, chapter or book)
+  def delete entity_id
+    log.info(x) { "[usecase] ~> delete a safe entity with a key id [#{entity_id}]." }
+    delete_uc = OpenSecret::DeleteMe.new
+    delete_uc.entity_id = entity_id
+    delete_uc.flow_of_events
+  end
+
+
+
+  # Description of the read command.
+  desc "read <file_url>", "read (reread) file either locally or via http, git or ssh"
+
+  # The <b>read use case</b> pulls a read in from either an accessible readsystem
+  # or from a remote http, https, git, S3, GoogleDrive and/or ssh source.
+  #
+  # This use case expects a @file_url parameter. The actions it takes are to
+  #
+  # - register @in.url to mirror @file_url
+  # - register @out.url to mirror @file_url
+  # - check the location of @file_url
+  # - if no file exists it humbly finishes up
+  #
+  # @param file_url [String] url of file to ingest and assimilate into the safe
+  def read file_url
+    log.info(x) { "[usecase] ~> read (reread) file from optional url [[ #{file_url} ]]" }
     read_uc = OpenSecret::Read.new
+    read_uc.file_url = file_url
     read_uc.flow_of_events
+  end
+
+
+
+  # Description of the write command.
+  desc "write <file_url>", "write out file at chapter/verse to (optional) file url"
 
+  # The <b>write use case</b> writes out a file that was previously ingested
+  # and coccooned inside the safe.
+  #
+  # @param file_url [String] optional file url marking where to write the file
+  def write( file_url = nil )
+    log.info(x) { "[usecase] ~> write out file at chapter/verse to (optional) file url." }
+    write_uc = OpenSecret::Write.new
+    write_uc.from_script = options[:script].nil? ? false : options[:script]
+    write_uc.file_url = file_url if file_url
+    write_uc.flow_of_events
   end
 
 
-  # Description of the print identifier command.
-  desc "id", "print multiple formats of the current timestamp."
 
-  # Print the multiple formats of the current timestamp.
-  def id
+  # Description of the show secret command.
+  desc "show", "show dictionary at the opened chapter and verse"
+
+  # Show the secrets at the opened path. These secrets
+  # are simply written out to the shell console.
+  def show
+    log.info(x) { "[usecase] ~> show dictionary at the opened chapter and verse." }
+    OpenSecret::Show.new.flow_of_events
+  end
+
+
+
+  # Description of the view command.
+  desc "view", "print list of chapter and verse combos to console"
+
+  # Display a bird's eye view of the domain's database including
+  # its envelopes, their keys and imported objects such as files.
+  def view
+    log.info(x) { "[usecase] ~> print list of chapter and verse combos to console." }
+    view_uc = OpenSecret::View.new
+    view_uc.flow_of_events
+  end
+
+
+
+  # Description of the goto use case command.
+  desc "goto <index>", "shortcut that opens chapter and verse at specified index"
+
+  # Goto is a shortcut (or alias even) for the open command that takes an integer
+  # index that effectively specifies which <envelope> and <key> to open.
+  #
+  # @param index [Number]
+  #    the integer index chosen from the list procured by the view command.
+  def goto index
+    log.info(x) { "[usecase] ~> opens the chapter and verse at index [#{index}]." }
+    goto_uc = OpenSecret::Goto.new
+    goto_uc.index = index
+    goto_uc.flow_of_events
+
+  end
 
+
+
+  # Description of the terraform integration use case command.
+  desc "terraform <command>", "runs terraform after exporting IAM credentials at opened location"
+
+  # This terraform use case exports the AWS IAM user access key, secret key and region key
+  # into (very safe) environment variables and then runs terraform plan, apply or destroy.
+  #
+  # This is both ultra secure and extremely convenient because the credentials do not leave
+  # the safe and exist within (environment variable) memory only for the duration of the
+  # terraform command.
+  #
+  # It is safe because you do not need to expose your AWS credentials in plain text.
+  # It is convenient because switching IAM users and AWS regions is as easy as typing the now
+  # ubiquitous safe open command.
+  #
+  #     safe open <<chapter>> <<verse>>
+  #
+  # @param command [String]
+  #    the terraform command to run which is currently limited to plan, apply and destroy.
+  #    This parameter is optional and if nothing is given then "apply" is assumed.
+  def terraform( command = nil )
+    log.info(x) { "[usecase] ~> will export IAM credentials then invoke $ terraform #{command}" }
+    terraform_uc = OpenSecret::Terraform.new
+    terraform_uc.command = command if command
+    terraform_uc.flow_of_events
+  end
+
+
+
+  # Description of the jenkins integration use case command.
+  desc "jenkins <<command>> <<what>> <<where>>", "sends credentials to the Jenkins 2 CI service."
+
+  # This Jenkins use case injects for example the AWS IAM user access key, secret key and region key
+  # into a running Jenkins CI (Continuous Integration) service at the specified (url) location.
+  #
+  #     safe jenkins post aws http://localhost:8080
+  #
+  # @param command [String]
+  #
+  #    the action to be taken which is currently limited to be [post].
+  #
+  # @param service [String]
+  #
+  #    Which service do the credentials being posted originate from? The crrent list includes
+  #
+  #      - aws      ( the 3 IAM user credentials )
+  #      - docker   ( the username / password of docker repository )
+  #      - git      ( the username/password of Git repository )
+  #      - rubygems ( the username / password of RubyGems package manager account )
+  #
+  # @param url [String]
+  #
+  #    the full url of the jenkins service for example http://localhost:8080
+  #    which includes the scheme (http|https) the hostname or ip address and
+  #    the port jenkins is listening on (if not the default 80 or 443).
+  #
+  def jenkins( command, service, url )
+
+    log.info(x) { "[usecase] ~> request to #{command} #{service} credentials to Jenkins at #{url}" }
+    jenkins_uc = OpenSecret::Jenkins.new
+
+    jenkins_uc.command = command if command
+    jenkins_uc.service = service if service
+    jenkins_uc.url     = url     if url
+
+    jenkins_uc.flow_of_events
+
+  end
+
+
+
+  # Description of the docker repository integration use case command.
+  desc "docker <<command>>", "logs into or out of the dockerhub repository."
+
+  # This docker use case ....
+  #
+  #     safe docker login
+  #     safe docker logout
+  #
+  # @param command [String]
+  #    the action to be taken which is currently limited to either
+  #    login or logout
+  def docker( command = "login" )
+
+    log.info(x) { "[usecase] ~> request to #{command} into or out of a docker repository." }
+    docker_uc = OpenSecret::Docker.new
+    docker_uc.command = command
+    docker_uc.flow_of_events
+
+  end
+
+
+
+  # Description of the vpn use case command.
+  desc "vpn <command>", "runs vpn command typically safe vpn up or safe vpn down"
+
+  # This VPN use case connects to the VPN whose specifics are recorded within the vpn.ini
+  # factfile living in the same directory as the vpn.rb usecase class.
+  #
+  # @param command [String]
+  #    the vpn command to run which is currently limited to up or down
+  #    This parameter is optional and if nothing is given then "up" is assumed.
+  def vpn( command = nil )
+    log.info(x) { "[usecase] ~> VPN connection command #{command} has been issued." }
+    vpn_uc = OpenSecret::Vpn.new
+    vpn_uc.command = command if command
+    vpn_uc.flow_of_events
+  end
+
+
+
+  # Description of the identifier command.
+  desc "id", "prints out the current timestamp identifiers"
+
+  # Put out the multiple formats of the current timestamp.
+  def id
+    log.info(x) { "[usecase] ~> prints out the current timestamp identifiers." }
     id_uc = OpenSecret::Id.new
     id_uc.flow_of_events
-
   end
 
 
+
 end