Service audit.edgelq.com in version v1alpha2, proto package ntt.audit.v1alpha2

Here is the list of resources supported in Audit service APIv1alpha2:

• ActivityLog resource
• AuditedResourceDescriptor resource
• MethodDescriptor resource
• ResourceChangeLog resource

ActivityLog Resource

ActivityLog Resource - describes notification of activity triggered by a request sent to an API service. ActivityLog creation is triggered by an API service when it receives either unary or stream request.

ActivityLog contains messages exchanged between client and server within single API call and finally exit status. ActivityLog is method oriented - service name + method name (for example IAM/CreateRoleBinding) is a leading information.

ActivityLog can have N associated ResourceChangeLog objects, if API call it describes made some changes in a data store. You can combine ActivityLog and ResourceChangeLog by making queries with request_id specified in a filter.

Name patterns:

• activityLogs/{activity_log}
• projects/{project}/activityLogs/{activity_log}
• organizations/{organization}/activityLogs/{activity_log}

Parent resources:

• Project
• Organization

This section covers the methods and messages to interact with ActivityLog resource.

ActivityLog Methods

Here is the list of ActivityLog resource methods:

• ListActivityLogs method
• CreateActivityLogs method

ListActivityLogs Method

ListActivityLogs

rpc ListActivityLogs(ListActivityLogsRequest) returns (ListActivityLogsResponse)

with the following messages:

• ListActivityLogsRequest request message
• ListActivityLogsResponse response message

Required Permissions:

• services/audit.edgelq.com/permissions/activityLogs.list

The equivalent REST API is:

GET /v1alpha2/activityLogs 

CreateActivityLogs Method

CreateActivityLogs

rpc CreateActivityLogs(CreateActivityLogsRequest) returns (CreateActivityLogsResponse)

with the following messages:

• CreateActivityLogsRequest request message
• CreateActivityLogsResponse response message

Required Permissions:

• services/audit.edgelq.com/permissions/activityLogs.create

The equivalent REST API is:

POST /v1alpha2/activityLogs (BODY: activity_logs)

ActivityLog Messages

Here is the list of ActivityLog resource messages:

• ActivityLog message
• ActivityLog.Event message
• ActivityLog.Method message
• ActivityLog.RequestMetadata message
• ActivityLog.RequestRouting message
• ActivityLog.Resource message
• ActivityLog.Event.ClientMsgEvent message
• ActivityLog.Event.RegionalServerMsgEvent message
• ActivityLog.Event.ServerMsgEvent message
• ActivityLog.Event.RegionalExitEvent message
• ActivityLog.Event.ExitEvent message
• ActivityLog.Resource.Difference message
• ListActivityLogsRequest message
• ListActivityLogsResponse message
• ListActivityLogsResponse.ErrorDetails message
• CreateActivityLogsRequest message
• CreateActivityLogsResponse message

ActivityLog Message

ActivityLog.Event Message

Event associated with activity.

ActivityLog.Method Message

Description of the executed method

ActivityLog.RequestMetadata Message

Additional information about request caller

ActivityLog.RequestRouting Message

Additional information regarding request routing. Request can be:

• Received and executed locally
• Received and redirected to another region
• Received, then split across multiple-regions. Responses are merged before sending back to client

ActivityLog.Resource Message

Description of the main resource activity refers to. For standard, goten-generated actions it’s same as resource assigned to the the method. For custom actions, in some cases, developer may pick however different resource (it is customizable in proto audit spec).

ActivityLog.Event.ClientMsgEvent Message

Describes client message event

ActivityLog.Event.RegionalServerMsgEvent Message

Describes message received from server in specific region. This type is used only for requests, which receiving server decided to split across many regions. Each regional server sends own response and executing server is responsible for merging all partial results into one. This type does not show what was sent to the client. TODO: No use case for now, just placeholder, no server implementation

ActivityLog.Event.ServerMsgEvent Message

Describes server message event

ActivityLog.Event.RegionalExitEvent Message

Describes exit code received from server in specific region. This type is used only for requests, which receiving server decided to split across many regions. Each regional server sends own response and executing server is responsible for merging all partial results into one. IT does not contain status actually sent to the client. TODO: No use case for now, just placeholder, no server implementation

ActivityLog.Event.ExitEvent Message

Describes exit event (request finished)

ActivityLog.Resource.Difference Message

Describes changes (in database) executed on the resource.

ListActivityLogsRequest Message

Request message for method [ListActivityLogs][ntt.audit.v1alpha2.ListActivityLogs]

Returns activities for specified time range and within specified filter. Activity logs are stored only in region which executed them and never duplicated. Because of that its important to pay attention to region IDs in a request object.

Basic supported filters are:

• –filter ‘service.name=[SERVICE_NAME]’ (what is happening in this service)
• –filter ‘service.name=[SERVICE_NAME] and method.type=[METHOD_NAME]’ (what is happening for this API call)
• –filter ‘authentication.principal=[PRINCIPAL_NAME]’ (what that person is doing)
• –filter ‘request_id=[REQUEST_ID]’ (I have request ID, what is actually this?)
• –filter ‘service.name=[SERVICE_NAME] and resource.name=[FULL_RESOURCE_NAME]’ (can I see activities on this resource?)

Its also possible to filter logs by their region of activity - by using field service.region_id in a filter field. Its important to note that logs may be present in multiple locations, if request was routed somewhere else or split & merged across many regions. Those activity logs may have different activity log names, but they will share same values in fields request_id and request_routing.

Be aware, that server will append scope filter condition (and scope=…) to the filter. Scope(s) will be extracted from fields parents in ListActivityLogsRequest object. Note you can query for multiple at once, both projects and organizations.

For all of the above filters you can replace filter condition compare (=) with IN operator. You can therefore query for multiple services, methods or users at once. Above filters are also preferred as we have optimization for them.

Activity logs can be filtered by custom labels (field labels in ActivityLog). Labels are defined per each API method - so you must specify service.name and method.type conditions to be able to query by labels.

For example, suppose you have a CreateVM method, which creates resource “VM”. Suppose there is a field “group” within resource body, which is reference to other resource. If you want to make a query like “who was creating VMs for that group”, then you need to create label “group” inside resource body. Then you will be able to make a query with following filter condition: –filter ‘service.name=vms.domain.com and method.type=CreateVM and labels.group=mySpecialVMGroup’.

Be aware, that Create/Update requests, which have resource object in their own bodies, will automatically inherit resource labels. So, basically you need to define “group” label in resource spec, not inside request. This is useful, as both Create/Update methods will have this label. This also allows code-gen to continue maintaining *derived.proto files.

Examples of usage (with cuttle - we are interested only in one region and scope):

• Checks connections to all devices within ssh-demo project starting from 8th of September 12 UTC time

$ cuttle audit query activity-log –parents ‘project/ssh-demo’ –filter ‘service.name=“devices.edgelq.com” and method.type=“ConnectToDevice” and service.regionId=“us-west”’ –interval ‘{“startTime”:“2020-09-08T12:00:00Z”}’ -o json

*Checks connections to device demo-device within ssh-demo project starting from 8th of September 12 UTC time

$ cuttle audit query activity-log –parents ‘project/ssh-demo’ –filter ‘service.name=“devices.edgelq.com” and method.type=“ConnectToDevice” and service.regionId=“us-west” and resource.name=“projects/ssh-demo/devices/demo-device”’ –interval ‘{“startTime”:“2020-09-08T12:00:00Z”}’ -o json

• Checks what is happening within whole iam service for project demo starting from 8th of September 12 UTC time

$ cuttle audit query activity-log –parents ‘project/demo’ –filter ‘service.name=“iam.edgelq.com” and service.regionId=“us-west”’ –filter ‘service.name=“iam.edgelq.com”’ –interval ‘{“startTime”:“2020-09-08T12:00:00Z”}’ -o json

• Checks activities within one hour for whole iam service for selected methods

$ cuttle audit query activity-log –parents ‘project/demo’ –filter ‘service.name=“iam.edgelq.com” and method.type IN [“CreateRoleBinding”, “UpdateRoleBinding”, “DeleteRoleBinding”] and service.regionId=“us-west”’ –interval ‘{“startTime”:“2020-09-08T12:00:00Z”, “endTime”:“2020-09-08T13:00:00Z”}’ -o json

• Checks modification of RoleBinding

$ cuttle audit query activity-log –parents ‘project/demo’ –filter ‘service.name=“iam.edgelq.com” and method.type=“UpdateRoleBinding” and labels.resource_name=“projects/x/roleBindings/myRB”’ –interval ‘{“startTime”:“2020-09-08T12:00:00Z”}’ -o json

• Checks what was happening with some device

$ cuttle audit query activity-log –parents ‘project/demo’ –filter ‘service.name=“devices.edgelq.com” and resource.name=“projects/x/devices/myDevice” and service.regionId=“us-west”’ –interval ‘{“startTime”:“2020-09-08T12:00:00Z”}’ -o json

• Checks activities made by specific user (we need their email)

$ cuttle audit query activity-log –parents ‘project/demo’ –filter ‘authentication.principal=“user:we.know.who@domain.com” and service.regionId=“us-west”’ –interval ‘{“startTime”:“2020-09-08T12:00:00Z”}’ -o json

• Checks activities made by specific service account (we need it’s email)

$ cuttle audit query activity-log –parents ‘project/demo’ –filter ‘authentication.principal=“serviceAccount:myServiceAccount@domain.com” and service.regionId=“us-west”’

ListActivityLogsResponse Message

Response message for method [ListActivityLogs][ntt.audit.v1alpha2.ListActivityLogs]

ListActivityLogsResponse.ErrorDetails Message

ErrorDetails is used when one of the queried regions fails to produce results. It is used in execution_errors field (see subfield ntt.rpc.Status.details).

CreateActivityLogsRequest Message

Request message for method [CreateActivityLogs][ntt.audit.v1alpha2.CreateActivityLogs]

Creates many activity logs at once - or appends existing, if some of the activity logs already exist (their name is already known).

This request should not be used by regular users - only API services should be able to submit activity logs. Developers of services should use logs exporter package offered along other Audit service packages instead of developing own components.

CreateActivityLogsResponse Message

Response message for method [CreateActivityLogs][ntt.audit.v1alpha2.CreateActivityLogs]

ActivityLog Enumerations

Here is the list of ActivityLog resource enumerations:

• ActivityLog.Category enumeration

ActivityLog.Category Enumeration

Activity log category. Each activity log basically describes read or write action, optionally describes other “operation” type.

AuditedResourceDescriptor Resource

AuditedResourceDescriptor Resource

Name patterns:

• auditedResourceDescriptors/{audited_resource_descriptor}

This section covers the methods and messages to interact with AuditedResourceDescriptor resource.

AuditedResourceDescriptor Methods

Here is the list of AuditedResourceDescriptor resource methods:

• GetAuditedResourceDescriptor method
• BatchGetAuditedResourceDescriptors method
• ListAuditedResourceDescriptors method
• WatchAuditedResourceDescriptor method
• WatchAuditedResourceDescriptors method
• CreateAuditedResourceDescriptor method
• UpdateAuditedResourceDescriptor method

GetAuditedResourceDescriptor Method

GetAuditedResourceDescriptor

rpc GetAuditedResourceDescriptor(GetAuditedResourceDescriptorRequest) returns (AuditedResourceDescriptor)

with the following messages:

• GetAuditedResourceDescriptorRequest request message
• AuditedResourceDescriptor response message

Required Permissions:

• services/audit.edgelq.com/permissions/auditedResourceDescriptors.get

The equivalent REST API is:

GET /v1alpha2/{name=auditedResourceDescriptors/*} 

BatchGetAuditedResourceDescriptors Method

BatchGetAuditedResourceDescriptors

rpc BatchGetAuditedResourceDescriptors(BatchGetAuditedResourceDescriptorsRequest) returns (BatchGetAuditedResourceDescriptorsResponse)

with the following messages:

• BatchGetAuditedResourceDescriptorsRequest request message
• BatchGetAuditedResourceDescriptorsResponse response message

Required Permissions:

• services/audit.edgelq.com/permissions/auditedResourceDescriptors.batchGet

The equivalent REST API is:

GET /v1alpha2/auditedResourceDescriptors:batchGet 

ListAuditedResourceDescriptors Method

ListAuditedResourceDescriptors

rpc ListAuditedResourceDescriptors(ListAuditedResourceDescriptorsRequest) returns (ListAuditedResourceDescriptorsResponse)

with the following messages:

• ListAuditedResourceDescriptorsRequest request message
• ListAuditedResourceDescriptorsResponse response message

Required Permissions:

• services/audit.edgelq.com/permissions/auditedResourceDescriptors.list

The equivalent REST API is:

GET /v1alpha2/auditedResourceDescriptors 

WatchAuditedResourceDescriptor Method

WatchAuditedResourceDescriptor

rpc WatchAuditedResourceDescriptor(WatchAuditedResourceDescriptorRequest) returns (WatchAuditedResourceDescriptorResponse)

with the following messages:

• WatchAuditedResourceDescriptorRequest request message
• WatchAuditedResourceDescriptorResponse response message

Required Permissions:

• services/audit.edgelq.com/permissions/auditedResourceDescriptors.watch

The equivalent REST API is:

POST /v1alpha2/{name=auditedResourceDescriptors/*}:watch 

WatchAuditedResourceDescriptors Method

WatchAuditedResourceDescriptors

rpc WatchAuditedResourceDescriptors(WatchAuditedResourceDescriptorsRequest) returns (WatchAuditedResourceDescriptorsResponse)

with the following messages:

• WatchAuditedResourceDescriptorsRequest request message
• WatchAuditedResourceDescriptorsResponse response message

Required Permissions:

• services/audit.edgelq.com/permissions/auditedResourceDescriptors.watch

The equivalent REST API is:

POST /v1alpha2/auditedResourceDescriptors:watch 

CreateAuditedResourceDescriptor Method

CreateAuditedResourceDescriptor

rpc CreateAuditedResourceDescriptor(CreateAuditedResourceDescriptorRequest) returns (AuditedResourceDescriptor)

with the following messages:

• CreateAuditedResourceDescriptorRequest request message
• AuditedResourceDescriptor response message

Required Permissions:

• services/audit.edgelq.com/permissions/auditedResourceDescriptors.create

The equivalent REST API is:

POST /v1alpha2/auditedResourceDescriptors (BODY: audited_resource_descriptor)

UpdateAuditedResourceDescriptor Method

UpdateAuditedResourceDescriptor

rpc UpdateAuditedResourceDescriptor(UpdateAuditedResourceDescriptorRequest) returns (AuditedResourceDescriptor)

with the following messages:

• UpdateAuditedResourceDescriptorRequest request message
• AuditedResourceDescriptor response message

Required Permissions:

• services/audit.edgelq.com/permissions/auditedResourceDescriptors.update

The equivalent REST API is:

PUT /v1alpha2/{audited_resource_descriptor.name=auditedResourceDescriptors/*} (BODY: audited_resource_descriptor)

AuditedResourceDescriptor Messages

Here is the list of AuditedResourceDescriptor resource messages:

• AuditedResourceDescriptor message
• GetAuditedResourceDescriptorRequest message
• BatchGetAuditedResourceDescriptorsRequest message
• BatchGetAuditedResourceDescriptorsResponse message
• ListAuditedResourceDescriptorsRequest message
• ListAuditedResourceDescriptorsResponse message
• WatchAuditedResourceDescriptorRequest message
• WatchAuditedResourceDescriptorResponse message
• WatchAuditedResourceDescriptorsRequest message
• WatchAuditedResourceDescriptorsResponse message
• WatchAuditedResourceDescriptorsResponse.PageTokenChange message
• CreateAuditedResourceDescriptorRequest message
• CreateAuditedResourceDescriptorRequest.ResponseMask message
• UpdateAuditedResourceDescriptorRequest message
• UpdateAuditedResourceDescriptorRequest.CAS message
• UpdateAuditedResourceDescriptorRequest.ResponseMask message

AuditedResourceDescriptor Message

GetAuditedResourceDescriptorRequest Message

A request message of the GetAuditedResourceDescriptor method.

BatchGetAuditedResourceDescriptorsRequest Message

A request message of the BatchGetAuditedResourceDescriptors method.

BatchGetAuditedResourceDescriptorsResponse Message

A response message of the BatchGetAuditedResourceDescriptors method.

ListAuditedResourceDescriptorsRequest Message

A request message of the ListAuditedResourceDescriptors method.

ListAuditedResourceDescriptorsResponse Message

A response message of the ListAuditedResourceDescriptors method.

WatchAuditedResourceDescriptorRequest Message

A request message of the WatchAuditedResourceDescriptor method.

WatchAuditedResourceDescriptorResponse Message

A response message of the WatchAuditedResourceDescriptor method.

WatchAuditedResourceDescriptorsRequest Message

A request message of the WatchAuditedResourceDescriptors method.

WatchAuditedResourceDescriptorsResponse Message

A response message of the WatchAuditedResourceDescriptors method.

WatchAuditedResourceDescriptorsResponse.PageTokenChange Message

CreateAuditedResourceDescriptorRequest Message

A request message of the CreateAuditedResourceDescriptor method.

CreateAuditedResourceDescriptorRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

UpdateAuditedResourceDescriptorRequest Message

A request message of the UpdateAuditedResourceDescriptor method.

UpdateAuditedResourceDescriptorRequest.CAS Message

CAS - Compare and Swap. This object is used if user wants to make update conditional based upon previous resource version.

UpdateAuditedResourceDescriptorRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

MethodDescriptor Resource

MethodDescriptor Resource

Name patterns:

• methodDescriptors/{method_descriptor}

This section covers the methods and messages to interact with MethodDescriptor resource.

MethodDescriptor Methods

Here is the list of MethodDescriptor resource methods:

• GetMethodDescriptor method
• BatchGetMethodDescriptors method
• ListMethodDescriptors method
• WatchMethodDescriptor method
• WatchMethodDescriptors method
• CreateMethodDescriptor method
• UpdateMethodDescriptor method

GetMethodDescriptor Method

GetMethodDescriptor

rpc GetMethodDescriptor(GetMethodDescriptorRequest) returns (MethodDescriptor)

with the following messages:

• GetMethodDescriptorRequest request message
• MethodDescriptor response message

Required Permissions:

• services/audit.edgelq.com/permissions/methodDescriptors.get

The equivalent REST API is:

GET /v1alpha2/{name=methodDescriptors/*} 

BatchGetMethodDescriptors Method

BatchGetMethodDescriptors

rpc BatchGetMethodDescriptors(BatchGetMethodDescriptorsRequest) returns (BatchGetMethodDescriptorsResponse)

with the following messages:

• BatchGetMethodDescriptorsRequest request message
• BatchGetMethodDescriptorsResponse response message

Required Permissions:

• services/audit.edgelq.com/permissions/methodDescriptors.batchGet

The equivalent REST API is:

GET /v1alpha2/methodDescriptors:batchGet 

ListMethodDescriptors Method

ListMethodDescriptors

rpc ListMethodDescriptors(ListMethodDescriptorsRequest) returns (ListMethodDescriptorsResponse)

with the following messages:

• ListMethodDescriptorsRequest request message
• ListMethodDescriptorsResponse response message

Required Permissions:

• services/audit.edgelq.com/permissions/methodDescriptors.list

The equivalent REST API is:

GET /v1alpha2/methodDescriptors 

WatchMethodDescriptor Method

WatchMethodDescriptor

rpc WatchMethodDescriptor(WatchMethodDescriptorRequest) returns (WatchMethodDescriptorResponse)

with the following messages:

• WatchMethodDescriptorRequest request message
• WatchMethodDescriptorResponse response message

Required Permissions:

• services/audit.edgelq.com/permissions/methodDescriptors.watch

The equivalent REST API is:

POST /v1alpha2/{name=methodDescriptors/*}:watch 

WatchMethodDescriptors Method

WatchMethodDescriptors

rpc WatchMethodDescriptors(WatchMethodDescriptorsRequest) returns (WatchMethodDescriptorsResponse)

with the following messages:

• WatchMethodDescriptorsRequest request message
• WatchMethodDescriptorsResponse response message

Required Permissions:

• services/audit.edgelq.com/permissions/methodDescriptors.watch

The equivalent REST API is:

POST /v1alpha2/methodDescriptors:watch 

CreateMethodDescriptor Method

CreateMethodDescriptor

rpc CreateMethodDescriptor(CreateMethodDescriptorRequest) returns (MethodDescriptor)

with the following messages:

• CreateMethodDescriptorRequest request message
• MethodDescriptor response message

Required Permissions:

• services/audit.edgelq.com/permissions/methodDescriptors.create

The equivalent REST API is:

POST /v1alpha2/methodDescriptors (BODY: method_descriptor)

UpdateMethodDescriptor Method

UpdateMethodDescriptor

rpc UpdateMethodDescriptor(UpdateMethodDescriptorRequest) returns (MethodDescriptor)

with the following messages:

• UpdateMethodDescriptorRequest request message
• MethodDescriptor response message

Required Permissions:

• services/audit.edgelq.com/permissions/methodDescriptors.update

The equivalent REST API is:

PUT /v1alpha2/{method_descriptor.name=methodDescriptors/*} (BODY: method_descriptor)

MethodDescriptor Messages

Here is the list of MethodDescriptor resource messages:

• MethodDescriptor message
• GetMethodDescriptorRequest message
• BatchGetMethodDescriptorsRequest message
• BatchGetMethodDescriptorsResponse message
• ListMethodDescriptorsRequest message
• ListMethodDescriptorsResponse message
• WatchMethodDescriptorRequest message
• WatchMethodDescriptorResponse message
• WatchMethodDescriptorsRequest message
• WatchMethodDescriptorsResponse message
• WatchMethodDescriptorsResponse.PageTokenChange message
• CreateMethodDescriptorRequest message
• CreateMethodDescriptorRequest.ResponseMask message
• UpdateMethodDescriptorRequest message
• UpdateMethodDescriptorRequest.CAS message
• UpdateMethodDescriptorRequest.ResponseMask message

MethodDescriptor Message

GetMethodDescriptorRequest Message

A request message of the GetMethodDescriptor method.

BatchGetMethodDescriptorsRequest Message

A request message of the BatchGetMethodDescriptors method.

BatchGetMethodDescriptorsResponse Message

A response message of the BatchGetMethodDescriptors method.

ListMethodDescriptorsRequest Message

A request message of the ListMethodDescriptors method.

ListMethodDescriptorsResponse Message

A response message of the ListMethodDescriptors method.

WatchMethodDescriptorRequest Message

A request message of the WatchMethodDescriptor method.

WatchMethodDescriptorResponse Message

A response message of the WatchMethodDescriptor method.

WatchMethodDescriptorsRequest Message

A request message of the WatchMethodDescriptors method.

WatchMethodDescriptorsResponse Message

A response message of the WatchMethodDescriptors method.

WatchMethodDescriptorsResponse.PageTokenChange Message

CreateMethodDescriptorRequest Message

A request message of the CreateMethodDescriptor method.

CreateMethodDescriptorRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

UpdateMethodDescriptorRequest Message

A request message of the UpdateMethodDescriptor method.

UpdateMethodDescriptorRequest.CAS Message

CAS - Compare and Swap. This object is used if user wants to make update conditional based upon previous resource version.

UpdateMethodDescriptorRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

ResourceChangeLog Resource

ResourceChangeLog Resource - describes notification of resource change. This log is resource oriented - it strictly is associated with single resource, where service name, resource type and resource name are the strongest attributes.

All resource changes are happening via API calls made to API services. Therefore, each ResourceChangeLog has associated ActivityLog. Relation is 1-N between activity and resource change logs, as one API call can modify multiple resources.

Name patterns:

• resourceChangeLogs/{resource_change_log}
• projects/{project}/resourceChangeLogs/{resource_change_log}
• organizations/{organization}/resourceChangeLogs/{resource_change_log}

Parent resources:

• Project
• Organization

This section covers the methods and messages to interact with ResourceChangeLog resource.

ResourceChangeLog Methods

Here is the list of ResourceChangeLog resource methods:

• ListResourceChangeLogs method
• CreatePreCommittedResourceChangeLogs method
• SetResourceChangeLogsCommitState method

ListResourceChangeLogs Method

ListResourceChangeLogs

rpc ListResourceChangeLogs(ListResourceChangeLogsRequest) returns (ListResourceChangeLogsResponse)

with the following messages:

• ListResourceChangeLogsRequest request message
• ListResourceChangeLogsResponse response message

Required Permissions:

• services/audit.edgelq.com/permissions/resourceChangeLogs.list

The equivalent REST API is:

GET /v1alpha2/resourceChangeLogs 

CreatePreCommittedResourceChangeLogs Method

CreatePreCommittedResourceChangeLogs

rpc CreatePreCommittedResourceChangeLogs(CreatePreCommittedResourceChangeLogsRequest) returns (CreatePreCommittedResourceChangeLogsResponse)

with the following messages:

• CreatePreCommittedResourceChangeLogsRequest request message
• CreatePreCommittedResourceChangeLogsResponse response message

Required Permissions:

• services/audit.edgelq.com/permissions/resourceChangeLogs.submit

The equivalent REST API is:

POST /v1alpha2/resourceChangeLogs 

SetResourceChangeLogsCommitState Method

SetResourceChangeLogsCommitState

rpc SetResourceChangeLogsCommitState(SetResourceChangeLogsCommitStateRequest) returns (SetResourceChangeLogsCommitStateResponse)

with the following messages:

• SetResourceChangeLogsCommitStateRequest request message
• SetResourceChangeLogsCommitStateResponse response message

Required Permissions:

• services/audit.edgelq.com/permissions/resourceChangeLogs.finalize

The equivalent REST API is:

POST /v1alpha2/resourceChangeLogs 

ResourceChangeLog Messages

Here is the list of ResourceChangeLog resource messages:

• ResourceChangeLog message
• ResourceChangeLog.ResourceChange message
• ResourceChangeLog.TransactionInfo message
• ListResourceChangeLogsRequest message
• ListResourceChangeLogsResponse message
• ListResourceChangeLogsResponse.ErrorDetails message
• CreatePreCommittedResourceChangeLogsRequest message
• CreatePreCommittedResourceChangeLogsResponse message
• SetResourceChangeLogsCommitStateRequest message
• SetResourceChangeLogsCommitStateResponse message

ResourceChangeLog Message

ResourceChangeLog.ResourceChange Message

Description of change on the resource

ResourceChangeLog.TransactionInfo Message

Information about transaction where change has been executed

ListResourceChangeLogsRequest Message

Request message for method [ListResourceChangeLogs][ntt.audit.v1alpha2.ListResourceChangeLogs]

Returns resource changes for specified time range, region, scope and filter. Note that resource change logs are Resource oriented - primary object is resource here. Audit monitors resources that have non-custom store.

Note that filter field is mandatory and minimal filters are:

• –filter ‘service.name=[SERVICE_NAME] and resource.type=[RESOURCE_NAME]’ (what is happening for this resource type)
• –filter ‘request_id=[REQUEST_ID]’ (which resources were changed by this request_id?)

Be aware that server will append scope filter condition (and scope IN …) to an any of the above filters. All scopes are extracted from parents field in ListResourceChangeLogsRequest body. This ensures that users can view only scopes he/she is allowed to.

For all of the above filters you can replace filter condition compare (=) with IN operator. You can therefore query for multiple services, methods or users at once. Above filters are also preferred as we have optimization for them.

Resource change logs can also be filtered by custom labels (field labels in ResourceChangeLog - pre and post versions). Labels are custom per each API resource - so you must specify service.name and resource.type conditions to enable them. For example, suppose you have a VM resource which contains “group” field, which is a reference to some other resource. If you create label “group” in VM resource spec (in proto model) you can make a following query: –filter ‘service.name=vms.domain.com and resource.type=VM and resource.post.labels.group=projects/P/vmgroups/myGroup’.

Examples of usage (with cuttle - we are interested only in one region and scope):

• Checks activities within one hour for role binding resources

$ cuttle audit query activity-log –parents ‘project/demo’ –filter ‘service.name=“IAM.edgelq.com” and resource.type=“RoleBinding”’ –interval ‘{“startTime”:“2020-09-08T12:00:00Z”, “endTime”:“2020-09-08T13:00:00Z”}’ -o json

• Checks modification of specific RoleBinding

$ cuttle audit query activity-log –parents ‘project/demo’ –filter ‘service.name=“IAM.edgelq.com” and resource.type=“RoleBinding” and resource.name=“projects/x/roleBindings/myRB”’ –interval ‘{“startTime”:“2020-09-08T12:00:00Z”}’ -o json

• Checks changes on resource RoleBinding made by specific user (we need their email)

$ cuttle audit query resource-change-log –parents ‘project/demo’ –filter ‘service.name=“IAM.edgelq.com” and resource.type=“RoleBinding” and authentication.principal=“user:we.know.who@domain.com”’ –interval ‘{“startTime”:“2020-09-08T12:00:00Z”}’ -o json

ListResourceChangeLogsResponse Message

Response message for method [ListResourceChangeLogs][ntt.audit.v1alpha2.ListResourceChangeLogs]

ListResourceChangeLogsResponse.ErrorDetails Message

ErrorDetails is used when one of the queried regions fails to produce results. It is used in execution_errors field (see subfield ntt.rpc.Status.details).

CreatePreCommittedResourceChangeLogsRequest Message

Request message for method [CreatePreCommittedResourceChangeLogs][ntt.audit.v1alpha2.CreatePreCommittedResourceChangeLogs]

Creates resource change log.

This request should not be used by regular users - only API services should be able to submit resource change logs. Developers of services should use logs exporter package offered along other Audit service packages instead of developing own components.

CreatePreCommittedResourceChangeLogsResponse Message

Response message for method [CreateResourceChangeLogs][ntt.audit.v1alpha2.CreateResourceChangeLogs]

SetResourceChangeLogsCommitStateRequest Message

Request message for method [SetResourceChangeLogsCommitState][ntt.audit.v1alpha2.SetResourceChangeLogsCommitState]

Sets transaction status of selected resource change logs.

This request should not be used by regular users - only API services should be able to modify resource change logs. Developers of services should use logs exporter package offered along other Audit service packages instead of developing own components.

SetResourceChangeLogsCommitStateResponse Message

Response message for method [SetResourceChangeLogsCommitState][ntt.audit.v1alpha2.SetResourceChangeLogsCommitState]

ResourceChangeLog Enumerations

Here is the list of ResourceChangeLog resource enumerations:

• ResourceChangeLog.ResourceChange.Action enumeration
• ResourceChangeLog.TransactionInfo.State enumeration

ResourceChangeLog.ResourceChange.Action Enumeration

Type of change

ResourceChangeLog.TransactionInfo.State Enumeration

State of the transaction.

Audit Service Shared Methods and Messages

Audit Service Shared Messages

Here is the list of Audit service shared messages:

• AuditedResourceDescriptorChange message
• AuditedResourceDescriptorChange.Added message
• AuditedResourceDescriptorChange.Current message
• AuditedResourceDescriptorChange.Modified message
• AuditedResourceDescriptorChange.Removed message
• Authentication message
• Authorization message
• LabelDescriptor message
• LabelKeySet message
• MethodDescriptorChange message
• MethodDescriptorChange.Added message
• MethodDescriptorChange.Current message
• MethodDescriptorChange.Modified message
• MethodDescriptorChange.Removed message
• ObjectState message
• ServiceData message
• TimeInterval message

AuditedResourceDescriptorChange Message

AuditedResourceDescriptorChange is used by Watch notifications Responses to describe change of single AuditedResourceDescriptor One of Added, Modified, Removed

AuditedResourceDescriptorChange.Added Message

AuditedResourceDescriptor has been added to query view

AuditedResourceDescriptorChange.Current Message

AuditedResourceDescriptor has been added or modified in a query view. Version used for stateless watching

AuditedResourceDescriptorChange.Modified Message

AuditedResourceDescriptor changed some of it’s fields - contains either full document or masked change

AuditedResourceDescriptorChange.Removed Message

Removed is returned when AuditedResourceDescriptor is deleted or leaves Query view

Authentication Message

Information about authorized principal who sent a request

Authorization Message

Information about authorization applicable for a request.

LabelDescriptor Message

LabelKeySet Message

LabelKeySet is used for defining PromotedLabelKeySets on Object descriptors

MethodDescriptorChange Message

MethodDescriptorChange is used by Watch notifications Responses to describe change of single MethodDescriptor One of Added, Modified, Removed

MethodDescriptorChange.Added Message

MethodDescriptor has been added to query view

MethodDescriptorChange.Current Message

MethodDescriptor has been added or modified in a query view. Version used for stateless watching

MethodDescriptorChange.Modified Message

MethodDescriptor changed some of it’s fields - contains either full document or masked change

MethodDescriptorChange.Removed Message

Removed is returned when MethodDescriptor is deleted or leaves Query view

ObjectState Message

State of the object - can be resource, request or response. DEPRECATED

ServiceData Message

Information about service processing a request

TimeInterval Message

A time interval extending just after a start time through an end time. If the start time is the same as the end time, then the interval represents a single point in time.