- release_tracks: [ALPHA, BETA, GA]

  help_text:
    brief: Filter an organization or source's findings and groups them by their specified properties.
    description: To group across all sources provide a '-' as the source id.
    examples: |
      Group findings under organization 123456 across all sources by their category:

        $ {command} 123456 --group-by="category"

      Group findings under project example-project across all sources by their category:

        $ {command} projects/example-project --group-by="category"

      Group findings under folders 456 across all sources by their category:

        $ {command} folders/456 --group-by="category"

      Group findings under organization 123456 and source 5678, by their category:

        $ {command} 123456 --source=5678 --group-by="category"

      Group ACTIVE findings under organization 123456 and source 5678, by their category:

        $ {command} 123456 --source=5678 --group-by="category" --filter="state=\"ACTIVE\""

      Group ACTIVE findings under organization 123456 and source 5678, on 2019-01-01T01:00:00 GMT, by their category:

        $ {command} 123456 --source=5678 --group-by="category" --filter="state=\"ACTIVE\"" --read-time="2019-01-01T01:00:00Z"

      Group findings under organization 123456 and source 5678 into following 3 state_changes (ADDED/CHANGED/UNCHANGED) based on the activity during past 24 hours:

        $ {command} 123456 --source=5678 --group-by="state_change" --compare-duration=86400s

  request:
    collection: securitycenter.organizations.sources.findings
    api_version: v1
    method: group
    modify_request_hooks:
    - googlecloudsdk.command_lib.scc.findings.request_hooks:GroupFindingsReqHook

  arguments:
    additional_arguments_hook: googlecloudsdk.command_lib.scc.hooks:AppendParentArg

    params:
    - !REF googlecloudsdk.command_lib.scc.findings.flags:source
    - arg_name: compare-duration
      api_field: groupFindingsRequest.compareDuration
      help_text: |
        When compare_duration is set, the GroupResult's "state_change" attribute is updated to
        indicate whether the finding had its state changed, the finding's state remained unchanged,
        or if the finding was added during the compare_duration period of time that precedes the
        read_time. This is the time between (read_time - compare_duration) and read_time.
        The state_change value is derived based on the presence and state of the finding at the two
        points in time. Intermediate state changes between the two times don't affect the result.
        For example, the results aren't affected if the finding is made inactive and then active
        again. Possible "state_change" values when compare_duration is specified:
        * 'CHANGED': indicates that the finding was present at the start of compare_duration, but changed its state at read_time.
        * 'UNCHANGED': indicates that the finding was present at the start of compare_duration and did not change state at read_time.
        * 'ADDED': indicates that the finding was not present at the start of compare_duration, but
        was present at read_time.
        If compare_duration is not specified, then the only possible state_change is "UNUSED",
        which will be the state_change set for all findings present at read_time. If this field is
        set then 'state_change' must be a specified field in 'group_by'.
    - arg_name: filter
      api_field: groupFindingsRequest.filter
      help_text: |
        Expression that defines the filter to apply across findings. The expression is a list of
        one or more restrictions combined via logical operators 'AND' and 'OR'. Parentheses are
        supported, and 'OR' has higher precedence than 'AND'. Restrictions have the form
        '<field> <operator> <value>' and may have a '-' character in front of them to indicate
        negation. Examples include: name, source_properties.a_property, security_marks.marks.marka.
        The supported operators are:
        *  '=' for all value types.
        *  '>', '<', '>=', '<=' for integer values.
        *  ':', meaning substring matching, for strings.

        The supported value types are:string literals in quotes, integer literals without quotes,
        boolean literals 'true' and 'false' without quotes.
        Some example filters: 'source_properties.size = 100', 'category=\"XSS\" AND event_time > 10'
        etc.
    - arg_name: group-by
      api_field: groupFindingsRequest.groupBy
      help_text: |
        Expression that defines what findings fields to use for grouping (including 'state').
        String value should follow SQL syntax: comma separated list  of fields.
        For example: "parent,resource_name".  The following fields are supported:
        * resource_name
        * category
        * state
        * parent
    - arg_name: page-size
      api_field: groupFindingsRequest.pageSize
      help_text: |
        Maximum number of results to return in a single response. Default is 10, minimum is 1,
        maximum is 1000.
    - arg_name: page-token
      api_field: groupFindingsRequest.pageToken
      help_text: |
        Response objects will return a non-null value for page-token to indicate that there is at least
        one additional page of data. User can either directly request that page by specifying the
        page-token explicitly or let gcloud fetch one-page-at-a-time.
    - arg_name: read-time
      api_field: groupFindingsRequest.readTime
      help_text: |
        Time used as a reference point when filtering findings. The filter is limited
        to findings existing at the supplied time and their values are those at that
        specific time. For example. 2019-02-28T07:00:00Z. Absence of this field will
        default to the API's version of NOW.
