Skip to content

Getting Started

Jump to bottom
WebbinRoot edited this page Jul 14, 2026 · 5 revisions

Getting Started

Requirements

Core (required)

  • Python 3.11+
  • pip

Common optional tools

  • gcloud CLI
    Used for ADC-based authentication workflows (ex. gcloud auth login).

  • prettytable
    Enables table-formatted terminal output mode rather than just txt stdout.

  • xlsxwriter
    Enables Excel (.xlsx) export support (ex. data export excel).

Install Options

Choose the install option that fits your workflow. GCPwn stores collected data in local SQLite databases, and the database path depends on how you installed the tool.

If you want a clean reset, remove the databases/ directory (ex. rm -r databases) for your install location.

Downloaded artifacts and exports are written under gcpwn_output/ in the runtime location (or the mounted output path in Docker).

Option 1: Clone + venv (recommended for contributors)

git clone https://github.com/NetSPI/gcpwn.git
cd gcpwn
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

Optional extras:

pip install prettytable==3.17.0
pip install xlsxwriter==3.2.9

Run:

python -m gcpwn

Database location for this option:

  • ./databases/ (inside the cloned gcpwn folder)
  • Example: ./databases/gcpwn.db

Option 2: PyPI install

pip3 install gcpwn

Optional extras:

pip3 install "gcpwn[table]"
pip3 install "gcpwn[excel]"
pip3 install "gcpwn[table,excel]"

Run:

gcpwn

If the shell cannot find gcpwn:

python -m gcpwn

Database location for this option:

  • Under your home directory at ~/.gcpwn/databases/ (site-packages is read-only, so GCPwn writes its data there)
  • Quick path check:
python -c "from gcpwn.core.db import DataController as D; print(D.database_path)"

Option 3: Release Download

Download a release binary from GitHub Releases:

Use the binary asset that matches your OS and CPU architecture (for example, Linux/macOS/Windows and amd64 vs arm64).

Example (Linux/macOS):

chmod +x ./gcpwn
./gcpwn

Database location for this option:

  • Runtime path used by the binary (commonly in the directory where you execute it) under databases/
  • Example: ./databases/gcpwn.db

Option 4: Docker

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

Build with optional extras:

# 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 .

With output/data persistence:

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

Database location for this option:

  • In-container default: /opt/gcpwn/databases/
  • If you use the volume mount above, host path: $(pwd)/databases/

First Interactive Session

  1. Create or select a workspace at startup.
  2. Add or select credentials (see Authentication Reference).
  3. If using ADC, set your active project context when needed:
gcloud config set project <PROJECT_ID>
  1. Run baseline collection:
# Minimal first pass
modules run enum_all

# Common day-one run
modules run enum_all --iam --download

# Deeper pass (large Resource Manager permission sets)
modules run enum_all --iam --all-permissions --download

# Run only a subset of services (comma/space separated tokens; omit to run all)
modules run enum_all --modules iam,storage gke

# Include the opt-in Cloud Asset Inventory pull (additive: bare enum_all skips it)
modules run enum_all --iam --asset-inventory

# Reuse the cached hierarchy instead of re-discovering projects/folders/orgs
modules run enum_all --iam --no-enum-resources

# Scoped Resource Manager deep-dive while still discovering broadly
modules run enum_all --modules resource-manager --iam --get --project-allowlist-file projects.txt --folder-allowlist 123456789012 --org-allowlist-file org_ids.txt

enum_all covers 43 GCP services. Choose which ones to run with --modules (comma/space separated tokens) — omit it to run everything. Tokens accept short names (storage, iam, bq, gke, secrets, compute, …) or full names (cloud-storage); run modules run enum_all --list-modules for the full list. enum_all also runs a once-only Google Workspace phase; enum_gcp is identical but skips Workspace, and enum_google_workspace runs only the Workspace enumerators.

Google Workspace note:

  • GCP credentials do not grant Workspace access. The Workspace enumerators call the Cloud Identity / Admin SDK Directory APIs, which need a principal Workspace recognizes as an admin — either an admin user credential (works directly) or a service account with domain-wide delegation that impersonates an admin via --impersonate <admin@domain>.
  • Directory scoping uses a directoryCustomerId (C...), resolved from --customer-id, the workspace_customer_id config, or derived + auto-persisted from the GCP org (--org-id). Full details in Authentication Reference → Google Workspace (Domain-Wide Delegation).

Cloud Asset Inventory note:

  • --asset-inventory is opt-in. A bare enum_all SKIPS it; enum_all --asset-inventory runs everything PLUS it. It list_assets (RESOURCE + IAM_POLICY) at project/folder/org scope and UPSERTS into the shared workspace tables (IAM policies, the resource tree, service accounts/keys/roles, compute instances, Workload Identity) as a force-multiplier and fallback.

Allowlist note:

  • If no allowlist flags are supplied, enum_all treats all discovered resources/projects as in scope.
  • Inline allowlist flags (--project-allowlist, --folder-allowlist, --org-allowlist) take literal IDs.
  • --*-allowlist-file flags take file paths (one ID per line).
  • --parent-allowlist-folder* and --parent-allowlist-org* constrain scope to descendants (any nested depth).
  • With both direct and parent allowlists, effective scope is their intersection. With parent-only allowlists, scope is all descendants under those parents.
  • If only one direct allowlist type is provided, other direct resource types are treated as out of scope unless also allowlisted.
  • With allowlists present, enum_all still runs baseline Resource Manager discovery, but non-Resource-Manager modules run only for projects inside the effective allowlist scope.
  • Exception: enum_gcp_policy_bindings still runs once at the end of enum_all.
  • enum_gcp_policy_bindings uses cached workspace resources, so resources enumerated in earlier runs (including outside the current allowlist) may still be included.
  1. Analyze and export what was collected:
  • Review permissions enumerated for the credentials used (What are my permissions?)
creds info
creds info --csv
  • Review the data enumerated in Excel or CSV (What data/services can I see?)
data export excel
data export csv
  • Review the data written to disk or downloaded (What can I download?)
./gcpwn_output/<workspace_id>_<workspace_name_slug>/
  1. Build OpenGraph JSON for BloodHound import:
modules run process_og_gcpwn_data --expand-inherited --reset --out Bloodhound_Output

-o/--out is an OUTPUT DIRECTORY; files are written into it as opengraph_<folder_name>.json. Import that JSON into BloodHound CE to review privilege-escalation paths.

Alternatively, build the graph directly from a Cloud Asset Inventory export FILE with no prior enumeration and no SQLite needed:

# 1. Export assets with gcloud (RESOURCE + IAM_POLICY) to a GCS object, then download it
gcloud asset export \
  --project <PROJECT_ID> \
  --content-type resource \
  --output-path "gs://<BUCKET>/assets.json"
# (repeat with --content-type iam-policy, or use --content-type=resource and a second
#  iam-policy export; gather the NDJSON export file(s) locally)

# 2. Build the graph straight from the export file
modules run process_og_gcpwn_data --cai-file ./assets.json --expand-inherited --out Bloodhound_Output

--cai-file accepts NDJSON from gcloud asset export or a JSON array of assets. The generated graph is exported but NOT persisted to the workspace's OpenGraph tables, and it cannot be combined with --use-existing-opengraph-db.

BloodHound CE installation/quickstart: https://bloodhound.specterops.io/get-started/quickstart/community-edition-quickstart

Where To Go Next

Home | Getting Started | Auth | Workspace | CLI Modules | Downloads | Data View/Export | IAM Workflow | OpenGraph Overview | OpenGraph Add Content

GCPwn Wiki

Core Operations

OpenGraph

Development

Clone this wiki locally