Module Development Guide

Module Development Guide

This guide reflects the current package layout and helper APIs.

Codebase Layout for Modules

• Runtime modules: gcpwn/modules/<service>/<category>/...
• Service helpers: gcpwn/modules/<service>/utilities/helpers.py
• Static service data: gcpwn/modules/<service>/utilities/data/*
• Module index metadata: gcpwn/mappings/module-mappings.json

Minimum New Module Checklist

1. Add module file with run_module(user_args, session) entrypoint.
2. Use argparse in-module (allow_abbrev=False).
3. Use shared helpers from gcpwn/core/utils/service_runtime.py when possible.
4. Store discovered rows with session.insert_data(...).
5. Record useful permissions/actions via shared IAM/action helpers used by existing modules.
6. Register module in gcpwn/mappings/module-mappings.json.
7. Add tests (at least focused unit coverage where feasible).

Module Shape (typical)

def run_module(user_args, session):
    parser = argparse.ArgumentParser(...)
    # add flags
    args = parser.parse_args(user_args)
    # enumerate/list/get/testIamPermissions/download
    # write rows via session.insert_data(...)
    return 0

Conventions

• Prefer existing helper utilities over one-off implementations.
• Keep service API error handling consistent (403 denied, 404, API disabled, generic errors).
• Keep CLI output concise and table-aware.
• Respect workspace/project context and project selectors.

Where command metadata comes from

Interactive module listing and info use:

• gcpwn/mappings/module-mappings.json

If you add a module but do not add this mapping, modules list/info/run behavior will be incomplete.

Testing

Run current suites:

python -m pytest -q -ra tests/unit tests/module_contracts

Relevant areas:

• tests/unit/core/
• tests/unit/opengraph/
• tests/unit/everything/
• tests/module_contracts/

OpenGraph-Specific Development

If adding new dangerous-path logic:

1. Update rule definitions (og_privilege_escalation_paths.json)
2. Update permission map coverage (og_permission_to_roles_map.json)
3. Add/adjust OpenGraph unit tests:
   • rule variants
   • combo path emission
   • coverage warnings and skip logic