GCPwn

Table of Contents

• Overview
• Documentation
• Installation TLDR
• First-Run TLDR
• Passthrough Mode TLDR
• Exploit Module TLDR
• OpenGraph TLDR
• Module/Data Output TLDR
• Audit / Logging TLDR
• Scripts Folder TLDR
• Dependency Inventory
• Repository Layout
• Who Is This For?
• Author, Contributors, and License
• Resources
• Credits

Overview

In the spirit of transparency: parts of this project and documentation were developed with LLM coding assistance. Review code and behavior in your environment before operational use. Ideally the dependency summary at the end of the README and explanations throughout should be enough to meet and verify your operational needs.

GCPwn (G-C-pwn) is a Google Cloud offensive security assessment framework built for workspace-driven credential handling, service enumeration, artifact collection, and graph-based attack-path analysis. It also supports limited Google Workspace enumeration at this time.

It is designed as a one-stop shop for three primary workflows:

• Reconnaissance and Enumeration: Use success/fail API behavior trackedin the background, explicit testIamPermissions calls, and IAM binding analysis to understand effective permissions from clear-box (probably a config audit) to opaque scenarios (finding creds during a pentest). Export data in JSON/CSV/Excel formats, download artifacts as they are found (for example, Artifact Registry Python packages), and run broad discovery with enum_all and download data throughout with the --download flag.
• Exploitation: Execute pre-packaged exploit workflows for blue-team validation and professional penetration-testing exercises.
• Graphing and OpenGraph: Convert collected data into OpenGraph output for BloodHound-style analysis (see below). By default, graphing focuses on selected privilege-escalation edges and can be expanded with more verbose output, inheritance evaluation, and multi-permission edge logic.

<p><strong><span style="color:red">Disclaimer:</span></strong> <span style="color:red">Use this tool only in systems, projects, and environments you own or are explicitly authorized to assess. Unauthorized use may violate law, policy, or terms of service.</span></p>

Documentation

Documentation is maintained in the GitHub Wiki:

• https://github.com/NetSPI/gcpwn/wiki

Quick wiki links:

• Getting Started: https://github.com/NetSPI/gcpwn/wiki/Getting-Started
• Authentication Reference: https://github.com/NetSPI/gcpwn/wiki/Authentication-Reference
• Workspace Instructions: https://github.com/NetSPI/gcpwn/wiki/Workspace-Instructions
• CLI Module Reference: https://github.com/NetSPI/gcpwn/wiki/CLI-Module-Reference
• Common Use Cases: https://github.com/NetSPI/gcpwn/wiki/Common-Use-Cases
• OpenGraph Overview and Usage: https://github.com/NetSPI/gcpwn/wiki/OpenGraph-Overview-and-Usage
• OpenGraph Add Your Own Content: https://github.com/NetSPI/gcpwn/wiki/OpenGraph-Add-Your-Own-Content

Additional project docs:

• Contributing: CONTRIBUTING.md
• Roadmap: ROADMAP.md
• License: LICENSE

Installation TLDR

The installation strategy is to keep non-google dependencies minimal hopefully making it easier for you to get the tool approved if needed. xlsxwriter and prettytable are optional and can be installed only if you want those extra features, as shown below.

Option 1: Local Git Clone Install

git clone https://github.com/NetSPI/gcpwn.git
cd gcpwn

python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip

Base install (no optional table/excel dependencies):

pip install -r requirements.txt

Install optional table output support:

pip install prettytable==3.17.0

Install optional Excel export support:

pip install xlsxwriter==3.2.9

Run the tool:

python -m gcpwn

Option 2: Pip Install (PyPI)

pip3 install gcpwn

If you want optional table rendering (table std output option in configs) and/or Excel export support (data export excel option):

pip3 install "gcpwn[table]"
pip3 install "gcpwn[excel]"
# both extras
pip3 install "gcpwn[table,excel]"

Run the tool:

gcpwn

If your shell cannot find gcpwn, run:

python -m gcpwn

Option 3: Release Download

Download a release binary from GitHub Releases:

• https://github.com/NetSPI/gcpwn/releases

Use the binary asset that aligns with your operating system and CPU architecture (for example, Linux/macOS/Windows and amd64 vs arm64).

Example (Linux/macOS):

chmod +x ./gcpwn
./gcpwn

Option 4: Docker

docker build -t gcpwn .
docker run --rm -it gcpwn

Build with optional extras (if you want table rendering and/or Excel export available in the container):

# prettytable extra
docker build --build-arg GCPWN_EXTRAS=table -t gcpwn .

# xlsxwriter extra
docker build --build-arg GCPWN_EXTRAS=excel -t gcpwn .

# both extras
docker build --build-arg GCPWN_EXTRAS=table,excel -t gcpwn .

If you want local persistence for DB/output between runs, mount volumes:

docker run --rm -it \
  -v "$(pwd)/databases:/opt/gcpwn/databases" \
  -v "$(pwd)/gcpwn_output:/opt/gcpwn/gcpwn_output" \
  gcpwn

First-Run TLDR

1. Create/select a workspace by starting the program using one of the commands in the Installation section above.
2. Load credentials (user/service/OAuth token). If you are using gcloud, you may need to run gcloud config set project <PROJECT_ID> when loading ADC-style credentials.
3. Start with broad enumeration, ideally with ONE of the options below:

# Minimal first pass: enumerate discovered GCP resources only (no testIamPermissions or download calls).
modules run enum_gcp

# Common first pass: run testIamPermissions checks on supported resources.
# Also runs a condensed list of permissions for org/folder/project resources.
modules run enum_gcp --iam

# Common first pass + downloads: run testIamPermissions and attempt content downloads where supported.
# Optional [--download-timeout <seconds>] restricts downloads to that many seconds PER service
# (per bucket for Cloud Storage, per download type per project elsewhere) -- once the limit is hit
# it skips the rest of that service's downloads and moves on.
modules run enum_gcp --iam --download [--download-timeout <seconds>]

# In-depth pass: --all-permissions includes large org/folder/project permission sets (10,000+ perms, executed in batches). Can take some time.
# See: gcpwn/modules/gcp/resourcemanager/utilities/data/all_*_permissions.txt for the full list or to customize it.
modules run enum_gcp --iam --all-permissions

# In-depth pass + downloads: enable artifact/content downloads where supported.
# Use `modules run enum_gcp -h` for token options.
# Example token: cloudrun_revision_env
modules run enum_gcp --iam --all-permissions --download

# ---- Scope + speed ----
# The commands above run enum_gcp (GCP only). Both enum_gcp and enum_all accept --parallel-services
# to enumerate GCP services concurrently across projects (default is 1 = sequential; set higher to fan out).
# enum_google_workspace is tenant-scoped -> it runs once and does NOT take --parallel-services.

# Same GCP sweep, but 3 services concurrently:
modules run enum_gcp --iam --parallel-services 3

# Pick specific services (comma/space separated tokens; omit to run all). See `-h` / --list-modules.
modules run enum_gcp --modules storage,iam gke

# --filter-enabled-services: probe each project's ENABLED APIs (serviceusage) ONCE, then
# enumerate ONLY the services whose API is enabled instead of brute-forcing all ~40.
# Falls back to running everything for a project if the probe is denied/empty.
modules run enum_gcp --iam --filter-enabled-services

# Reuse the already-cached project/folder/org hierarchy (skip Resource Manager re-discovery).
modules run enum_gcp --iam --no-enum-resources

# Google Workspace only (users/groups/admin-roles/OUs/domains/devices/OAuth grants).
# Needs Workspace admin creds, OR a service account with domain-wide delegation ->
# pass --impersonate <admin@domain> (or set it once: `configs set workspace_admin_subject <admin@domain>`):
modules run enum_google_workspace --impersonate admin@yourdomain.com

# Everything at once: enum_all = the GCP sweep + a once-only Google Workspace phase at the end:
modules run enum_all --iam --parallel-services 3

# Google Drive content download is opt-in (NOT covered by --download above). Add --download-google-drive
# to ALSO pull Drive file content in the Workspace phase (runs enum_drive --all-users --download).
# NOTE: beta / early version -- treat Drive download as experimental for now.
modules run enum_all --iam --parallel-services 3 --download-google-drive

4. Review what was collected:

# Downloaded artifacts are written under gcpwn_output/ by default.

# Export collected data.
# CSV/JSON work in base install; Excel requires the optional Excel dependency