hunt

Documentation

Overview

Package hunt provides GRR flow object which handles associated API calls via an arbitrary transfer protocol.

Index

• func EmailCCAddresses(emailAddresses []string) func(args *aupb.ApiCreateHuntApprovalArgs)
• func ListApprovals(ctx context.Context, conn Connector, fn func(a *Approval) error) error
• func ListHunts(ctx context.Context, conn Connector, fn func(h *Hunt) error) (int64, error)
• func ModifyClientLimit(limit int64) func(args *ahpb.ApiModifyHuntArgs)
• func ModifyClientRate(rate int64) func(args *ahpb.ApiModifyHuntArgs)
• func ModifyExpires(expires uint64) func(args *ahpb.ApiModifyHuntArgs)
• type Approval
  • func (a *Approval) Get(ctx context.Context) error
  • func (a *Approval) Grant(ctx context.Context) error
• type Connector
• type ConnectorSubset
• type CreateHuntOption
  • func CreateHuntRunnerArgs(huntRunnerArgs *flowpb.HuntRunnerArgs) CreateHuntOption
• type Hunt
  • func CreateHunt(ctx context.Context, conn Connector, flowName string, flowArgs proto.Message, ...) (*Hunt, error)
  • func NewHunt(huntID string, conn Connector, data *ahpb.ApiHunt) *Hunt
  • func (h *Hunt) Approval(id string, username string) *Approval
  • func (h *Hunt) CreateApproval(ctx context.Context, reason string, notifiedUsers []string, ...) (*Approval, error)
  • func (h *Hunt) Get(ctx context.Context) error
  • func (h *Hunt) GetFilesArchive(ctx context.Context, format *ahpb.ApiGetHuntFilesArchiveArgs_ArchiveFormat) (io.ReadCloser, error)
  • func (h *Hunt) ListResults(ctx context.Context, fn func(r *Result) error) (int64, error)
  • func (h *Hunt) Modify(ctx context.Context, options ...func(args *ahpb.ApiModifyHuntArgs)) error
  • func (h *Hunt) Start(ctx context.Context) error
  • func (h *Hunt) Stop(ctx context.Context) error
• type Result
  • func (r *Result) Payload() (proto.Message, error)

Functions

func EmailCCAddresses

func EmailCCAddresses(emailAddresses []string) func(args *aupb.ApiCreateHuntApprovalArgs)

EmailCCAddresses is an optional argument that can be passed into CreateApproval to add email cc addresses for the operation. Example usage could look like this: CreateApproval(ctx, conn, EmailCCAddresses([]string{...})).

func ListApprovals

func ListApprovals(ctx context.Context, conn Connector, fn func(a *Approval) error) error

ListApprovals sends a request to GRR server to list all the hunt approvals belonging to requesting user and calls fn (a callback function) on each Approval object.

func ListHunts

func ListHunts(ctx context.Context, conn Connector, fn func(h *Hunt) error) (int64, error)

ListHunts sends a request to GRR server to list all GRR hunts and calls fn (a callback function) on each Hunt object. Total count of first request is returned.

func ModifyClientLimit

func ModifyClientLimit(limit int64) func(args *ahpb.ApiModifyHuntArgs)

ModifyClientLimit is an optional argument that can be passed into ModifyHunt to change the client limit of the request. Example usage could look like this: h.ModifyHunt(ctx, hunt.ModifyClientLimit(10)).

func ModifyClientRate

func ModifyClientRate(rate int64) func(args *ahpb.ApiModifyHuntArgs)

ModifyClientRate is an optional argument that can be passed into ModifyHunt to change the client rate of the request. Example usage could look like this: h.ModifyHunt(ctx, hunt.ModifyClientRate(10)).

func ModifyExpires

func ModifyExpires(expires uint64) func(args *ahpb.ApiModifyHuntArgs)

ModifyExpires is an optional argument that can be passed into ModifyHunt to change expires of the request. Example usage could look like this: h.ModifyHunt(ctx, hunt.ModifyExpires(10)).

Types

type Approval

type Approval struct {
	ID       string
	HuntID   string
	Username string
	Data     *aupb.ApiHuntApproval
	// contains filtered or unexported fields
}

Approval wraps ApiHuntApproval data.

func (*Approval) Get

func (a *Approval) Get(ctx context.Context) error

Get sends a request to GRR server to get information for a hunt approval and fills it in Data field. If an error occurs, Data field will stay unchanged.

func (*Approval) Grant

func (a *Approval) Grant(ctx context.Context) error

Grant sends a request to GRR server to grand a hunt approval. If an error occurs, Data field will stay unchanged.

type Connector

type Connector interface {
	ConnectorSubset
	// GetUsername returns username of the current user.
	GetUsername(ctx context.Context) (string, error)
}

Connector abstracts GRR communication protocols (i.e. HTTP, Stubby) and handles API calls related to hunts.

type ConnectorSubset

type ConnectorSubset interface {
	// Lists GRR hunts.
	ListHunts(ctx context.Context, args *ahpb.ApiListHuntsArgs, fn func(m *ahpb.ApiHunt) error) (int64, error)
	// Lists all the results returned by a given hunt.
	ListHuntResults(ctx context.Context, args *ahpb.ApiListHuntResultsArgs, fn func(m *ahpb.ApiHuntResult) error) (int64, error)
	// Gets detailed information about a hunt with a given id.
	GetHunt(ctx context.Context, args *ahpb.ApiGetHuntArgs) (*ahpb.ApiHunt, error)
	// Modifies a hunt.
	ModifyHunt(ctx context.Context, args *ahpb.ApiModifyHuntArgs) (*ahpb.ApiHunt, error)
	// Streams ZIP/TAR.GZ archive with all the files downloaded during the hunt.
	GetHuntFilesArchive(ctx context.Context, args *ahpb.ApiGetHuntFilesArchiveArgs) (io.ReadCloser, error)
	// Returns information for a hunt approval with a given reason.
	GetHuntApproval(ctx context.Context, args *aupb.ApiGetHuntApprovalArgs) (*aupb.ApiHuntApproval, error)
	// Grants (adds caller to the approvers list) hunt approval.
	GrantHuntApproval(ctx context.Context, args *aupb.ApiGrantHuntApprovalArgs) (*aupb.ApiHuntApproval, error)
	// List hunt approvals of a current user.
	ListHuntApprovals(ctx context.Context, args *aupb.ApiListHuntApprovalsArgs, fn func(m *aupb.ApiHuntApproval) error) error
	// Create a new hunt.
	CreateHunt(ctx context.Context, args *ahpb.ApiCreateHuntArgs) (*ahpb.ApiHunt, error)
	// Create a new hunt approval.
	CreateHuntApproval(ctx context.Context, args *aupb.ApiCreateHuntApprovalArgs) (*aupb.ApiHuntApproval, error)
}

ConnectorSubset is introduced due to root object GRRAPI in api.go. GetUsername is an API method that will be used by multiple objects (e.g. Hunt, Client), so ConnectorSubset, rather than Connector defined below, is embedded to Connector in api.go, in order to avoid duplication of GetUsername of that interface.

type CreateHuntOption

type CreateHuntOption func(args *ahpb.ApiCreateHuntArgs)

CreateHuntOption is a function signature for avoiding repetitive typing.

func CreateHuntRunnerArgs

func CreateHuntRunnerArgs(huntRunnerArgs *flowpb.HuntRunnerArgs) CreateHuntOption

CreateHuntRunnerArgs is an optional argument that can be passed into CreateHunt to define the runner arguments of new hunt. Example usage could look like this: CreateHunt(ctx, conn, CreateHuntRunnerArgs(&flowpb.HuntRunnerArgs{...})).

type Hunt

type Hunt struct {
	ID string

	// Proto with hunt information returned from GRR server.
	Data *ahpb.ApiHunt
	// contains filtered or unexported fields
}

Hunt object is a helper object to send requests to GRR server via an arbitrary transfer protocol.

func CreateHunt

func CreateHunt(ctx context.Context, conn Connector, flowName string, flowArgs proto.Message, options ...CreateHuntOption) (*Hunt, error)

CreateHunt sends a request to GRR server to create a new hunt with given flow name and flow args.

func NewHunt

func NewHunt(huntID string, conn Connector, data *ahpb.ApiHunt) *Hunt

NewHunt returns a new hunt with given huntID and connector.

func (*Hunt) Approval

func (h *Hunt) Approval(id string, username string) *Approval

Approval returns a Approval ref with given approval id, username and current hunt id.

func (*Hunt) CreateApproval

func (h *Hunt) CreateApproval(ctx context.Context, reason string, notifiedUsers []string, options ...func(args *aupb.ApiCreateHuntApprovalArgs)) (*Approval, error)

CreateApproval sends a request to GRR server to create a new hunt approval with given reason and notify users.

func (*Hunt) Get

func (h *Hunt) Get(ctx context.Context) error

Get sends a request to GRR server to get information for a hunt and fills it in Data field. If an error occurs, Data field will stay unchanged.

func (*Hunt) GetFilesArchive

func (h *Hunt) GetFilesArchive(ctx context.Context, format *ahpb.ApiGetHuntFilesArchiveArgs_ArchiveFormat) (io.ReadCloser, error)

GetFilesArchive sends a request to GRR server to get ZIP or TAR.GZ archive with all the files downloaded by the hunt. This function starts a goroutine that runs until all data is read, or the readcloser is closed, or an error occurs in the go routine.

func (*Hunt) ListResults

func (h *Hunt) ListResults(ctx context.Context, fn func(r *Result) error) (int64, error)

ListResults sends a request to GRR server to list all the results returned by a given hunt and calls fn (a callback function) on each Result object. Total count of first request is returned.

func (*Hunt) Modify

func (h *Hunt) Modify(ctx context.Context, options ...func(args *ahpb.ApiModifyHuntArgs)) error

Modify sends a request to GRR server to modify a hunt. If an error occurs, Data field will stay unchanged.

func (*Hunt) Start

func (h *Hunt) Start(ctx context.Context) error

Start sends a request to GRR server to start a hunt. If an error occurs, Data field will stay unchanged.

func (*Hunt) Stop

func (h *Hunt) Stop(ctx context.Context) error

Stop sends a request to GRR server to stop a hunt. If an error occurs, Data field will stay unchanged.

type Result

type Result struct {
	Data *ahpb.ApiHuntResult
}

Result wraps ApiHuntResult data.

func (*Result) Payload

func (r *Result) Payload() (proto.Message, error)

Payload returns the payload of a hunt Result.