retraced

package module
Version: v0.0.0-...-c67ad26 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 27, 2019 License: Apache-2.0 Imports: 19 Imported by: 0

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.

client, err := NewClient("f4228ca2220d4d0a89d39a93f9987658", "ce6eba2ba9534e94ad48624079bcccf6")
if err != nil {
	log.Fatal(err)
}
client.Component = "Web Dashboard"
client.Version = "0.3.0"
client.ViewLogAction = "audit.log.view"
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"`
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL