> For the complete documentation index, see [llms.txt](https://docs.forestall.io/fsprotect/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.forestall.io/fsprotect/edges/gcp/gcp_custom_privileged_role.md).

# GCP\_CUSTOM\_PRIVILEGED\_ROLE

## Summary

|                            |                                           |
| -------------------------- | ----------------------------------------- |
| **FSProtect ACL Alias**    | GCP\_CUSTOM\_PRIVILEGED\_ROLE             |
| **GCP Alias**              | IAM & Hierarchy Control                   |
| **Affected Object Types**  | Organizations, Folders, Projects          |
| **Exploitation Certainty** | Likely                                    |
| **Granting Roles**         | Any custom IAM role flagged as privileged |

## Description

`GCP_CUSTOM_PRIVILEGED_ROLE` represents an assignment of a GCP **custom IAM role** that is flagged as privileged and does **not** have an explicit, mapped attack path edge. Unlike predefined roles, custom roles are organization- or project-defined and can contain any combination of permissions. This makes them particularly dangerous because a custom role may appear innocuous by name but contain highly sensitive permissions, and the permissions are not covered by specific attack path mappings.

Custom privileged roles are often created during migrations, automation setups, or in attempts to implement least-privilege but inadvertently combine dangerous permissions. They are also a common persistence mechanism: an attacker who creates or modifies a custom role can hide high-privilege access behind a benign-sounding role name.

## Identification

### gcloud CLI

```bash
# List all custom roles in a project
PROJECT_ID="my-project"
gcloud iam roles list --project=$PROJECT_ID --format=json

# Inspect a specific custom role's permissions
CUSTOM_ROLE="projects/${PROJECT_ID}/roles/CustomProjectRole"
gcloud iam roles describe $(basename $CUSTOM_ROLE) --project=$PROJECT_ID --format=json | \
  jq '.includedPermissions[]'

# Find who is assigned custom roles in a project
gcloud projects get-iam-policy $PROJECT_ID --format=json | \
  jq '.bindings[] | select(.role | contains("/roles/")) | {role: .role, members: .members}'
```

### GCP Console

1. Open **GCP Console** → **IAM & Admin** → **Roles**.
2. Select "Custom" tab.
3. Click each role and review **Included Permissions**.
4. Cross-reference against **IAM** page bindings.

## Exploitation

The exact exploitation steps depend on the specific permissions present in the custom role.

**Common dangerous permissions found in flagged custom roles and their attack vectors:**

* `resourcemanager.projects.setIamPolicy` → privilege escalation via IAM policy manipulation → see [GCP\_CAN\_SET\_PROJECT\_IAMPOLICY](https://docs.forestall.io/fsprotect/edges/gcp/gcp_can_set_project_iampolicy)
* `resourcemanager.folders.setIamPolicy` → privilege escalation via IAM policy manipulation → see [GCP\_CAN\_SET\_FOLDER\_IAMPOLICY](https://docs.forestall.io/fsprotect/edges/gcp/gcp_can_set_folder_iampolicy)
* `resourcemanager.organizations.setIamPolicy` → privilege escalation via IAM policy manipulation → see [GCP\_CAN\_SET\_ORG\_IAMPOLICY](https://docs.forestall.io/fsprotect/edges/gcp/gcp_can_set_org_iampolicy)
* `iam.serviceAccounts.actAs` → SA attachment to compute resources → see [GCP\_CAN\_ACT\_AS\_SA](https://docs.forestall.io/fsprotect/edges/gcp/gcp_can_act_as_sa).
* `iam.serviceAccounts.getAccessToken` → direct SA token generation → see [GCP\_CAN\_IMPERSONATE\_SA](https://docs.forestall.io/fsprotect/edges/gcp/gcp_can_impersonate_sa).
* `compute.instances.create` + SA attachment → vehicle for token extraction → see [GCP\_CAN\_CREATE\_COMPUTE](https://docs.forestall.io/fsprotect/edges/gcp/gcp_can_create_compute) + [GCP\_CAN\_ACT\_AS\_SA](https://docs.forestall.io/fsprotect/edges/gcp/gcp_can_act_as_sa).

## Mitigation

1. **Audit all custom roles flagged by this edge** — identify what permissions each contains and whether they're necessary.
2. **Remove or split roles containing dangerous permission combinations** — do not allow a single custom role to include those permissions together.
3. **Enforce naming conventions and documentation** for custom roles so their purpose is transparent and auditable.
4. **Restrict `roles/iam.roleAdmin`** to dedicated automation accounts — this role controls custom role creation/modification.
5. **Regularly review custom role bindings** — custom roles should have a documented owner, business justification, and expiry policy.

## Detection

| Log Type       | Method                    | Key Fields                                         |
| -------------- | ------------------------- | -------------------------------------------------- |
| Admin Activity | `CreateRole` `UpdateRole` | `resource.type=iam_role`, custom role modification |
| Admin Activity | `SetIamPolicy`            | New binding adding a custom role                   |

```bash
# Monitor for custom role creations and updates in a project
PROJECT_ID="my-project"
gcloud logging read \
  'protoPayload.methodName=("google.iam.admin.v1.CreateRole" OR "google.iam.admin.v1.UpdateRole")' \
  --project=$PROJECT_ID \
  --format="table(timestamp, protoPayload.authenticationInfo.principalEmail, protoPayload.resourceName, protoPayload.methodName)"

# Monitor for new custom role assignments in a project
gcloud logging read \
  'protoPayload.methodName="SetIamPolicy" AND protoPayload.serviceData.policyDelta.bindingDeltas.role:"/roles/"' \
  --project=$PROJECT_ID \
  --format="table(timestamp, protoPayload.authenticationInfo.principalEmail, protoPayload.serviceData.policyDelta.bindingDeltas)"
```

Alert on:

* Any creation or update of a custom role (`CreateRole`, `UpdateRole`).
* Modifications to custom roles adding dangerous permissions (`setIamPolicy`, `actAs`, `getAccessToken`).
* New bindings assigning custom roles to human users or external identities.
* Custom role assignments at org or folder scope.

## References

* <https://cloud.google.com/iam/docs/creating-custom-roles>
* <https://cloud.google.com/iam/docs/understanding-custom-roles>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.forestall.io/fsprotect/edges/gcp/gcp_custom_privileged_role.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.