Documentation
¶
Overview ¶
Package audittools provides a toolkit for establishing a connection to a RabbitMQ server (with sane defaults) and publishing audit messages in the CADF format to it. Events are serialized into the subset of CADF that Hermes (https://github.com/sapcc/hermes) can consume.
To use this library, build an Auditor object, then use its Record() function to push events.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func GenerateUUID ¶
func GenerateUUID() string
GenerateUUID generates an UUID based on random numbers (RFC 4122). Failure will result in program termination.
Types ¶
type Auditor ¶
type Auditor interface {
Record(Event)
}
Auditor is a high-level interface for audit event acceptors. In a real process, use NewAuditor() or NewNullAuditor() depending on whether you have RabbitMQ client credentials. In a test scenario, use NewMockAuditor() to get an assertable mock implementation.
func NewAuditor ¶
func NewAuditor(ctx context.Context, opts AuditorOpts) (Auditor, error)
NewAuditor builds an Auditor connected to a RabbitMQ instance, using the provided configuration.
func NewNullAuditor ¶
func NewNullAuditor() Auditor
NewNullAuditor returns an Auditor that does nothing (except produce a debug log of the discarded event). This is only intended to be used for non-productive deployments without a Hermes instance.
type AuditorOpts ¶
type AuditorOpts struct {
// Required. Identifies the current process within the events sent by it.
// The Observer.ID field should be set to a UUID, such as those generated by GenerateUUID().
Observer Observer
// Optional. If given, RabbitMQ connection options will be read from the following environment variables:
// - "${PREFIX}_HOSTNAME" (defaults to "localhost")
// - "${PREFIX}_PORT" (defaults to "5672")
// - "${PREFIX}_USERNAME" (defaults to "guest")
// - "${PREFIX}_PASSWORD" (defaults to "guest")
// - "${PREFIX}_QUEUE_NAME" (required)
EnvPrefix string
// Required if EnvPrefix is empty, ignored otherwise.
// Contains the RabbitMQ connection options that would otherwise be read from environment variables.
ConnectionURL string
QueueName string
// Optional. If given, the Auditor will register its Prometheus metrics with this registry instead of the default registry.
// The following metrics are registered:
// - "audittools_successful_submissions" (counter, no labels)
// - "audittools_failed_submissions" (counter, no labels)
Registry prometheus.Registerer
}
AuditorOpts contains options for NewAuditor().
type Event ¶
type Event struct {
Time time.Time
Request *http.Request
// User is usually a *gopherpolicy.Token instance.
User UserInfo
// ReasonCode is used to determine whether the Event.Outcome was a 'success' or 'failure'.
// It is recommended to use a constant from: https://golang.org/pkg/net/http/#pkg-constants
ReasonCode int
Action cadf.Action
Target Target
}
Event is a high-level representation of an audit event. The Auditor will serialize it into its wire format (type cadf.Event) before sending it to Hermes.
func (Event) ToCADF ¶
ToCADF is a low-level function that converts this event into the CADF format. Most applications will use the high-level interface of Auditor.Record() instead.
Warning: This function uses GenerateUUID() to generate the Event.ID. Unexpected errors during UUID generation will be logged and result in program termination.
type EventParameters ¶
type EventParameters = Event
EventParameters is a deprecated alias for Event.
type MockAuditor ¶
type MockAuditor struct {
// contains filtered or unexported fields
}
MockAuditor is a test double that satisfies the Auditor interface. It stores events sent to it and provides test assertions on those events.
func NewMockAuditor ¶
func NewMockAuditor() *MockAuditor
NewMockAuditor constructs a new MockAuditor instance.
func (*MockAuditor) ExpectEvents ¶
func (a *MockAuditor) ExpectEvents(t *testing.T, expectedEvents ...cadf.Event)
ExpectEvents checks that the recorded events are equivalent to the supplied expectation. At the end of the call, the recording will be disposed, so the next ExpectEvents call will not check against the same events again.
If you do not have a *testing.T (e.g. under Ginkgo), use func RecordedEvents instead.
func (*MockAuditor) IgnoreEventsUntilNow ¶
func (a *MockAuditor) IgnoreEventsUntilNow()
IgnoreEventsUntilNow clears the list of recorded events, so that the next ExpectEvents() or RecordedEvents() will only cover events generated after this point.
func (*MockAuditor) Record ¶
func (a *MockAuditor) Record(event Event)
Record implements the Auditor interface.
func (*MockAuditor) RecordedEvents ¶
func (a *MockAuditor) RecordedEvents() []cadf.Event
RecordedEvents returns the list of recorded events. At the end of the call, the recording will be disposed, so the next RecordedEvents call will not see the same events again.
This is intended for use with test assertion libraries where ExpectEvents does not work For Ginkgo/Gomega specifically, we recommend matching the event payloads with the gstruct submodule of gomega.
type Observer ¶
Observer is like cadf.Resource, but contains only the fields that need to be set for an event observer.
type Target ¶
type Target interface {
// Serializes this object into its wire format as it appears in the Target field of type cadf.Event.
Render() cadf.Resource
}
Target is implemented by types that describe the target object of an audit event. It appears in the high-level Event type from this package.
type UserInfo ¶
type UserInfo interface {
// Serializes this object into its wire format as it appears in the Initiator field of type cadf.Event.
// For events originating in HTTP request handlers, the provided Host object should be placed in the Host field of the result.
AsInitiator(cadf.Host) cadf.Resource
}
UserInfo is implemented by types that describe a user who is taking an action on an OpenStack service. The most important implementor of this interface is *gopherpolicy.Token, for actions taken by authenticated users. Application-specific custom implementors can be used for actions taken by internal processes like cronjobs.
Source Files