go-agent: github.com/sqreen/go-agent/sdk Index | Files | Directories

package sdk

import "github.com/sqreen/go-agent/sdk"

Index

Package Files

agent.go context.go event.go record.go request.go user.go

Variables

var HTTPRequestRecordContextKey = &ContextKey{"sqreen.rr"}

HTTPRequestRecordContextKey is a context key. It can be used in HTTP handlers with context.Context.Value() to access the HTTPRequestRecord that was associated with the request by the middleware. The associated value will be of type *HTTPRequestRecord.

func GracefulStop Uses

func GracefulStop()

func SetAgent Uses

func SetAgent(a types.Agent)

SetAgent allows the agent to set its SDK entry points. It is automatically set by the agent when it initializes itself.

type ContextKey Uses

type ContextKey struct {
    // This string value must be used by middelware functions whose framework
    // expects context keys of type string, such as Gin. `sdk.FromContext()`
    // expect this behaviour to fallback to string keys when getting the value
    // from the pointer address returned null.
    String string
}

ContextKey allows to insert context values avoiding string collisions. Cf. `context.WithValue()`.

type EventProperties Uses

type EventProperties types.EventProperties

EventProperties is an interface type representing extra custom event properties, suitable for wire-format.

type EventPropertyMap Uses

type EventPropertyMap map[string]string

EventPropertyMap is the type used to represent extra custom event properties.

props := sdk.EventPropertyMap{
	"key1": "value1",
	"key2": "value2",
}
sdk.FromContext(ctx).TrackEvent("my.event").WithProperties(props)

func (EventPropertyMap) MarshalJSON Uses

func (p EventPropertyMap) MarshalJSON() ([]byte, error)

type EventUserIdentifiersMap Uses

type EventUserIdentifiersMap map[string]string

EventUserIdentifiersMap is the type used to represent user identifiers in collected events. It is a key-value map that should uniquely identify a user.

For example:

uid := sdk.EventUserIdentifiersMap{"uid": "my-uid"}
sdk.FromContext(ctx).ForUser(uid).TrackEvent("my.event")

type HTTPRequest Uses

type HTTPRequest struct {
    // contains filtered or unexported fields
}

HTTPRequest is a convenience type to hold together the request and its request record. Most importantly, it is created by `sdk.NewHTTPRequest()` by middleware functions to ensure that the request pointer it contains is the one having the context value expected by `sdk.FromContext()`.

func NewHTTPRequest Uses

func NewHTTPRequest(req *http.Request) *HTTPRequest

NewHTTPRequest returns a new HTTP request handle for the given HTTP request. It is a convenience value making sure the wrapped request has the request record value, which can be retrieved using `sdk.FromContext()` to perform.

func (*HTTPRequest) Close Uses

func (r *HTTPRequest) Close()

func (*HTTPRequest) Record Uses

func (r *HTTPRequest) Record() *HTTPRequestRecord

func (*HTTPRequest) Request Uses

func (r *HTTPRequest) Request() *http.Request

func (*HTTPRequest) SecurityResponse Uses

func (r *HTTPRequest) SecurityResponse() http.Handler

func (*HTTPRequest) UserSecurityResponse Uses

func (r *HTTPRequest) UserSecurityResponse() http.Handler

type HTTPRequestEvent Uses

type HTTPRequestEvent struct {
    // contains filtered or unexported fields
}

HTTPRequestEvent is a SDK event. Its methods allow request handlers to add options further specifying the event, such as a unique user identifier, extra properties, etc.

func (*HTTPRequestEvent) WithProperties Uses

func (e *HTTPRequestEvent) WithProperties(p EventProperties) *HTTPRequestEvent

WithProperties adds custom properties to the event.

props := sdk.EventPropertyMap{
	"key1": "value1",
	"key2": "value2",
}
sdk.FromContext(ctx).TrackEvent("my.event").WithProperties(prop)

func (*HTTPRequestEvent) WithTimestamp Uses

func (e *HTTPRequestEvent) WithTimestamp(t time.Time) *HTTPRequestEvent

WithTimestamp adds a custom timestamp to the event. By default, the timestamp is set to `time.Now()` value at the time of the call to the event creation.

sdk.FromContext(ctx).TrackEvent("my.event").WithTimestamp(yourTimestamp)

func (*HTTPRequestEvent) WithUserIdentifiers Uses

func (e *HTTPRequestEvent) WithUserIdentifiers(id EventUserIdentifiersMap) *HTTPRequestEvent

WithUserIdentifier associates the given user identifier map `id` to the event.

uid := sdk.EventUserIdentifierMap{"uid": "my-uid"}
sdk.FromContext(ctx).Identify(uid)

type HTTPRequestRecord Uses

type HTTPRequestRecord struct {
    // contains filtered or unexported fields
}

HTTPRequestRecord is the SDK record associated to a HTTP request. Its methods allow request handlers to track custom security events.

func FromContext Uses

func FromContext(ctx context.Context) *HTTPRequestRecord

FromContext allows to access the request record from request handlers if present, and nil otherwise. The value is stored in handler contexts by the middleware function of the framework, and is of type *HTTPRequestRecord. It is possible to use it with framework's contexts when they implement Go's `context.Context` interface.

router.GET("/", func(c *gin.Context) {
	// Accessing the SDK through framework's context (when possible).
	sdk.FromContext(c).TrackEvent("my.event.one")
	aFunction(c.Request)
}

func aFunction(req *http.Request) {
	// Accessing the SDK through the request context
	sdk.FromContext(req.Context()).TrackEvent("my.event.two")
	// ...
}

func (*HTTPRequestRecord) Close Uses

func (ctx *HTTPRequestRecord) Close()

Close the request record to signal the HTTP request handling is now done.

func (*HTTPRequestRecord) ForUser Uses

func (ctx *HTTPRequestRecord) ForUser(id EventUserIdentifiersMap) *UserHTTPRequestRecord

ForUser returns a new user request record for the given user `id`. Its methods allow to perform security events related to this user. A call to this method does not create a new event.

Note that it doesn't associate the user to the request unless `Identify()` is explicitly called.

Usage example:

uid := sdk.EventUserIdentifiersMap{"uid": "my-uid"}
sqUser := sdk.FromContext(ctx).ForUser(uid)
sqUser.TrackAuthSuccess()
props := sdk.EventPropertyMap{"key": "value"}
sqUser.TrackEvent("my.event.one").WithProperties(props)

func (*HTTPRequestRecord) TrackEvent Uses

func (ctx *HTTPRequestRecord) TrackEvent(event string) *HTTPRequestEvent

TrackEvent allows to track a custom security-related event having the given event name. It creates a new event whose additional options can be set using the returned value's methods, such as `WithProperties()` or `WithTimestamp()`. A call to this method creates a new event.

uid := sdk.EventUserIdentifiersMap{"uid": "my-uid"}
props := sdk.EventPropertyMap{"key": "value"}
sqreen := sdk.FromContext(ctx)
sqreen.TrackEvent("my.event").WithUserIdentifiers(uid).WithProperties(props)

func (*HTTPRequestRecord) Whitelisted Uses

func (ctx *HTTPRequestRecord) Whitelisted() bool

type SecurityResponseMatch Uses

type SecurityResponseMatch struct {
    Handler http.Handler
}

SecurityResponseMatch is an error type wrapping the security response that matched the request and helping in bubbling up to Sqreen's middleware function to abort the request.

func (SecurityResponseMatch) Error Uses

func (SecurityResponseMatch) Error() string

type UserHTTPRequestEvent Uses

type UserHTTPRequestEvent struct {
    // contains filtered or unexported fields
}

UserHTTPRequestEvent is a SDK event. Its methods allow request handlers to add options further specifying the event, such as a unique user identifier, extra properties, etc.

func (*UserHTTPRequestEvent) WithProperties Uses

func (e *UserHTTPRequestEvent) WithProperties(p EventPropertyMap) *UserHTTPRequestEvent

WithProperties adds custom properties to the event.

props := sdk.EventPropertyMap{
	"key1": "value1",
	"key2": "value2",
}
sdk.FromContext(ctx).TrackEvent("my.event").WithProperties(prop)

func (*UserHTTPRequestEvent) WithTimestamp Uses

func (e *UserHTTPRequestEvent) WithTimestamp(t time.Time) *UserHTTPRequestEvent

WithTimestamp adds a custom timestamp to the event. By default, the timestamp is set to `time.Now()` value at the time of the call to the event creation.

sdk.FromContext(ctx).TrackEvent("my.event").WithTimestamp(yourTimestamp)

type UserHTTPRequestRecord Uses

type UserHTTPRequestRecord struct {
    // contains filtered or unexported fields
}

UserHTTPRequestRecord is the SDK record associated to a HTTP request for a given user. Its methods allow request handlers to signal security events related to the given user. It allows to send security events related to a single user.

func (*UserHTTPRequestRecord) Identify Uses

func (ctx *UserHTTPRequestRecord) Identify() *UserHTTPRequestRecord

Identify globally associates the given user-identifiers to the current request. A call to this method should be followed by a call to method `SecurityResponse()` to check if the request should be aborted.

Every event happening in the same request will be therefore automatically associated to these user-identifiers, unless overwritten and forced using `WithUserIdentifiers()`.

They are also required to find security responses for users, for example to block a specific user.

This method and `MatchSecurityResponse()` are not concurrency-safe.

Usage example:

uid := sdk.EventUserIdentifiersMap{"uid": "my-uid"}
sqUser := sdk.FromContext(ctx).ForUser(uid)
sqUser.Identify()
if match, err := sqUser.MatchSecurityResponse(); match {
	// Return now to stop further handling the request and let Sqreen's
	// middleware apply the configured security response and abort the
	// request. The returned error may help aborting from sub-functions by
	// returning it to the callers when the Go error handling pattern is
	// used.
	return err
}

func (*UserHTTPRequestRecord) MatchSecurityResponse Uses

func (ctx *UserHTTPRequestRecord) MatchSecurityResponse() (match bool, err error)

MatchSecurityResponse returns `true` and a non-nil error if a security response matches the current request. The handler should stop serving the request by returning from the function up to Sqreen's middleware function which will apply the security response and abort the request. Note that `panic()` shouldn't be used.

The returned error may help aborting from sub-functions by returning it to the callers when the Go error handling pattern is used.

This method and `Identify()` are not concurrency-safe.

func (*UserHTTPRequestRecord) TrackAuth Uses

func (ctx *UserHTTPRequestRecord) TrackAuth(loginSuccess bool) *UserHTTPRequestRecord

TrackAuth allows to track a user authentication. The boolean value `loginSuccess` must be true when the user successfully logged in, false otherwise. A call to this method creates a new event.

uid := sdk.EventUserIdentifiersMap{"uid": "my-uid"}
sqUser := sdk.FromContext(ctx).ForUser(uid)
sqUser.TrackAuthSuccess()

func (*UserHTTPRequestRecord) TrackAuthFailure Uses

func (ctx *UserHTTPRequestRecord) TrackAuthFailure() *UserHTTPRequestRecord

TrackAuthFailure is equivalent to `TrackAuth(false)`.

func (*UserHTTPRequestRecord) TrackAuthSuccess Uses

func (ctx *UserHTTPRequestRecord) TrackAuthSuccess() *UserHTTPRequestRecord

TrackAuthSuccess is equivalent to `TrackAuth(true)`.

func (*UserHTTPRequestRecord) TrackEvent Uses

func (ctx *UserHTTPRequestRecord) TrackEvent(event string) *UserHTTPRequestEvent

TrackEvent is a convenience method to send a custom security event associated to the user. It is equivalent to using method `WithUserIdentifiers()` of the regular `TrackEvent()` method. So it is equivalent to `sdk.FromContext(ctx).TrackEvent("event").WithUserIdentifiers(uid)`. This alternative should be considered when performing multiple user events as it allow to write a few less code.

Usage example:

uid := sdk.EventUserIdentifiersMap{"uid": "my-uid"}
sqUser := sdk.FromContext(ctx).ForUser(uid)
sqUser.TrackSignup()
if match, _ := sqUser.MatchSecurityResponse(); match {
	return
}
sqUser.TrackEvent("my.event.one")
sqUser.TrackEvent("my.event.two")
// ...

func (*UserHTTPRequestRecord) TrackSignup Uses

func (ctx *UserHTTPRequestRecord) TrackSignup() *UserHTTPRequestRecord

TrackSignup allows to track a user signup. A call to this method creates a new event.

uid := sdk.EventUserIdentifiersMap{"uid": "my-uid"}
sqUser := sdk.FromContext(ctx).ForUser(uid)
sqUser.TrackSignup()

Directories

PathSynopsis
middleware/sqecho
middleware/sqgin
middleware/sqgrpcThis package provides gRPC interceptors, which are Sqreen's middleware functions for gRPC allowing to monitor and protect the received requests.
middleware/sqhttp

Package sdk imports 5 packages (graph) and is imported by 5 packages. Updated 2019-07-25. Refresh now. Tools for package owners.