postures

Creates, updates, deletes, gets or lists a postures resource.

Overview

Name	postures
Type	Resource
Id	google.securityposture.postures

Fields

The following fields are returned by SELECT queries:

get

Successful response

Name	Datatype	Description
name	string	Required. Identifier. The name of the posture, in the format organizations/{organization}/locations/global/postures/{posture_id}.
annotations	object	Optional. The user-specified annotations for the posture. For details about the values you can use in an annotation, see AIP-148: Standard fields.
categories	array	Output only. The categories that the posture belongs to, as determined by the Security Posture API.
createTime	string (google-datetime)	Output only. The time at which the posture was created.
description	string	Optional. A description of the posture.
etag	string	Optional. An opaque identifier for the current version of the posture at the specified revision_id. To prevent concurrent updates from overwriting each other, always provide the etag when you update a posture. You can also provide the etag when you delete a posture, to help ensure that you're deleting the intended version of the posture.
policySets	array	Required. The PolicySet resources that the posture includes.
reconciling	boolean	Output only. Whether the posture is in the process of being updated.
revisionId	string	Output only. Immutable. An opaque eight-character string that identifies the revision of the posture. A posture can have multiple revisions; when you deploy a posture, you deploy a specific revision of the posture.
state	string	Required. The state of the posture at the specified revision_id.
updateTime	string (google-datetime)	Output only. The time at which the posture was last updated.

list

Successful response

Name	Datatype	Description
name	string	Required. Identifier. The name of the posture, in the format organizations/{organization}/locations/global/postures/{posture_id}.
annotations	object	Optional. The user-specified annotations for the posture. For details about the values you can use in an annotation, see AIP-148: Standard fields.
categories	array	Output only. The categories that the posture belongs to, as determined by the Security Posture API.
createTime	string (google-datetime)	Output only. The time at which the posture was created.
description	string	Optional. A description of the posture.
etag	string	Optional. An opaque identifier for the current version of the posture at the specified revision_id. To prevent concurrent updates from overwriting each other, always provide the etag when you update a posture. You can also provide the etag when you delete a posture, to help ensure that you're deleting the intended version of the posture.
policySets	array	Required. The PolicySet resources that the posture includes.
reconciling	boolean	Output only. Whether the posture is in the process of being updated.
revisionId	string	Output only. Immutable. An opaque eight-character string that identifies the revision of the posture. A posture can have multiple revisions; when you deploy a posture, you deploy a specific revision of the posture.
state	string	Required. The state of the posture at the specified revision_id.
updateTime	string (google-datetime)	Output only. The time at which the posture was last updated.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	organizationsId, locationsId, posturesId	revisionId	Gets a single revision of a Posture.
list	select	organizationsId, locationsId	pageSize, pageToken, filter	Lists the most recent revisions of all Posture resources in a specified organization and location.
create	insert	organizationsId, locationsId	postureId	Creates a new Posture.
patch	update	organizationsId, locationsId, posturesId	updateMask, revisionId	Updates a revision of an existing Posture. If the posture revision that you update is currently deployed, then a new revision of the posture is created. To prevent concurrent updates from overwriting each other, always follow the read-modify-write pattern when you update a posture: 1. Call GetPosture to get the current version of the posture. 2. Update the fields in the posture as needed. 3. Call UpdatePosture to update the posture. Ensure that your request includes the etag value from the GetPosture response. Important: If you omit the etag when you call UpdatePosture, then the updated posture unconditionally overwrites the existing posture.
delete	delete	organizationsId, locationsId, posturesId	etag	Deletes all revisions of a Posture. You can only delete a posture if none of its revisions are deployed.
extract	exec	organizationsId, locationsId		Extracts existing policies from an organization, folder, or project, and applies them to another organization, folder, or project as a Posture. If the other organization, folder, or project already has a posture, then the result of the long-running operation is an ALREADY_EXISTS error.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
locationsId	string
organizationsId	string
posturesId	string
etag	string
filter	string
pageSize	integer (int32)
pageToken	string
postureId	string
revisionId	string
updateMask	string (google-fieldmask)

SELECT examples

get

Gets a single revision of a Posture.

SELECT
name,
annotations,
categories,
createTime,
description,
etag,
policySets,
reconciling,
revisionId,
state,
updateTime
FROM google.securityposture.postures
WHERE organizationsId = '{{ organizationsId }}' -- required
AND locationsId = '{{ locationsId }}' -- required
AND posturesId = '{{ posturesId }}' -- required
AND revisionId = '{{ revisionId }}';

list

Lists the most recent revisions of all Posture resources in a specified organization and location.

SELECT
name,
annotations,
categories,
createTime,
description,
etag,
policySets,
reconciling,
revisionId,
state,
updateTime
FROM google.securityposture.postures
WHERE organizationsId = '{{ organizationsId }}' -- required
AND locationsId = '{{ locationsId }}' -- required
AND pageSize = '{{ pageSize }}'
AND pageToken = '{{ pageToken }}'
AND filter = '{{ filter }}';

INSERT examples

create

Creates a new Posture.

INSERT INTO google.securityposture.postures (
data__name,
data__state,
data__description,
data__policySets,
data__etag,
data__annotations,
organizationsId,
locationsId,
postureId
)
SELECT 
'{{ name }}',
'{{ state }}',
'{{ description }}',
'{{ policySets }}',
'{{ etag }}',
'{{ annotations }}',
'{{ organizationsId }}',
'{{ locationsId }}',
'{{ postureId }}'
RETURNING
name,
done,
error,
metadata,
response
;

Manifest

# Description fields are for documentation purposes
- name: postures
  props:
    - name: organizationsId
      value: string
      description: Required parameter for the postures resource.
    - name: locationsId
      value: string
      description: Required parameter for the postures resource.
    - name: name
      value: string
      description: >
        Required. Identifier. The name of the posture, in the format `organizations/{organization}/locations/global/postures/{posture_id}`.
        
    - name: state
      value: string
      description: >
        Required. The state of the posture at the specified `revision_id`.
        
      valid_values: ['STATE_UNSPECIFIED', 'DEPRECATED', 'DRAFT', 'ACTIVE']
    - name: description
      value: string
      description: >
        Optional. A description of the posture.
        
    - name: policySets
      value: array
      description: >
        Required. The PolicySet resources that the posture includes.
        
    - name: etag
      value: string
      description: >
        Optional. An opaque identifier for the current version of the posture at the specified `revision_id`. To prevent concurrent updates from overwriting each other, always provide the `etag` when you update a posture. You can also provide the `etag` when you delete a posture, to help ensure that you're deleting the intended version of the posture.
        
    - name: annotations
      value: object
      description: >
        Optional. The user-specified annotations for the posture. For details about the values you can use in an annotation, see [AIP-148: Standard fields](https://google.aip.dev/148#annotations).
        
    - name: postureId
      value: string

UPDATE examples

patch

Updates a revision of an existing Posture. If the posture revision that you update is currently deployed, then a new revision of the posture is created. To prevent concurrent updates from overwriting each other, always follow the read-modify-write pattern when you update a posture: 1. Call GetPosture to get the current version of the posture. 2. Update the fields in the posture as needed. 3. Call UpdatePosture to update the posture. Ensure that your request includes the etag value from the GetPosture response. Important: If you omit the etag when you call UpdatePosture, then the updated posture unconditionally overwrites the existing posture.

UPDATE google.securityposture.postures
SET 
data__name = '{{ name }}',
data__state = '{{ state }}',
data__description = '{{ description }}',
data__policySets = '{{ policySets }}',
data__etag = '{{ etag }}',
data__annotations = '{{ annotations }}'
WHERE 
organizationsId = '{{ organizationsId }}' --required
AND locationsId = '{{ locationsId }}' --required
AND posturesId = '{{ posturesId }}' --required
AND updateMask = '{{ updateMask}}'
AND revisionId = '{{ revisionId}}'
RETURNING
name,
done,
error,
metadata,
response;

DELETE examples

delete

Deletes all revisions of a Posture. You can only delete a posture if none of its revisions are deployed.

DELETE FROM google.securityposture.postures
WHERE organizationsId = '{{ organizationsId }}' --required
AND locationsId = '{{ locationsId }}' --required
AND posturesId = '{{ posturesId }}' --required
AND etag = '{{ etag }}';

Lifecycle Methods

extract

Extracts existing policies from an organization, folder, or project, and applies them to another organization, folder, or project as a Posture. If the other organization, folder, or project already has a posture, then the result of the long-running operation is an ALREADY_EXISTS error.

EXEC google.securityposture.postures.extract 
@organizationsId='{{ organizationsId }}' --required, 
@locationsId='{{ locationsId }}' --required 
@@json=
'{
"postureId": "{{ postureId }}", 
"workload": "{{ workload }}"
}';