This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

SPEKTRA Edge Audit Service API

Understanding the Audit service API.
  • 1:
  • 2:

SPEKTRA Edge audit service helps store audit logs to record all API activities for all users and service accounts. Audit logs provide the ability to check who made a specific operation and the actual changes made to the data (for operations such as create/update). The audit log also records the timestamp and the IP address of the user.

There are two types of audit logs:

  1. Activity Logs
  2. Resource Change Logs

The audit logging is automatically enabled for all SPEKTRA Edge services such as IAM, Devices, Applications, Proxies, Monitoring, Limits, Secrets, etc. It is highly recommended to enable it for all 3rd party services too.

Full API Specifications (with resources):

Resources

Activity Logs

Activity logs record all API operations that are performed by any user.

The contents of the activity log include:

  • scope (project, organization, or service name)
  • request ID (useful to correlate with resource change logs)
  • user data (User email or service account details)
  • metadata (Source IP address of the request and user agent name)
  • request method (MethodName and API version)
  • authorization (List of Permissions that are granted for this operation and list of permissions that were denied)
  • Service information (name and region to which the request is made)
  • resource details (resource name, field-mask for the operation, and resource data before and after the API operation )
  • API request category
    • Create
    • Read
    • Delete
    • SpecUpdate
    • StateUpdate
    • MetadataUpdate
    • Custom Operations
    • Internal
    • Rejected
    • ClientError
    • ServerError
  • events related to the request
    • client request
    • server response
    • regions routing
    • etc.

Resource Change Logs

Resource change logs record the details of the events related to changes made on a specific resource. A resource change log is always related to an activity log. A single API request may modify multiple resources and therefore there is a 1:N relation between the activity log and Resource change log. Activity logs and resource change logs can be correlated using the Request ID field.

The contents of resource change logs include:

  • scope
  • request ID
  • timestamp
  • user data (user name or service account details)
  • Service Information (name and the region to which the request is made)
  • resource change details
    • resource name
    • type
    • value of resource before and after the operation
  • Transaction Details
    • Transaction ID
    • retry counter
    • Transaction States:
      • PRE_COMMITTED
      • COMMITTED
      • ROLLED_BACK

Retrieving logs

In this short quickstart guide we will show you how to retrieve both activity logs and resource change logs using our CLI:

Retrieving Activity logs using CLI

Audit logs can be queried by providing three input parameters:

  • Parents

    Project, Organization, or Service name

  • Interval

    Time interval for the queried data. Start time is mandatory. If the end time is not provided, the current time is taken.

  • Filter

    Activity logs can be filtered based on any of the fields in the API schema.

We support =, !=, IN, and NOT IN filter conditions. Multiple conditions can be combined using AND.

Sample query to fetch activity logs for a given resource:

cuttle audit query activity-logs \
  --parents 'projects/<projectID' \
  --filter 'service.name="devices.edgelq.com" \
    and resource.name="projects/<projectID>/regions/us-west2/devices/<deviceID>"' \
  --interval '{"startTime":"2022-06-07T00:00:00Z"}' \
  --page-size 20 -o json

Sample query to fetch activity logs for a given user:

cuttle audit query activity-logs \
  --parents 'projects/<projectID' \
  --filter 'authentication.principal=”user:<emailID>”"' \
  --interval '{"startTime":"2022-06-07T00:00:00Z"}' \
  --page-size 20 -o json

Sample query to fetch all user triggered API operations in IAM service (skip service accounts):

cuttle audit query activity-logs \
  --parents 'projects/<projectID>' \
  --filter 'service.name="iam.edgelq.com" \
    and authentication.principalType="user"' \
  --interval '{"startTime":"2022-08-10T00:00:00Z"}' \
  --page-size 20 \
  -o json

Sample query to fetch activity logs involving important user triggered changes (using IN condition):

cuttle audit query activity-logs \
  --parents 'projects/<projectID>' \
  --filter 'service.name="devices.edgelq.com" and \
    category IN (“Creation”, “SpecUpdate", “Deletion”)' \
  --interval '{"startTime":"2022-06-07T00:00:00Z"}'

Retrieving Resource Change logs using CLI

Resource Change logs can be queried in a similar way to audit logs:

  • Parents

    Project, Organization, or Service name

  • Interval

    Time interval of the queried data. Start time is mandatory. If the end time is not provided, the current time is taken as the end time.

  • Filter

    Filter must mandatorily specify service.name+resource.type or request_id

Sample query to fetch all resource change logs for a specific request ID (from activity log):

cuttle audit query resource-change-logs \
  --parents 'projects/<projectID>' \
  --filter 'requestId=<requestID from activity log> \
  --interval '{"startTime":"2022-07-20T00:00:00Z"}' \
  -o json

Sample query to fetch all resource change logs for a specific resource type:

cuttle audit query resource-change-logs \
  --parents 'projects/<projectID>' \
  --filter 'service.name="devices.edgelq.com" and resource.type="Device"' \
  --interval '{"startTime":"2022-06-01T00:00:00Z"}' \
  --page-size 20 -o json

Sample query to fetch all resource change logs for a specific resource ID:

cuttle audit query resource-change-logs \
  --parents 'projects/<projectID>' \
  --filter 'service.name="devices.edgelq.com" and \
    resource.type="Device" and \
    resource.name="projects/<projectID>/regions/us-west2/devices/<deviceID>"' \
  --interval '{"startTime":"2022-06-01T00:00:00Z"}' \
  --page-size 20 -o json

1 -

Understanding the audit.edgelq.com service APIv1, in proto package ntt.audit.v1.

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

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

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:

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

Parent resources:

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

ActivityLog Methods

Here is the list of ActivityLog resource methods:

ListActivityLogs Method

ListActivityLogs

rpc ListActivityLogs(ListActivityLogsRequest) returns (ListActivityLogsResponse)

with the following messages:

Required Permissions:

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

The equivalent REST API is:

GET /v1/activityLogs

CreateActivityLogs Method

CreateActivityLogs

rpc CreateActivityLogs(CreateActivityLogsRequest) returns (CreateActivityLogsResponse)

with the following messages:

Required Permissions:

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

The equivalent REST API is:

POST /v1/activityLogs (BODY: activity_logs)

ActivityLog Messages

Here is the list of ActivityLog resource messages:

ActivityLog Message

Name Type Description
name string (name of ActivityLog) Name of ActivityLog. It contains scope + ID of the log. ID is a base64 encoded unique key that identifies tuple: scope request_id authentication.principal request_metadata.ip_address request_metadata.user_agent request_routing.via_region request_routing.dest_regions authorization.granted_permissions authorization.denied_permissions service.name service.region_id method.type method.version resource.name resource.difference.fields category labels Key is not to be decoded outside of service, but treated as opaque string
scope string Contains scope from name field without resource ID. Used for internal purpose for filtering (logs are using custom store). Example formats are: - organization/umbrella - projects/mars_exploration - services/devices.edgelq.com
request_id uint64 Generated ID of the request. Same ID must be used in ResourceChangeLog objects associated with this request.
authentication Authentication Authentication data - informs who made a request
authorization Authorization Authorization data - informs what permissions were granted or denied for associated request
service ServiceData Information about the service
method ActivityLog.Method Information about the method
request_metadata ActivityLog.RequestMetadata Request metadata
request_routing ActivityLog.RequestRouting Request routing
resource ActivityLog.Resource Primary resource for this activity.
category ActivityLog.Category Category of the activity log.
labels map<string, string> List of query-able labels
events repeated ActivityLog.Event List of events attached to this log

ActivityLog.Event Message

Event associated with activity.

Name Type Description
client_message ActivityLog.Event.ClientMsgEvent Client message received event
server_message ActivityLog.Event.ServerMsgEvent Server message sent event
exit ActivityLog.Event.ExitEvent Request finished event
regional_server_message ActivityLog.Event.RegionalServerMsgEvent Server received response from another server (used for split & merge) which describes PARTIAL result to be sent to the client.
regional_exit ActivityLog.Event.RegionalServerMsgEvent Server received exit code from another server (used for split & merge). In case it contains error, its likely final exit will contain this too.

ActivityLog.Method Message

Description of the executed method

Name Type Description
type string Type name of a method, for example “UpdateRoleBinding”.
version string Version in which method was executed.

ActivityLog.RequestMetadata Message

Additional information about request caller

Name Type Description
ip_address string Source IP from where request came
user_agent string Agent used by the 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
Name Type Description
via_region string ID of a region which originally received request, if redirection or split & merge was required
dest_regions repeated string IDs of regions to which request was actually addressed.

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).

Name Type Description
name string full name of the resource
difference ActivityLog.Resource.Difference difference contains update information of the resource. Left empty if the request described by this activity log did not update the resource.

ActivityLog.Event.ClientMsgEvent Message

Describes client message event

Name Type Description
data .google.protobuf.Any Message contents
time .google.protobuf.Timestamp Time of a message

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

Name Type Description
data .google.protobuf.Any Message contents
time .google.protobuf.Timestamp Time of a message
region_id string Region ID where message comes from.

ActivityLog.Event.ServerMsgEvent Message

Describes server message event

Name Type Description
data .google.protobuf.Any Message contents
time .google.protobuf.Timestamp Time of a message

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

Name Type Description
status Status Final status of a request for given region
time .google.protobuf.Timestamp Time when request finished
region_id string Region ID where status comes from

ActivityLog.Event.ExitEvent Message

Describes exit event (request finished)

Name Type Description
status Status Final status of a request
time .google.protobuf.Timestamp Time when request finished

ActivityLog.Resource.Difference Message

Describes changes (in database) executed on the resource.

Name Type Description
fields .google.protobuf.FieldMask List of updated field paths (which are either marked as a state or spec fields). Proper, actual values are stored in “before” and “after” fields. Populated only for updating requests.
before .google.protobuf.Any State of the resource before update. Note that “before” object contains only values of fields present in “fields”. It does not contain whole resource as it was before the update.
after .google.protobuf.Any State of the resource after update. Note that “after” object contains only values of fields present in “fields”. It does not contain whole resource as it is after the update.

ListActivityLogsRequest Message

A request message of the ListActivityLogs method.

It 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. It’s important to note that logs may be present in multiple locations, if request was routed somewhere else or split and 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 'projects/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 'projects/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 'projects/demo' \
  --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 'projects/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 'projects/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 'projects/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 'projects/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 'projects/demo' \
  --filter 'authentication.principal="serviceAccount:sa@domain.com" and \
            service.regionId="us-west"' \
  --interval '{"startTime":"2020-09-08T12:00:00Z"}' \
  -o json
Name Type Description
parents repeated string (parent name of ActivityLog) Parent references of ntt.audit.v1.ActivityLog - provides list of all scopes we want to query about
filter string (filter of ActivityLog) A audit filter that specifies which activity logs should be returned
interval TimeInterval The time interval for which results should be returned. Only logs that contain data points in the specified interval are included in the response.
page_size int32 Cap on a number of activity logs to be included in a response. Number of logs in an actual response can be higher, since logs are read in bulk with second precision - exceed logs above the limit will share same timestamp as the logs below the limit. Results will be adjusted to the “end time” taken from interval field (adjusted also by page_token if provided).
page_token string Token which identifies next page with further results. Token should be taken from [ListActivityLogsResponse.next_page_token][ntt.audit.v1.ListActivityLogsResponse.next_page_token].

ListActivityLogsResponse Message

A response message of the ListActivityLogs method.

Name Type Description
activity_logs repeated ActivityLog One or more activity method logs that match the filter included in the request. Contains results from all queried regions. Its possible however that some logs may be missing, for this see execution_errors.
next_page_token string If there are more results than have been returned, then this field is set to a non-empty value. To see the additional results, use that value as pageToken in the next call to this method.
execution_errors repeated Status Query execution errors that may have caused the response data returned to be incomplete. Because logs are stored only locally (for each region), all activity log queries are split and merged by a receiving request server according to the queried regions. Its possible that some regions will fail when request is redirected to them, but others not. For each failed region, one execution error will be appended. In each ntt.rpc.Status message, fields code and message will contain error obtained from failed regional server, while field details will contain always one item and this item will be of type ErrorDetails.

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).

Name Type Description
region_id string region id which failed to give results.

CreateActivityLogsRequest Message

A request message of the CreateActivityLogs method.

Name Type Description
activity_logs repeated ActivityLog List of activity logs to be added to service. Can be coming from different scopes but must be submitted to the same region and service.

CreateActivityLogsResponse Message

A response message of the CreateActivityLogs nmethod.

Name Type Description
log_names repeated string (name of ActivityLog) Activity log names - one name per each activity log, in same order as in the request

ActivityLog Enumerations

Here is the list of ActivityLog resource enumerations:

ActivityLog.Category Enumeration

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

Name Description
Undefined Undefined, should never be used
Operation Describes all requests that involved execution of some special operation, for example, SSH connection could be put in this category. It’s for requests that cannot be classified clearly as a read or write.
Creation Describes all requests that involved creation of a new resource.
Deletion Describes all requests which involved deletion of an existing resource.
SpecUpdate Describes all update requests that changed specification fields in an existing resource(s).
StateUpdate Describes all update requests that changed state fields in an existing resource(s) (but not specification).
MetaUpdate Describes all update requests that are neither of SpecUpdate or StateUpdate type. It is for non-significant updates like modification of metadata annotations.
Internal Describes an internal update of the system (like controller creating role binding for each group member for each role assigned to group). It includes all CUD requests as long as they are result of an internal system balancing.
Rejected Describes request that has been rejected and therefore no action has happened. This is result of lack of permission/authentication.
ClientError Describes request that has failed due to client error (like validation error)
ServerError Describes request that has failed due to server issue.
Read Describes any read request (like BatchGet, Get, List, Watch).

AuditedResourceDescriptor Resource

AuditedResourceDescriptor Resource

Name patterns:

  • services/{service}/auditedResourceDescriptors/{audited_resource_descriptor}

Parent resources:

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

AuditedResourceDescriptor Methods

Here is the list of AuditedResourceDescriptor resource methods:

GetAuditedResourceDescriptor Method

GetAuditedResourceDescriptor

rpc GetAuditedResourceDescriptor(GetAuditedResourceDescriptorRequest) returns (AuditedResourceDescriptor)

with the following messages:

Required Permissions:

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

The equivalent REST API is:

GET /v1/{name=services/*/auditedResourceDescriptors/*}

BatchGetAuditedResourceDescriptors Method

BatchGetAuditedResourceDescriptors

rpc BatchGetAuditedResourceDescriptors(BatchGetAuditedResourceDescriptorsRequest) returns (BatchGetAuditedResourceDescriptorsResponse)

with the following messages:

Required Permissions:

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

The equivalent REST API is:

GET /v1/auditedResourceDescriptors:batchGet

ListAuditedResourceDescriptors Method

ListAuditedResourceDescriptors

rpc ListAuditedResourceDescriptors(ListAuditedResourceDescriptorsRequest) returns (ListAuditedResourceDescriptorsResponse)

with the following messages:

Required Permissions:

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

The equivalent REST API is:

GET /v1/{parent=services/*}/auditedResourceDescriptors

WatchAuditedResourceDescriptor Method

WatchAuditedResourceDescriptor

rpc WatchAuditedResourceDescriptor(WatchAuditedResourceDescriptorRequest) returns (WatchAuditedResourceDescriptorResponse)

with the following messages:

Required Permissions:

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

The equivalent REST API is:

POST /v1/{name=services/*/auditedResourceDescriptors/*}:watch

WatchAuditedResourceDescriptors Method

WatchAuditedResourceDescriptors

rpc WatchAuditedResourceDescriptors(WatchAuditedResourceDescriptorsRequest) returns (WatchAuditedResourceDescriptorsResponse)

with the following messages:

Required Permissions:

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

The equivalent REST API is:

POST /v1/{parent=services/*}/auditedResourceDescriptors:watch

CreateAuditedResourceDescriptor Method

CreateAuditedResourceDescriptor

rpc CreateAuditedResourceDescriptor(CreateAuditedResourceDescriptorRequest) returns (AuditedResourceDescriptor)

with the following messages:

Required Permissions:

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

The equivalent REST API is:

POST /v1/{parent=services/*}/auditedResourceDescriptors (BODY: audited_resource_descriptor)

UpdateAuditedResourceDescriptor Method

UpdateAuditedResourceDescriptor

rpc UpdateAuditedResourceDescriptor(UpdateAuditedResourceDescriptorRequest) returns (AuditedResourceDescriptor)

with the following messages:

Required Permissions:

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

The equivalent REST API is:

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

DeleteAuditedResourceDescriptor Method

DeleteAuditedResourceDescriptor

rpc DeleteAuditedResourceDescriptor(DeleteAuditedResourceDescriptorRequest) returns (Empty)

with the following messages:

Required Permissions:

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

The equivalent REST API is:

DELETE /v1/{name=services/*/auditedResourceDescriptors/*}

AuditedResourceDescriptor Messages

Here is the list of AuditedResourceDescriptor resource messages:

AuditedResourceDescriptor Message

Name Type Description
name string (name of AuditedResourceDescriptor) Name of AuditedResourceDescriptor
display_name string Optional. A concise name for the audited object type that might be displayed in user interfaces. It should be a Title Cased Noun Phrase, without any article or other determiners.
description string Optional. A detailed description of the audited object type that might be used in documentation.
labels repeated LabelDescriptor Required. A set of labels used to describe instances of this audited resource type. For example, for “RoleBinding” we can define name+member. This can allow us to make query like “who allowed user X to do those things?”
promoted_label_key_sets repeated LabelKeySet Promoted Label Key Sets allow defining multiple indexing rules for underlying backend enabling query optimizations.
versions repeated string List of API versions which define this resource
spec_fields repeated string List of spec fields
state_fields repeated string List of state fields
meta_fields repeated string List of meta fields
metadata Meta Metadata is an object with information like create, update and delete time (for async deleted resources), has user labels/annotations, sharding information, multi-region syncing information and may have non-schema owners (useful for taking ownership of resources belonging to lower level services by higher ones).

GetAuditedResourceDescriptorRequest Message

A request message of the GetAuditedResourceDescriptor method.

Name Type Description
name string (name of AuditedResourceDescriptor) Name of ntt.audit.v1.AuditedResourceDescriptor
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

BatchGetAuditedResourceDescriptorsRequest Message

A request message of the BatchGetAuditedResourceDescriptors method.

Name Type Description
names repeated string (name of AuditedResourceDescriptor) Names of AuditedResourceDescriptors
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

BatchGetAuditedResourceDescriptorsResponse Message

A response message of the BatchGetAuditedResourceDescriptors method.

Name Type Description
audited_resource_descriptors repeated AuditedResourceDescriptor found AuditedResourceDescriptors
missing repeated string (name of AuditedResourceDescriptor) list of not found AuditedResourceDescriptors

ListAuditedResourceDescriptorsRequest Message

A request message of the ListAuditedResourceDescriptors method.

Name Type Description
parent string (parent name of AuditedResourceDescriptor) Parent name of ntt.audit.v1.AuditedResourceDescriptor
page_size int32 Requested page size. Server may return fewer AuditedResourceDescriptors than requested. If unspecified, server will pick an appropriate default.
page_token string (cursor of AuditedResourceDescriptor) A token identifying a page of results the server should return. Typically, this is the value of ListAuditedResourceDescriptorsResponse.next_page_token.
order_by string (orderBy of AuditedResourceDescriptor) Order By - https://cloud.google.com/apis/design/design_patterns#list_pagination list of field path with order directive, either ‘asc’ or ‘desc’. If direction is not provided, ‘asc’ is assumed. e.g. “state.nested_field asc, state.something.else desc, theme”
filter string (filter of AuditedResourceDescriptor) Filter - filter results by field criteria. Simplified SQL-like syntax with following operators: <=, >=, =, !=, <, >, LIKE, CONTAINS (aliases CONTAIN, HAS, HAVE), IN, IS [NOT] NULL
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask
include_paging_info bool Indicates if list response should contain total count and offset (fields current_offset and total_results_count).

ListAuditedResourceDescriptorsResponse Message

A response message of the ListAuditedResourceDescriptors method.

Name Type Description
audited_resource_descriptors repeated AuditedResourceDescriptor The list of AuditedResourceDescriptors
prev_page_token string (cursor of AuditedResourceDescriptor) A token to retrieve previous page of results. Pass this value in the ListAuditedResourceDescriptorsRequest.page_token.
next_page_token string (cursor of AuditedResourceDescriptor) A token to retrieve next page of results. Pass this value in the ListAuditedResourceDescriptorsRequest.page_token.
current_offset int32 Current offset from the first page or 0 if no page tokens were given, paging info was not requested or there was an error while trying to get it). Page index can be computed from offset and limit provided in a request.
total_results_count int32 Number of total AuditedResourceDescriptors across all pages or 0, if there are no items, paging info was not requested or there was an error while trying to get it.

WatchAuditedResourceDescriptorRequest Message

A request message of the WatchAuditedResourceDescriptor method.

Name Type Description
name string (name of AuditedResourceDescriptor) Name of ntt.audit.v1.AuditedResourceDescriptor
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

WatchAuditedResourceDescriptorResponse Message

A response message of the WatchAuditedResourceDescriptor method.

Name Type Description
change AuditedResourceDescriptorChange

WatchAuditedResourceDescriptorsRequest Message

A request message of the WatchAuditedResourceDescriptors method.

Name Type Description
type WatchType Type of a watch. Identifies how server stream data to a client, which fields in a request are allowed and which fields in response are relevant.
parent string (parent name of AuditedResourceDescriptor) Parent name of ntt.audit.v1.AuditedResourceDescriptor
page_size int32 Requested page size. Server may return fewer AuditedResourceDescriptors than requested. If unspecified, server will pick an appropriate default. Can be populated only for stateful watch type.
page_token string (cursor of AuditedResourceDescriptor) A token identifying a page of results the server should return. Can be populated only for stateful watch type.
order_by string (orderBy of AuditedResourceDescriptor) Order By - https://cloud.google.com/apis/design/design_patterns#list_pagination Can be populated only for stateful watch type.
resume_token string A token identifying watch resume point from previous session. Can be populated only for stateless watch type.
starting_time .google.protobuf.Timestamp Point in the time from which we want to start getting updates. This field can be populated only for stateless watch type and if resume token is not known yet. If specified, initial snapshot will NOT be provided. It is assumed client can obtain it using separate means. Watch responses will contain resume tokens which should be used to resume broken connection.
filter string (filter of AuditedResourceDescriptor) Filter - filter results by field criteria. Simplified SQL-like syntax with following operators: <=, >=, =, !=, <, >, LIKE, CONTAINS (aliases CONTAIN, HAS, HAVE), IN, IS [NOT] NULL
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view Changes to AuditedResourceDescriptor that don’t affect any of masked fields won’t be sent back.
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask Changes to AuditedResourceDescriptor that don’t affect any of masked fields won’t be sent back.
max_chunk_size int32 Maximum amount of changes in each response message. Query result response is divided on the server side into chunks with size of a specified amount to limit memory footprint of each message. Responses will hold information whether more elements will continue for the actual change. If unspecified, server will pick an appropriate default.

WatchAuditedResourceDescriptorsResponse Message

A response message of the WatchAuditedResourceDescriptors method.

Name Type Description
audited_resource_descriptor_changes repeated AuditedResourceDescriptorChange Changes of AuditedResourceDescriptors
is_current bool If request specified max_chunk_size (or this limit was enforced if stateless watch has been chosen), then responses with “full changeset” will be divided into chunks. Client should keep receiving messages and, once is_current has value true, combine this recent message with all previous ones where is_current is false. If this is the first is_current in a whole watch stream, then it means that client should have, at this moment, contain snapshot of the current situation (or more accurately, snapshot of situation at the moment of request). All AuditedResourceDescriptors will be of type Added/Current (depending on watch_type specified in the request). Further responses will be incremental - however messages may still be chunked and is_current logic still applies. is_current is always true for stateful watch if max_chunk_size was left to 0.
page_token_change WatchAuditedResourceDescriptorsResponse.PageTokenChange When present, PageTokens used for page navigation should be updated. Present only if is_current is true (last chunk).
resume_token string Token that can be used if current connection drops and client needs to reconnect. Populated only for stateless watch type. Present only if is_current is true (last chunk).
snapshot_size int64 Server may occasionally send information how many resources should client have in its state so far (response message without any changes, but with snapshot_size field specified). If client has different value than the one sent by the server, then it should be treated by a client as an error and should reconnect. If value is smaller then 0, then client should ignore this field as unpopulated. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will be never sent together with is_current, is_soft_reset and is_hard_reset flags.
is_soft_reset bool In case of internal issue server may send response message with this flag. It indicates that client should drop all changes from recent responses where is_current is false only! If last message had is_current set to true, client should do nothing and process normally. Resume token received before is still valid. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will never be sent along with is_current, is_hard_reset or snapshot_size.
is_hard_reset bool In case of internal issue server may send response message with this flag. After receiving, client should clear whole state (drop all changes received so far) as server will send new snapshot (AuditedResourceDescriptors will contains changes of type Current only). Any resume tokens should be discarded as well. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will never be sent along with is_current, is_soft_reset or snapshot_size.

WatchAuditedResourceDescriptorsResponse.PageTokenChange Message

Name Type Description
prev_page_token string (cursor of AuditedResourceDescriptor) New token to retrieve previous page of results.
next_page_token string (cursor of AuditedResourceDescriptor) New token to retrieve next page of results.

CreateAuditedResourceDescriptorRequest Message

A request message of the CreateAuditedResourceDescriptor method.

Name Type Description
parent string (parent name of AuditedResourceDescriptor) Parent name of ntt.audit.v1.AuditedResourceDescriptor
audited_resource_descriptor AuditedResourceDescriptor AuditedResourceDescriptor resource body
response_mask CreateAuditedResourceDescriptorRequest.ResponseMask Optional masking applied to response object to reduce message response size.

CreateAuditedResourceDescriptorRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

Name Type Description
skip_entire_response_body bool If this flag has value true, then response will contain just empty resource without any fields populated.
body_mask .google.protobuf.FieldMask If this field is populated, then resource in response will contain only specific fields.

UpdateAuditedResourceDescriptorRequest Message

A request message of the UpdateAuditedResourceDescriptor method.

Name Type Description
audited_resource_descriptor AuditedResourceDescriptor AuditedResourceDescriptor resource body
update_mask .google.protobuf.FieldMask FieldMask applied to request - change will be applied only for fields in the mask
cas UpdateAuditedResourceDescriptorRequest.CAS Conditional update applied to request if update should be executed only for specific resource state. If this field is populated, then server will fetch existing resource, compare with the one stored in the cas field (after applying field mask) and proceed with update only and only if they match. Otherwise RPC error Aborted will be returned.
allow_missing bool If set to true, and the resource is not found, a new resource will be created. In this situation, ‘field_mask’ is ignored. https://google.aip.dev/134#create-or-update
response_mask UpdateAuditedResourceDescriptorRequest.ResponseMask reduce message response size.

UpdateAuditedResourceDescriptorRequest.CAS Message

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

Name Type Description
conditional_state AuditedResourceDescriptor Conditional desired state of a resource before update.
field_mask .google.protobuf.FieldMask Field paths from conditional state of resource server should check and compare.

UpdateAuditedResourceDescriptorRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

Name Type Description
skip_entire_response_body bool If this flag has value true, then response will contain just empty resource without any fields populated. Field body_mask is ignored if set.
updated_fields_only bool Include all fields that were actually updated during processing. Note this may be larger than update mask if some fields were computed additionally. Name is added as well.
body_mask .google.protobuf.FieldMask If this field is populated, then resource in response will contain only specific fields. If skip_entire_response_body is true, this field is ignored.

DeleteAuditedResourceDescriptorRequest Message

A request message of the DeleteAuditedResourceDescriptor method.

Name Type Description
name string (name of AuditedResourceDescriptor) Name of ntt.audit.v1.AuditedResourceDescriptor

MethodDescriptor Resource

MethodDescriptor Resource

Name patterns:

  • services/{service}/methodDescriptors/{method_descriptor}

Parent resources:

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

MethodDescriptor Methods

Here is the list of MethodDescriptor resource methods:

GetMethodDescriptor Method

GetMethodDescriptor

rpc GetMethodDescriptor(GetMethodDescriptorRequest) returns (MethodDescriptor)

with the following messages:

Required Permissions:

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

The equivalent REST API is:

GET /v1/{name=services/*/methodDescriptors/*}

BatchGetMethodDescriptors Method

BatchGetMethodDescriptors

rpc BatchGetMethodDescriptors(BatchGetMethodDescriptorsRequest) returns (BatchGetMethodDescriptorsResponse)

with the following messages:

Required Permissions:

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

The equivalent REST API is:

GET /v1/methodDescriptors:batchGet

ListMethodDescriptors Method

ListMethodDescriptors

rpc ListMethodDescriptors(ListMethodDescriptorsRequest) returns (ListMethodDescriptorsResponse)

with the following messages:

Required Permissions:

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

The equivalent REST API is:

GET /v1/{parent=services/*}/methodDescriptors

WatchMethodDescriptor Method

WatchMethodDescriptor

rpc WatchMethodDescriptor(WatchMethodDescriptorRequest) returns (WatchMethodDescriptorResponse)

with the following messages:

Required Permissions:

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

The equivalent REST API is:

POST /v1/{name=services/*/methodDescriptors/*}:watch

WatchMethodDescriptors Method

WatchMethodDescriptors

rpc WatchMethodDescriptors(WatchMethodDescriptorsRequest) returns (WatchMethodDescriptorsResponse)

with the following messages:

Required Permissions:

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

The equivalent REST API is:

POST /v1/{parent=services/*}/methodDescriptors:watch

CreateMethodDescriptor Method

CreateMethodDescriptor

rpc CreateMethodDescriptor(CreateMethodDescriptorRequest) returns (MethodDescriptor)

with the following messages:

Required Permissions:

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

The equivalent REST API is:

POST /v1/{parent=services/*}/methodDescriptors (BODY: method_descriptor)

UpdateMethodDescriptor Method

UpdateMethodDescriptor

rpc UpdateMethodDescriptor(UpdateMethodDescriptorRequest) returns (MethodDescriptor)

with the following messages:

Required Permissions:

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

The equivalent REST API is:

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

DeleteMethodDescriptor Method

DeleteMethodDescriptor

rpc DeleteMethodDescriptor(DeleteMethodDescriptorRequest) returns (Empty)

with the following messages:

Required Permissions:

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

The equivalent REST API is:

DELETE /v1/{name=services/*/methodDescriptors/*}

MethodDescriptor Messages

Here is the list of MethodDescriptor resource messages:

MethodDescriptor Message

Name Type Description
name string (name of MethodDescriptor) Name of MethodDescriptor
metadata Meta Metadata is an object with information like create, update and delete time (for async deleted resources), has user labels/annotations, sharding information, multi-region syncing information and may have non-schema owners (useful for taking ownership of resources belonging to lower level services by higher ones).
display_name string Optional. A concise name for the audited object type that might be displayed in user interfaces. It should be a Title Cased Noun Phrase, without any article or other determiners.
description string Optional. A detailed description of the audited method type that might be used in documentation.
labels repeated LabelDescriptor A set of labels used to describe instances of this audited method type. For example, for “UpdateRoleBinding” we can define member label. This can allow us to make query like “who tried to give user X permissions to those things?”
promoted_label_key_sets repeated LabelKeySet Promoted Label Key Sets allow defining multiple indexing rules for underlying backend enabling query optimizations.
versions repeated string List of API versions which define this method

GetMethodDescriptorRequest Message

A request message of the GetMethodDescriptor method.

Name Type Description
name string (name of MethodDescriptor) Name of ntt.audit.v1.MethodDescriptor
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

BatchGetMethodDescriptorsRequest Message

A request message of the BatchGetMethodDescriptors method.

Name Type Description
names repeated string (name of MethodDescriptor) Names of MethodDescriptors
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

BatchGetMethodDescriptorsResponse Message

A response message of the BatchGetMethodDescriptors method.

Name Type Description
method_descriptors repeated MethodDescriptor found MethodDescriptors
missing repeated string (name of MethodDescriptor) list of not found MethodDescriptors

ListMethodDescriptorsRequest Message

A request message of the ListMethodDescriptors method.

Name Type Description
parent string (parent name of MethodDescriptor) Parent name of ntt.audit.v1.MethodDescriptor
page_size int32 Requested page size. Server may return fewer MethodDescriptors than requested. If unspecified, server will pick an appropriate default.
page_token string (cursor of MethodDescriptor) A token identifying a page of results the server should return. Typically, this is the value of ListMethodDescriptorsResponse.next_page_token.
order_by string (orderBy of MethodDescriptor) Order By - https://cloud.google.com/apis/design/design_patterns#list_pagination list of field path with order directive, either ‘asc’ or ‘desc’. If direction is not provided, ‘asc’ is assumed. e.g. “state.nested_field asc, state.something.else desc, theme”
filter string (filter of MethodDescriptor) Filter - filter results by field criteria. Simplified SQL-like syntax with following operators: <=, >=, =, !=, <, >, LIKE, CONTAINS (aliases CONTAIN, HAS, HAVE), IN, IS [NOT] NULL
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask
include_paging_info bool Indicates if list response should contain total count and offset (fields current_offset and total_results_count).

ListMethodDescriptorsResponse Message

A response message of the ListMethodDescriptors method.

Name Type Description
method_descriptors repeated MethodDescriptor The list of MethodDescriptors
prev_page_token string (cursor of MethodDescriptor) A token to retrieve previous page of results. Pass this value in the ListMethodDescriptorsRequest.page_token.
next_page_token string (cursor of MethodDescriptor) A token to retrieve next page of results. Pass this value in the ListMethodDescriptorsRequest.page_token.
current_offset int32 Current offset from the first page or 0 if no page tokens were given, paging info was not requested or there was an error while trying to get it). Page index can be computed from offset and limit provided in a request.
total_results_count int32 Number of total MethodDescriptors across all pages or 0, if there are no items, paging info was not requested or there was an error while trying to get it.

WatchMethodDescriptorRequest Message

A request message of the WatchMethodDescriptor method.

Name Type Description
name string (name of MethodDescriptor) Name of ntt.audit.v1.MethodDescriptor
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

WatchMethodDescriptorResponse Message

A response message of the WatchMethodDescriptor method.

Name Type Description
change MethodDescriptorChange

WatchMethodDescriptorsRequest Message

A request message of the WatchMethodDescriptors method.

Name Type Description
type WatchType Type of a watch. Identifies how server stream data to a client, which fields in a request are allowed and which fields in response are relevant.
parent string (parent name of MethodDescriptor) Parent name of ntt.audit.v1.MethodDescriptor
page_size int32 Requested page size. Server may return fewer MethodDescriptors than requested. If unspecified, server will pick an appropriate default. Can be populated only for stateful watch type.
page_token string (cursor of MethodDescriptor) A token identifying a page of results the server should return. Can be populated only for stateful watch type.
order_by string (orderBy of MethodDescriptor) Order By - https://cloud.google.com/apis/design/design_patterns#list_pagination Can be populated only for stateful watch type.
resume_token string A token identifying watch resume point from previous session. Can be populated only for stateless watch type.
starting_time .google.protobuf.Timestamp Point in the time from which we want to start getting updates. This field can be populated only for stateless watch type and if resume token is not known yet. If specified, initial snapshot will NOT be provided. It is assumed client can obtain it using separate means. Watch responses will contain resume tokens which should be used to resume broken connection.
filter string (filter of MethodDescriptor) Filter - filter results by field criteria. Simplified SQL-like syntax with following operators: <=, >=, =, !=, <, >, LIKE, CONTAINS (aliases CONTAIN, HAS, HAVE), IN, IS [NOT] NULL
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view Changes to MethodDescriptor that don’t affect any of masked fields won’t be sent back.
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask Changes to MethodDescriptor that don’t affect any of masked fields won’t be sent back.
max_chunk_size int32 Maximum amount of changes in each response message. Query result response is divided on the server side into chunks with size of a specified amount to limit memory footprint of each message. Responses will hold information whether more elements will continue for the actual change. If unspecified, server will pick an appropriate default.

WatchMethodDescriptorsResponse Message

A response message of the WatchMethodDescriptors method.

Name Type Description
method_descriptor_changes repeated MethodDescriptorChange Changes of MethodDescriptors
is_current bool If request specified max_chunk_size (or this limit was enforced if stateless watch has been chosen), then responses with “full changeset” will be divided into chunks. Client should keep receiving messages and, once is_current has value true, combine this recent message with all previous ones where is_current is false. If this is the first is_current in a whole watch stream, then it means that client should have, at this moment, contain snapshot of the current situation (or more accurately, snapshot of situation at the moment of request). All MethodDescriptors will be of type Added/Current (depending on watch_type specified in the request). Further responses will be incremental - however messages may still be chunked and is_current logic still applies. is_current is always true for stateful watch if max_chunk_size was left to 0.
page_token_change WatchMethodDescriptorsResponse.PageTokenChange When present, PageTokens used for page navigation should be updated. Present only if is_current is true (last chunk).
resume_token string Token that can be used if current connection drops and client needs to reconnect. Populated only for stateless watch type. Present only if is_current is true (last chunk).
snapshot_size int64 Server may occasionally send information how many resources should client have in its state so far (response message without any changes, but with snapshot_size field specified). If client has different value than the one sent by the server, then it should be treated by a client as an error and should reconnect. If value is smaller then 0, then client should ignore this field as unpopulated. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will be never sent together with is_current, is_soft_reset and is_hard_reset flags.
is_soft_reset bool In case of internal issue server may send response message with this flag. It indicates that client should drop all changes from recent responses where is_current is false only! If last message had is_current set to true, client should do nothing and process normally. Resume token received before is still valid. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will never be sent along with is_current, is_hard_reset or snapshot_size.
is_hard_reset bool In case of internal issue server may send response message with this flag. After receiving, client should clear whole state (drop all changes received so far) as server will send new snapshot (MethodDescriptors will contains changes of type Current only). Any resume tokens should be discarded as well. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will never be sent along with is_current, is_soft_reset or snapshot_size.

WatchMethodDescriptorsResponse.PageTokenChange Message

Name Type Description
prev_page_token string (cursor of MethodDescriptor) New token to retrieve previous page of results.
next_page_token string (cursor of MethodDescriptor) New token to retrieve next page of results.

CreateMethodDescriptorRequest Message

A request message of the CreateMethodDescriptor method.

Name Type Description
parent string (parent name of MethodDescriptor) Parent name of ntt.audit.v1.MethodDescriptor
method_descriptor MethodDescriptor MethodDescriptor resource body
response_mask CreateMethodDescriptorRequest.ResponseMask Optional masking applied to response object to reduce message response size.

CreateMethodDescriptorRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

Name Type Description
skip_entire_response_body bool If this flag has value true, then response will contain just empty resource without any fields populated.
body_mask .google.protobuf.FieldMask If this field is populated, then resource in response will contain only specific fields.

UpdateMethodDescriptorRequest Message

A request message of the UpdateMethodDescriptor method.

Name Type Description
method_descriptor MethodDescriptor MethodDescriptor resource body
update_mask .google.protobuf.FieldMask FieldMask applied to request - change will be applied only for fields in the mask
cas UpdateMethodDescriptorRequest.CAS Conditional update applied to request if update should be executed only for specific resource state. If this field is populated, then server will fetch existing resource, compare with the one stored in the cas field (after applying field mask) and proceed with update only and only if they match. Otherwise RPC error Aborted will be returned.
allow_missing bool If set to true, and the resource is not found, a new resource will be created. In this situation, ‘field_mask’ is ignored. https://google.aip.dev/134#create-or-update
response_mask UpdateMethodDescriptorRequest.ResponseMask reduce message response size.

UpdateMethodDescriptorRequest.CAS Message

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

Name Type Description
conditional_state MethodDescriptor Conditional desired state of a resource before update.
field_mask .google.protobuf.FieldMask Field paths from conditional state of resource server should check and compare.

UpdateMethodDescriptorRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

Name Type Description
skip_entire_response_body bool If this flag has value true, then response will contain just empty resource without any fields populated. Field body_mask is ignored if set.
updated_fields_only bool Include all fields that were actually updated during processing. Note this may be larger than update mask if some fields were computed additionally. Name is added as well.
body_mask .google.protobuf.FieldMask If this field is populated, then resource in response will contain only specific fields. If skip_entire_response_body is true, this field is ignored.

DeleteMethodDescriptorRequest Message

A request message of the DeleteMethodDescriptor method.

Name Type Description
name string (name of MethodDescriptor) Name of ntt.audit.v1.MethodDescriptor

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:

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

Parent resources:

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

ResourceChangeLog Methods

Here is the list of ResourceChangeLog resource methods:

ListResourceChangeLogs Method

ListResourceChangeLogs

rpc ListResourceChangeLogs(ListResourceChangeLogsRequest) returns (ListResourceChangeLogsResponse)

with the following messages:

Required Permissions:

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

The equivalent REST API is:

GET /v1/resourceChangeLogs

CreatePreCommittedResourceChangeLogs Method

CreatePreCommittedResourceChangeLogs

rpc CreatePreCommittedResourceChangeLogs(CreatePreCommittedResourceChangeLogsRequest) returns (CreatePreCommittedResourceChangeLogsResponse)

with the following messages:

Required Permissions:

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

The equivalent REST API is:

POST /v1/resourceChangeLogs

SetResourceChangeLogsCommitState Method

SetResourceChangeLogsCommitState

rpc SetResourceChangeLogsCommitState(SetResourceChangeLogsCommitStateRequest) returns (SetResourceChangeLogsCommitStateResponse)

with the following messages:

Required Permissions:

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

The equivalent REST API is:

POST /v1/resourceChangeLogs

ResourceChangeLog Messages

Here is the list of ResourceChangeLog resource messages:

ResourceChangeLog Message

Name Type Description
name string (name of ResourceChangeLog) Name of ResourceChangeLog. It contains scope + ID of the log. ID is a base64 encoded unique key that identifies tuple: scope request_id authentication.principal service.name service.region_id resource.name resource.type resource.pre.labels resource.post.labels ID part should not be decoded, but treated as opaque string
scope string Contains scope from name field without resource ID. Used for internal purpose for filtering (logs are using custom store). Supported formats are: - organization/umbrella - projects/mars_exploration - services/devices.edgelq.com
request_id uint64 Unique identifier of request - it must match the one in the associated activity log.
timestamp .google.protobuf.Timestamp Time of the change - equal to request timestamp (activity log)
authentication Authentication Authentication data - informs who made a change
service ServiceData Information about the service
resource ResourceChangeLog.ResourceChange Describes change on the resource
transaction ResourceChangeLog.TransactionInfo Describes state of the transaction

ResourceChangeLog.ResourceChange Message

Description of change on the resource

Name Type Description
name string Fully qualified name of the resource (eg. “RoleBinding/Public”) that has changed from this request (if successful)
type string Name of the resource type for example “RoleBinding”.
action ResourceChangeLog.ResourceChange.Action Action on the resource
updated_fields .google.protobuf.FieldMask Field mask with different fields, populated only for update action types.
previous .google.protobuf.Any Previous values of updated fields. Its populated only if update_fields is provided and for those fields only. It is skipped for deletes.
current .google.protobuf.Any Current values of updated fields in case of update. Whole resource in case of creation, empty in case of deletion.
labels map<string, string> List of query-able labels. They are taken from both before and after resource, but after has higher priority
pre ObjectState State of the resource before change. It is empty if action is CREATE DEPRECATED and not populated for new resources
post ObjectState State of the resource after change. It is empty if action is DELETE DEPRECATED and not populated for new resources

ResourceChangeLog.TransactionInfo Message

Information about transaction where change has been executed

Name Type Description
identifier string unique identifier of the transaction.
try_counter int32 Indicator of try counter. If transaction has been concluded at first try, try_counter will be 1. If on the second try, then number will be 2 (etc).
state ResourceChangeLog.TransactionInfo.State State of the transaction.

ListResourceChangeLogsRequest Message

A request message of the ListResourceChangeLogs method.

It 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 'projects/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 'projects/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 'projects/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
Name Type Description
parents repeated string (parent name of ResourceChangeLog) Parent names of ntt.audit.v1.ResourceChangeLog
filter string (filter of ResourceChangeLog) A audit filter that specifies which resource change logs should be returned
interval TimeInterval The time interval for which results should be returned. Only logs that contain data points in the specified interval are included in the response.
page_size int32 Cap on a number of resource change logs to be included in a response. Number of logs in an actual response can be higher, since logs are read in bulk with second precision - exceed logs above the limit will share same timestamp as the logs below the limit. Results will be adjusted to the “end time” taken from interval field (adjusted also by page_token if provided).
page_token string Token which identifies next page with further results. Token should be taken from ListResourceChangeLogsResponse [ListResourceChangeLogsResponse.next_page_token][ntt.audit.v1.ListResourceChangeLogsResponse.next_page_token].

ListResourceChangeLogsResponse Message

A response message of the ListResourceChangeLogs method.

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.

Name Type Description
resource_change_logs repeated ResourceChangeLog One or more resource change logs that match the filter included in the request. Contains results from all queried regions. Its possible however that some logs may be missing, for this see execution_errors.
next_page_token string If there are more results than have been returned, then this field is set to a non-empty value. To see the additional results, use that value as pageToken in the next call to this method.
execution_errors repeated Status Query execution errors that may have caused the response data returned to be incomplete. Because logs are stored only locally (for each region), all resource change log queries are split and merged by a receiving request server according to the queried regions. Its possible that some regions will fail when request is redirected to them, but others not. For each failed region, one execution error will be appended. In each ntt.rpc.Status message, fields code and message will contain error obtained from failed regional server, while field details will contain always one item and this item will be of type ErrorDetails.

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).

Name Type Description
region_id string region id which failed to give results.

CreatePreCommittedResourceChangeLogsRequest Message

A request message of the CreatePreCommittedResourceChangeLogs method.

Name Type Description
request_id uint64 ID of the request - must be same as the one used in activity logs
timestamp .google.protobuf.Timestamp Time of the request
authentication Authentication Authentication data - informs who made a change
service ServiceData Information about the service
transaction ResourceChangeLog.TransactionInfo Information about transaction
changes repeated ResourceChangeLog.ResourceChange List of changes

CreatePreCommittedResourceChangeLogsResponse Message

A response message of the CreatePreCommittedResourceChangeLogs method.

Name Type Description
log_keys repeated bytes Resource change log keys - one key per each resource change, in same order

SetResourceChangeLogsCommitStateRequest Message

A request message of the SetResourceChangeLogsCommitState method.

Name Type Description
log_keys repeated bytes list of resource change log keys.
service ServiceData Information about the service - must be same as before, used for authorization purpose
timestamp .google.protobuf.Timestamp Time of the request - must be same as in CreatePreCommittedResourceChangeLogsRequest
tx_result ResourceChangeLog.TransactionInfo.State final state of the transaction - must be COMMITTED or ROLLED_BACK

SetResourceChangeLogsCommitStateResponse Message

A response message of the SetResourceChangeLogsCommitState method.

Name Type Description
none none none

ResourceChangeLog Enumerations

Here is the list of ResourceChangeLog resource enumerations:

ResourceChangeLog.ResourceChange.Action Enumeration

Type of change

Name Description
UNDEFINED to avoid blank item when printing logs
CREATE Resource has been created
DELETE Resource has been deleted
SPEC_UPDATE Update contains spec fields
STATE_UPDATE Update contains state fields, but not spec
META_UPDATE Update contains neither spec or state fields.
UPDATE UPDATE is deprecated in favor of specific update types.

ResourceChangeLog.TransactionInfo.State Enumeration

State of the transaction.

Name Description
UNDEFINED
PRE_COMMITTED Indicates that this change did not happen - it is just proposal of the change. Such a log should be followed by another ResourceChangeLog with value COMMITTED or ROLLED_BACK. If one transaction has been retried multiple times, then there may be multiple records with PRE_COMMITTED, last record should indicate final transaction state.
COMMITTED Indicates change has been committed successfully.
ROLLED_BACK Indicates that change did not happen. Log of this type should be treated as attempt of change.

Audit Service Shared Methods and Messages

Audit Service Shared Messages

Here is the list of Audit service shared messages:

AuditedResourceDescriptorChange Message

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

Name Type Description
added AuditedResourceDescriptorChange.Added Added is returned when watched document is added, either created or enters Query view
modified AuditedResourceDescriptorChange.Modified Modified is returned when watched document is modified
current AuditedResourceDescriptorChange.Current Current is returned in stateless watch when document enters query view or is modified within.
removed AuditedResourceDescriptorChange.Removed Removed is returned when AuditedResourceDescriptor is deleted or leaves Query view

AuditedResourceDescriptorChange.Added Message

AuditedResourceDescriptor has been added to query view

Name Type Description
audited_resource_descriptor AuditedResourceDescriptor
view_index int32 Integer describing index of added AuditedResourceDescriptor in resulting query view.

AuditedResourceDescriptorChange.Current Message

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

Name Type Description
audited_resource_descriptor AuditedResourceDescriptor

AuditedResourceDescriptorChange.Modified Message

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

Name Type Description
name string (name of AuditedResourceDescriptor) Name of modified AuditedResourceDescriptor
audited_resource_descriptor AuditedResourceDescriptor New version of AuditedResourceDescriptor or masked difference, depending on mask_changes instrumentation of issued [WatchAuditedResourceDescriptorRequest] or [WatchAuditedResourceDescriptorsRequest]
field_mask .google.protobuf.FieldMask Used when mask_changes is set, contains field paths of modified properties.
previous_view_index int32 Previous view index specifies previous position of modified AuditedResourceDescriptor. When modification doesn’t affect sorted order, value will remain identical to [view_index].
view_index int32 Integer specifying AuditedResourceDescriptor new index in resulting query view.

AuditedResourceDescriptorChange.Removed Message

Removed is returned when AuditedResourceDescriptor is deleted or leaves Query view

Name Type Description
name string (name of AuditedResourceDescriptor)
view_index int32 Integer specifying removed AuditedResourceDescriptor index. Not populated in stateless watch type.

Authentication Message

Information about authorized principal who sent a request

Name Type Description
principal string Name of the principal, for example: “user:our_new_admin@example.com”
principal_type string Principal type - user, serviceAccount, anonymous

Authorization Message

Information about authorization applicable for a request.

Name Type Description
granted_permissions repeated string List of permissions that were granted
denied_permissions repeated string List of permissions that were denied

LabelDescriptor Message

Name Type Description
key string The label key.
versions repeated string List of versions where label is supported

LabelKeySet Message

LabelKeySet is used for defining PromotedLabelKeySets on Object descriptors

Name Type Description
label_keys repeated string
versions repeated string List of versions where label set is supported

MethodDescriptorChange Message

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

Name Type Description
added MethodDescriptorChange.Added Added is returned when watched document is added, either created or enters Query view
modified MethodDescriptorChange.Modified Modified is returned when watched document is modified
current MethodDescriptorChange.Current Current is returned in stateless watch when document enters query view or is modified within.
removed MethodDescriptorChange.Removed Removed is returned when MethodDescriptor is deleted or leaves Query view

MethodDescriptorChange.Added Message

MethodDescriptor has been added to query view

Name Type Description
method_descriptor MethodDescriptor
view_index int32 Integer describing index of added MethodDescriptor in resulting query view.

MethodDescriptorChange.Current Message

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

Name Type Description
method_descriptor MethodDescriptor

MethodDescriptorChange.Modified Message

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

Name Type Description
name string (name of MethodDescriptor) Name of modified MethodDescriptor
method_descriptor MethodDescriptor New version of MethodDescriptor or masked difference, depending on mask_changes instrumentation of issued [WatchMethodDescriptorRequest] or [WatchMethodDescriptorsRequest]
field_mask .google.protobuf.FieldMask Used when mask_changes is set, contains field paths of modified properties.
previous_view_index int32 Previous view index specifies previous position of modified MethodDescriptor. When modification doesn’t affect sorted order, value will remain identical to [view_index].
view_index int32 Integer specifying MethodDescriptor new index in resulting query view.

MethodDescriptorChange.Removed Message

Removed is returned when MethodDescriptor is deleted or leaves Query view

Name Type Description
name string (name of MethodDescriptor)
view_index int32 Integer specifying removed MethodDescriptor index. Not populated in stateless watch type.

ObjectState Message

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

Name Type Description
data .google.protobuf.Any Object data
labels map<string, string> Values for all of the labels listed in the associated audited object descriptor - they are extracted from protobuf object and used for filtering

ServiceData Message

Information about service processing a request

Name Type Description
name string Fully qualified service name executing a request
region_id string Region of the service handling this 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.

Name Type Description
end_time .google.protobuf.Timestamp Optional - end of the time interval. If not provided, current time will be assumed.
start_time .google.protobuf.Timestamp Required. The beginning of the time interval. The start time must not be later than the end time.

2 -

Understanding the audit.edgelq.com service APIv1alpha2, in proto package ntt.audit.v1alpha2.

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

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:

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

ActivityLog Methods

Here is the list of ActivityLog resource methods:

ListActivityLogs Method

ListActivityLogs

rpc ListActivityLogs(ListActivityLogsRequest) returns (ListActivityLogsResponse)

with the following messages:

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:

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

Name Type Description
name string (name of ActivityLog) Name of ActivityLog. It contains scope + ID of the log. ID is a base64 encoded unique key that identifies tuple: scope request_id authentication.principal request_metadata.ip_address request_metadata.user_agent request_routing.via_region request_routing.dest_regions authorization.granted_permissions authorization.denied_permissions service.name service.region_id method.type method.version resource.name resource.difference.fields category labels Key is not to be decoded outside of service, but treated as opaque string
scope string Contains scope from name field without resource ID. Used for internal purpose for filtering (logs are using custom store). Example formats are: - organization/umbrella - projects/mars_exploration - <system>
request_id uint64 Generated ID of the request. Same ID must be used in ResourceChangeLog objects associated with this request.
authentication Authentication Authentication data - informs who made a request
authorization Authorization Authorization data - informs what permissions were granted or denied for associated request
service ServiceData Information about the service
method ActivityLog.Method Information about the method
request_metadata ActivityLog.RequestMetadata Request metadata
request_routing ActivityLog.RequestRouting Request routing
resource ActivityLog.Resource Primary resource for this activity.
category ActivityLog.Category Category of the activity log.
labels map<string, string> List of query-able labels
events repeated ActivityLog.Event List of events attached to this log

ActivityLog.Event Message

Event associated with activity.

Name Type Description
client_message ActivityLog.Event.ClientMsgEvent Client message received event
server_message ActivityLog.Event.ServerMsgEvent Server message sent event
exit ActivityLog.Event.ExitEvent Request finished event
regional_server_message ActivityLog.Event.RegionalServerMsgEvent Server received response from another server (used for split & merge) which describes PARTIAL result to be sent to the client.
regional_exit ActivityLog.Event.RegionalServerMsgEvent Server received exit code from another server (used for split & merge). In case it contains error, its likely final exit will contain this too.

ActivityLog.Method Message

Description of the executed method

Name Type Description
type string Type name of a method, for example “UpdateRoleBinding”.
version string Version in which method was executed.

ActivityLog.RequestMetadata Message

Additional information about request caller

Name Type Description
ip_address string Source IP from where request came
user_agent string Agent used by the 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
Name Type Description
via_region string ID of a region which originally received request, if redirection or split & merge was required
dest_regions repeated string IDs of regions to which request was actually addressed.

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).

Name Type Description
name string full name of the resource
difference ActivityLog.Resource.Difference difference contains update information of the resource. Left empty if the request described by this activity log did not update the resource.

ActivityLog.Event.ClientMsgEvent Message

Describes client message event

Name Type Description
data .google.protobuf.Any Message contents
time .google.protobuf.Timestamp Time of a message

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

Name Type Description
data .google.protobuf.Any Message contents
time .google.protobuf.Timestamp Time of a message
region_id string Region ID where message comes from.

ActivityLog.Event.ServerMsgEvent Message

Describes server message event

Name Type Description
data .google.protobuf.Any Message contents
time .google.protobuf.Timestamp Time of a message

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

Name Type Description
status Status Final status of a request for given region
time .google.protobuf.Timestamp Time when request finished
region_id string Region ID where status comes from

ActivityLog.Event.ExitEvent Message

Describes exit event (request finished)

Name Type Description
status Status Final status of a request
time .google.protobuf.Timestamp Time when request finished

ActivityLog.Resource.Difference Message

Describes changes (in database) executed on the resource.

Name Type Description
fields .google.protobuf.FieldMask List of updated field paths (which are either marked as a state or spec fields). Proper, actual values are stored in “before” and “after” fields. Populated only for updating requests.
before .google.protobuf.Any State of the resource before update. Note that “before” object contains only values of fields present in “fields”. It does not contain whole resource as it was before the update.
after .google.protobuf.Any State of the resource after update. Note that “after” object contains only values of fields present in “fields”. It does not contain whole resource as it is after the update.

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”’

Name Type Description
parents repeated string (parent name of ActivityLog) Parent references of ntt.audit.v1alpha2.ActivityLog - provides list of all scopes we want to query about
filter string (filter of ActivityLog) A audit filter that specifies which activity logs should be returned
interval TimeInterval The time interval for which results should be returned. Only logs that contain data points in the specified interval are included in the response.
page_size int32 Cap on a number of activity logs to be included in a response. Number of logs in an actual response can be higher, since logs are read in bulk with second precision - exceed logs above the limit will share same timestamp as the logs below the limit. Results will be adjusted to the “end time” taken from interval field (adjusted also by page_token if provided).
page_token string Token which identifies next page with further results. Token should be taken from [ListActivityLogsResponse.next_page_token][ntt.audit.v1alpha2.ListActivityLogsResponse.next_page_token].

ListActivityLogsResponse Message

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

Name Type Description
activity_logs repeated ActivityLog One or more activity method logs that match the filter included in the request. Contains results from all queried regions. Its possible however that some logs may be missing, for this see execution_errors.
next_page_token string If there are more results than have been returned, then this field is set to a non-empty value. To see the additional results, use that value as pageToken in the next call to this method.
execution_errors repeated Status Query execution errors that may have caused the response data returned to be incomplete. Because logs are stored only locally (for each region), all activity log queries are split and merged by a receiving request server according to the queried regions. Its possible that some regions will fail when request is redirected to them, but others not. For each failed region, one execution error will be appended. In each ntt.rpc.Status message, fields code and message will contain error obtained from failed regional server, while field details will contain always one item and this item will be of type ErrorDetails.

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).

Name Type Description
region_id string region id which failed to give results.

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.

Name Type Description
activity_logs repeated ActivityLog List of activity logs to be added to service. Can be coming from different scopes but must be submitted to the same region.

CreateActivityLogsResponse Message

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

Name Type Description
log_names repeated string (name of ActivityLog) Activity log names - one name per each activity log, in same order as in the request

ActivityLog Enumerations

Here is the list of ActivityLog resource enumerations:

ActivityLog.Category Enumeration

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

Name Description
Undefined Undefined, should never be used
Operation Describes all requests that involved execution of some special operation, for example, SSH connection could be put in this category. It’s for requests that cannot be classified clearly as a read or write.
Creation Describes all requests that involved creation of a new resource.
Deletion Describes all requests which involved deletion of an existing resource.
SpecUpdate Describes all update requests that changed specification fields in an existing resource(s).
StateUpdate Describes all update requests that changed state fields in an existing resource(s) (but not specification).
MetaUpdate Describes all update requests that are neither of SpecUpdate or StateUpdate type. It is for non-significant updates like modification of metadata annotations.
Internal Describes an internal update of the system (like controller creating role binding for each group member for each role assigned to group). It includes all CUD requests as long as they are result of an internal system balancing.
Rejected Describes request that has been rejected and therefore no action has happened. This is result of lack of permission/authentication.
ClientError Describes request that has failed due to client error (like validation error)
ServerError Describes request that has failed due to server issue.
Read Describes any read request (like BatchGet, Get, List, Watch).

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

GetAuditedResourceDescriptor

rpc GetAuditedResourceDescriptor(GetAuditedResourceDescriptorRequest) returns (AuditedResourceDescriptor)

with the following messages:

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:

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:

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:

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:

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:

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:

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

Name Type Description
name string (name of AuditedResourceDescriptor) Name of AuditedResourceDescriptor - contains service name and resource type name, separated by ‘/’ sign. Example name: “iam.edgelq.com/RoleBinding”
display_name string Optional. A concise name for the audited object type that might be displayed in user interfaces. It should be a Title Cased Noun Phrase, without any article or other determiners.
description string Optional. A detailed description of the audited object type that might be used in documentation.
labels repeated LabelDescriptor Required. A set of labels used to describe instances of this audited resource type. For example, for “RoleBinding” we can define name+member. This can allow us to make query like “who allowed user X to do those things?”
promoted_label_key_sets repeated LabelKeySet Promoted Label Key Sets allow defining multiple indexing rules for underlying backend enabling query optimizations.
versions repeated string List of API versions which define this resource
spec_fields repeated string List of spec fields
state_fields repeated string List of state fields
meta_fields repeated string List of meta fields
metadata Meta Metadata

GetAuditedResourceDescriptorRequest Message

A request message of the GetAuditedResourceDescriptor method.

Name Type Description
name string (name of AuditedResourceDescriptor) Name of ntt.audit.v1alpha2.AuditedResourceDescriptor
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

BatchGetAuditedResourceDescriptorsRequest Message

A request message of the BatchGetAuditedResourceDescriptors method.

Name Type Description
names repeated string (name of AuditedResourceDescriptor) Names of AuditedResourceDescriptors
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

BatchGetAuditedResourceDescriptorsResponse Message

A response message of the BatchGetAuditedResourceDescriptors method.

Name Type Description
audited_resource_descriptors repeated AuditedResourceDescriptor found AuditedResourceDescriptors
missing repeated string (name of AuditedResourceDescriptor) list of not found AuditedResourceDescriptors

ListAuditedResourceDescriptorsRequest Message

A request message of the ListAuditedResourceDescriptors method.

Name Type Description
page_size int32 Requested page size. Server may return fewer AuditedResourceDescriptors than requested. If unspecified, server will pick an appropriate default.
page_token string (cursor of AuditedResourceDescriptor) A token identifying a page of results the server should return. Typically, this is the value of ListAuditedResourceDescriptorsResponse.next_page_token.
order_by string (orderBy of AuditedResourceDescriptor) Order By - https://cloud.google.com/apis/design/design_patterns#list_pagination list of field path with order directive, either ‘asc’ or ‘desc’. If direction is not provided, ‘asc’ is assumed. e.g. “state.nested_field asc, state.something.else desc, theme”
filter string (filter of AuditedResourceDescriptor) Filter - filter results by field criteria. Simplified SQL-like syntax with following operators: <=, >=, =, !=, <, >, LIKE, CONTAINS (aliases CONTAIN, HAS, HAVE), IN, IS [NOT] NULL
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask
include_paging_info bool Indicates if list response should contain total count and offset (fields current_offset and total_results_count).

ListAuditedResourceDescriptorsResponse Message

A response message of the ListAuditedResourceDescriptors method.

Name Type Description
audited_resource_descriptors repeated AuditedResourceDescriptor The list of AuditedResourceDescriptors
prev_page_token string (cursor of AuditedResourceDescriptor) A token to retrieve previous page of results. Pass this value in the ListAuditedResourceDescriptorsRequest.page_token.
next_page_token string (cursor of AuditedResourceDescriptor) A token to retrieve next page of results. Pass this value in the ListAuditedResourceDescriptorsRequest.page_token.
current_offset int32 Current offset from the first page or 0 if no page tokens were given, paging info was not requested or there was an error while trying to get it). Page index can be computed from offset and limit provided in a request.
total_results_count int32 Number of total AuditedResourceDescriptors across all pages or 0, if there are no items, paging info was not requested or there was an error while trying to get it.

WatchAuditedResourceDescriptorRequest Message

A request message of the WatchAuditedResourceDescriptor method.

Name Type Description
name string (name of AuditedResourceDescriptor) Name of ntt.audit.v1alpha2.AuditedResourceDescriptor
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

WatchAuditedResourceDescriptorResponse Message

A response message of the WatchAuditedResourceDescriptor method.

Name Type Description
change AuditedResourceDescriptorChange

WatchAuditedResourceDescriptorsRequest Message

A request message of the WatchAuditedResourceDescriptors method.

Name Type Description
type WatchType Type of a watch. Identifies how server stream data to a client, which fields in a request are allowed and which fields in response are relevant.
page_size int32 Requested page size. Server may return fewer AuditedResourceDescriptors than requested. If unspecified, server will pick an appropriate default. Can be populated only for stateful watch type.
page_token string (cursor of AuditedResourceDescriptor) A token identifying a page of results the server should return. Can be populated only for stateful watch type.
order_by string (orderBy of AuditedResourceDescriptor) Order By - https://cloud.google.com/apis/design/design_patterns#list_pagination Can be populated only for stateful watch type.
resume_token string A token identifying watch resume point from previous session. Can be populated only for stateless watch type.
starting_time .google.protobuf.Timestamp Point in the time from which we want to start getting updates. This field can be populated only for stateless watch type and if resume token is not known yet. If specified, initial snapshot will NOT be provided. It is assumed client can obtain it using separate means. Watch responses will contain resume tokens which should be used to resume broken connection.
filter string (filter of AuditedResourceDescriptor) Filter - filter results by field criteria. Simplified SQL-like syntax with following operators: <=, >=, =, !=, <, >, LIKE, CONTAINS (aliases CONTAIN, HAS, HAVE), IN, IS [NOT] NULL
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view Changes to AuditedResourceDescriptor that don’t affect any of masked fields won’t be sent back.
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask Changes to AuditedResourceDescriptor that don’t affect any of masked fields won’t be sent back.
max_chunk_size int32 Maximum amount of changes in each response message. Query result response is divided on the server side into chunks with size of a specified amount to limit memory footprint of each message. Responses will hold information whether more elements will continue for the actual change. If unspecified, server will pick an appropriate default.

WatchAuditedResourceDescriptorsResponse Message

A response message of the WatchAuditedResourceDescriptors method.

Name Type Description
audited_resource_descriptor_changes repeated AuditedResourceDescriptorChange Changes of AuditedResourceDescriptors
is_current bool If request specified max_chunk_size (or this limit was enforced if stateless watch has been chosen), then responses with “full changeset” will be divided into chunks. Client should keep receiving messages and, once is_current has value true, combine this recent message with all previous ones where is_current is false. If this is the first is_current in a whole watch stream, then it means that client should have, at this moment, contain snapshot of the current situation (or more accurately, snapshot of situation at the moment of request). All AuditedResourceDescriptors will be of type Added/Current (depending on watch_type specified in the request). Further responses will be incremental - however messages may still be chunked and is_current logic still applies. is_current is always true for stateful watch if max_chunk_size was left to 0.
page_token_change WatchAuditedResourceDescriptorsResponse.PageTokenChange When present, PageTokens used for page navigation should be updated. Present only if is_current is true (last chunk).
resume_token string Token that can be used if current connection drops and client needs to reconnect. Populated only for stateless watch type. Present only if is_current is true (last chunk).
snapshot_size int64 Server may occasionally send information how many resources should client have in its state so far (response message without any changes, but with snapshot_size field specified). If client has different value than the one sent by the server, then it should be treated by a client as an error and should reconnect. If value is smaller then 0, then client should ignore this field as unpopulated. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will be never sent together with is_current, is_soft_reset and is_hard_reset flags.
is_soft_reset bool In case of internal issue server may send response message with this flag. It indicates that client should drop all changes from recent responses where is_current is false only! If last message had is_current set to true, client should do nothing and process normally. Resume token received before is still valid. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will never be sent along with is_current, is_hard_reset or snapshot_size.
is_hard_reset bool In case of internal issue server may send response message with this flag. After receiving, client should clear whole state (drop all changes received so far) as server will send new snapshot (AuditedResourceDescriptors will contains changes of type Current only). Any resume tokens should be discarded as well. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will never be sent along with is_current, is_soft_reset or snapshot_size.

WatchAuditedResourceDescriptorsResponse.PageTokenChange Message

Name Type Description
prev_page_token string (cursor of AuditedResourceDescriptor) New token to retrieve previous page of results.
next_page_token string (cursor of AuditedResourceDescriptor) New token to retrieve next page of results.

CreateAuditedResourceDescriptorRequest Message

A request message of the CreateAuditedResourceDescriptor method.

Name Type Description
audited_resource_descriptor AuditedResourceDescriptor AuditedResourceDescriptor resource body
response_mask CreateAuditedResourceDescriptorRequest.ResponseMask Optional masking applied to response object to reduce message response size.

CreateAuditedResourceDescriptorRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

Name Type Description
skip_entire_response_body bool If this flag has value true, then response will contain just empty resource without any fields populated.
body_mask .google.protobuf.FieldMask If this field is populated, then resource in response will contain only specific fields.

UpdateAuditedResourceDescriptorRequest Message

A request message of the UpdateAuditedResourceDescriptor method.

Name Type Description
audited_resource_descriptor AuditedResourceDescriptor AuditedResourceDescriptor resource body
update_mask .google.protobuf.FieldMask FieldMask applied to request - change will be applied only for fields in the mask
cas UpdateAuditedResourceDescriptorRequest.CAS Conditional update applied to request if update should be executed only for specific resource state. If this field is populated, then server will fetch existing resource, compare with the one stored in the cas field (after applying field mask) and proceed with update only and only if they match. Otherwise RPC error Aborted will be returned.
allow_missing bool If set to true, and the resource is not found, a new resource will be created. In this situation, ‘field_mask’ is ignored. https://google.aip.dev/134#create-or-update
response_mask UpdateAuditedResourceDescriptorRequest.ResponseMask reduce message response size.

UpdateAuditedResourceDescriptorRequest.CAS Message

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

Name Type Description
conditional_state AuditedResourceDescriptor Conditional desired state of a resource before update.
field_mask .google.protobuf.FieldMask Field paths from conditional state of resource server should check and compare.

UpdateAuditedResourceDescriptorRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

Name Type Description
skip_entire_response_body bool If this flag has value true, then response will contain just empty resource without any fields populated. Field body_mask is ignored if set.
updated_fields_only bool Include all fields that were actually updated during processing. Note this may be larger than update mask if some fields were computed additionally. Name is added as well.
body_mask .google.protobuf.FieldMask If this field is populated, then resource in response will contain only specific fields. If skip_entire_response_body is true, this field is ignored.

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

GetMethodDescriptor

rpc GetMethodDescriptor(GetMethodDescriptorRequest) returns (MethodDescriptor)

with the following messages:

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:

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:

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:

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:

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:

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:

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

Name Type Description
name string (name of MethodDescriptor) Name of MethodDescriptor - contains service name and method type name, separated by ‘/’ sign. Example name: “iam.edgelq.com/CreateRoleBinding”
display_name string Optional. A concise name for the audited object type that might be displayed in user interfaces. It should be a Title Cased Noun Phrase, without any article or other determiners.
description string Optional. A detailed description of the audited method type that might be used in documentation.
labels repeated LabelDescriptor A set of labels used to describe instances of this audited method type. For example, for “UpdateRoleBinding” we can define member label. This can allow us to make query like “who tried to give user X permissions to those things?”
promoted_label_key_sets repeated LabelKeySet Promoted Label Key Sets allow defining multiple indexing rules for underlying backend enabling query optimizations.
versions repeated string List of API versions which define this method
metadata Meta Metadata

GetMethodDescriptorRequest Message

A request message of the GetMethodDescriptor method.

Name Type Description
name string (name of MethodDescriptor) Name of ntt.audit.v1alpha2.MethodDescriptor
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

BatchGetMethodDescriptorsRequest Message

A request message of the BatchGetMethodDescriptors method.

Name Type Description
names repeated string (name of MethodDescriptor) Names of MethodDescriptors
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

BatchGetMethodDescriptorsResponse Message

A response message of the BatchGetMethodDescriptors method.

Name Type Description
method_descriptors repeated MethodDescriptor found MethodDescriptors
missing repeated string (name of MethodDescriptor) list of not found MethodDescriptors

ListMethodDescriptorsRequest Message

A request message of the ListMethodDescriptors method.

Name Type Description
page_size int32 Requested page size. Server may return fewer MethodDescriptors than requested. If unspecified, server will pick an appropriate default.
page_token string (cursor of MethodDescriptor) A token identifying a page of results the server should return. Typically, this is the value of ListMethodDescriptorsResponse.next_page_token.
order_by string (orderBy of MethodDescriptor) Order By - https://cloud.google.com/apis/design/design_patterns#list_pagination list of field path with order directive, either ‘asc’ or ‘desc’. If direction is not provided, ‘asc’ is assumed. e.g. “state.nested_field asc, state.something.else desc, theme”
filter string (filter of MethodDescriptor) Filter - filter results by field criteria. Simplified SQL-like syntax with following operators: <=, >=, =, !=, <, >, LIKE, CONTAINS (aliases CONTAIN, HAS, HAVE), IN, IS [NOT] NULL
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask
include_paging_info bool Indicates if list response should contain total count and offset (fields current_offset and total_results_count).

ListMethodDescriptorsResponse Message

A response message of the ListMethodDescriptors method.

Name Type Description
method_descriptors repeated MethodDescriptor The list of MethodDescriptors
prev_page_token string (cursor of MethodDescriptor) A token to retrieve previous page of results. Pass this value in the ListMethodDescriptorsRequest.page_token.
next_page_token string (cursor of MethodDescriptor) A token to retrieve next page of results. Pass this value in the ListMethodDescriptorsRequest.page_token.
current_offset int32 Current offset from the first page or 0 if no page tokens were given, paging info was not requested or there was an error while trying to get it). Page index can be computed from offset and limit provided in a request.
total_results_count int32 Number of total MethodDescriptors across all pages or 0, if there are no items, paging info was not requested or there was an error while trying to get it.

WatchMethodDescriptorRequest Message

A request message of the WatchMethodDescriptor method.

Name Type Description
name string (name of MethodDescriptor) Name of ntt.audit.v1alpha2.MethodDescriptor
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask

WatchMethodDescriptorResponse Message

A response message of the WatchMethodDescriptor method.

Name Type Description
change MethodDescriptorChange

WatchMethodDescriptorsRequest Message

A request message of the WatchMethodDescriptors method.

Name Type Description
type WatchType Type of a watch. Identifies how server stream data to a client, which fields in a request are allowed and which fields in response are relevant.
page_size int32 Requested page size. Server may return fewer MethodDescriptors than requested. If unspecified, server will pick an appropriate default. Can be populated only for stateful watch type.
page_token string (cursor of MethodDescriptor) A token identifying a page of results the server should return. Can be populated only for stateful watch type.
order_by string (orderBy of MethodDescriptor) Order By - https://cloud.google.com/apis/design/design_patterns#list_pagination Can be populated only for stateful watch type.
resume_token string A token identifying watch resume point from previous session. Can be populated only for stateless watch type.
starting_time .google.protobuf.Timestamp Point in the time from which we want to start getting updates. This field can be populated only for stateless watch type and if resume token is not known yet. If specified, initial snapshot will NOT be provided. It is assumed client can obtain it using separate means. Watch responses will contain resume tokens which should be used to resume broken connection.
filter string (filter of MethodDescriptor) Filter - filter results by field criteria. Simplified SQL-like syntax with following operators: <=, >=, =, !=, <, >, LIKE, CONTAINS (aliases CONTAIN, HAS, HAVE), IN, IS [NOT] NULL
field_mask .google.protobuf.FieldMask A list of extra fields to be obtained for each response item on top of fields defined by request field view Changes to MethodDescriptor that don’t affect any of masked fields won’t be sent back.
view View View defines list of standard response fields present in response items. Additional fields can be amended by request field field_mask Changes to MethodDescriptor that don’t affect any of masked fields won’t be sent back.
max_chunk_size int32 Maximum amount of changes in each response message. Query result response is divided on the server side into chunks with size of a specified amount to limit memory footprint of each message. Responses will hold information whether more elements will continue for the actual change. If unspecified, server will pick an appropriate default.

WatchMethodDescriptorsResponse Message

A response message of the WatchMethodDescriptors method.

Name Type Description
method_descriptor_changes repeated MethodDescriptorChange Changes of MethodDescriptors
is_current bool If request specified max_chunk_size (or this limit was enforced if stateless watch has been chosen), then responses with “full changeset” will be divided into chunks. Client should keep receiving messages and, once is_current has value true, combine this recent message with all previous ones where is_current is false. If this is the first is_current in a whole watch stream, then it means that client should have, at this moment, contain snapshot of the current situation (or more accurately, snapshot of situation at the moment of request). All MethodDescriptors will be of type Added/Current (depending on watch_type specified in the request). Further responses will be incremental - however messages may still be chunked and is_current logic still applies. is_current is always true for stateful watch if max_chunk_size was left to 0.
page_token_change WatchMethodDescriptorsResponse.PageTokenChange When present, PageTokens used for page navigation should be updated. Present only if is_current is true (last chunk).
resume_token string Token that can be used if current connection drops and client needs to reconnect. Populated only for stateless watch type. Present only if is_current is true (last chunk).
snapshot_size int64 Server may occasionally send information how many resources should client have in its state so far (response message without any changes, but with snapshot_size field specified). If client has different value than the one sent by the server, then it should be treated by a client as an error and should reconnect. If value is smaller then 0, then client should ignore this field as unpopulated. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will be never sent together with is_current, is_soft_reset and is_hard_reset flags.
is_soft_reset bool In case of internal issue server may send response message with this flag. It indicates that client should drop all changes from recent responses where is_current is false only! If last message had is_current set to true, client should do nothing and process normally. Resume token received before is still valid. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will never be sent along with is_current, is_hard_reset or snapshot_size.
is_hard_reset bool In case of internal issue server may send response message with this flag. After receiving, client should clear whole state (drop all changes received so far) as server will send new snapshot (MethodDescriptors will contains changes of type Current only). Any resume tokens should be discarded as well. This field should be checked only for stateless watch. In stateful those kind of errors are handled by the server side. Will never be sent along with is_current, is_soft_reset or snapshot_size.

WatchMethodDescriptorsResponse.PageTokenChange Message

Name Type Description
prev_page_token string (cursor of MethodDescriptor) New token to retrieve previous page of results.
next_page_token string (cursor of MethodDescriptor) New token to retrieve next page of results.

CreateMethodDescriptorRequest Message

A request message of the CreateMethodDescriptor method.

Name Type Description
method_descriptor MethodDescriptor MethodDescriptor resource body
response_mask CreateMethodDescriptorRequest.ResponseMask Optional masking applied to response object to reduce message response size.

CreateMethodDescriptorRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

Name Type Description
skip_entire_response_body bool If this flag has value true, then response will contain just empty resource without any fields populated.
body_mask .google.protobuf.FieldMask If this field is populated, then resource in response will contain only specific fields.

UpdateMethodDescriptorRequest Message

A request message of the UpdateMethodDescriptor method.

Name Type Description
method_descriptor MethodDescriptor MethodDescriptor resource body
update_mask .google.protobuf.FieldMask FieldMask applied to request - change will be applied only for fields in the mask
cas UpdateMethodDescriptorRequest.CAS Conditional update applied to request if update should be executed only for specific resource state. If this field is populated, then server will fetch existing resource, compare with the one stored in the cas field (after applying field mask) and proceed with update only and only if they match. Otherwise RPC error Aborted will be returned.
allow_missing bool If set to true, and the resource is not found, a new resource will be created. In this situation, ‘field_mask’ is ignored. https://google.aip.dev/134#create-or-update
response_mask UpdateMethodDescriptorRequest.ResponseMask reduce message response size.

UpdateMethodDescriptorRequest.CAS Message

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

Name Type Description
conditional_state MethodDescriptor Conditional desired state of a resource before update.
field_mask .google.protobuf.FieldMask Field paths from conditional state of resource server should check and compare.

UpdateMethodDescriptorRequest.ResponseMask Message

ResponseMask allows client to reduce response message size.

Name Type Description
skip_entire_response_body bool If this flag has value true, then response will contain just empty resource without any fields populated. Field body_mask is ignored if set.
updated_fields_only bool Include all fields that were actually updated during processing. Note this may be larger than update mask if some fields were computed additionally. Name is added as well.
body_mask .google.protobuf.FieldMask If this field is populated, then resource in response will contain only specific fields. If skip_entire_response_body is true, this field is ignored.

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:

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

ResourceChangeLog Methods

Here is the list of ResourceChangeLog resource methods:

ListResourceChangeLogs Method

ListResourceChangeLogs

rpc ListResourceChangeLogs(ListResourceChangeLogsRequest) returns (ListResourceChangeLogsResponse)

with the following messages:

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:

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:

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

Name Type Description
name string (name of ResourceChangeLog) Name of ResourceChangeLog. It contains scope + ID of the log. ID is a base64 encoded unique key that identifies tuple: scope request_id authentication.principal service.name service.region_id resource.name resource.type resource.pre.labels resource.post.labels ID part should not be decoded, but treated as opaque string
scope string Contains scope from name field without resource ID. Used for internal purpose for filtering (logs are using custom store). Supported formats are: - organization/umbrella - projects/mars_exploration - <system>
request_id uint64 Unique identifier of request - it must match the one in the associated activity log.
timestamp .google.protobuf.Timestamp Time of the change - equal to request timestamp (activity log)
authentication Authentication Authentication data - informs who made a change
service ServiceData Information about the service
resource ResourceChangeLog.ResourceChange Describes change on the resource
transaction ResourceChangeLog.TransactionInfo Describes state of the transaction

ResourceChangeLog.ResourceChange Message

Description of change on the resource

Name Type Description
name string Fully qualified name of the resource (eg. “RoleBinding/Public”) that has changed from this request (if successful)
type string Name of the resource type for example “RoleBinding”.
action ResourceChangeLog.ResourceChange.Action Action on the resource
updated_fields .google.protobuf.FieldMask Field mask with different fields, populated only for update action types.
previous .google.protobuf.Any Previous values of updated fields. Its populated only if update_fields is provided and for those fields only. It is skipped for deletes.
current .google.protobuf.Any Current values of updated fields in case of update. Whole resource in case of creation, empty in case of deletion.
labels map<string, string> List of query-able labels. They are taken from both before and after resource, but after has higher priority
pre ObjectState State of the resource before change. It is empty if action is CREATE DEPRECATED and not populated for new resources
post ObjectState State of the resource after change. It is empty if action is DELETE DEPRECATED and not populated for new resources

ResourceChangeLog.TransactionInfo Message

Information about transaction where change has been executed

Name Type Description
identifier string unique identifier of the transaction.
try_counter int32 Indicator of try counter. If transaction has been concluded at first try, try_counter will be 1. If on the second try, then number will be 2 (etc).
state ResourceChangeLog.TransactionInfo.State State of the transaction.

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

Name Type Description
parents repeated string (parent name of ResourceChangeLog) Parent names of ntt.audit.v1alpha2.ResourceChangeLog
filter string (filter of ResourceChangeLog) A audit filter that specifies which resource change logs should be returned
interval TimeInterval The time interval for which results should be returned. Only logs that contain data points in the specified interval are included in the response.
page_size int32 Cap on a number of resource change logs to be included in a response. Number of logs in an actual response can be higher, since logs are read in bulk with second precision - exceed logs above the limit will share same timestamp as the logs below the limit. Results will be adjusted to the “end time” taken from interval field (adjusted also by page_token if provided).
page_token string Token which identifies next page with further results. Token should be taken from ListResourceChangeLogsResponse [ListResourceChangeLogsResponse.next_page_token][ntt.audit.v1alpha2.ListResourceChangeLogsResponse.next_page_token].

ListResourceChangeLogsResponse Message

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

Name Type Description
resource_change_logs repeated ResourceChangeLog One or more resource change logs that match the filter included in the request. Contains results from all queried regions. Its possible however that some logs may be missing, for this see execution_errors.
next_page_token string If there are more results than have been returned, then this field is set to a non-empty value. To see the additional results, use that value as pageToken in the next call to this method.
execution_errors repeated Status Query execution errors that may have caused the response data returned to be incomplete. Because logs are stored only locally (for each region), all resource change log queries are split and merged by a receiving request server according to the queried regions. Its possible that some regions will fail when request is redirected to them, but others not. For each failed region, one execution error will be appended. In each ntt.rpc.Status message, fields code and message will contain error obtained from failed regional server, while field details will contain always one item and this item will be of type ErrorDetails.

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).

Name Type Description
region_id string region id which failed to give results.

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.

Name Type Description
request_id uint64 ID of the request - must be same as the one used in activity logs
timestamp .google.protobuf.Timestamp Time of the request
authentication Authentication Authentication data - informs who made a change
service ServiceData Information about the service
transaction ResourceChangeLog.TransactionInfo Information about transaction
changes repeated ResourceChangeLog.ResourceChange List of changes

CreatePreCommittedResourceChangeLogsResponse Message

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

Name Type Description
log_keys repeated bytes Resource change log keys - one key per each resource change, in same order

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.

Name Type Description
log_keys repeated bytes list of resource change log keys.
timestamp .google.protobuf.Timestamp Time of the request - must be same as in CreatePreCommittedResourceChangeLogsRequest
tx_result ResourceChangeLog.TransactionInfo.State final state of the transaction - must be COMMITTED or ROLLED_BACK

SetResourceChangeLogsCommitStateResponse Message

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

Name Type Description
none none none

ResourceChangeLog Enumerations

Here is the list of ResourceChangeLog resource enumerations:

ResourceChangeLog.ResourceChange.Action Enumeration

Type of change

Name Description
UNDEFINED to avoid blank item when printing logs
CREATE Resource has been created
DELETE Resource has been deleted
SPEC_UPDATE Update contains spec fields
STATE_UPDATE Update contains state fields, but not spec
META_UPDATE Update contains neither spec or state fields.
UPDATE UPDATE is deprecated in favor of specific update types.

ResourceChangeLog.TransactionInfo.State Enumeration

State of the transaction.

Name Description
UNDEFINED
PRE_COMMITTED Indicates that this change did not happen - it is just proposal of the change. Such a log should be followed by another ResourceChangeLog with value COMMITTED or ROLLED_BACK. If one transaction has been retried multiple times, then there may be multiple records with PRE_COMMITTED, last record should indicate final transaction state.
COMMITTED Indicates change has been committed successfully.
ROLLED_BACK Indicates that change did not happen. Log of this type should be treated as attempt of change.

Audit Service Shared Methods and Messages

Audit Service Shared Messages

Here is the list of Audit service shared messages:

AuditedResourceDescriptorChange Message

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

Name Type Description
added AuditedResourceDescriptorChange.Added Added is returned when watched document is added, either created or enters Query view
modified AuditedResourceDescriptorChange.Modified Modified is returned when watched document is modified
current AuditedResourceDescriptorChange.Current Current is returned in stateless watch when document enters query view or is modified within.
removed AuditedResourceDescriptorChange.Removed Removed is returned when AuditedResourceDescriptor is deleted or leaves Query view

AuditedResourceDescriptorChange.Added Message

AuditedResourceDescriptor has been added to query view

Name Type Description
audited_resource_descriptor AuditedResourceDescriptor
view_index int32 Integer describing index of added AuditedResourceDescriptor in resulting query view.

AuditedResourceDescriptorChange.Current Message

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

Name Type Description
audited_resource_descriptor AuditedResourceDescriptor

AuditedResourceDescriptorChange.Modified Message

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

Name Type Description
name string (name of AuditedResourceDescriptor) Name of modified AuditedResourceDescriptor
audited_resource_descriptor AuditedResourceDescriptor New version of AuditedResourceDescriptor or masked difference, depending on mask_changes instrumentation of issued [WatchAuditedResourceDescriptorRequest] or [WatchAuditedResourceDescriptorsRequest]
field_mask .google.protobuf.FieldMask Used when mask_changes is set, contains field paths of modified properties.
previous_view_index int32 Previous view index specifies previous position of modified AuditedResourceDescriptor. When modification doesn’t affect sorted order, value will remain identical to [view_index].
view_index int32 Integer specifying AuditedResourceDescriptor new index in resulting query view.

AuditedResourceDescriptorChange.Removed Message

Removed is returned when AuditedResourceDescriptor is deleted or leaves Query view

Name Type Description
name string (name of AuditedResourceDescriptor)
view_index int32 Integer specifying removed AuditedResourceDescriptor index. Not populated in stateless watch type.

Authentication Message

Information about authorized principal who sent a request

Name Type Description
principal string Name of the principal, for example: “user:our_new_admin@example.com”
principal_type string Principal type - user, serviceAccount, anonymous

Authorization Message

Information about authorization applicable for a request.

Name Type Description
granted_permissions repeated string List of permissions that were granted
denied_permissions repeated string List of permissions that were denied

LabelDescriptor Message

Name Type Description
key string The label key.
versions repeated string List of versions where label is supported

LabelKeySet Message

LabelKeySet is used for defining PromotedLabelKeySets on Object descriptors

Name Type Description
label_keys repeated string
versions repeated string List of versions where label set is supported

MethodDescriptorChange Message

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

Name Type Description
added MethodDescriptorChange.Added Added is returned when watched document is added, either created or enters Query view
modified MethodDescriptorChange.Modified Modified is returned when watched document is modified
current MethodDescriptorChange.Current Current is returned in stateless watch when document enters query view or is modified within.
removed MethodDescriptorChange.Removed Removed is returned when MethodDescriptor is deleted or leaves Query view

MethodDescriptorChange.Added Message

MethodDescriptor has been added to query view

Name Type Description
method_descriptor MethodDescriptor
view_index int32 Integer describing index of added MethodDescriptor in resulting query view.

MethodDescriptorChange.Current Message

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

Name Type Description
method_descriptor MethodDescriptor

MethodDescriptorChange.Modified Message

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

Name Type Description
name string (name of MethodDescriptor) Name of modified MethodDescriptor
method_descriptor MethodDescriptor New version of MethodDescriptor or masked difference, depending on mask_changes instrumentation of issued [WatchMethodDescriptorRequest] or [WatchMethodDescriptorsRequest]
field_mask .google.protobuf.FieldMask Used when mask_changes is set, contains field paths of modified properties.
previous_view_index int32 Previous view index specifies previous position of modified MethodDescriptor. When modification doesn’t affect sorted order, value will remain identical to [view_index].
view_index int32 Integer specifying MethodDescriptor new index in resulting query view.

MethodDescriptorChange.Removed Message

Removed is returned when MethodDescriptor is deleted or leaves Query view

Name Type Description
name string (name of MethodDescriptor)
view_index int32 Integer specifying removed MethodDescriptor index. Not populated in stateless watch type.

ObjectState Message

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

Name Type Description
data .google.protobuf.Any Object data
labels map<string, string> Values for all of the labels listed in the associated audited object descriptor - they are extracted from protobuf object and used for filtering

ServiceData Message

Information about service processing a request

Name Type Description
name string Fully qualified service name executing a request
region_id string Region of the service handling this 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.

Name Type Description
end_time .google.protobuf.Timestamp Optional - end of the time interval. If not provided, current time will be assumed.
start_time .google.protobuf.Timestamp Required. The beginning of the time interval. The start time must not be later than the end time.