shieldpress-tracker 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4ba3c8cf44d7637a43997a65762cebe985040105944be0f767009d6e6587769a
+  data.tar.gz: 955a4f2848f902e752e042de0d5ea9b7653083fb3bdc0958232aed4ef101659c
+SHA512:
+  metadata.gz: 61cc4a6aa6a6584cf9b80d7197593a11a46bf19172c79bb516cd3565e0ee5fddfda80dbefb4b3fecbc19da3d6d0e9f019f0e6288973a5954f68d6c8ccc8a6da4
+  data.tar.gz: '0148c792dbdd13c93964fbab0b257908eb383b79c62fa00d28233b0603f19640145b0611a0ffccc66e33d2b15f9e34b5baebf4d1a89d9582dd2c7a03d83d1dbc'

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 1.0.0 - 2026-07-19
+
+- Initial RubyGems release.
+- Added system, runtime, HTTP, error, security, environment and dependency collectors.
+- Added periodic reporting, heartbeat, request filtering and Rack middleware.
+- Added automatic Rails middleware registration after initialization.
+- Added recursive credential redaction before report serialization.

data/LICENSE

@@ -0,0 +1,6 @@
+MIT License
+
+Copyright (c) 2026 ShieldPress
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files, to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies, subject to the conditions of the MIT License.
+

data/README.md

@@ -0,0 +1,57 @@
+<p align="center">
+  <a href="https://shieldpress.net/">
+    <img src="https://shieldpress.net/logo.png" alt="ShieldPress" width="500">
+  </a>
+</p>
+
+# shieldpress-tracker for Ruby
+
+Monitoring, performance and application-security telemetry for Ruby 2.7+, Rack and Rails. It uses only Ruby standard-library dependencies.
+
+Dashboard: [https://shieldpress.net/](https://shieldpress.net/)
+
+## Install
+
+```bash
+gem install shieldpress-tracker
+```
+
+## Quick start
+
+```ruby
+require 'shieldpress_tracker'
+
+tracker = ShieldPress.init(
+  api_key: 'YOUR_SHIELDPRESS_API_KEY',
+  site_id: 'auto',
+  app_name: 'my-ruby-app'
+)
+```
+
+Configuration can also use `SHIELDPRESS_API_KEY`, `SHIELDPRESS_SITE_ID`, `SHIELDPRESS_API_URL`, `SHIELDPRESS_APP_NAME` and `SHIELDPRESS_APP_VERSION` environment variables.
+
+## Rack
+
+```ruby
+use ShieldPressTracker::Middleware, ShieldPress.instance
+run MyApp
+```
+
+Rails automatically adds the Rack middleware when `ShieldPress.init` runs from an initializer.
+
+## Manual instrumentation
+
+```ruby
+tracker.record_request(path: '/orders', method: 'POST', status_code: 201, duration_ms: 42.5)
+tracker.capture_error(StandardError.new('Invalid order'), order_id: 123)
+tracker.analyze_request(url: '/login', method: 'POST', headers: headers, body: body, ip: '203.0.113.2')
+tracker.record_auth_failure(ip: '203.0.113.2', url: '/login', reason: 'bad password')
+tracker.record_rate_limit(ip: '203.0.113.2', url: '/api')
+tracker.record_cors_violation(ip: '203.0.113.2', origin: 'https://untrusted.example', url: '/api')
+tracker.flush
+tracker.stop
+```
+
+Options: `api_url`, `report_interval`, `system_metrics`, `http_tracking`, `error_tracking`, `security_tracking`, `dep_audit`, `dep_audit_interval`, `runtime_metrics`, `env_security`, `heartbeat`, `app_version`, `environment`, `tags`, `ignore_paths`, `max_error_buffer`, `max_security_buffer`, and `debug`.
+
+The SDK never raises a network/reporting failure into the host application. Reports are sent to `/api/tracker/report` with Bearer authentication.

data/lib/shieldpress_tracker/collectors.rb

@@ -0,0 +1,120 @@
+require "etc"
+require "json"
+require "rbconfig"
+require "socket"
+require "time"
+
+module ShieldPressTracker
+  module Helpers
+    def self.percentile(values, percentile)
+      return 0 if values.empty?
+      values.sort[[(percentile / 100.0 * values.length).ceil - 1, 0].max]
+    end
+  end
+
+  class HttpCollector
+    def initialize
+      @records, @started, @mutex = [], Process.clock_gettime(Process::CLOCK_MONOTONIC), Mutex.new
+    end
+    def record(path:, method:, status_code:, duration_ms:)
+      @mutex.synchronize { @records.shift(1000) if @records.length >= 10_000; @records << [path, method, status_code.to_i, duration_ms.to_f] }
+    rescue StandardError
+      nil
+    end
+    def flush
+      records = @mutex.synchronize { rows = @records; @records = []; rows }
+      return nil if records.empty?
+      now = Process.clock_gettime(Process::CLOCK_MONOTONIC); elapsed = [now - @started, 0.001].max; @started = now
+      durations, statuses, grouped = records.map(&:last), Hash.new(0), Hash.new { |h, k| h[k] = [] }
+      records.each { |path, method, status, ms| statuses[status.to_s] += 1; grouped[[method, path]] << [status, ms] }
+      top = grouped.map do |(method, path), rows|
+        times = rows.map(&:last)
+        { path: path, method: method, count: rows.length, avgMs: (times.sum / times.length).round,
+          p95Ms: Helpers.percentile(times, 95), errorCount: rows.count { |r| r[0] >= 400 } }
+      end.sort_by { |x| -x[:count] }.first(20)
+      { totalRequests: records.length, totalErrors: records.count { |r| r[2] >= 500 }, avgResponseMs: (durations.sum / durations.length).round,
+        p50ResponseMs: Helpers.percentile(durations, 50), p95ResponseMs: Helpers.percentile(durations, 95),
+        p99ResponseMs: Helpers.percentile(durations, 99), maxResponseMs: durations.max, statusCodes: statuses,
+        topPaths: top, requestsPerSecond: (records.length / elapsed).round(2) }
+    rescue StandardError
+      nil
+    end
+  end
+
+  class ErrorCollector
+    def initialize(maximum); @maximum, @events, @mutex = maximum, [], Mutex.new end
+    def capture(error, meta = {})
+      event = { message: error.to_s[0, 4096], type: error.class.name, timestamp: Time.now.utc.iso8601 }
+      event[:stack] = Array(error.backtrace).join("\n")[0, 4096] if error.respond_to?(:backtrace)
+      meta = meta.dup
+      { url: :url, method: :method, status_code: :statusCode }.each { |from, to| event[to] = meta.delete(from) if meta.key?(from) }
+      event[:meta] = meta unless meta.empty?
+      @mutex.synchronize { @events << event; @events = @events.last(@maximum) }
+    rescue StandardError
+      nil
+    end
+    def flush; @mutex.synchronize { rows = @events; @events = []; rows } end
+  end
+
+  class SecurityCollector
+    RULES = [
+      [:sql_injection, :critical, /\b(union|select|drop|delete)\b.*\b(from|table|where)\b|--|\/\*/i],
+      [:xss_attempt, :high, /<script|javascript:|onerror\s*=/i],
+      [:command_injection, :critical, /[;&|`]\s*(rm|curl|wget|bash|sh|python)\b|\$\(/i],
+      [:suspicious_path, :high, /\.\.\/|%2e%2e|\/\.env|\/\.git/i],
+      [:bot_detected, :medium, /sqlmap|nikto|nmap|burp|nuclei|wpscan/i]
+    ].freeze
+    def initialize(maximum); @maximum, @events, @ips, @mutex = maximum, [], {}, Mutex.new end
+    def record(type:, severity:, message:, **data)
+      event = { type: type, severity: severity, message: message.to_s[0, 4096], timestamp: Time.now.utc.iso8601 }.merge(data.compact)
+      @mutex.synchronize do
+        @events << event; @events = @events.last(@maximum)
+        if data[:ip]; row = (@ips[data[:ip]] ||= { count: 0, types: [] }); row[:count] += 1; row[:types] |= [type]; end
+      end
+    end
+    def analyze(url:, method: "GET", headers: {}, body: nil, ip: nil, query: nil)
+      headers = headers.transform_keys { |k| k.to_s.downcase }; text = "#{url} #{body} #{query.to_json}"; ua = headers["user-agent"].to_s
+      RULES.each do |type, severity, pattern|
+        target = type == :bot_detected ? ua : text
+        record(type: type, severity: severity, message: "#{type.to_s.tr('_', ' ')} detected in request", ip: ip, url: url,
+               method: method, userAgent: ua, payload: %i[sql_injection xss_attempt command_injection].include?(type) ? text[0, 500] : nil) if pattern.match?(target)
+      end
+      record(type: :oversized_payload, severity: :medium, message: "Request payload exceeds 10MB", ip: ip, url: url, method: method) if headers["content-length"].to_i > 10 * 1024 * 1024
+    rescue StandardError
+      nil
+    end
+    def flush
+      events = @mutex.synchronize { rows = @events; @events = []; rows }
+      return nil if events.empty? && @ips.empty?
+      severity = %i[critical high medium low info].to_h { |x| [x, 0] }; types = Hash.new(0)
+      events.each { |e| severity[e[:severity]] += 1; types[e[:type]] += 1 }
+      ips = @ips.map { |ip, row| { ip: ip, count: row[:count], types: row[:types] } }.sort_by { |x| -x[:count] }.first(10)
+      { totalEvents: events.length, bySeverity: severity, byType: types, topOffendingIps: ips, events: events.last(50) }
+    rescue StandardError
+      nil
+    end
+  end
+
+  module Metrics
+    def self.system
+      { cpuPercent: 0, cpuCount: Etc.nprocessors, memUsedMb: 0, memTotalMb: 0, memPercent: 0,
+        uptimeSeconds: Process.clock_gettime(Process::CLOCK_MONOTONIC).round, loadAvg: [0, 0, 0], platform: RUBY_PLATFORM,
+        rubyVersion: RUBY_VERSION, pid: Process.pid, osName: RbConfig::CONFIG["host_os"], osArch: RbConfig::CONFIG["host_cpu"],
+        hostname: Socket.gethostname, cwd: Dir.pwd, execPath: RbConfig.ruby }
+    end
+    def self.runtime
+      { threadCount: Thread.list.length, gcCount: GC.stat[:count], heapLiveSlots: GC.stat[:heap_live_slots], rubyEngine: defined?(RUBY_ENGINE) ? RUBY_ENGINE : "ruby" }
+    end
+    def self.environment
+      names = ENV.keys.select { |k| k.match?(/KEY|SECRET|TOKEN|PASSWORD|CREDENTIAL/i) }.first(50)
+      { rubyVersion: RUBY_VERSION, rubyPlatform: RUBY_PLATFORM, debugModeEnabled: !!$DEBUG,
+        envVarWarnings: names.map { |k| "Potential secret present in environment variable: #{k}" }, securityHeaders: [], opensslVersion: defined?(OpenSSL) ? OpenSSL::OPENSSL_VERSION : nil }
+    end
+    def self.dependencies
+      specs = Gem.loaded_specs.values
+      { totalDeps: specs.length, totalVulnerabilities: 0, bySeverity: {}, vulnerabilities: [], outdatedCount: 0,
+        lastAuditAt: Time.now.utc.iso8601, packages: specs.first(200).map { |s| { name: s.name, version: s.version.to_s } } }
+    end
+  end
+end
+

data/lib/shieldpress_tracker/config.rb

@@ -0,0 +1,30 @@
+module ShieldPressTracker
+  class Config
+    DEFAULTS = {
+      api_url: "https://api.shieldpress.net", report_interval: 60, system_metrics: true,
+      http_tracking: true, error_tracking: true, security_tracking: true, dep_audit: true,
+      dep_audit_interval: 3600, runtime_metrics: true, env_security: true, heartbeat: true,
+      app_name: "ruby-app", app_version: "0.0.0", environment: "production", tags: {},
+      ignore_paths: ["/health", "/healthz", "/ready", "/favicon.ico", "/assets/*"],
+      max_error_buffer: 100, max_security_buffer: 500, debug: false
+    }.freeze
+
+    attr_reader(*DEFAULTS.keys, :api_key, :site_id)
+
+    def initialize(values = {})
+      values = values.transform_keys(&:to_sym)
+      @api_key = values[:api_key] || ENV["SHIELDPRESS_API_KEY"] || ENV["SHIELDPRESS_SECRET"]
+      @site_id = values[:site_id] || ENV["SHIELDPRESS_SITE_ID"] || ENV["SHIELDPRESS_APP_ID"]
+      raise ArgumentError, "[ShieldPress] api_key is required" if @api_key.to_s.empty?
+      raise ArgumentError, "[ShieldPress] site_id is required" if @site_id.to_s.empty?
+      DEFAULTS.each do |key, default|
+        env = { api_url: "SHIELDPRESS_API_URL", app_name: "SHIELDPRESS_APP_NAME", app_version: "SHIELDPRESS_APP_VERSION" }[key]
+        value = values.key?(key) ? values[key] : (env && ENV[env]) || default
+        instance_variable_set("@#{key}", value)
+      end
+      @api_url = @api_url.sub(%r{/$}, "")
+      @environment = values[:environment] || ENV["APP_ENV"] || ENV["RACK_ENV"] || "production"
+    end
+  end
+end
+

data/lib/shieldpress_tracker/middleware.rb

@@ -0,0 +1,20 @@
+module ShieldPressTracker
+  class Middleware
+    def initialize(app, tracker = nil); @app, @tracker = app, tracker || ShieldPress.instance end
+    def call(env)
+      started = Process.clock_gettime(Process::CLOCK_MONOTONIC); path = env["PATH_INFO"] || "/"; method = env["REQUEST_METHOD"] || "GET"
+      headers = env.select { |k, _| k.start_with?("HTTP_") }.to_h { |k, v| [k.delete_prefix("HTTP_").tr("_", "-").downcase, v] }
+      @tracker.analyze_request(url: path, method: method, headers: headers, ip: env["REMOTE_ADDR"], query: env["QUERY_STRING"])
+      status, response_headers, body = @app.call(env)
+      [status, response_headers, body]
+    rescue StandardError => e
+      @tracker.capture_error(e, url: path, method: method); raise
+    ensure
+      if started
+        duration = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000
+        @tracker.record_request(path: path, method: method, status_code: status || 500, duration_ms: duration)
+      end
+    end
+  end
+end
+

data/lib/shieldpress_tracker/railtie.rb

@@ -0,0 +1,10 @@
+if defined?(Rails::Railtie)
+  module ShieldPressTracker
+    class Railtie < Rails::Railtie
+      initializer "shieldpress_tracker.middleware" do |app|
+        app.middleware.use ShieldPressTracker::Middleware if ShieldPress.configured?
+      end
+    end
+  end
+end
+

data/lib/shieldpress_tracker/reporter.rb

@@ -0,0 +1,42 @@
+require "json"
+require "net/http"
+require "uri"
+
+module ShieldPressTracker
+  class Reporter
+    SENSITIVE_KEY = /authorization|cookie|password|passwd|secret|token|api[_-]?key|credential/i
+    SENSITIVE_TEXT = /(bearer\s+)[A-Za-z0-9._~+\-\/=]+|([?&](?:password|passwd|secret|token|api[_-]?key)=)[^&\s]+/i
+
+    def redact(value, depth = 0)
+      return "[MAX_DEPTH]" if depth > 12
+      case value
+      when Hash
+        value.each_with_object({}) { |(key, item), out| out[key] = key.to_s.match?(SENSITIVE_KEY) ? "[REDACTED]" : redact(item, depth + 1) }
+      when Array
+        value.first(500).map { |item| redact(item, depth + 1) }
+      when String
+        value.gsub(SENSITIVE_TEXT) { "#{Regexp.last_match(1) || Regexp.last_match(2)}[REDACTED]" }[0, 16_384]
+      else
+        value
+      end
+    end
+
+    def initialize(api_url, api_key, debug = false); @uri, @api_key, @debug = URI(api_url + "/api/tracker/report"), api_key, debug end
+    def send(payload)
+      payload = redact(payload)
+      body = JSON.generate(payload)
+      if body.bytesize > 512 * 1024
+        payload[:_truncated] = true; payload[:errors] = Array(payload[:errors]).first(20)
+        payload[:security][:events] = Array(payload[:security][:events]).first(10) if payload[:security]
+        body = JSON.generate(payload)
+      end
+      request = Net::HTTP::Post.new(@uri); request["Content-Type"] = "application/json"
+      request["Authorization"] = "Bearer #{@api_key}"; request["User-Agent"] = "shieldpress-tracker-ruby/1.0.0"; request.body = body
+      response = Net::HTTP.start(@uri.host, @uri.port, use_ssl: @uri.scheme == "https", open_timeout: 5, read_timeout: 10) { |http| http.request(request) }
+      response.code.to_i.between?(200, 299)
+    rescue StandardError => e
+      warn("[ShieldPress] report failed: #{e.message}") if @debug
+      false
+    end
+  end
+end

data/lib/shieldpress_tracker/tracker.rb

@@ -0,0 +1,64 @@
+require "uri"
+require_relative "config"
+require_relative "collectors"
+require_relative "reporter"
+
+module ShieldPressTracker
+  class Tracker
+    attr_reader :config, :http_collector, :error_collector, :security_collector
+    def initialize(config = {})
+      @config = Config.new(config); @http_collector = HttpCollector.new
+      @error_collector = ErrorCollector.new(@config.max_error_buffer); @security_collector = SecurityCollector.new(@config.max_security_buffer)
+      @reporter = Reporter.new(@config.api_url, @config.api_key, @config.debug); @stopped = false; @last_audit = Time.at(0)
+    end
+    def start
+      return self if @thread&.alive?
+      @stopped = false
+      @thread = Thread.new do
+        Thread.current.name = "shieldpress-reporter" if Thread.current.respond_to?(:name=)
+        until @stopped; sleep(@config.report_interval.to_i); flush unless @stopped; end
+      end
+      @thread.abort_on_exception = false
+      self
+    end
+    def stop(flush: true); @stopped = true; @thread&.kill; self.flush if flush; self end
+    def ignored?(path)
+      path = URI.parse(path).path rescue path
+      @config.ignore_paths.any? { |pattern| pattern.end_with?("/*") ? path.start_with?(pattern[0..-2]) : path == pattern }
+    end
+    def record_request(path:, method: "GET", status_code: 200, duration_ms: 0)
+      @http_collector.record(path: path, method: method, status_code: status_code, duration_ms: duration_ms) if @config.http_tracking && !ignored?(path)
+    end
+    def analyze_request(url:, method: "GET", headers: {}, body: nil, ip: nil, query: nil)
+      @security_collector.analyze(url: url, method: method, headers: headers, body: body, ip: ip, query: query) if @config.security_tracking && !ignored?(url)
+    end
+    def capture_error(error, meta = {}); @error_collector.capture(error, meta) if @config.error_tracking end
+    def record_auth_failure(ip: nil, url: nil, method: nil, reason: nil)
+      @security_collector.record(type: :auth_failure, severity: :medium, message: "Authentication failed#{reason ? ": #{reason}" : ""}", ip: ip, url: url, method: method)
+    end
+    def record_rate_limit(ip: nil, url: nil, method: nil, limit: nil)
+      @security_collector.record(type: :rate_limit_hit, severity: :low, message: "Rate limit triggered", ip: ip, url: url, method: method, meta: { limit: limit })
+    end
+    def record_cors_violation(ip: nil, origin: nil, url: nil)
+      @security_collector.record(type: :cors_violation, severity: :medium, message: "CORS policy blocked request from origin: #{origin || 'unknown'}", ip: ip, url: url)
+    end
+    def record_security_event(type:, severity:, message:, **data)
+      @security_collector.record(type: type, severity: severity, message: message, **data)
+    end
+    def flush
+      c = @config
+      payload = { siteId: c.site_id, appName: c.app_name, appVersion: c.app_version, environment: c.environment,
+                  tags: c.tags, timestamp: Time.now.utc.iso8601 }
+      payload[:system] = Metrics.system if c.system_metrics
+      http = @http_collector.flush if c.http_tracking; payload[:http] = http if http
+      errors = @error_collector.flush if c.error_tracking; payload[:errors] = errors unless errors.nil? || errors.empty?
+      security = @security_collector.flush if c.security_tracking; payload[:security] = security if security
+      payload[:runtime] = Metrics.runtime if c.runtime_metrics; payload[:envSecurity] = Metrics.environment if c.env_security
+      if c.dep_audit && Time.now - @last_audit >= c.dep_audit_interval.to_i; payload[:depAudit] = Metrics.dependencies; @last_audit = Time.now; end
+      payload[:heartbeat] = true if c.heartbeat
+      @reporter.send(payload)
+    rescue StandardError
+      false
+    end
+  end
+end

data/lib/shieldpress_tracker/version.rb

@@ -0,0 +1,4 @@
+module ShieldPressTracker
+  VERSION = "1.0.0"
+end
+

data/lib/shieldpress_tracker.rb

@@ -0,0 +1,14 @@
+require_relative "shieldpress_tracker/version"
+require_relative "shieldpress_tracker/tracker"
+require_relative "shieldpress_tracker/middleware"
+
+module ShieldPress
+  class << self
+    def init(**config); @instance&.stop(flush: false); @instance = ShieldPressTracker::Tracker.new(config).start end
+    def instance; @instance || raise("ShieldPress.init must be called first") end
+    def configured?; !@instance.nil? end
+  end
+end
+
+require_relative "shieldpress_tracker/railtie" if defined?(Rails::Railtie)
+

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: shieldpress-tracker
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- ShieldPress
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-07-19 00:00:00.000000000 Z
+dependencies: []
+description:
+email:
+- hello@shieldpress.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/shieldpress_tracker.rb
+- lib/shieldpress_tracker/collectors.rb
+- lib/shieldpress_tracker/config.rb
+- lib/shieldpress_tracker/middleware.rb
+- lib/shieldpress_tracker/railtie.rb
+- lib/shieldpress_tracker/reporter.rb
+- lib/shieldpress_tracker/tracker.rb
+- lib/shieldpress_tracker/version.rb
+homepage: https://shieldpress.net
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/vithanhlam/ShieldPress-Tracker-Ruby-Gem
+  changelog_uri: https://github.com/vithanhlam/ShieldPress-Tracker-Ruby-Gem/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.33
+signing_key:
+specification_version: 4
+summary: Monitoring, performance and security SDK for Ruby applications
+test_files: []