legion-logging 1.2.5 → 1.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c5c68f56d267c3653df2d9a713072d2ab81445f437f64761e23ebd4bc8323e73
-  data.tar.gz: f78f23e438594a7eab25499a154b27d9fb0d043c54773c72c2f63affb9aa76b6
+  metadata.gz: d4a463a1d341069c5c5ed0f15e98dfc25a3572e440bbba3f09d63ffc825c7f0f
+  data.tar.gz: 5e6a1dbbec201fb5fcd4e4c6d000ecba84f53bf78a5f25f74e5b75145ff11683
 SHA512:
-  metadata.gz: 05a90fe04d73b187c72bb1d5bdc732ae2b314670306174bf0430f0e996bab0ed7e76fa51209a7dd295c94f5b4bac173a67032de51f5d7d2e89fee5ddcf26c361
-  data.tar.gz: 2a3b358b39146cb6e7bb6971f5cd7e881a528df16bd8823bea4cfa7cd8877f09bb9d8c57770176274e1a44e09b2731a86ae39354cc1ba4966aa76685b7d36eeb
+  metadata.gz: dae39ad0842e8fdf132993d465a9ff6bedab0e6174bf42c9f9ab4ffad98377d3352b6ecc3aca218480fb2c6be9eb36c9efb80c0230e0c95a2dbe2011da6461ad
+  data.tar.gz: 07c5e18d680c68e83bd03a3d20f64a2cf9ab62c513a00773d5a55a58e9f7c3fcf0f98268b8b3a63de8e18509fe0a237922e4eec6de64132a815e970da96d2a33

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Legion::Logging Changelog
 
+## v1.2.6
+
+### Added
+- `Legion::Logging::Redactor`: PII/PHI redaction module with built-in patterns for SSN, email, phone, MRN, DOB, and credit card numbers
+- Sensitive field-name redaction: fields named `password`, `secret`, `token`, `api_key`, `authorization` are always fully redacted
+- Recursive redaction of nested hashes and arrays
+- Custom pattern support via `Legion::Settings[:logging, :redactor, :custom_patterns]`
+- `Legion::Logging::Shipper`: structured log event forwarding to external collectors with batch buffering and level filtering
+- `Legion::Logging::Shipper::FileTransport`: writes JSON-lines to rotated log files for pickup by Filebeat/Fluentd
+- `Legion::Logging::Shipper::HttpTransport`: POSTs JSON batches to HTTP endpoints (Splunk HEC, ELK Logstash)
+- All SIEM shipping features disabled by default; opt-in via `logging.shipper.enabled: true`
+
 ## v1.2.5
 
 ### Fixed

data/CLAUDE.md

@@ -8,16 +8,19 @@
 Ruby logging class for the LegionIO framework. Provides colorized console output via Rainbow, structured JSON logging (`format: :json`), and a consistent logging interface across all Legion gems and extensions.
 
 **GitHub**: https://github.com/LegionIO/legion-logging
+**Version**: 1.2.5
 **License**: Apache-2.0
 
 ## Architecture
 
 ```
 Legion::Logging (singleton module)
-├── Methods    # Log level methods: debug, info, warn, error, fatal, unknown
-├── Builder    # Output destination (stdout/file), log level, formatter
-├── Logger     # Core logger configuration and setup
-└── Version    # VERSION constant
+├── Methods         # Log level methods: debug, info, warn, error, fatal, unknown
+├── Builder         # Output destination (stdout/file), log level, formatter
+├── Logger          # Core logger configuration and setup
+├── MultiIO         # Write to multiple destinations simultaneously
+├── SIEMExporter    # PHI-redacting SIEM export (Splunk HEC, ELK/OpenSearch)
+└── Version         # VERSION constant (1.2.5)
 ```
 
 ### Key Design Patterns
@@ -27,6 +30,8 @@ Legion::Logging (singleton module)
 - **Setup Method**: `Legion::Logging.setup(log_file:, level:)` configures output destination and level
 - **Structured JSON**: `format: :json` in settings outputs machine-parseable JSON log lines
 - **Shared Interface**: Same method signature (`info`, `warn`, `error`, etc.) across all Legion components
+- **MultiIO**: Splits writes to stdout and a log file simultaneously (used by Builder when `log_file` is set)
+- **SIEMExporter**: PHI redaction (SSN, phone, MRN, DOB patterns), `export_to_splunk` (HEC), `format_for_elk`
 
 ## Dependencies
 
@@ -43,6 +48,7 @@ Legion::Logging (singleton module)
 | `lib/legion/logging/builder.rb` | Output config and formatter |
 | `lib/legion/logging/logger.rb` | Core logger setup |
 | `lib/legion/logging/multi_io.rb` | Multi-output IO (write to multiple destinations simultaneously) |
+| `lib/legion/logging/siem_exporter.rb` | PHI-redacting SIEM export helpers (Splunk HEC, ELK format) |
 | `lib/legion/logging/version.rb` | VERSION constant |
 
 ## Role in LegionIO

data/Gemfile

@@ -3,6 +3,9 @@
 source 'https://rubygems.org'
 
 gemspec
+
+gem 'logger'
+
 group :test do
   gem 'rake'
   gem 'rspec'

data/README.md

@@ -1,6 +1,8 @@
 # legion-logging
 
-Logging module for the [LegionIO](https://github.com/LegionIO/LegionIO) framework. Provides colorized console output via Rainbow and a consistent logging interface across all Legion gems and extensions.
+Logging module for the [LegionIO](https://github.com/LegionIO/LegionIO) framework. Provides colorized console output via Rainbow, structured JSON logging, multi-output IO, and a consistent logging interface across all Legion gems and extensions.
+
+**Version**: 1.2.5
 
 ## Installation
 
@@ -39,6 +41,27 @@ Legion::Logging.setup(level: 'info', format: :json)
 
 This is useful for log aggregation pipelines (Elasticsearch, Splunk, etc.).
 
+### Multi-Output IO
+
+`Legion::Logging::MultiIO` writes to multiple destinations simultaneously — for example, stdout and a file at the same time. Used internally by the Builder when `log_file` is set alongside console output.
+
+### SIEM Export
+
+`Legion::Logging::SIEMExporter` provides PHI-redacting export helpers for security event pipelines:
+
+```ruby
+# Redact PHI patterns (SSN, phone, MRN, DOB) from a string
+clean = Legion::Logging::SIEMExporter.redact_phi(raw_message)
+
+# Export to Splunk HEC
+Legion::Logging::SIEMExporter.export_to_splunk(event, hec_url: url, token: token)
+
+# Format for ELK/OpenSearch
+Legion::Logging::SIEMExporter.format_for_elk(event, index: 'legion')
+```
+
+PHI patterns redacted: SSN (`###-##-####`), phone (`###-###-####`), MRN (`XX#######`), DOB (`##/##/####`).
+
 ## Requirements
 
 - Ruby >= 3.4

data/lib/legion/logging/redactor.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Legion
+  module Logging
+    module Redactor
+      PATTERNS = {
+        ssn:         /\b\d{3}-\d{2}-\d{4}\b/,
+        email:       /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/,
+        phone:       /\b(?:\+1[-.\s]?)?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}\b/,
+        mrn:         /\bMRN[:\s]*\d{6,10}\b/i,
+        dob:         %r{\bDOB[:\s]*\d{1,2}[/-]\d{1,2}[/-]\d{2,4}\b}i,
+        credit_card: /\b\d{4}[-\s]?\d{4}[-\s]?\d{4}[-\s]?\d{4}\b/
+      }.freeze
+
+      SENSITIVE_FIELDS = %w[password secret token api_key authorization].freeze
+
+      REDACTED = '[REDACTED]'
+
+      class << self
+        def redact(event)
+          return event unless event.is_a?(Hash)
+
+          event.each_with_object({}) do |(key, value), result|
+            result[key] = sensitive_field?(key) ? REDACTED : redact_value(value)
+          end
+        end
+
+        def redact_value(value)
+          case value
+          when String then redact_string(value)
+          when Hash   then redact(value)
+          when Array  then value.map { |v| redact_value(v) }
+          else value
+          end
+        end
+
+        def redact_string(str)
+          result = str.dup
+          all_patterns.each_value { |pattern| result.gsub!(pattern, REDACTED) }
+          result
+        end
+
+        private
+
+        def sensitive_field?(key)
+          SENSITIVE_FIELDS.include?(key.to_s.downcase)
+        end
+
+        def all_patterns
+          @all_patterns ||= build_patterns
+        end
+
+        def build_patterns
+          patterns = PATTERNS.dup
+          custom = custom_patterns
+          custom.each { |name, regex| patterns[name.to_sym] = regex }
+          patterns
+        end
+
+        def custom_patterns
+          return {} unless defined?(Legion::Settings)
+
+          raw = Legion::Settings[:logging, :redactor, :custom_patterns]
+          return {} unless raw.is_a?(Hash)
+
+          raw.each_with_object({}) do |(name, pattern_str), acc|
+            acc[name] = Regexp.new(pattern_str)
+          rescue RegexpError
+            # skip invalid patterns
+          end
+        end
+
+        def reset_pattern_cache!
+          @all_patterns = nil
+        end
+      end
+    end
+  end
+end

data/lib/legion/logging/shipper/file_transport.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'json'
+
+module Legion
+  module Logging
+    module Shipper
+      module FileTransport
+        DEFAULT_PATH = '/var/log/legion/siem.log'
+
+        class << self
+          def ship(event)
+            path = resolve_path
+            FileUtils.mkdir_p(File.dirname(path))
+            File.open(path, 'a') do |f|
+              f.puts(::JSON.generate(event))
+            end
+            true
+          rescue StandardError => e
+            Legion::Logging.error("FileTransport ship failed: #{e.message}") if defined?(Legion::Logging)
+            false
+          end
+
+          private
+
+          def resolve_path
+            return settings_path if settings_path
+
+            DEFAULT_PATH
+          end
+
+          def settings_path
+            return nil unless defined?(Legion::Settings)
+
+            Legion::Settings[:logging, :shipper, :file, :path]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/logging/shipper/http_transport.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+require 'uri'
+
+module Legion
+  module Logging
+    module Shipper
+      module HttpTransport
+        class << self
+          def ship(events)
+            endpoint = resolve_endpoint
+            return false unless endpoint
+
+            uri   = URI(endpoint)
+            batch = Array(events)
+            body  = build_body(batch, uri)
+
+            response = post(uri, body)
+            response.is_a?(Net::HTTPSuccess)
+          rescue StandardError => e
+            Legion::Logging.error("HttpTransport ship failed: #{e.message}") if defined?(Legion::Logging)
+            false
+          end
+
+          private
+
+          def post(uri, body)
+            req = Net::HTTP::Post.new(uri)
+            req['Content-Type'] = 'application/json'
+            apply_auth(req)
+
+            Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https',
+                                                     open_timeout: 5, read_timeout: 10) do |http|
+              http.request(req, body)
+            end
+          end
+
+          def build_body(events, uri)
+            # Splunk HEC expects { event: ... } per event; others expect an array
+            if splunk_hec?(uri)
+              events.map { |e| ::JSON.generate({ event: e, time: Time.now.to_f }) }.join("\n")
+            else
+              ::JSON.generate(events)
+            end
+          end
+
+          def splunk_hec?(uri)
+            uri.path.include?('/services/collector')
+          end
+
+          def apply_auth(req)
+            token = auth_token
+            return unless token
+
+            req['Authorization'] = if splunk_hec?(URI(req.path.empty? ? '/' : req.uri&.to_s || '/'))
+                                     "Splunk #{token}"
+                                   else
+                                     "Bearer #{token}"
+                                   end
+          end
+
+          def auth_token
+            return nil unless defined?(Legion::Settings)
+
+            Legion::Settings[:logging, :shipper, :auth_token]
+          end
+
+          def resolve_endpoint
+            return nil unless defined?(Legion::Settings)
+
+            Legion::Settings[:logging, :shipper, :endpoint]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legion/logging/shipper.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require_relative 'redactor'
+require_relative 'shipper/file_transport'
+require_relative 'shipper/http_transport'
+
+module Legion
+  module Logging
+    module Shipper
+      LEVEL_ORDER = %w[debug info warn error fatal].freeze
+
+      TRANSPORTS = {
+        file: FileTransport,
+        http: HttpTransport
+      }.freeze
+
+      class << self
+        def ship(event)
+          return unless enabled?
+          return unless shippable_level?(event[:level] || event['level'])
+
+          redacted  = Redactor.redact(event)
+          transport = TRANSPORTS[transport_type]
+          buffer_event(redacted) if transport
+        end
+
+        def flush
+          return if @buffer.nil? || @buffer.empty?
+
+          transport = TRANSPORTS[transport_type]
+          return unless transport
+
+          batch = nil
+          @mutex.synchronize do
+            batch = @buffer.dup
+            @buffer.clear
+          end
+
+          deliver(transport, batch)
+        end
+
+        def start
+          return unless enabled?
+          return if @flush_thread&.alive?
+
+          @buffer = []
+          @mutex  = Mutex.new
+          interval = flush_interval
+          @flush_thread = Thread.new do
+            loop do
+              sleep interval
+              flush
+            end
+          end
+          @flush_thread.abort_on_exception = false
+        end
+
+        def stop
+          @flush_thread&.kill
+          @flush_thread = nil
+          flush
+        end
+
+        def enabled?
+          return false unless defined?(Legion::Settings)
+
+          Legion::Settings[:logging, :shipper, :enabled] == true
+        end
+
+        private
+
+        def buffer_event(event)
+          @buffer  ||= []
+          @mutex   ||= Mutex.new
+
+          full = false
+          @mutex.synchronize do
+            @buffer << event
+            full = @buffer.size >= batch_size
+          end
+
+          flush if full
+        end
+
+        def deliver(transport, batch)
+          if transport.method(:ship).arity == 1
+            # HttpTransport accepts a batch array
+            transport.ship(batch)
+          else
+            batch.each { |e| transport.ship(e) }
+          end
+        rescue StandardError => e
+          Legion::Logging.error("Shipper deliver failed: #{e.message}") if defined?(Legion::Logging)
+        end
+
+        def shippable_level?(level)
+          return true if level.nil?
+
+          min = minimum_level
+          LEVEL_ORDER.index(level.to_s.downcase).to_i >= LEVEL_ORDER.index(min).to_i
+        end
+
+        def transport_type
+          return :file unless defined?(Legion::Settings)
+
+          key = Legion::Settings[:logging, :shipper, :transport]
+          key ? key.to_sym : :file
+        end
+
+        def batch_size
+          return 100 unless defined?(Legion::Settings)
+
+          Legion::Settings[:logging, :shipper, :batch_size] || 100
+        end
+
+        def flush_interval
+          return 5 unless defined?(Legion::Settings)
+
+          Legion::Settings[:logging, :shipper, :flush_interval] || 5
+        end
+
+        def minimum_level
+          return 'warn' unless defined?(Legion::Settings)
+
+          levels = Legion::Settings[:logging, :shipper, :levels]
+          return 'warn' unless levels.is_a?(Array) && !levels.empty?
+
+          levels.min_by { |l| LEVEL_ORDER.index(l.to_s) || 99 }.to_s
+        end
+      end
+    end
+  end
+end

data/lib/legion/logging/version.rb

@@ -2,6 +2,6 @@
 
 module Legion
   module Logging
-    VERSION = '1.2.5'
+    VERSION = '1.2.6'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legion-logging
 version: !ruby/object:Gem::Version
-  version: 1.2.5
+  version: 1.2.6
 platform: ruby
 authors:
 - Esity
@@ -61,6 +61,10 @@ files:
 - lib/legion/logging/logger.rb
 - lib/legion/logging/methods.rb
 - lib/legion/logging/multi_io.rb
+- lib/legion/logging/redactor.rb
+- lib/legion/logging/shipper.rb
+- lib/legion/logging/shipper/file_transport.rb
+- lib/legion/logging/shipper/http_transport.rb
 - lib/legion/logging/siem_exporter.rb
 - lib/legion/logging/version.rb
 - sonar-project.properties