Audit | Golang SDK
The audit API is designed for recording a trail of application-based user activity in a scalable, tamper-proof log.
UpdateRoots
func (rp *ArweaveRootsProvider) UpdateRoots(ctx context.Context, treeSizes []string) map[int]RootfetchTransaction
func (s *ArweaveRootsProvider) fetchTransaction(ctx context.Context, txID string, target *Root) errorVerifySignature
func (ee *EventEnvelope) VerifySignature() EventVerificationgetPublicKey
func (ee EventEnvelope) getPublicKey() (string, error)String
func (ev EventVerification) String() stringSignEvent
func (i *LogEvent) SignEvent(s signer.Signer, pki map[string]string) errorIsVerifiable
func (event *SearchEvent) IsVerifiable() boolIsVerifiable checks if a record can be verifiable with the published proof
VerifyConsistencyProof
func (ee *SearchEvent) VerifyConsistencyProof(publishedRoots map[int]Root)VerifyMembershipProof
func (ee *SearchEvent) VerifyMembershipProof(root *Root)VerifiableRecords
func (events SearchEvents) VerifiableRecords() SearchEventsVerifiableRecords returns a slice of records that can be verifiable by the published proof
SetTenant
func (e *StandardEvent) SetTenant(tid string)Tenant
func (e *StandardEvent) Tenant() stringDownload search results
func (a *audit) DownloadResults(ctx context.Context, input *DownloadRequest) (*pangea.PangeaResponse[DownloadResult], error)Get all search results as a compressed (gzip) CSV file.
response, err := client.DownloadResults(ctx, &audit.DownloadRequest{
ResultID: "pas_[...]",
Format: audit.DFcsv,
})
Log an entry
func (a *audit) Log(ctx context.Context, event any, verbose bool) (*pangea.PangeaResponse[LogResult], error)Create a log entry in the Secure Audit Log.
event := audit.Event{
Message: "hello world",
}
logResponse, err := auditcli.Log(ctx, event, true)
Log multiple entries
func (a *audit) LogBulk(ctx context.Context, events []any, verbose bool) (*pangea.PangeaResponse[LogBulkResult], error)Create multiple log entries in the Secure Audit Log.
event := audit.Event{
Message: "hello world",
}
events := []audit.Event{event}
logResponse, err := auditcli.LogBulk(ctx, events, true)
Log multiple entries asynchronously
func (a *audit) LogBulkAsync(ctx context.Context, events []any, verbose bool) (*pangea.PangeaResponse[LogBulkResult], error)Asynchronously create multiple log entries in the Secure Audit Log.
event := audit.Event{
Message: "hello world",
}
events := []audit.Event{event}
logResponse, err := auditcli.LogBulkAsync(ctx, events, true)
Tamperproof verification
func (a *audit) Root(ctx context.Context, input *RootInput) (*pangea.PangeaResponse[RootOutput], error)Returns current root hash and consistency proof.
input := &audit.RootInput{
TreeSize: pangea.Int(10),
}
rootResponse, err := auditcli.Root(ctx, input)
Search for events
func (a *audit) Search(ctx context.Context, input *SearchInput) (*pangea.PangeaResponse[SearchOutput], error)Search for events that match the provided search criteria.
input := &audit.SearchInput{
Query: pangea.String("message:log-123"),
IncludeMembershipProof: pangea.Bool(true),
}
searchResponse, err := auditcli.Search(ctx, input)
Search results
func (a *audit) SearchResults(ctx context.Context, input *SearchResultsInput) (*pangea.PangeaResponse[SearchResultsOutput], error)Page through results from a previous search.
input := &audit.SearchResultsInput{
ID: "pas_sqilrhruwu54uggihqj3aie24wrctakr",
}
res, err := auditcli.SearchResults(ctx, input)
getLogBulkRequest
func (a *audit) getLogBulkRequest(events []any, verbose bool) (*LogBulkRequest, error)getLogEvent
func (a *audit) getLogEvent(event any) (*LogEvent, error)getLogRequest
func (a *audit) getLogRequest(event any, verbose bool) (*LogRequest, error)newEventEnvelopeFromMap
func (a *audit) newEventEnvelopeFromMap(m map[string]any) (*EventEnvelope, error)processLogBulkResult
func (a *audit) processLogBulkResult(ctx context.Context, br *LogBulkResult) errorprocessLogResult
func (a *audit) processLogResult(ctx context.Context, log *LogResult) errorprocessSearchEvents
func (a *audit) processSearchEvents(ctx context.Context, events SearchEvents, root *Root, unpRoot *Root) errorType ArweaveRootsProvider
type ArweaveRootsProvider structtype ArweaveRootsProvider struct {
TreeName string
Client *arweave.Arweave
Roots map[int]Root
}Type Client
type Client interfacetype Client interface {
Log(ctx context.Context, event any, verbose bool) (*pangea.PangeaResponse[LogResult], error)
LogBulk(ctx context.Context, event []any, verbose bool) (*pangea.PangeaResponse[LogBulkResult], error)
LogBulkAsync(ctx context.Context, event []any, verbose bool) (*pangea.PangeaResponse[LogBulkResult], error)
Search(ctx context.Context, req *SearchInput) (*pangea.PangeaResponse[SearchOutput], error)
SearchResults(ctx context.Context, req *SearchResultsInput) (*pangea.PangeaResponse[SearchResultsOutput], error)
Root(ctx context.Context, req *RootInput) (*pangea.PangeaResponse[RootOutput], error)
// Get all search results as a compressed (gzip) CSV file.
DownloadResults(ctx context.Context, input *DownloadRequest) (*pangea.PangeaResponse[DownloadResult], error)
// Base service methods
pangea.BaseServicer
}Type DownloadFormat
type DownloadFormat stringtype DownloadFormat stringType DownloadRequest
type DownloadRequest structtype DownloadRequest struct {
pangea.BaseRequest
// ID returned by the search API.
ResultID string `json:"result_id"`
// Format for the records.
Format DownloadFormat `json:"format,omitempty"`
}Type DownloadResult
type DownloadResult structtype DownloadResult struct {
// URL where search results can be downloaded.
DestURL string `json:"dest_url"`
}Type EventEnvelope
type EventEnvelope structtype EventEnvelope struct {
// A structured record describing that <actor> did <action> on <target>
// changing it from <old> to <new> and the operation was <status>,
// and/or a free-form <message>.
Event any `json:"event"`
// An optional client-side signature for forgery protection.
// max len of 256 bytes
Signature *string `json:"signature,omitempty"`
// The base64-encoded ed25519 public key used for the signature, if one is provided
PublicKey *string `json:"public_key,omitempty"`
// A server-supplied timestamp.
ReceivedAt *pu.PangeaTimestamp `json:"received_at,omitempty"`
}Type EventVerification
type EventVerification inttype EventVerification intType LogBulkRequest
type LogBulkRequest structtype LogBulkRequest struct {
// Base request has ConfigID for multi-config projects
pangea.BaseRequest
Events []*LogEvent `json:"events"`
// If true, be verbose in the response; include root, membership and consistency proof, etc.
// default: false
Verbose bool `json:"verbose"`
}Type LogBulkResult
type LogBulkResult structtype LogBulkResult struct {
Results []LogResult `json:"results"`
}Type LogEvent
type LogEvent structtype LogEvent struct {
// A structured event describing an auditable activity.
Event any `json:"event"`
// An optional client-side signature for forgery protection.
// max len of 256 bytes
Signature *string `json:"signature,omitempty"`
// The base64-encoded ed25519 public key used for the signature, if one is provided
PublicKey *string `json:"public_key,omitempty"`
}Type LogRequest
type LogRequest structtype LogRequest struct {
// Base request has ConfigID for multi-config projects
pangea.BaseRequest
LogEvent
// If true, be verbose in the response; include root, membership and consistency proof, etc.
// default: false
Verbose bool `json:"verbose"`
// Previous unpublished root
PrevRoot *string `json:"prev_root,omitempty"`
}Type LogResult
type LogResult structtype LogResult struct {
EventEnvelope *EventEnvelope
RawEnvelope map[string]any `json:"envelope"`
// The hash of the event data.
// max len of 64 bytes
Hash string `json:"hash"`
UnpublishedRootHash *string `json:"unpublished_root,omitempty"`
MembershipProof *string `json:"membership_proof,omitempty"`
ConsistencyProof *[]string `json:"consistency_proof,omitempty"`
MembershipVerification EventVerification
ConcistencyVerification EventVerification
SignatureVerification EventVerification
}Type LogSigningMode
type LogSigningMode inttype LogSigningMode intType Option
type Option func(*audit) errortype Option func(*audit) errorType Root
type Root structtype Root struct {
// The name of the Merkle Tree
TreeName string `json:"tree_name"`
// The size of the tree (the number of records)
Size int `json:"size"`
// The root hash
// max len of 64 bytes
RootHash string `json:"root_hash"`
// The URL where this root has been published
URL *string `json:"url"`
// The date/time when this root was published
PublishedAt *time.Time `json:"published_at"`
// Consistency proof to verify that this root is a continuation of the previous one
ConsistencyProof *[]string `json:"consistency_proof"`
}Type RootInput
type RootInput structtype RootInput struct {
// Base request has ConfigID for multi-config projects
pangea.BaseRequest
// The size of the tree (the number of records)
TreeSize int `json:"tree_size,omitempty"`
}Type RootOutput
type RootOutput structtype RootOutput struct {
Data Root `json:"data"`
}Type RootsProvider
type RootsProvider interfacetype RootsProvider interface {
UpdateRoots(ctx context.Context, treeSizes []string) map[int]Root
}Type SearchEvent
type SearchEvent structtype SearchEvent struct {
// Include Event data and security information
EventEnvelope *EventEnvelope
RawEnvelope map[string]any `json:"envelope"`
// The record's hash
// len of 64 bytes
Hash string `json:"hash"`
// The index of the leaf of the Merkle Tree where this record was inserted.
LeafIndex *int `json:"leaf_index"`
// A cryptographic proof that the record has been persisted in the log.
MembershipProof *string `json:"membership_proof"`
Published *bool `json:"published"`
MembershipVerification EventVerification
ConsistencyVerification EventVerification
SignatureVerification EventVerification
}Type SearchEvents
type SearchEvents []*SearchEventtype SearchEvents []*SearchEventType SearchInput
type SearchInput structtype SearchInput struct {
// Base request has ConfigID for multi-config projects
pangea.BaseRequest
// Natural search string; list of keywords with optional `<option>:<value>` qualifiers.
//
// Query is a required field.
//
// The following optional qualifiers are supported:
// * action:
// * actor:
// * message:
// * new:
// * old:
// * status:
// * target:
//
// examples:
// actor:root target:/etc/shadow
Query string `json:"query"`
// Specify the sort order of the response. "asc" or "desc"
Order string `json:"order,omitempty"`
// Name of column to sort the results by.
OrderBy string `json:"order_by,omitempty"`
// The start of the time range to perform the search on.
Start *time.Time `json:"start,omitempty"`
// The end of the time range to perform the search on. All records up to the latest if left out.
End *time.Time `json:"end,omitempty"`
// Number of audit records to include from the first page of the results.
Limit int `json:"limit,omitempty"`
// Maximum number of results to return.
// min 1 max 10000
MaxResults int `json:"max_results,omitempty"`
// If true include root, membership and consistency proof
Verbose *bool `json:"verbose,omitempty"`
// A list of keys to restrict the search results to. Useful for partitioning data available to the query string.
SearchRestriction *SearchRestriction `json:"search_restriction,omitempty"`
}Type SearchOutput
type SearchOutput structtype SearchOutput struct {
// Identifier to supply to search_results API to fetch/paginate through search results.
// ID is always populated on a successful response.
ID string `json:"id"`
// The time when the results will no longer be available to page through via the results API.
// ExpiresAt is always populated on a successful response.
ExpiresAt *time.Time `json:"expires_at"`
// The total number of results that were returned by the search.
// Count is always populated on a successful response.
Count int `json:"count"`
// A list of matching audit records.
// Events is always populated on a successful response.
Events SearchEvents `json:"events"`
// A root of a Merkle Tree
Root *Root `json:"root,omitempty"`
// A unpublished root of a Merkle Tree
UnpublishedRoot *Root `json:"unpublished_root,omitempty"`
}Type SearchRestriction
type SearchRestriction structtype SearchRestriction struct {
// A list of actors to restrict the search to.
Actor []string `json:"actor,omitempty"`
// A list of sources to restrict the search to.
Source []string `json:"source,omitempty"`
// A list of targets to restrict the search to.
Target []string `json:"target,omitempty"`
// A list of actions to restrict the search to.
Action []string `json:"action,omitempty"`
// A list of status to restrict the search to.
Status []string `json:"status,omitempty"`
}Type SearchResultsInput
type SearchResultsInput structtype SearchResultsInput struct {
// Base request has ConfigID for multi-config projects
pangea.BaseRequest
// A search results identifier returned by the search call
// ID is a required field
ID string `json:"id"`
// Number of audit records to include from the first page of the results.
Limit int `json:"limit,omitempty"`
// Offset from the start of the result set to start returning results from.
Offset *int `json:"offset,omitempty"`
}Type SearchResultsOutput
type SearchResultsOutput structtype SearchResultsOutput struct {
// The total number of results that were returned by the search.
// Count is always populated on a successful response.
Count int `json:"count"`
// A list of matching audit records.
// Events is always populated on a successful response.
Events SearchEvents `json:"events"`
// A root of a Merkle Tree
Root *Root `json:"root"`
// A unpublished root of a Merkle Tree
UnpublishedRoot *Root `json:"unpublished_root"`
}Type StandardEvent
type StandardEvent structtype StandardEvent struct {
// Record who performed the auditable activity.
// max len is 128 bytes
// examples:
// John Doe
// user-id
// DennisNedry@InGen.com
Actor string `json:"actor,omitempty"`
// The auditable action that occurred."
// max len is 32 bytes
// examples:
// created
// deleted
// updated
Action string `json:"action,omitempty"`
// A message describing a detailed account of what happened.
// This can be recorded as free-form text or as a JSON-formatted string.
// Message is a required field.
// max len of 65536 bytes
Message string `json:"message"`
// The value of a record after it was changed.
// max len of 65536 bytes
New string `json:"new,omitempty"`
// The value of a record before it was changed.
// max len of 65536 bytes
Old string `json:"old,omitempty"`
// Used to record the location from where an activity occurred.
// max len of 128 bytes
Source string `json:"source,omitempty"`
// Record whether or not the activity was successful.
// examples:
// failure
// success
// max len of 32 bytes
Status string `json:"status,omitempty"`
// Used to record the specific record that was targeted by the auditable activity.
// max len of 128 bytes
Target string `json:"target,omitempty"`
// An optional client-supplied timestamp.
Timestamp *pu.PangeaTimestamp `json:"timestamp,omitempty"`
// TenantID field
TenantID string `json:"tenant_id,omitempty"`
}Type Tenanter
type Tenanter interfacetype Tenanter interface {
Tenant() string
SetTenant(string)
}Type ValidateEvents
type ValidateEvents []*ValidatedEventtype ValidateEvents []*ValidatedEventType ValidatedEvent
type ValidatedEvent structtype ValidatedEvent struct {
// the event that was validated
Event *EventEnvelope
// True if the event was successfully validated nil if there is no membership to validate
MembershipProofStatus *bool
// True if the event was successfully validated nil if there is no hash to validate
ConsistencyProofStatus *bool
}Type audit
type audit structtype audit struct {
pangea.BaseService
signer *signer.Signer
verifyProofs bool
skipEventVerification bool
publicKeyInfo map[string]string
rp RootsProvider
lastUnpRootHash *string
tenantID string
schema any
}Type proof
type proof []proofItemtype proof []proofItemType proofItem
type proofItem structtype proofItem struct {
Side proofSide
Hash hash.Hash
}Type proofSide
type proofSide uinttype proofSide uintType rootProof
type rootProof []rootProofItemtype rootProof []rootProofItemType rootProofItem
type rootProofItem structtype rootProofItem struct {
Hash hash.Hash
Proof proof
}