apptrail-application-events-sdk 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0a56d565f6da67bd2bc4bbfb36c20f599e0ef18bd7ec0f5e969caae6c592409c
+  data.tar.gz: b3c67d43208b9a8eb134bb529d023c33c24bae80b4485ed41dcc6ca224865131
+SHA512:
+  metadata.gz: 9955cd66982d262361d7cbfdd6672ce4f34ff03e4caf65fc883ddcede9ba0fc2d3386b7fe93e32e2f1cbeed1fc0ee3f1d4450c87131eb7e94491ce6f182ed5ce
+  data.tar.gz: 76618a0b1bd9f2800a37f167b2781210664da5bb4458a4be29c50d842d14d0e8c2f46bdafd4c3d353e1652625c08bd3062c007233a18b763c5f373a01010a0ce

data/README.md

@@ -0,0 +1,93 @@
+# Apptrail Application Events SDK for Ruby
+
+You can use the Apptrail Application Events SDK for Ruby to send audit logs from your
+Ruby applications to your customers.
+
+## Learn more
+
+- [Working with events](https://apptrail.com/docs/applications/guide/working-with-events/overview)
+- [Full SDK Reference](https://apptrail.com/docs/applications/guide/working-with-events/using-the-events-sdk/application-events-sdk-ruby)
+- [Developer Guide](https://apptrail.com/docs/applications/guide)
+- [Apptrail](https://apptrail.com)
+
+## Notes and tips
+
+- Instantiate the client once at the top of your application and reuse it to prevent unnecessary recreation.
+
+## Installing
+
+```bash
+gem "apptrail-application-events-sdk"
+```
+
+Inside of your Ruby program, run:
+
+```
+require "apptrail-application-events-sdk"
+```
+
+## Instantiating client
+
+```ruby
+require "apptrail-application-events-sdk"
+
+my_api_key = loadMySecretApiKey()
+my_region = "us-west-2"
+
+events_client = Apptrail::ApptrailEventsClient.new(
+  region: my_region,
+  apiKey: my_api_key,
+)
+```
+
+## Sending an event
+
+```ruby
+event = {
+  tenantId: "cust_MGY4MmYzNDMtZjEwOC00OWI",
+  eventName: "CreateRepository",
+  eventTime: "2022-01-26T06:01:00Z",
+  actor: {
+    id: "acct_MmRlODllZDctM2I0Yi0",
+    details: {
+      type: "account",
+      name: "API Access",
+    },
+  },
+  resources: [
+    {
+      id: "repo_YWI5NjkzY2UtNzI1Ny00N",
+      details: {
+        repositoryType: "V2",
+      },
+    },
+  ],
+  sourceIpAddress: "103.6.179.245",
+  userAgent: "Apache-HttpClient/4.5.3 (Java/11.0.11)",
+  tags: {
+    severity: "LOW",
+  },
+  eventDetails: {
+    request: {
+      repositoryName: "my-repository",
+    },
+  },
+}
+
+events_client.putEvent(event)
+```
+
+## Handling errors
+
+As a best practice, you should handle errors while sending events, especially if you are sending critical logs. The Events client includes automatic retries with backoff, but errors can happen due to rare server issues or client side issues.
+
+You can choose what to do with failing events. For example, you may sideline them to disk, or a dead letter queue for retry or remediation.
+
+```ruby
+begin
+  events_client.putEvent(event);
+rescue ApptrailError => e
+  puts e
+  # handle error
+end
+```

data/lib/apptrail-application-events-sdk.rb

@@ -0,0 +1,170 @@
+require 'logger'
+require 'stringio'
+require "base64"
+require "json"
+require 'securerandom'
+require "http"
+require "json-schema"
+require "retriable"
+
+#HTTP.default_options = HTTP::Options.new(features: {logging: { logger: Logger.new(STDOUT)}})
+
+module Apptrail
+  class << self
+    # Defines the logger used for debugging for the Apptrail module.
+    # For example, log to STDOUT by setting this to Logger.new(STDOUT).
+    #
+    # @return [Logger]
+    attr_accessor :logger
+
+    def logger
+      @logger ||= Logger.new($stdout).tap do |log|
+        log.progname = self.name
+      end
+    end
+
+    
+  end
+
+  class ApptrailError < StandardError; end
+  class ApptrailRetryableError < ApptrailError; end
+
+  Retriable.configure do |c|
+    c.contexts[:s3] = {
+      tries: 3,
+      base_interval: 0.04,
+      on: Apptrail::ApptrailRetryableError,
+      on_retry: Proc.new { puts 'Retrying...' },
+      max_interval: 0.12,
+      max_elapsed_time: 4,
+      rand_factor: 0.2,
+    }
+  end
+
+  # You can use the Apptrail Application Events Client to send
+  # audit log events from your Ruby applications.
+  #
+  # See [Sending events](https://apptrail.com/docs/applications/guide/working-with-events/overview).
+  class ApptrailEventsClient
+    @_form_data = nil
+    @_upload_url = nil
+
+    SCHEMA = JSON.parse(File.read(
+      File.expand_path('../raw-event-schema.json', __FILE__)
+    )).freeze
+    private_constant :SCHEMA
+
+    def inspect
+      "#<ApptrailEventsClient:#{object_id}>"
+    end
+
+    def to_s
+      "ApptrailEventsClient{}"
+    end
+
+    def initialize(region:, api_key:)
+      @_region = region
+      begin
+        parsed_key = Base64.urlsafe_decode64(api_key)
+        application_id, *_  = parsed_key.split(',', 3)
+        @_application_id = application_id
+      rescue
+        raise ArgumentError, "Invalid API Key." 
+      end
+
+      @_base_api_url = "https://events.#{region}.apptrail.com/applications/session"
+      @_api_key = api_key
+    end
+
+    # Send a single audit event to log to Apptrail.
+    #
+    # @param events [Array<ApptrailEvent>]] An array of events to log. See [Apptrail Event Format](https://apptrail.com/docs/applications/guide/event-format) for a full description of the event format.
+    def put_event(event)
+      put_events([event])
+    end
+
+
+    # Send a list of up to 1000 audit events to log to Apptrail.
+    #
+    # @param events [Array<ApptrailEvent>]] An array of events to log. See [Apptrail Event Format](https://apptrail.com/docs/applications/guide/event-format) for a full description of the event format.
+    def put_events(events)
+      unless events.is_a?(Array)
+        raise TypeError, "Must pass in array of events."
+      end
+      unless events.length <= 1000
+        raise ArgumentError, "Can not send more than 1000 events in a single PutEvents call."
+      end
+
+      begin
+        JSON::Validator.validate!(SCHEMA, events, :list => true, :parse_data => false)
+      rescue JSON::Schema::ValidationError => e
+        raise Apptrail::ApptrailError.new(e.message)
+      end
+
+      if @_upload_url.nil? || @_form_data.nil?
+        _refresh_post_policy()
+      end
+
+      content = ""
+      events.each do |evt|
+        content << JSON.generate(evt)
+        content << "\n"
+      end
+
+      filename = SecureRandom.uuid + ".jsonl"
+      s3_key = File.join(@_application_id, filename)
+
+      form_file = HTTP::FormData::File.new(StringIO.new(content), :filename => filename)
+
+      new_form_opts = {
+        **@_form_data,
+        :key => s3_key,
+        :file => form_file
+      }
+
+      begin
+        Retriable.with_context(:s3) do
+          resp = HTTP.post(@_upload_url, :form => new_form_opts)
+          if !resp.status.success?
+            if (resp.status.server_error?)
+              raise ApptrailRetryableError.new("Server Error while putting events.")
+            elsif (resp.status.client_error?)
+              if (resp.status.code === 403 && resp.body.to_s.include?("Policy expired"))
+                _refresh_post_policy()
+                raise ApptrailRetryableError.new("Session expired.")
+              else
+                puts resp.body.to_s
+                raise ApptrailError.new("Error while putting events.")
+              end
+            else
+              raise ApptrailError.new("Error while putting events.")
+            end
+          end
+        end
+      rescue
+        raise ApptrailError.new("Failed to put #{events.length} events. Encountered error.")
+      else
+        Apptrail::logger.info("Successfully wrote #{events.length} events.")
+      end
+
+    end
+
+    private
+
+    def _refresh_post_policy
+      puts @_base_api_url
+      resp = HTTP
+        .auth("Bearer #{@_api_key}")
+        .get(@_base_api_url)
+      if !resp.status.success?
+        raise ApptrailError.new("Error refreshing credentials, status code: #{resp.code}")
+      end
+      result = JSON.parse(resp.body.to_s)
+      @_upload_url = result["uploadUrl"]
+      @_form_data = result["form"]
+    end
+
+    
+  end
+
+end

data/lib/raw-event-schema.json

@@ -0,0 +1,89 @@
+{
+  "type": "object",
+  "description": "An Apptrail event is a record of a an activity performed on your customer resources in your application. \n\n @see https://apptrail.com/docs/applications/guide/working-with-events/overview",
+  "properties": {
+    "tenantId": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_\\-+=]*$",
+      "description": "The ID of the tenant this event is associated with and will be delivered to. For more on tenants @see https://apptrail.com/docs/applications/guide/working-with-tenants."
+    },
+    "eventTime": {
+      "type": "string",
+      "format": "date-time",
+      "description": "The time the event occurred. Formatted as an ISO 8601 formatted string, e.g. 2021-12-06T16:09:38Z."
+    },
+    "eventName": {
+      "type": "string",
+      "description": "The name of the event as a string. You should represent unique events with unique names. For example if you are adding audit logs to an API, event names could correspond to your API methods."
+    },
+    "actor": {
+      "type": "object",
+      "description": "Actor specifies the identity that performed the action being logged. This may be a user or machine client. Consumers can filter based on this attribute.",
+      "required": [
+        "id"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "description": "A string representing the identity of the actor."
+        },
+        "details": {
+          "type": "object",
+          "description": "Additional arbitrary metadata related to the actor."
+        }
+      }
+    },
+    "resources": {
+      "type": "array",
+      "description": "If applicable, contains information about the relevant resources that the action this event is recording is related to.",
+      "items": {
+        "type": "object",
+        "required": [
+          "id"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "A unique identifier for this resource."
+          },
+          "details": {
+            "type": "object",
+            "description": "Additional arbitrary metadata related to the resource."
+          }
+        }
+      }
+    },
+    "sourceIpAddress": {
+      "type": "string",
+      "description": "The IP address the activity/request being recorded was made from.",
+      "oneOf": [
+        {
+          "format": "ipv4"
+        },
+        {
+          "format": "ipv6"
+        }
+      ]
+    },
+    "userAgent": {
+      "type": "string",
+      "description": "The agent through which the request was made, e.g. `Mozilla/5.0` or `python-requests/2.20.1`."
+    },
+    "eventDetails": {
+      "type": "object",
+      "description": "Any additional custom information as a JSON object can be included in this field."
+    },
+    "tags": {
+      "type": "object",
+      "description": "Tags are key value metadata that you associate with events. Users can search and filter events based on these tags.",
+      "additionalProperties": {
+        "type": "string"
+      }
+    }
+  },
+  "required": [
+    "eventTime",
+    "eventName",
+    "tenantId"
+  ]
+}

metadata

@@ -0,0 +1,88 @@
+--- !ruby/object:Gem::Specification
+name: apptrail-application-events-sdk
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Apptrail Team
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2022-01-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.1'
+- !ruby/object:Gem::Dependency
+  name: retriable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: json-schema
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+description: Send audit logs from your Ruby applications using the Apptrail Application
+  Events SDK for Ruby.
+email: support@apptrail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/apptrail-application-events-sdk.rb
+- lib/raw-event-schema.json
+homepage: https://apptrail.com/docs/applications/guide
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.3
+signing_key: 
+specification_version: 4
+summary: Apptrail Application Events SDK for Ruby
+test_files: []