github.com/cloudwan/edgelq-sdk@v1.15.4/audit/proto/v1alpha2/activity_log_custom.proto

syntax = "proto3";

package ntt.audit.v1alpha2;

import "edgelq-sdk/audit/proto/v1alpha2/activity_log.proto";
import "edgelq-sdk/audit/proto/v1alpha2/common.proto";
import "edgelq-sdk/common/rpc/status.proto";

option go_package = "github.com/cloudwan/edgelq-sdk/audit/client/v1alpha2/activity_log;activity_log_client";
option java_multiple_files = false;
option java_outer_classname = "ActivityLogCustomProto";
option java_package = "com.ntt.audit.pb.v1alpha2";

// 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"'
message ListActivityLogsRequest {
  // Parent references of ntt.audit.v1alpha2.ActivityLog - provides list of all
  // scopes we want to query about
  repeated string parents = 1;

  // A audit filter that specifies which activity logs should be returned
  string filter = 2;

  // The time interval for which results should be returned. Only logs
  // that contain data points in the specified interval are included
  // in the response.
  TimeInterval interval = 4;

  // 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).
  int32 page_size = 5;

  // Token which identifies next page with further results. Token should be
  // taken from
  // [ListActivityLogsResponse.next_page_token][ntt.audit.v1alpha2.ListActivityLogsResponse.next_page_token].
  string page_token = 6;

  reserved 3;
}

// Response message for method
// [ListActivityLogs][ntt.audit.v1alpha2.ListActivityLogs]
message ListActivityLogsResponse {
  // 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.
  repeated ActivityLog activity_logs = 1;

  // 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.
  string next_page_token = 2;

  // 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.
  repeated ntt.rpc.Status execution_errors = 3;

  // 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).
  message ErrorDetails {
    // region id which failed to give results.
    string region_id = 1;
  }
}

// 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.
message CreateActivityLogsRequest {
  // List of activity logs to be added to service. Can be coming from different
  // scopes but must be submitted to the same region.
  repeated ActivityLog activity_logs = 1;
}

// Response message for method
// [CreateActivityLogs][ntt.audit.v1alpha2.CreateActivityLogs]
message CreateActivityLogsResponse {
  // Activity log names - one name per each activity log, in same order
  // as in the request
  repeated string log_names = 1;
}