provenance 2.0.0

data/lib/provenance/sinks/proc.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Provenance
+  module Sinks
+    # Calls a block or callable with each batch.
+    class Proc
+      # @param callable [#call, nil]
+      def initialize(callable = nil, &block)
+        @callable = callable || block
+        raise ArgumentError, "proc sink needs a callable or a block" unless @callable.respond_to?(:call)
+      end
+
+      # @param batch [Array<Hash>]
+      # @return [void]
+      def deliver(batch)
+        @callable.call(batch)
+      end
+    end
+  end
+end

data/lib/provenance/sinks.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "provenance/sinks/logger"
+require "provenance/sinks/io"
+require "provenance/sinks/http"
+require "provenance/sinks/proc"
+require "provenance/sinks/memory"
+
+module Provenance
+  # Destinations for serialized events. A sink is any object responding to
+  # +#deliver(batch)+, where +batch+ is an Array of serialized events (Hashes).
+  module Sinks
+    module_function
+
+    # Builds a sink from a type symbol or returns a sink object unchanged.
+    #
+    # @param type [Symbol, #deliver]
+    # @return [#deliver]
+    def build(type, *args, **options, &block)
+      return type if type.respond_to?(:deliver)
+
+      case type.to_sym
+      when :logger then Logger.new(*args, **options)
+      when :io then IO.new(*args, **options)
+      when :http then HTTP.new(*args, **options)
+      when :proc then Proc.new(*args, &block)
+      when :memory then Memory.new
+      when :kafka
+        require "provenance/sinks/kafka"
+        Kafka.new(*args, **options)
+      else raise ConfigurationError, "unknown sink #{type.inspect}"
+      end
+    end
+  end
+end

data/lib/provenance/testing.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Provenance
+  # Test helpers. While {capture} runs, tracking is enabled regardless of
+  # +config.enabled+ and events go to the capture instead of the outbox or sinks.
+  module Testing
+    @captures = []
+    @lock = Mutex.new
+
+    class << self
+      # Collects the native events emitted while the block runs.
+      #
+      # @return [Array<Hash>] native events
+      def capture
+        events = []
+        @lock.synchronize { @captures << events }
+        begin
+          yield
+        ensure
+          @lock.synchronize { @captures.delete_if { |c| c.equal?(events) } }
+        end
+        events
+      end
+
+      # @return [Boolean] whether a capture is active
+      def capturing?
+        !@captures.empty?
+      end
+
+      # @api private
+      def record(event)
+        @lock.synchronize { @captures.each { |c| c << event } }
+      end
+    end
+  end
+end

data/lib/provenance/uuid.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Provenance
+  # UUIDv7 generation (RFC 9562): 48-bit Unix millisecond timestamp followed by
+  # random bits, so ids sort by creation time.
+  module UUID
+    module_function
+
+    # @param time [Time] timestamp to embed
+    # @return [String] a UUIDv7 in canonical 8-4-4-4-12 form
+    def v7(time = Time.now)
+      ms = (time.to_r * 1000).to_i
+      bytes = [ms >> 16, ms & 0xffff].pack("Nn").b + SecureRandom.random_bytes(10)
+      bytes.setbyte(6, (bytes.getbyte(6) & 0x0f) | 0x70)
+      bytes.setbyte(8, (bytes.getbyte(8) & 0x3f) | 0x80)
+      hex = bytes.unpack1("H*")
+      [hex[0, 8], hex[8, 4], hex[12, 4], hex[16, 4], hex[20, 12]].join("-")
+    end
+  end
+end

data/lib/provenance/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Provenance
+  # Current gem version.
+  VERSION = "2.0.0"
+end

data/lib/provenance.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+require "active_support"
+require "active_support/core_ext"
+require "active_support/isolated_execution_state"
+require "active_record"
+
+require "provenance/version"
+require "provenance/errors"
+require "provenance/uuid"
+require "provenance/json_safe"
+require "provenance/configuration"
+require "provenance/actor"
+require "provenance/context"
+require "provenance/entity_change"
+require "provenance/action"
+require "provenance/registry"
+require "provenance/redactor"
+require "provenance/event"
+require "provenance/serializers"
+require "provenance/sinks"
+require "provenance/integrity"
+require "provenance/emitter"
+require "provenance/recorder"
+require "provenance/model"
+require "provenance/middleware"
+require "provenance/controller"
+require "provenance/job"
+require "provenance/rake"
+require "provenance/outbox"
+
+# Provenance emits one action-level audit event per HTTP request, background job,
+# rake task or explicit block, and delivers it to security and observability tooling.
+#
+# @example
+#   Provenance.configure do |c|
+#     c.sink :logger
+#   end
+module Provenance
+  autoload :RelayJob, "provenance/relay_job"
+
+  STATE_KEY = :provenance_action
+  SUPPRESS_KEY = :provenance_suppressed
+  private_constant :STATE_KEY, :SUPPRESS_KEY
+
+  class << self
+    # Yields the global configuration and validates it afterwards.
+    #
+    # @yieldparam config [Configuration]
+    # @return [Configuration]
+    # @raise [ConfigurationError] when the resulting configuration is invalid
+    def configure
+      yield config
+      config.validate!
+      config
+    end
+
+    # @return [Configuration] the global configuration
+    def config
+      @config ||= Configuration.new
+    end
+
+    # Replaces the global configuration with defaults. Mostly useful in tests.
+    #
+    # @return [Configuration]
+    def reset_config!
+      @config = Configuration.new
+    end
+
+    # @return [Registry] the registry of models tracked with +has_provenance+
+    def registry
+      @registry ||= Registry.new
+    end
+
+    # @return [Boolean] whether tracking is active for the current execution context
+    def enabled?
+      (config.enabled || Testing.capturing?) && !suppressed?
+    end
+
+    # @return [Boolean] whether tracking is suppressed by {without}
+    def suppressed?
+      ActiveSupport::IsolatedExecutionState[SUPPRESS_KEY].to_i.positive?
+    end
+
+    # The action currently open in this thread or fiber, if any.
+    #
+    # @return [Action, nil]
+    def current
+      ActiveSupport::IsolatedExecutionState[STATE_KEY]
+    end
+
+    # Opens an explicit action. Explicit actions are always auditable. Nested scopes
+    # attach their changes and metadata to the outermost action.
+    #
+    # @param name [String] action name, e.g. "users.import"
+    # @param actor [Object, Hash, Actor, nil] who performs the action
+    # @param metadata [Hash] arbitrary JSON-safe data
+    # @yieldparam action [Action]
+    # @return [Object] the block's return value
+    def action(name, actor: nil, metadata: {}, &block)
+      raise ArgumentError, "a block is required" unless block
+
+      track(kind: :custom, name: name, actor: actor, metadata: metadata, explicit: true, &block)
+    end
+
+    # Runs the block with change tracking and emission suppressed.
+    #
+    # @return [Object] the block's return value
+    def without
+      state = ActiveSupport::IsolatedExecutionState
+      state[SUPPRESS_KEY] = state[SUPPRESS_KEY].to_i + 1
+      yield
+    ensure
+      state[SUPPRESS_KEY] -= 1
+    end
+
+    # Runs the block inside an action of the given kind, or inside the already open
+    # action when there is one. Used by the HTTP, job and rake integrations.
+    #
+    # @param kind [Symbol] :http, :job, :task or :custom
+    # @param name [String, nil]
+    # @param actor [Object, nil]
+    # @param metadata [Hash]
+    # @param explicit [Boolean]
+    # @param caused_by [String, nil] id of the parent action
+    # @param context [Context, nil]
+    # @yieldparam action [Action]
+    # @return [Object] the block's return value
+    def track(kind:, name:, actor: nil, metadata: {}, explicit: false, caused_by: nil, context: nil)
+      if (outer = current)
+        outer.annotate(**metadata) if metadata.present?
+        outer.actor = actor if actor && outer.explicit_actor.nil?
+        return yield(outer)
+      end
+
+      action = Action.new(kind: kind, name: name, actor: actor, metadata: metadata,
+        explicit: explicit, caused_by: caused_by, context: context)
+      within(action) { yield(action) }
+    end
+
+    # Makes +action+ current for the duration of the block, records an unhandled
+    # exception as the outcome and hands the action to the emitter afterwards.
+    #
+    # @param action [Action]
+    # @return [Object] the block's return value
+    def within(action)
+      state = ActiveSupport::IsolatedExecutionState
+      previous = state[STATE_KEY]
+      state[STATE_KEY] = action
+      begin
+        yield
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        action.fail!(e)
+        raise
+      ensure
+        state[STATE_KEY] = previous
+        Emitter.finish(action)
+      end
+    end
+  end
+end
+
+require "provenance/testing"
+require "provenance/railtie" if defined?(Rails::Railtie)

data/lib/tasks/provenance.rake

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+namespace :provenance do
+  desc "Verify the integrity chain of events stored in the outbox"
+  task verify: :environment do
+    key = Provenance.config.integrity.key
+    abort "provenance:verify: integrity.key is not configured" if key.blank?
+
+    broken = Provenance::Outbox::Record.where.not(seq: nil).distinct.pluck(:app).filter_map do |app|
+      events = Provenance::Outbox::Record.where(app: app).where.not(seq: nil).order(:seq).map(&:event)
+      seq = Provenance::Integrity.verify(events, key: key)
+      puts "#{app}: #{seq ? "broken at seq #{seq}" : "ok (#{events.size} events)"}"
+      seq
+    end
+    abort "provenance:verify: integrity check failed" if broken.any?
+  end
+
+  desc "Deliver pending outbox events now"
+  task relay: :environment do
+    puts "delivered #{Provenance::Outbox::Relay.run} events"
+  end
+end

data/schema/event-2.json

@@ -0,0 +1,126 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:provenance:event:2",
+  "title": "Provenance action event",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "id", "occurred_at", "app", "action", "actor", "request", "outcome", "changes", "metadata"],
+  "properties": {
+    "schema": {"const": "provenance/event@2"},
+    "id": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+    },
+    "occurred_at": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$"
+    },
+    "app": {"type": "string", "minLength": 1},
+    "action": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "name", "caused_by"],
+      "properties": {
+        "kind": {"enum": ["http", "job", "task", "custom"]},
+        "name": {"type": "string"},
+        "caused_by": {"type": ["string", "null"]}
+      }
+    },
+    "actor": {
+      "oneOf": [{"type": "null"}, {"$ref": "#/$defs/actor"}]
+    },
+    "request": {
+      "oneOf": [
+        {"type": "null"},
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["id", "method", "path", "status", "ip", "user_agent"],
+          "properties": {
+            "id": {"type": ["string", "null"]},
+            "method": {"type": "string"},
+            "path": {"type": "string"},
+            "status": {"type": ["integer", "null"]},
+            "ip": {"type": ["string", "null"]},
+            "user_agent": {"type": ["string", "null"]}
+          }
+        }
+      ]
+    },
+    "outcome": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["result", "error"],
+      "properties": {
+        "result": {"enum": ["success", "failure", "denied"]},
+        "error": {
+          "oneOf": [
+            {"type": "null"},
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["class", "message"],
+              "properties": {
+                "class": {"type": "string"},
+                "message": {"type": "string", "maxLength": 500}
+              }
+            }
+          ]
+        }
+      }
+    },
+    "changes": {"type": "array", "items": {"$ref": "#/$defs/change"}},
+    "metadata": {"type": "object"},
+    "integrity": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["seq", "prev", "mac"],
+      "properties": {
+        "seq": {"type": "integer", "minimum": 1},
+        "prev": {"type": ["string", "null"], "pattern": "^[0-9a-f]{64}$"},
+        "mac": {"type": "string", "pattern": "^[0-9a-f]{64}$"}
+      }
+    }
+  },
+  "$defs": {
+    "actor": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "type", "display", "roles", "impersonator"],
+      "properties": {
+        "id": {"type": ["string", "null"]},
+        "type": {"type": ["string", "null"]},
+        "display": {"type": ["string", "null"]},
+        "roles": {"type": "array", "items": {"type": "string"}},
+        "impersonator": {"oneOf": [{"type": "null"}, {"$ref": "#/$defs/actor"}]}
+      }
+    },
+    "change": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["entity", "entity_id", "operation", "diff"],
+      "properties": {
+        "entity": {"type": "string"},
+        "entity_id": {"type": ["string", "null"]},
+        "operation": {
+          "enum": ["create", "update", "destroy", "link", "unlink", "bulk_update", "bulk_delete", "bulk_insert"]
+        },
+        "diff": {"type": ["object", "null"]},
+        "association": {"type": "string"},
+        "target": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["type", "id"],
+          "properties": {
+            "type": {"type": "string"},
+            "id": {"type": ["string", "null"]}
+          }
+        },
+        "count": {"type": ["integer", "null"]},
+        "where": {"type": ["string", "null"]},
+        "ids": {"type": "array", "items": {"type": "string"}},
+        "truncated": {"type": "boolean"}
+      }
+    }
+  }
+}

metadata

@@ -0,0 +1,150 @@
+--- !ruby/object:Gem::Specification
+name: provenance
+version: !ruby/object:Gem::Version
+  version: 2.0.0
+platform: ruby
+authors:
+- Ivan Nikolaev
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activejob
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+description: 'Provenance records who did what, through which entry point, with what
+  outcome and which records changed: one event per HTTP request, job, rake task or
+  explicit block, delivered to SIEM, log pipelines and webhooks in native, OCSF or
+  CloudEvents format.'
+email:
+- ivan_n6_20@icloud.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/generators/provenance/install/install_generator.rb
+- lib/generators/provenance/install/templates/create_provenance_outbox.rb.tt
+- lib/generators/provenance/install/templates/initializer.rb.tt
+- lib/provenance.rb
+- lib/provenance/action.rb
+- lib/provenance/actor.rb
+- lib/provenance/configuration.rb
+- lib/provenance/context.rb
+- lib/provenance/controller.rb
+- lib/provenance/emitter.rb
+- lib/provenance/entity_change.rb
+- lib/provenance/errors.rb
+- lib/provenance/event.rb
+- lib/provenance/integrity.rb
+- lib/provenance/job.rb
+- lib/provenance/json_safe.rb
+- lib/provenance/middleware.rb
+- lib/provenance/model.rb
+- lib/provenance/outbox.rb
+- lib/provenance/outbox/record.rb
+- lib/provenance/outbox/relay.rb
+- lib/provenance/railtie.rb
+- lib/provenance/rake.rb
+- lib/provenance/recorder.rb
+- lib/provenance/redactor.rb
+- lib/provenance/registry.rb
+- lib/provenance/relay_job.rb
+- lib/provenance/rspec.rb
+- lib/provenance/serializers.rb
+- lib/provenance/serializers/cloud_events.rb
+- lib/provenance/serializers/native.rb
+- lib/provenance/serializers/ocsf.rb
+- lib/provenance/sinks.rb
+- lib/provenance/sinks/http.rb
+- lib/provenance/sinks/io.rb
+- lib/provenance/sinks/kafka.rb
+- lib/provenance/sinks/logger.rb
+- lib/provenance/sinks/memory.rb
+- lib/provenance/sinks/proc.rb
+- lib/provenance/testing.rb
+- lib/provenance/uuid.rb
+- lib/provenance/version.rb
+- lib/tasks/provenance.rake
+- schema/event-2.json
+homepage: https://github.com/inikalaev/provenance
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/inikalaev/provenance
+  source_code_uri: https://github.com/inikalaev/provenance
+  changelog_uri: https://github.com/inikalaev/provenance/blob/v2/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Action-level, tamper-evident audit events for Rails applications
+test_files: []