gcp-iam-policies
Cloud Asset Inventory API로 Google Cloud IAM 정책을 검색해 역할과 주 구성원 조합마다 한 행을 출력합니다.
문법
gcp-iam-policies [profile=STRING] [scope=STRING] [types=STRING] [query=STRING] [limit=INT]
옵션
- profile=STRING
- 선택 옵션. Google Cloud 접속 프로파일 식별자. 쉼표로 여러 개를 지정하면 프로파일마다 차례로 조회하고 profile 필드로 구분합니다. 생략하면 사용 권한이 있는 모든 Google Cloud 접속 프로파일로 조회합니다. 조회 중 한 프로파일에서 오류가 나면 그때까지 출력한 결과는 남고, 나머지 프로파일은 조회하지 않은 채 쿼리가 오류로 끝납니다.
- scope=STRING
- 선택 옵션. 조회 범위.
projects/프로젝트ID(또는projects/프로젝트번호),folders/폴더번호,organizations/조직번호중 하나. 지정한 범위와 그 아래 자원에 설정된 정책을 조회합니다. 생략하면 서비스 계정 JSON 키의 프로젝트를 조회합니다. - types=STRING
- 선택 옵션. 정책이 붙은 자원의 자산 유형. 쉼표로 여러 개를 지정할 수 있고 정규표현식을 지원합니다. 예:
cloudresourcemanager.googleapis.com/Organization,storage.googleapis.com/Bucket. 자주 쓰는 유형은 gcp-assets의 자산 유형 표를 참고합니다. - query=STRING
- 선택 옵션. IAM 정책 검색식. 예:
policy:user@example.com,policy:roles/owner,memberTypes:user,policy.role.permissions:storage.buckets.update. 검색식 문법은 IAM 정책 검색 문서를 참고합니다. - limit=INT
- 선택 옵션. 프로파일별 최대 출력 건수(행 기준). 1 이상의 정수. 생략하면 전체를 조회합니다.
출력 필드
| 필드 | 타입 | 이름 | 설명 |
|---|---|---|---|
| profile | 문자열 | 프로파일 | 접속 프로파일 이름 |
| member | 문자열 | 주 구성원 | 예: user:user@example.com, allUsers |
| member_type | 문자열 | 주 구성원 유형 | member의 접두어. 예: user, serviceAccount, group, domain, allUsers |
| role | 문자열 | 역할 | 예: roles/owner |
| asset_type | 문자열 | 자산 유형 | 자원의 자산 유형 |
| resource | 문자열 | 자원 | 정책이 붙은 자원의 전체 이름 |
| project_id | 문자열 | 프로젝트 ID | 사용자가 지정한 프로젝트 ID. 리소스가 프로젝트에 속하지 않으면(조직·폴더 등) 빈 값 |
| project_name | 문자열 | 프로젝트 이름 | 프로젝트 표시 이름. 리소스가 프로젝트에 속하지 않으면(조직·폴더 등) 빈 값 |
| condition_title | 문자열 | 조건 제목 | IAM 조건 제목. 조건이 있는 권한만 값이 있음 |
| condition_expression | 문자열 | 조건식 | IAM 조건의 CEL 표현식. 예: request.time < timestamp("2026-12-31T00:00:00Z") |
| condition_description | 문자열 | 조건 설명 | IAM 조건 설명 |
| project | 문자열 | 프로젝트 | projects/{번호} 형식의 소속 프로젝트. 조직·폴더 정책은 빈 값 |
| folders | 목록 | 폴더 | folders/{번호} 형식의 상위 폴더 목록 |
| organization | 문자열 | 조직 | organizations/{번호} 형식의 소속 조직 |
| matched_permissions | 목록 | 일치한 권한 | policy.role.permissions 검색식에 일치한 이 역할의 권한 목록 |
오류 코드
파싱 오류
| 오류 메시지 | 원인 | 해결 |
|---|---|---|
| 사용 가능한 Google Cloud 프로파일이 없습니다. | 프로파일 식별자가 틀렸거나 사용 권한이 없음 | profile 옵션에 접속 프로파일 식별자 입력, 프로파일 사용 권한 확인 |
| scope 형식이 올바르지 않습니다: {scope} | scope 형식 오류, 또는 폴더·조직을 이름으로 지정함 | projects/, folders/, organizations/ 다음에 ID·번호 입력 |
| limit은 양의 정수여야 합니다: {limit} | limit이 0 이하이거나 숫자가 아님 | 1 이상의 정수 입력 |
런타임 오류
| 오류 메시지 | 원인 | 해결 |
|---|---|---|
| HTTP 403: PERMISSION_DENIED - The caller does not have permission | 조회 범위에 Cloud 애셋 뷰어 역할이 없음 | gcp-check-permissions로 확인하고 해당 범위에 역할 부여 |
| HTTP 403: PERMISSION_DENIED - Cloud Asset API has not been used in project ... | 서비스 계정 프로젝트에서 Cloud Asset API 미사용 설정 | 서비스 계정이 속한 프로젝트에서 Cloud Asset API 사용 설정 |
| HTTP 400: INVALID_ARGUMENT - Invalid query syntax, Unsupported field: ... | 검색식 문법 오류, 지원하지 않는 필드 | 오류 메시지의 지원 필드 목록과 검색식 문법 문서를 참고해 수정 |
| HTTP 400: INVALID_ARGUMENT - Please quote term ... with double quotes | 검색식에 특수 문자가 든 검색어를 따옴표 없이 사용 | 검색어를 "로 감싸기 |
| token exchange failed, HTTP 400: Invalid grant | JSON 키 오류, 서비스 계정·키 삭제 | 새 키를 발급해 접속 프로파일 수정 |
설명
지정한 범위에서 Cloud Asset Inventory의 searchAllIamPolicies API로 자원에 직접 설정된 IAM 정책을 검색합니다. 정책 하나에는 여러 역할 바인딩이 있고 바인딩마다 여러 주 구성원이 있으므로, 역할 × 주 구성원 조합마다 한 행으로 펼쳐 출력합니다. 상위 폴더·조직에서 상속된 권한은 그 상위 자원의 행으로 나옵니다.
member_type으로 사용자(user), 서비스 계정(serviceAccount), 그룹(group), 도메인(domain), 전체 공개(allUsers, allAuthenticatedUsers)를 구분할 수 있어 과도한 권한이나 공개 권한 점검에 활용합니다.
gcp-assets와 같은 방식으로 프로젝트 ID와 이름(project_id, project_name)을 채웁니다. 폴더·조직은 번호로만 나옵니다.
Note
조회 결과는 Google Cloud가 수집한 최근 시점의 정책이며, 권한 정보는 반영이 늦을 수 있습니다. 그룹 구성원은 펼치지 않으므로 group 행의 실제 사용자는 Google Workspace 등에서 확인합니다.
사용 예
예시: 조직 전체 권한 현황
상황: 조직 안에서 어떤 유형의 주 구성원이 어디에 권한을 가졌는지 파악합니다.
gcp-iam-policies profile=gcp scope=organizations/123456789012
| stats count by asset_type, member_type
예상 결과:
| asset_type | member_type | count |
|---|---|---|
| cloudresourcemanager.googleapis.com/Organization | user | 4 |
| cloudresourcemanager.googleapis.com/Organization | domain | 2 |
| cloudresourcemanager.googleapis.com/Organization | serviceAccount | 2 |
| cloudresourcemanager.googleapis.com/Project | user | 3 |
결과 해석: 조직 수준 권한은 아래 모든 프로젝트에 상속되므로 특히 주의해서 봅니다.
예시: 소유자 권한 보유자
상황: 소유자(roles/owner) 권한을 가진 주 구성원을 프로젝트별로 확인합니다.
gcp-iam-policies profile=gcp scope=organizations/123456789012 query="policy:roles/owner"
| fields project_id, resource, role, member
예상 결과:
| project_id | resource | role | member |
|---|---|---|---|
| my-project-123456 | //cloudresourcemanager.googleapis.com/projects/my-project-123456 | roles/owner | user:user@example.com |
결과 해석: 소유자는 모든 자원을 변경·삭제할 수 있습니다. 필요 이상으로 부여되지 않았는지 점검합니다.
예시: 전체 공개 권한 탐지
상황: 누구나 접근할 수 있게 공개된 자원을 찾습니다.
gcp-iam-policies profile=gcp scope=organizations/123456789012
| search member_type == "allUsers" or member_type == "allAuthenticatedUsers"
| fields project_id, asset_type, resource, role, member
결과 해석: 결과가 있으면 의도한 공개인지 확인하고, 아니면 해당 자원의 권한을 회수합니다.
예시: 조건부 권한
상황: 기간 제한 등 조건이 걸린 권한을 확인합니다.
gcp-iam-policies profile=gcp scope=organizations/123456789012
| search isnotnull(condition_expression)
| fields resource, role, member, condition_title, condition_expression
결과 해석: 만료 시각이 지난 조건부 권한은 더 이상 효력이 없으므로 정리 대상입니다.
예시: 특정 권한을 포함한 역할 보유자
상황: 프로젝트를 조회할 수 있는 권한(resourcemanager.projects.get)을 가진 주 구성원과, 그 권한을 준 역할을 확인합니다.
gcp-iam-policies profile=gcp scope=organizations/123456789012 query="policy.role.permissions:resourcemanager.projects.get"
| fields resource, role, member, matched_permissions
결과 해석: matched_permissions에 그 행의 역할에서 일치한 권한이 나옵니다.