Getting Started

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/workspaces.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:

• Inside the installed gcpwn package directory (<site-packages>/databases/)
• Quick path check:

python -c "from gcpwn.core.db import DataController as D; print(D.workspace_database)"

Option 3: Release Download

Download a release binary from GitHub Releases:

• https://github.com/NetSPI/gcpwn/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/workspaces.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>

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

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

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_policy_bindings still runs once at the end of enum_all.
• enum_policy_bindings uses cached workspace resources, so resources enumerated in earlier runs (including outside the current allowlist) may still be included.

5. 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>/

6. Build OpenGraph JSON for BloodHound import:

modules run enum_gcp_cloud_hound_data --expand-inherited --reset --out Bloodhound_Output.json

Import Bloodhound_Output.json into BloodHound CE to review privilege-escalation paths.

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

Where To Go Next

• Auth mode details and startup syntax: Authentication Reference
• Workspace commands (credential/project/config/data menus): Workspace Instructions
• Module flags, categories, and orchestrator flows: CLI Module Reference
• Goal-driven operator workflows: Common Use Cases
• Artifact/content collection patterns with --download: Downloads to Disk
• SQL querying, export formats, and safe wipe operations: Data View/Export
• End-to-end IAM processing workflow from enumeration to analysis: IAM Enumeration and Analysis Workflow
• OpenGraph generation behavior and operational run patterns: OpenGraph Overview and Usage
• Custom single-permission and multi-permission edge authoring: OpenGraph - Add Your Own Content
• Developer extension path for writing/updating modules: Module Development Guide