README

Tests

Install the dependencies to run the tests:

go get -u github.com/satori/go.uuid
go get -u github.com/stretchr/testify/assert

Documentation

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Actor

type Actor struct {
	// Id is the unique id (in the environment) for this actor
	ID string `json:"id"`

	// Name is the display name for this actor. It can be email
	Name string `json:"name"`

	// Href represents a URL to the actor
	Href string `json:"href"`

	// Fields are any additional data to store with the actor
	Fields Fields `json:"fields,omitempty"`
}

    Actor represents an entity that performs an action

    type Client

    type Client struct {
    
    	// Endpoint is the retraced api base url, default is `https://api.retraced.io`
    	Endpoint string
    	// Component is an identifier for a specific component of a vendor app platform
    	Component string
    	// Version is an identifier for the specific version of this component, usually a git SHA
    	Version string
    	// ViewLogAction is the action logged when a Viewer Token is used, default is 'audit.log.view'
    	ViewLogAction string
    	//
    	HttpClient *http.Client
    	// contains filtered or unexported fields
    }

      Client represents a client that can send events into the retraced service.

      Example

        Initialize a new client with your projectID and API key and then configure options.

        Output:
        
        

        func NewClient

        func NewClient(projectID string, apiToken string) (*Client, error)

          NewClient creates a new retraced api client that can be used to send events

          func NewClientWithVersion

          func NewClientWithVersion(projectID string, apiToken string, component string, version string) (*Client, error)

            NewClientWithVersion Same as NewClient, but includes params for specifying the Component and Version of the Retraced client application

            func (*Client) ExportCSV

            func (c *Client) ExportCSV(ctx context.Context, w io.Writer, sq *StructuredQuery, mask *EventNodeMask) (err error)

              ExportCSV writes all events matching a query to w as CSV records

              func (*Client) GetViewerToken

              func (c *Client) GetViewerToken(groupID string, isAdmin bool, actorID string, targetID string) (*ViewerToken, error)

                GetViewerToken will return a one-time use token that can be used to view a group's audit log.

                func (*Client) NewStream

                func (c *Client) NewStream(sq *StructuredQuery, mask *EventNodeMask) (*Stream, error)

                func (*Client) Query

                func (c *Client) Query(sq *StructuredQuery, mask *EventNodeMask, pageSize int) (EventsPager, error)

                  Query searches for events using the Publisher API's GraphQL endpoint.

                  func (*Client) ReportEvent

                  func (c *Client) ReportEvent(event *Event) (*NewEventRecord, error)

                    ReportEvent is the method to call to send a new event.

                    type Event

                    type Event struct {
                    	// Action is a short, readable word to describe the action
                    	Action string `json:"action"`
                    
                    	// Group is the team that will be able to see this event in the audit log
                    	Group *Group `json:"group,omitempty"`
                    
                    	// Created is a timestamp representing when the event took place
                    	Created time.Time `json:"created"`
                    
                    	// CRUD is a list of the most basic verbs that describe the type of action
                    	CRUD string `json:"crud"`
                    
                    	// Target represents the item that had an action performed on it
                    	Target *Target `json:"target,omitempty"`
                    
                    	// Description is a string with the full details of the event
                    	Description string `json:"description"`
                    
                    	// SourceIP is the client ip address where the event was performed
                    	SourceIP string `json:"source_ip"`
                    
                    	// Actor represents the entity that performed the action
                    	Actor *Actor `json:"actor,omitempty"`
                    
                    	// Fields are any additional data to store with the event
                    	Fields Fields `json:"fields,omitempty"`
                    
                    	// IsFailure is an optional flag that, when set, indicates that this audited event is a failed use of privileges
                    	IsFailure bool `json:"is_failure"`
                    
                    	// IsAnonymous is an optional flag that, when set, indicates that this is an anonymous event
                    	IsAnonymous bool `json:"is_anonymous"`
                    
                    	// Component is an identifier for a specific component of a vendor app platform
                    	// Component can be set on each Event, or on an instance of retraced.Client
                    	Component string `json:"component"`
                    
                    	// Version is an identifier for the specific version of this component, usually a git SHA
                    	// Version can be set on each Event, or on an instance of retraced.Client
                    	Version string `json:"version"`
                    	// contains filtered or unexported fields
                    }

                      Event represents a single audited event. Required fields: Action, Group

                      func (*Event) BuildHashTarget

                      func (event *Event) BuildHashTarget(newEvent *NewEventRecord) []byte

                        BuildHashTarget builds a string that will be used to compute a hash of the event

                        func (*Event) VerifyHash

                        func (event *Event) VerifyHash(newEvent *NewEventRecord) error

                          VerifyHash computes a hash of the sent event, and verifies that it matches the hash we got back from Retraced API

                          type EventEdge

                          type EventEdge struct {
                          	Cursor string     `json:"cursor"`
                          	Node   *EventNode `json:"node"`
                          }

                          type EventNode

                          type EventNode struct {
                          	// ID is the uuid generated by the Retraced API when the event was
                          	// reported.
                          	ID string `json:"id"`
                          
                          	// Action is the reported Action.
                          	Action string `json:"action"`
                          
                          	// Group contains an augmented form of the reported group: if the
                          	// reported event included a group.ID and no group.Name, but the group
                          	// Name could be inferred from the group.ID at the time of creation,
                          	// then group.Name will be defined.
                          	Group *Group `json:"group"`
                          
                          	// Created is the reported Created timestamp.
                          	Created time.Time `json:"created"`
                          
                          	// CRUD is the reported CRUD field.
                          	CRUD string
                          
                          	// Target is an augmented form of the reported target. If the reported
                          	// event included a target.ID, then target.Name, target.Type,
                          	// target.Href, and target.Fields will be populated with any data known
                          	// about the target at the time the event was reported.
                          	Target *Target `json:"target"`
                          
                          	// Description is the reported Description.
                          	Description string `json:"description"`
                          
                          	// SourceIP is the reported SourceIP.
                          	SourceIP string `json:"source_ip"`
                          
                          	// Actor is an augmented form of the reported actor. If the reported
                          	// event included an actor.ID, then actor.Name, actor.Href, and
                          	// actor.Fields will be populated with any data known about the actor
                          	// at the time the event was reported.
                          	Actor *Actor `json:"actor"`
                          
                          	// Fields contains the reported Fields.
                          	Fields Fields `json:"fields"`
                          
                          	// IsFailure is the reported IsFailure flag.
                          	IsFailure bool `json:"is_failure"`
                          
                          	// IsAnonymous is the reported IsAnonymous flag.
                          	IsAnonymous bool `json:"is_anonymous"`
                          
                          	// Component is the reported Component.
                          	Component string `json:"component"`
                          
                          	// Version is the reported Version.
                          	Version string `json:"version"`
                          
                          	// Display the holds the display templates for the event.
                          	Display *Display `json:"display"`
                          
                          	// Country is populated from the reported SourceIP.
                          	Country string `json:"country"`
                          
                          	// LocSubdiv1 is populated from the reported SourceIP.
                          	LocSubdiv1 string `json:"loc_subdiv1"`
                          
                          	// LocSubdiv2 is populated from the reported SourceIP.
                          	LocSubdiv2 string `json:"loc_subdiv2"`
                          
                          	// Received is the timestamp the Retraced API received the reported event.
                          	Received time.Time `json:"received"`
                          
                          	// CanonicalTime is the reported Created timestamp if defined, else the
                          	// Received time.
                          	CanonicalTime time.Time `json:"canonical_time"`
                          
                          	// Raw is the json of the original reported event.
                          	Raw string `json:"raw"`
                          }

                            EventNode represents an event returned from the Retraced GraphQL API. Some fields are identical to the reported Event field and others are modified or added.

                            type EventNodeMask

                            type EventNodeMask struct {
                            	ID            bool
                            	Action        bool
                            	CRUD          bool
                            	Description   bool
                            	IsFailure     bool
                            	IsAnonymous   bool
                            	SourceIP      bool
                            	Country       bool
                            	LocSubdiv1    bool
                            	LocSubdiv2    bool
                            	Received      bool
                            	Created       bool
                            	CanonicalTime bool
                            	Component     bool
                            	Version       bool
                            	Fields        bool
                            	Raw           bool
                            
                            	GroupID   bool
                            	GroupName bool
                            
                            	ActorID     bool
                            	ActorName   bool
                            	ActorHref   bool
                            	ActorFields bool
                            
                            	TargetID     bool
                            	TargetName   bool
                            	TargetHref   bool
                            	TargetType   bool
                            	TargetFields bool
                            
                            	DisplayMarkdown bool
                            }

                              EventNodeMask specifies fields to retrieve in a GraphQL search.

                              func (*EventNodeMask) AnyActor

                              func (mask *EventNodeMask) AnyActor() bool

                                AnyActor is true iff any actor field is on.

                                func (*EventNodeMask) AnyDisplay

                                func (mask *EventNodeMask) AnyDisplay() bool

                                  AnyDisplay is true iff any display field is on.

                                  func (*EventNodeMask) AnyGroup

                                  func (mask *EventNodeMask) AnyGroup() bool

                                    AnyGroup is true iff any group field (id or name) is on.

                                    func (*EventNodeMask) AnyTarget

                                    func (mask *EventNodeMask) AnyTarget() bool

                                      AnyTarget is true iff any target field is on.

                                      func (*EventNodeMask) CSVHeaders

                                      func (mask *EventNodeMask) CSVHeaders() []string

                                        CSVHeaders generates a row of header fields

                                        func (*EventNodeMask) CSVRow

                                        func (mask *EventNodeMask) CSVRow(e *EventNode) []string

                                          CSVRow formats an event as a csv row

                                          func (*EventNodeMask) SearchOpQuery

                                          func (mask *EventNodeMask) SearchOpQuery() (string, error)

                                            SearchOpQuery generates the graphQL query body string for a search operation.

                                            type EventsConnection

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

                                              EventsConnection handles cursor-based pagination over query results.

                                              func (*EventsConnection) CurrentPageNumber

                                              func (ec *EventsConnection) CurrentPageNumber() int

                                              func (*EventsConnection) CurrentResults

                                              func (ec *EventsConnection) CurrentResults() []*EventNode

                                              func (*EventsConnection) HasNextPage

                                              func (ec *EventsConnection) HasNextPage() bool

                                              func (*EventsConnection) HasPreviousPage

                                              func (ec *EventsConnection) HasPreviousPage() bool

                                              func (*EventsConnection) NextPage

                                              func (ec *EventsConnection) NextPage() error

                                              func (*EventsConnection) TotalCount

                                              func (ec *EventsConnection) TotalCount() int

                                              func (*EventsConnection) TotalPages

                                              func (ec *EventsConnection) TotalPages() int

                                              type EventsPager

                                              type EventsPager interface {
                                              	NextPage() error
                                              	TotalPages() int
                                              	HasNextPage() bool
                                              	HasPreviousPage() bool
                                              	CurrentPageNumber() int
                                              	CurrentResults() []*EventNode
                                              	TotalCount() int
                                              }

                                              type Fields

                                              type Fields map[string]string

                                              func (Fields) String

                                              func (fields Fields) String() string

                                                json without chance of error

                                                func (*Fields) UnmarshalJSON

                                                func (fields *Fields) UnmarshalJSON(data []byte) error

                                                  UnmarshalJSON handles [{key: "", value: ""},...] as returned by GraphQL.

                                                  type Group

                                                  type Group struct {
                                                  	// Id is the unique id (in the environment) for this group/team
                                                  	ID string `json:"id"`
                                                  
                                                  	// Name is the display name for this group/team.
                                                  	Name string `json:"name"`
                                                  }

                                                    Group represents a tenant in the application. Audit logs will be scoped by this value.

                                                    type MockEventsPager

                                                    type MockEventsPager struct {
                                                    	Pages [][]*EventNode
                                                    	sync.Mutex
                                                    	// contains filtered or unexported fields
                                                    }

                                                    func (*MockEventsPager) CurrentPageNumber

                                                    func (p *MockEventsPager) CurrentPageNumber() int

                                                    func (*MockEventsPager) CurrentResults

                                                    func (p *MockEventsPager) CurrentResults() []*EventNode

                                                    func (*MockEventsPager) HasNextPage

                                                    func (p *MockEventsPager) HasNextPage() bool

                                                    func (*MockEventsPager) HasPreviousPage

                                                    func (p *MockEventsPager) HasPreviousPage() bool

                                                    func (*MockEventsPager) NextPage

                                                    func (p *MockEventsPager) NextPage() error

                                                    func (*MockEventsPager) TotalCount

                                                    func (p *MockEventsPager) TotalCount() int

                                                    func (*MockEventsPager) TotalPages

                                                    func (p *MockEventsPager) TotalPages() int

                                                    type NewEventRecord

                                                    type NewEventRecord struct {
                                                    	ID   string `json:"id"`
                                                    	Hash string `json:"hash"`
                                                    }

                                                      NewEventRecord is returned from the Retraced API when an event is created

                                                      type Stream

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

                                                        Stream returns a single event on every Read. It wraps an EventsConnection and fetches the next page as needed to fullfill Reads.

                                                        func (*Stream) Read

                                                        func (s *Stream) Read() (*EventNode, error)

                                                          Read returns the next unread Event or io.EOF if there are no more. It is safe for concurrent access.

                                                          type StructuredQuery

                                                          type StructuredQuery struct {
                                                          	Action        string
                                                          	CRUD          string
                                                          	ReceivedStart time.Time
                                                          	ReceivedEnd   time.Time
                                                          	CreatedStart  time.Time
                                                          	CreatedEnd    time.Time
                                                          	ActorName     string
                                                          	ActorID       string
                                                          	Description   string
                                                          	Location      string
                                                          }

                                                          func (*StructuredQuery) String

                                                          func (sq *StructuredQuery) String() string

                                                          type Target

                                                          type Target struct {
                                                          	// Id is the id of the target
                                                          	ID string `json:"id"`
                                                          
                                                          	// Name can be used to represent the name of the target
                                                          	Name string `json:"name"`
                                                          
                                                          	// Type describes the type of target
                                                          	Type string `json:"type"`
                                                          
                                                          	// Href is a reference to the target
                                                          	Href string `json:"href"`
                                                          
                                                          	// Fields can store any additional data on the target
                                                          	Fields Fields `json:"fields,omitempty"`
                                                          }

                                                            Target represents an object that an action was taken on

                                                            type ViewerToken

                                                            type ViewerToken struct {
                                                            	Token string `json:"token"`
                                                            }