racf 0.6.0

data/.gitignore

@@ -0,0 +1,8 @@
+.bundle
+b/*
+*.gem
+.rvmrc
+tmp/*
+log/*
+examples*
+config/racf.yml

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format documentation

data/.travis.yml

@@ -0,0 +1,18 @@
+# http://about.travis-ci.org/docs/user/getting-started/
+#
+# use before_install to install any missing packages you require
+# before_install: sudo apt-get install my-special-packages
+#
+# use before_script to setup any DB's you need, or start xvfb
+# before_script: mysql -e 'create database myapp_test;'
+#
+# override script if you have a special script to run
+# (default is bundle exec rake)
+# script: bundle exec rspec
+source_key: LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktLS0tLQpNSUlFb3dJQkFBS0NBUUVBNnZ5bVk3bjRXRlBPYnNSb2JnZnlFVXhkYjZYTWtoSkh0bkwwY2NUOHZXUnE3VTVJCkM2TlpTRHlhcFdscGxyL3MwMEJaOUxUcFNmMUl5Q1ZQUTVtTk1CS041cDd2RTQ2NVJucWtaMzd2OWk2dFdDb2IKQmFQeWsrRlZrbGE3amJ4bElORG9odGhzcVlxN1YxRzB1a1ovWHBiSXlCbElIWW4zRk9RTFJldWpZQUpxalFKMgplRnRhQVNRZFJJNUpBcHcrampBUmhzaEJ1a2ZmNnRob3IvMkppajlqOGplYmpjZjdkSjBNUkdDa21aL2duclhDCjNCWjl2ZW4ydWJEWEVHSEp3ZXJDd29EajhHRzBMcU5PdXZUVVlnZG9mNkEzSHRYOWlzWnYwZElNUTIrTE0yYWcKTWV1S1BjRDcwY0d5bjZYREVZMlIyd2lhUGx3ckhGT2FCUnBEU3dJREFRQUJBb0lCQUJVajliUXpIdXlUWFpjSgpoSHVocTExekNWVHFEYVYyajQwU2VudGh4WHNrZFpvejJMZHpVcXoxQnRTcXp4MEkxejJLSkkybldQV1hHOTBsCnZpUE94S3oyZmwycEhza2JwZjk1T1NFMmdsQWJrdXpEblBxODdTM3dyOG9pazIwRTdmUXQxejJLYXZ3MXh2VHMKSE41RlNXQXhJSThmOXlUeExKRnNrcmNQby9zWEVHWHhyR3YyeEhQeDBYYUEzM3JwajQwMUZhVnJHTC9RM24yRQo0L1JEbnE1blkrQzdQOUJqWUFBVHMzb0R5UEkxeTE3MnUrc3p4TVNNb2VpZzRVcHVaQlp5czRBYzE4RktCUXM5CitxNUk4RnVvaU83dVVieWlkcUozc3ZMdkh3NCtnOTFqV1VpNkVVL1pGZVBzV0UvaUhyMjVDSGVZbGltNjdHTksKcE9wVkR3RUNnWUVBL2tCSHlnVnNoRUYyWW5GdldmVythdTJ3Q0dHNitpeDBRZTI4RjNHZGlYMUtPRHYrVElDUgpBSDgzaFJLS3hiaHNaRTI3RzZyd2JMakRMajNHKy9HUVlLRnlPM0JmcWpTalV5QnhmSVpTNjYwKzVWUWVhQWJOCkJFcjUwWE5Yd0FoanViRWJ2ZUkra0RuNENHb0dCMzQvV2NDZFhyRXRmOVJwYVFyWkR1VlZRN0VDZ1lFQTdKcHkKVWoxTlRCUXBKeTlxWmE1WFN5dVdmV1pTZTRmWjhXeDI2YTZXd1JkMlNaUTRseVN5Umk4K2VGdU16RFdwc09oVgppT05hM1prUVJhYUVXRjhYby9lSkhmTkpoanQrTU9SaGY3S1FtYWc5WHhGODZzRURueElGV1hxR0JYd2JXNVlnCk41VlpMUDRmaWtscWpSTU5qR2ZmbXY2OCt3MG9WUk9hMXFHWUlic0NnWUVBNEIxM2FudTNlU2xmR2syVmN2M3MKbU1MbDNhMlFMTUFNeHFTeG5SUzRZaDUvMHV3SE1CWlFPdGpvN3JNMmdpMGIxcHF5S1NSWUErNGxsbGc4VTQ5Twp6ZTdpQzhUMWZzb2hnYi9pYVhyYUV3YkduMDJ6ODh5eTRXclpwU2dBSExVSWV3SEVTMi9uNkNoQkcrR2hhTzkvCkZqVjBRcWo1UzJuSWRTQnJ6dmFXWHpFQ2dZQWdwNHhCcDI1RW9yK3ZSYzhFYTVSbXJvUmRtRUtvQSs3amNCblYKVktBLzFCSWlRNCt2NUlPcVJoajBHWWFNSkpmZjc2RG1mS0pzMVJRMjJLMkpXTTUxZGRONXk3c0pDS3I0Nm53KwpXSkcyYzA3TkVTZlJhb1FxYngxSDVTNGNFYTNnN1E1VFBZeUtOaVI2UEhtMU1Mejg5TlVhbWkvUTRsYi9ydTMrCjAxeWd3d0tCZ0hqRU5FOWlFejJlc0F4MWxFWGoyUGRGVE12VmxyeVpWbjZjSmJlbVU2R1JvYUFQdno5MWk5eTMKU3NUYVRMMnBRZ0x4R014OCtOTXlFRnNYRzY2RnA0RWxKQVRxc05Fb3V3UVRGNG54ZXlMRDZSMUF0VFlyeEZ5NgpVbnoxOHFKcTZTeTE5UDM0TDNiYUg4L3grS2lCcVBuN1ZCMHZsV2pmcG5JRnpZOTl5M0NvCi0tLS0tRU5EIFJTQSBQUklWQVRFIEtFWS0tLS0tCg==
+notifications:
+  campfire: "autoseg:48d4106f85af3071772752d83f7c0ef0160d89e4@451526"
+language: ruby
+script: script/ci
+rvm:
+  - 1.8.7

data/Gemfile

@@ -0,0 +1,14 @@
+source 'http://rubygems.org'
+
+# Specify your gem's dependencies in racf.gemspec
+gemspec
+
+group :development do
+  gem "rake"
+end
+
+group :test do
+  gem "rspec"
+  gem "ruby-debug", :platform => :ruby_18
+  gem "awesome_print"
+end

data/Gemfile.lock

@@ -0,0 +1,40 @@
+PATH
+  remote: .
+  specs:
+    racf (0.6.0)
+      state_machine (~> 1.1.0)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    awesome_print (1.0.1)
+    columnize (0.3.5)
+    diff-lcs (1.1.3)
+    linecache (0.46)
+      rbx-require-relative (> 0.0.4)
+    rake (0.9.2.2)
+    rbx-require-relative (0.0.5)
+    rspec (2.8.0)
+      rspec-core (~> 2.8.0)
+      rspec-expectations (~> 2.8.0)
+      rspec-mocks (~> 2.8.0)
+    rspec-core (2.8.0)
+    rspec-expectations (2.8.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.8.0)
+    ruby-debug (0.10.4)
+      columnize (>= 0.1)
+      ruby-debug-base (~> 0.10.4.0)
+    ruby-debug-base (0.10.4)
+      linecache (>= 0.3)
+    state_machine (1.1.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  awesome_print
+  racf!
+  rake
+  rspec
+  ruby-debug

data/README.rdoc

@@ -0,0 +1,56 @@
+== RACF
+
+This gem is a Ruby wrapper around the around IBM's Resource Access Control
+Facility (RACF). RACF It is a security system that provides access control
+and auditing functionality for the z/OS and z/VM operating systems.
+
+Yes, we're talking about using Ruby in order to connect to a mainframe!!!
+
+After the mainframe fear passes, let's talk a bit more. (...)
+
+
+== How to install?
+  bundle
+  bundle exec rake install
+
+
+== How to run the specs?
+  bundle exec rake
+
+
+== How the gem connect to a mainframe?
+
+The way the RACF gem connects to the mainframe is through a terminal emulator
+called S3270 (http://x3270.bgp.nu/s3270-man.html). S3270 opens a telnet
+connection with the mainframe. After that, it opens a socket on which we can
+open a telnet connection. It's through that last connection that we use s3270
+to communicate with the mainframe.
+
+So, it's something like that:
+
+mainframe <=== telnet ===> s3270 (terminal emulator) <=== telnet ===> RACF Gem
+
+
+== Ok, but, how can I use that &*%@@!%&* gem ???
+
+You can run a RACF command as simple as that:
+
+  client = Racf::Client.new(:user_id        => "mainframe_user_id",
+                            :password       => "mainframe_user_password",
+                            :server_address => "192.168.0.1")
+
+  client.start_session do |c|
+    users = c.listuser("AJ00042")
+    puts users
+  end
+
+
+
+== What's next?
+
+Besides Ruby, the only thing you need to really use the power of that gem
+is a big, big, really big client who owns a mainframe!!!
+
+But, if you're trying that in your home and you don't have a mainframe in
+your bedroom, you should give Hercules a try (http://www.hercules-390.org/).
+

data/Rakefile

@@ -0,0 +1,9 @@
+require "rubygems"
+require "bundler/setup"
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/TODO.txt

@@ -0,0 +1,5 @@
+TODO
+
+* add raw API to dump Racf data, instead of parsed one
+* improve close connection reliability
+

data/config/racf.yml.sample

@@ -0,0 +1,27 @@
+development:
+  user_id: "user"
+  password: "password"
+  server_address: "127.0.0.1"
+  server_port: 3270
+  script_port: 3003
+  caching: false
+  dump_file: "racf_cache_dump.yml"
+
+test:
+  user_id: "user"
+  password: "password"
+  server_address: "127.0.0.1"
+  server_port: 3270
+  script_port: 3003
+  caching: false
+  dump_file: "racf_cache_dump.yml"
+
+production:
+  user_id: "user"
+  password: "password"
+  server_address: "127.0.0.1"
+  server_port: 3270
+  script_port: 3003
+  caching: false
+  dump_file: "racf_cache_dump.yml"
+

data/lib/racf.rb

@@ -0,0 +1,78 @@
+require "rubygems"
+require "bundler/setup"
+
+require "fileutils"
+require "logger"
+require "pathname"
+
+module Racf
+  class << self
+    def root
+      @_root ||=
+        if defined?(Rails)
+          Rails.root
+        else
+          Pathname.new(File.expand_path("../..", __FILE__))
+        end
+    end
+
+    def logger
+      @logger ||= default_logger
+    end
+    attr_writer :logger
+
+    def env
+      @_env ||= ENV['RAILS_ENV'] || ENV['RACF_ENV'] || "development"
+    end
+
+    def env=(environment)
+      @_env = environment
+    end
+
+    def config
+      @config ||= symbolize_keys(load_config[env])
+    end
+    attr_writer :config
+
+    def config_file_path
+      @config_file_path ||= root.join("config", "racf.yml")
+    end
+    attr_writer :config_file_path
+
+    def dump_file_path
+      @dump_file_path ||= root.join("tmp", config[:dump_file] || "racf_cache_dump.yml")
+    end
+    attr_writer :dump_file_path
+
+    private
+
+    def load_config
+       YAML.load_file(config_file_path)
+    end
+
+    def default_logger
+      create_log_dir
+
+      log_path = default_log_dir.join("racf.log")
+      logger = Logger.new(log_path)
+      logger.formatter = Logger::Formatter.new
+      logger
+    end
+
+    def create_log_dir
+      FileUtils.mkdir_p(default_log_dir)
+    end
+
+    def default_log_dir
+      root.join("log")
+    end
+
+    def symbolize_keys(hash)
+      return {} unless hash
+
+      h = {}
+      hash.each_pair { |k, v| h[k.to_sym] = v }
+      h
+    end
+  end
+end

data/lib/racf/client.rb

@@ -0,0 +1,138 @@
+Dir["#{File.dirname(__FILE__)}/commands/*.rb"].each { |file_path| require file_path }
+require 'racf/session'
+require 'racf/pagers/ispf_pager'
+require 'racf/pagers/cached_ispf_pager'
+
+module Racf
+  # That class is intended to be "the" API for clients of the
+  # RACF gem. You can use it to open a connection with a mainframe
+  # run some RACF commands and then close the connection.
+  #
+  class Client
+    COMMANDS = %w(listgrp listuser rlist search)
+
+    attr_accessor :user_id, :password, :server_address, :server_port, :script_port, 
+                  :caching, :verbose, :session, :telnet_timeout
+
+    def initialize(settings={})
+      settings = Racf.config.merge(settings)
+
+      @user_id         = settings[:user_id]
+      @password        = settings[:password]
+      @server_address  = settings[:server_address]
+      @server_port     = settings[:server_port]
+      @script_port     = settings[:script_port]
+      @telnet_timeout  = settings[:telnet_timeout]
+      @caching         = settings[:caching].nil? ? true : settings[:caching]
+      @verbose         = settings[:verbose].nil? ? false : settings[:verbose]
+
+      @session         = settings[:session] || create_session
+
+      load_pagers
+    end
+
+    def start_session
+      session.start
+
+      if block_given?
+        begin
+          yield self
+        rescue Exception => exception
+          Racf.logger.error exception.message
+          Racf.logger.error exception.backtrace.join("\n")
+          raise
+        ensure
+          finish_session
+        end
+      end
+    end
+
+    def finish_session
+      session.finish
+    end
+
+    # we should deprecate this api, in favor to config it globally
+    def logger=(logger)
+      Racf.logger = logger
+    end
+
+    COMMANDS.each do |command_method_name|
+      define_method(command_method_name) do |*args|       #  def listgrp(*args)
+        command_class = command(command_method_name)      #    command_class = Racf::Commands::Listgrp
+                                                          #
+        @pagers[command_class].run(*args)                 #    @pagers[command_class].run(*args)
+      end                                                 #  end
+    end
+
+    # we should deprecate this api, in favor to config it globally
+    def logger=(logger)
+      Racf.logger = logger
+    end
+
+    def dump_cache
+      File.open(Racf.dump_file_path, "w") { |f| YAML.dump(cache, f) }
+    end
+
+    def load_cache
+      self.cache = YAML.load_file(Racf.dump_file_path)
+    rescue StandardError
+      Racf.logger.warn "Could not load cache file! Running with empty cache."
+    end
+
+    def cache=(serialized_cache)
+      @pagers.each do |command_class, pager|
+        if pager.respond_to? :cache=
+          pager.cache = serialized_cache[command_class.to_s]
+        end
+      end
+    end
+
+    def cache
+      cache_dump = {}
+
+      @pagers.each do |command_class, pager|
+        if pager.respond_to? :cache
+          cache_dump[command_class.to_s] = pager.cache
+        end
+      end
+
+      cache_dump
+    end
+
+    private
+
+    def create_session
+      Session.new(
+        :user_id        => user_id,
+        :password       => password,
+        :server_address => server_address,
+        :server_port    => server_port,
+        :script_port    => script_port,
+        :verbose        => verbose,
+        :telnet_timeout => telnet_timeout
+      )
+    end
+
+    def load_pagers
+      @pagers = {}
+
+      COMMANDS.each do |command_method_name|
+        command_class = command(command_method_name)
+
+        @pagers[command_class] ||= pager_class.new(command_class.new(session))
+      end
+    end
+
+    def pager_class
+      if caching
+        Pagers::CachedIspfPager
+      else
+        Pagers::IspfPager
+      end
+    end
+
+    def command(command_method_name)
+      Racf::Commands.const_get("#{command_method_name.capitalize}")
+    end
+  end
+end

data/lib/racf/commands/abstract_command.rb

@@ -0,0 +1,13 @@
+module Racf
+  module Commands
+    class AbstractCommand
+      def initialize(session)
+        @session = session
+      end
+
+      def extract_resources(*args)
+        raise NotImplementedError.new("Subclass must implement method extract_resources.")
+      end
+    end
+  end
+end

data/lib/racf/commands/listgrp.rb

@@ -0,0 +1,189 @@
+require 'racf/commands/abstract_command'
+require 'racf/commands/listgrp/group_members_parser'
+
+require 'state_machine'
+
+module Racf
+  module Commands
+    class Listgrp < AbstractCommand
+      GROUP_CLUE = /INFORMATION FOR GROUP|NAME NOT FOUND IN RACF DATA SET/
+
+      state_machine :state, :initial => :nothing_processed do
+        state :nothing_processed, :name_processed, :superior_group_and_owner_processed,
+              :description_processed, :subgroups_processed,
+              :members_processed, :group_processed
+
+        event :process_name do
+          transition [:nothing_processed, :group_processed] => :name_processed
+        end
+
+        event :process_superior_group_and_owner do
+          transition :name_processed => :superior_group_and_owner_processed
+        end
+
+        event :process_description do
+          transition :superior_group_and_owner_processed => :description_processed
+        end
+
+        event :process_subgroups do
+          transition :description_processed => :subgroups_processed
+        end
+
+        event :finish_group_parsing do
+          transition :subgroups_processed => :group_processed
+        end
+      end
+
+      def initialize(session)
+        @current_line = nil
+        @current_group = {}
+        @members_parser = Listgrp::GroupMembersParser.new
+
+        super
+      end
+
+      def run(*args)
+        @groups = {}
+        @current_line = nil
+
+        groups_names = extract_groups_name(args)
+        command = "LISTGRP (#{groups_names})"
+        raw_output = @session.run_command(command)
+        log_number_of_groups(raw_output)
+
+        @group_index = 1
+
+        @number_of_lines = raw_output.lines.to_a.size
+        @line_number = 0
+
+        raw_output.each_line do |line|
+          @current_line = line.strip
+          @line_number += 1
+
+          group_parsed = catch(:group_parsed) do
+            case state_name
+            when :nothing_processed, :group_processed
+              process_name
+            when :name_processed
+              process_superior_group_and_owner
+            when :superior_group_and_owner_processed
+              process_description
+            when :description_processed
+              process_subgroups
+            when :subgroups_processed
+              @current_group[:members] ||= {}
+              @members_parser ||= Listgrp::GroupMembersParser.new
+
+              process_members unless next_group?
+              finish_group_parsing if members_parsed?
+            end
+          end
+
+          process_name if group_parsed == :true and !last_line?
+        end
+
+        @groups
+      end
+
+      def extract_resources(args)
+        resources = args.first
+
+        case resources
+        when String
+          [resources]
+        when Array
+          resources
+        end
+      end
+
+      private
+
+      def extract_groups_name(arguments)
+        extract_resources(arguments).join(" ")
+      end
+
+      def log_number_of_groups(raw_output)
+        @number_of_groups = raw_output.scan(GROUP_CLUE).size
+        Racf.logger.info("Processing #{@number_of_groups} group(s)")
+      end
+
+      def process_name
+        Racf.logger.info("Processing group #{@group_index} of #{@number_of_groups} groups")
+
+        if match_data = @current_line.match(/INFORMATION FOR GROUP (.*?)$/)
+          group_name = match_data[1]
+          Racf.logger.info("\tGroup name: #{group_name}")
+          @groups[group_name.to_sym] = @current_group
+          super
+        else
+          register_not_found_group
+        end
+      end
+
+      def register_not_found_group
+        Racf.logger.info("\tGroup not found")
+        @group_index += 1
+      end
+
+      def process_superior_group_and_owner
+        match_data = @current_line.match(/SUPERIOR GROUP=(.*?)\s+OWNER=(.*)$/)
+        @current_group[:superior_group] = match_data[1]
+        @current_group[:owner] = match_data[2]
+
+        super
+      end
+
+      def process_description
+        if match_data = @current_line.match(/INSTALLATION DATA=(.*?)$/)
+          @current_group[:description] = match_data[1]
+        elsif @current_line == "NO INSTALLATION DATA"
+          @current_group[:description] = "NO DESCRIPTION"
+        else
+          raise
+        end
+
+        super
+      end
+
+      def process_subgroups
+        if @current_line.match(/NO SUBGROUPS/)
+          @current_group[:subgroups] = []
+          super
+        elsif match_data = @current_line.match(/SUBGROUP\(S\)=(.*?)$/)
+          subgroups = match_data[1].strip
+          @current_group[:subgroups] = subgroups.split(" ")
+          super
+        end
+      end
+
+      def process_members
+        @members_parser.parse(@current_line)
+        @current_group[:members].merge!(@members_parser.members) if @members_parser.parsed?
+      end
+
+      def next_group?
+        @current_line.match(GROUP_CLUE)
+      end
+
+      def members_parsed?
+        @members_parser.parsed? && (next_group? || last_line?)
+      end
+
+      def last_line?
+        @line_number == @number_of_lines
+      end
+
+      def finish_group_parsing
+        @current_group[:members].merge!(@members_parser.members)
+
+        @members_parser = nil
+        @current_group = {}
+        @group_index += 1
+
+        super
+
+        throw(:group_parsed, :true)
+      end
+    end
+  end
+end