retraced

package module
v1.0.1 Latest Latest
Warning

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

 Go to latest Published: Aug 23, 2024 License: Apache-2.0 Imports: 18 Imported by: 3

README

Usage

Refer to our docs for details on the usage of this SDK.

Local development

Install the dependencies to run the tests

go get

Run tests

go test -v

Run SDK client test

Ensure you are running Retraced, then run:

go test -timeout 30s -run ^TestClientQuery$ github.com/retracedhq/retraced-go/tests -count=1

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,omitempty"`

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

	// 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("", "dev", "dev")
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(endpoint string, projectID string, apiToken string) (*Client, error)

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

func NewClientWithVersion 

func NewClientWithVersion(endpoint string, 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) DeleteViewerSessions 

func (c *Client) DeleteViewerSessions(groupID string, actorID string) error

DeleteViewerSessions will delete all viewer sessions for the given actor in the given group.

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 Display 

type Display struct {
	Markdown string `json:"markdown"`
}

https://preview.retraced.io/documentation/advanced-retraced/display-templates/

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,omitempty"`

	// SourceIP is the client ip address where the event was performed
	SourceIP string `json:"source_ip,omitempty"`

	// 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,omitempty"`

	// IsAnonymous is an optional flag that, when set, indicates that this is an anonymous event
	IsAnonymous bool `json:"is_anonymous,omitempty"`

	// 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,omitempty"`

	// 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,omitempty"`

	ExternalID string `json:"external_id,omitempty"`

	Metadata Fields `json:"metadata,omitempty"`
	// 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"`

	ExternalID string `json:"external_id"`

	Metadata Fields `json:"metadata"`
}

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
	ExternalID    bool
	Metadata      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. {"key": "value", ...} as returned by json.Marshal when data is marshalled in Go.

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,omitempty"`

	// Type describes the type of target
	Type string `json:"type,omitempty"`

	// Href is a reference to the target
	Href string `json:"href,omitempty"`

	// 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"`
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.