Module: Cased

Defined in:
lib/cased.rb,
lib/cased/cli.rb,
lib/cased/error.rb,
lib/cased/model.rb,
lib/cased/query.rb,
lib/cased/config.rb,
lib/cased/policy.rb,
lib/cased/cli/log.rb,
lib/cased/clients.rb,
lib/cased/context.rb,
lib/cased/version.rb,
lib/cased/response.rb,
lib/cased/cli/config.rb,
lib/cased/http/error.rb,
lib/cased/cli/session.rb,
lib/cased/http/client.rb,
lib/cased/test_helper.rb,
lib/cased/cli/identity.rb,
lib/cased/cli/recorder.rb,
lib/cased/publishers/base.rb,
lib/cased/rack_middleware.rb,
lib/cased/sensitive/range.rb,
lib/cased/context/expander.rb,
lib/cased/publishers/error.rb,
lib/cased/sensitive/result.rb,
lib/cased/sensitive/string.rb,
lib/cased/sensitive/handler.rb,
lib/cased/cli/asciinema/file.rb,
lib/cased/cli/authentication.rb,
lib/cased/collection_response.rb,
lib/cased/sensitive/processor.rb,
lib/cased/cli/asciinema/writer.rb,
lib/cased/cli/interactive_session.rb,
lib/cased/publishers/http_publisher.rb,
lib/cased/publishers/null_publisher.rb,
lib/cased/publishers/test_publisher.rb,
lib/cased/instrumentation/controller.rb,
lib/cased/instrumentation/log_subscriber.rb,
lib/cased/publishers/active_support_publisher.rb,
lib/cased/integrations/sidekiq/client_middleware.rb,
lib/cased/integrations/sidekiq/server_middleware.rb

Defined Under Namespace

Modules: CLI, HTTP, Instrumentation, Integrations, Model, Publishers, Sensitive, TestHelper Classes: Clients, CollectionResponse, Config, Context, Error, Policy, Query, RackMiddleware, Response

Constant Summary collapse

VERSION = 
'0.8.0'

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.publishers ⇒ Array<Cased::Publishers::Base>

The list of publishers that will receive the processed audit event when calling Cased.publish.

The desired behavior for Cased.publish should not change based on the order of the publishers.

Examples:

Adding a publisher to the stack

Cased.publishers << Cased::Publishers::KafkaPublisher.new

Setting the list of publishers

Cased.publishers = [
  Cased::Publishers::KafkaPublisher.new,
]

Returns:



95
96
97
98
99
100
 
# File 'lib/cased.rb', line 95

def self.publishers
  @publishers ||= [
    Cased::Publishers::HTTPPublisher.new,
    Cased::Publishers::ActiveSupportPublisher.new,
  ]
end

Class Method Details

.clients ⇒ Object 



102
103
104
 
# File 'lib/cased.rb', line 102

def self.clients
  @clients ||= Cased::Clients.new
end

.config ⇒ Cased::Config

Returns:



63
64
65
 
# File 'lib/cased.rb', line 63

def self.config
  @config ||= Cased::Config.new
end

.configure(&block) ⇒ void

This method returns an undefined value.

Examples:

Cased.configure do |config|
  config.policy_key = 'policy_test_1dQpY5JliYgHSkEntAbMVzuOROh'
end


73
74
75
 
# File 'lib/cased.rb', line 73

def self.configure(&block)
  block.call(config)
end

.console(options = {}) ⇒ void

This method returns an undefined value.

Configures a default context for console sessions.

When a console session is started you don’t have the context generated from a typical web request lifecycle where authentication will happen and an IP address is present. This uses the server’s hostname as a standard location for migrations or data transitions.

Parameters:

  • options (Hash) (defaults to: {}) 


209
210
211
212
213
 
# File 'lib/cased.rb', line 209

def self.console(options = {})
  context.merge({
    location: Socket.gethostname,
  }.merge(options))
end

.context ⇒ Cased::Context

Returns:



145
146
147
 
# File 'lib/cased.rb', line 145

def self.context
  Context.current
end

.exception_handler ⇒ Proc?

Applications can determine where they want exceptions generated by Cased to be sent.

Returns:

  • (Proc, nil) 


169
170
171
 
# File 'lib/cased.rb', line 169

def self.exception_handler
  @exception_handler
end

.exception_handler=(handler) ⇒ void

This method returns an undefined value.

Sets the system user to be used for Cased events that do not contain an actor.

Examples:

Cased.exception_handler = Proc.new do |exception|
  Raven.capture_exception(exception)
end

Parameters:

  • handler (Proc) —

    • The Proc or lambda that takes a single exception argument.

Raises:

  • (ArgumentError) —

    if the provided handler does not respond to call or accept an argument.



185
186
187
188
189
190
191
192
193
194
195
196
197
 
# File 'lib/cased.rb', line 185

def self.exception_handler=(handler)
  if handler.nil?
    @exception_handler = nil
    return
  elsif !handler.respond_to?(:call)
    @exception_handler = nil
    raise ArgumentError, "#{handler.class} does not respond to #call"
  elsif handler.arity != 1
    raise ArgumentError, 'handler does not accept any arguments'
  end

  @exception_handler = handler
end

.handle_exception(exception) ⇒ void

This method returns an undefined value.

The main entry point to handling any exceptions encountered in the event creation lifecycle.

Parameters:

  • exception (Exception) —

    the exception to be raised

Raises:

  • (Exception) —

    if Cased is configured to raise on errors



155
156
157
158
159
160
161
162
163
164
 
# File 'lib/cased.rb', line 155

def self.handle_exception(exception)
  raise exception if config.raise_on_errors?

  if exception_handler.nil?
    warn exception.message
    return
  end

  exception_handler.call(exception)
end

.id(model) ⇒ String

Generates Cased compatible resource identifier.

Parameters:

  • model (Object) —

    an object that responds to #cased_id

Returns:

  • (String) —

    the Cased::Model#cased_id

Raises:



222
223
224
225
226
 
# File 'lib/cased.rb', line 222

def self.id(model)
  raise Cased::Error::MissingIdentifier unless model.respond_to?(:cased_id)

  model.cased_id
end

.policies ⇒ Hash{Symbol => Cased::Policy, nil}

Examples:

Cased.policies[:organization]

Returns:



37
38
39
40
41
42
43
 
# File 'lib/cased.rb', line 37

def self.policies
  @policies ||= Hash.new do |hash, name|
    key = name.to_sym
    api_key = Cased.config.policy_key(key)
    hash[key] = Policy.new(api_key: api_key)
  end
end

.policy ⇒ Cased::Policy?

Helper method for accessing the applications default policy.

Examples:

Cased.configure do |config|
  config.policy_key = 'policy_test_1dQpY5JliYgHSkEntAbMVzuOROh'
end

policy = Cased.policy
policy.events.each do |event|
  puts event['action'] # => user.login
end

Returns:



58
59
60
 
# File 'lib/cased.rb', line 58

def self.policy
  policies[:default]
end

.publish(audit_event) ⇒ Array, false

Examples:

Cased.publish(
  action: "user.login",
  actor: "[email protected]",
  actor_id: "user_1dQpY5JliYgHSkEntAbMVzuOROh",
  http_user_agent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/83.0.4103.106 Safari/537.36",
  http_url: "https://app.cased.com/",
  http_method: "GET",
  language: "en-US"
)

With User object that includes Cased::Model

Cased.publish(
  action: "user.login",
  actor: User.find(1),
)

Parameters:

  • audit_event (Hash) —

    the audit event.

Returns:

  • (Array) —

    of responses from Cased.publishers

  • (false) —

    if Cased has been silenced.

Raises:

  • (ArgumentError) —

    if a publisher does not implement the #publish method



128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
 
# File 'lib/cased.rb', line 128

def self.publish(audit_event)
  return false if config.silence?

  processed_audit_event = process(audit_event)

  publishers.each do |publisher|
    unless publisher.respond_to?(:publish)
      raise ArgumentError, "#{publisher.class} must implement #{publisher.class}#publish"
    end

    publisher.publish(processed_audit_event.dup)
  rescue StandardError => e
    handle_exception(e)
  end
end

.sensitive(label, handler) ⇒ Object 



28
29
30
 
# File 'lib/cased.rb', line 28

def self.sensitive(label, handler)
  Cased::Sensitive::Handler.register(label, handler)
end

.silence ⇒ Object

Don’t send any events to Cased that are created within the lifecycle of the block.

Examples:

Cased.silence do
  user.save
end


234
235
236
237
238
239
240
 
# File 'lib/cased.rb', line 234

def self.silence
  original_silence = config.silence?
  config.silence = true
  yield
ensure
  config.silence = original_silence
end