gcphelpit 0.1.0__tar.gz

gcphelpit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 gcphelpit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gcphelpit-0.1.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: gcphelpit
+Version: 0.1.0
+Summary: A friendly CLI that scans Google Cloud snapshots and finds security, IAM, cost, and reliability issues.
+Author: gcphelpit
+License: MIT
+Keywords: gcp,google-cloud,security,iam,audit,cli
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.9
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Provides-Extra: gcp
+Requires-Dist: google-cloud-asset>=3.0; extra == "gcp"
+Dynamic: license-file
+
+# gcphelpit — free CLI to scan Google Cloud for security, IAM, cost & reliability
+
+![Python](https://img.shields.io/badge/python-3.9%2B-blue)
+![License: MIT](https://img.shields.io/badge/license-MIT-green)
+![Checks](https://img.shields.io/badge/checks-16-orange)
+![Mock-first](https://img.shields.io/badge/mock--first-no%20cloud%20access-brightgreen)
+
+**gcphelpit** is a free, open-source command-line tool that scans a snapshot of your
+Google Cloud project and finds **security, IAM, cost, and reliability** issues — with a
+**plain-English fix for each finding**.
+
+It is **mock-first**: it reads a JSON snapshot of your resources, so it runs — and is
+fully testable — with **zero live cloud access or credentials**. A live GCP adapter can
+be layered on later behind the same interface.
+
+> 🌐 Part of **[GoogleHelpit](https://eliyas-123.github.io/gcphelpit/)** — a community hub of
+> troubleshooting guides, tutorials, and tools for Google Cloud & Workspace.
+> See the [gcphelpit tool page](https://eliyas-123.github.io/gcphelpit/tool.html).
+
+## Who is this for
+
+- You want to **audit a Google Cloud project without giving a tool live access** — point it at an exported JSON snapshot instead.
+- You want **security, IAM, cost, and reliability** covered in **one** pass, not four separate tools.
+- You want each finding to come with a **recommended fix in plain English**, not just a rule ID.
+- You want to **gate CI/CD** on GCP misconfigurations with a simple exit code.
+
+## Install & run
+
+```bash
+git clone https://github.com/EliyaS-123/gcphelpit-cli && cd gcphelpit-cli
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e .
+
+# Scan the bundled demo snapshot
+gcphelpit scan
+```
+
+Or install straight from GitHub, no clone needed:
+
+```bash
+pip install git+https://github.com/EliyaS-123/gcphelpit-cli.git
+```
+
+You'll get a colour-coded table of findings, each with the offending resource and a
+recommended fix.
+
+## What it checks
+
+`gcphelpit checks` lists all built-in checks. They span four categories, each finding
+paired with a plain-English fix:
+
+| Category      | Examples |
+| ------------- | -------- |
+| `security`    | public buckets, world-open firewall ports, public/no-SSL Cloud SQL |
+| `iam`         | primitive owner/editor roles, external members, user-managed SA keys |
+| `cost`        | unattached disks, idle static IPs, stopped VMs, no budget alert |
+| `reliability` | no DB backups, single-zone prod DB, no deletion protection |
+
+## Usage
+
+```bash
+gcphelpit scan                          # scan the bundled demo snapshot
+gcphelpit scan -f my-project.json       # scan your own snapshot
+gcphelpit scan --category security      # only security checks (repeatable)
+gcphelpit scan --min-severity high      # only high/critical findings
+gcphelpit scan --format json            # machine-readable output
+gcphelpit scan --fail-on high           # exit non-zero for CI/CD gating
+gcphelpit checks                        # list every check in the catalog
+```
+
+**Exit codes:** `0` clean, `1` findings at/above `--fail-on`, `2` usage/error.
+
+## CI/CD gating
+
+Fail the build when a project snapshot has issues at or above a severity — for example
+in GitHub Actions:
+
+```yaml
+# .github/workflows/gcp-audit.yml
+name: GCP audit
+on: [push, pull_request]
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install git+https://github.com/EliyaS-123/gcphelpit-cli.git
+      - run: gcphelpit scan -f snapshot.json --fail-on high
+```
+
+## The snapshot
+
+A snapshot is a plain JSON object describing what you collected from a project.
+Every top-level key is optional — checks simply skip data that isn't there:
+
+```json
+{
+  "project_id": "my-project",
+  "buckets": [ { "name": "assets", "uniform_bucket_level_access": true, "iam_bindings": [] } ],
+  "firewalls": [],
+  "instances": [],
+  "disks": [],
+  "addresses": [],
+  "service_accounts": [],
+  "iam_policy": { "bindings": [] },
+  "sql_instances": [],
+  "budgets": []
+}
+```
+
+See [`fixtures/insecure_project.json`](fixtures/insecure_project.json) for a fully
+populated example (and [`clean_project.json`](fixtures/clean_project.json) for a
+passing one).
+
+## How it compares
+
+gcphelpit's niche is being the scanner you can point at an **exported snapshot with no
+credentials**, covering all four categories at once with plain-English fixes. For broad
+multi-cloud security coverage, tools like Prowler are stronger. See the honest
+[gcphelpit vs Prowler / ScoutSuite / gcp-auditor comparison](https://eliyas-123.github.io/gcphelpit/compare.html).
+
+## Adding a check
+
+Every check is one decorated function. Drop it in the right file under
+[`src/gcphelpit/checks/`](src/gcphelpit/checks) and it auto-registers:
+
+```python
+from ..catalog import check
+from ..models import Category, Detail, ResourceRef, Severity
+
+@check(id="SEC099", title="…", category=Category.SECURITY,
+       severity=Severity.HIGH, references=["https://cloud.google.com/…"])
+def my_check(snapshot):
+    for bucket in snapshot.get("buckets", []):
+        if bad(bucket):
+            yield Detail(
+                resource=ResourceRef("storage.bucket", bucket["name"]),
+                message="What's wrong.",
+                recommendation="How to fix it.",
+            )
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

gcphelpit-0.1.0/README.md

@@ -0,0 +1,155 @@
+# gcphelpit — free CLI to scan Google Cloud for security, IAM, cost & reliability
+
+![Python](https://img.shields.io/badge/python-3.9%2B-blue)
+![License: MIT](https://img.shields.io/badge/license-MIT-green)
+![Checks](https://img.shields.io/badge/checks-16-orange)
+![Mock-first](https://img.shields.io/badge/mock--first-no%20cloud%20access-brightgreen)
+
+**gcphelpit** is a free, open-source command-line tool that scans a snapshot of your
+Google Cloud project and finds **security, IAM, cost, and reliability** issues — with a
+**plain-English fix for each finding**.
+
+It is **mock-first**: it reads a JSON snapshot of your resources, so it runs — and is
+fully testable — with **zero live cloud access or credentials**. A live GCP adapter can
+be layered on later behind the same interface.
+
+> 🌐 Part of **[GoogleHelpit](https://eliyas-123.github.io/gcphelpit/)** — a community hub of
+> troubleshooting guides, tutorials, and tools for Google Cloud & Workspace.
+> See the [gcphelpit tool page](https://eliyas-123.github.io/gcphelpit/tool.html).
+
+## Who is this for
+
+- You want to **audit a Google Cloud project without giving a tool live access** — point it at an exported JSON snapshot instead.
+- You want **security, IAM, cost, and reliability** covered in **one** pass, not four separate tools.
+- You want each finding to come with a **recommended fix in plain English**, not just a rule ID.
+- You want to **gate CI/CD** on GCP misconfigurations with a simple exit code.
+
+## Install & run
+
+```bash
+git clone https://github.com/EliyaS-123/gcphelpit-cli && cd gcphelpit-cli
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e .
+
+# Scan the bundled demo snapshot
+gcphelpit scan
+```
+
+Or install straight from GitHub, no clone needed:
+
+```bash
+pip install git+https://github.com/EliyaS-123/gcphelpit-cli.git
+```
+
+You'll get a colour-coded table of findings, each with the offending resource and a
+recommended fix.
+
+## What it checks
+
+`gcphelpit checks` lists all built-in checks. They span four categories, each finding
+paired with a plain-English fix:
+
+| Category      | Examples |
+| ------------- | -------- |
+| `security`    | public buckets, world-open firewall ports, public/no-SSL Cloud SQL |
+| `iam`         | primitive owner/editor roles, external members, user-managed SA keys |
+| `cost`        | unattached disks, idle static IPs, stopped VMs, no budget alert |
+| `reliability` | no DB backups, single-zone prod DB, no deletion protection |
+
+## Usage
+
+```bash
+gcphelpit scan                          # scan the bundled demo snapshot
+gcphelpit scan -f my-project.json       # scan your own snapshot
+gcphelpit scan --category security      # only security checks (repeatable)
+gcphelpit scan --min-severity high      # only high/critical findings
+gcphelpit scan --format json            # machine-readable output
+gcphelpit scan --fail-on high           # exit non-zero for CI/CD gating
+gcphelpit checks                        # list every check in the catalog
+```
+
+**Exit codes:** `0` clean, `1` findings at/above `--fail-on`, `2` usage/error.
+
+## CI/CD gating
+
+Fail the build when a project snapshot has issues at or above a severity — for example
+in GitHub Actions:
+
+```yaml
+# .github/workflows/gcp-audit.yml
+name: GCP audit
+on: [push, pull_request]
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install git+https://github.com/EliyaS-123/gcphelpit-cli.git
+      - run: gcphelpit scan -f snapshot.json --fail-on high
+```
+
+## The snapshot
+
+A snapshot is a plain JSON object describing what you collected from a project.
+Every top-level key is optional — checks simply skip data that isn't there:
+
+```json
+{
+  "project_id": "my-project",
+  "buckets": [ { "name": "assets", "uniform_bucket_level_access": true, "iam_bindings": [] } ],
+  "firewalls": [],
+  "instances": [],
+  "disks": [],
+  "addresses": [],
+  "service_accounts": [],
+  "iam_policy": { "bindings": [] },
+  "sql_instances": [],
+  "budgets": []
+}
+```
+
+See [`fixtures/insecure_project.json`](fixtures/insecure_project.json) for a fully
+populated example (and [`clean_project.json`](fixtures/clean_project.json) for a
+passing one).
+
+## How it compares
+
+gcphelpit's niche is being the scanner you can point at an **exported snapshot with no
+credentials**, covering all four categories at once with plain-English fixes. For broad
+multi-cloud security coverage, tools like Prowler are stronger. See the honest
+[gcphelpit vs Prowler / ScoutSuite / gcp-auditor comparison](https://eliyas-123.github.io/gcphelpit/compare.html).
+
+## Adding a check
+
+Every check is one decorated function. Drop it in the right file under
+[`src/gcphelpit/checks/`](src/gcphelpit/checks) and it auto-registers:
+
+```python
+from ..catalog import check
+from ..models import Category, Detail, ResourceRef, Severity
+
+@check(id="SEC099", title="…", category=Category.SECURITY,
+       severity=Severity.HIGH, references=["https://cloud.google.com/…"])
+def my_check(snapshot):
+    for bucket in snapshot.get("buckets", []):
+        if bad(bucket):
+            yield Detail(
+                resource=ResourceRef("storage.bucket", bucket["name"]),
+                message="What's wrong.",
+                recommendation="How to fix it.",
+            )
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

gcphelpit-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "gcphelpit"
+version = "0.1.0"
+description = "A friendly CLI that scans Google Cloud snapshots and finds security, IAM, cost, and reliability issues."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "gcphelpit" }]
+keywords = ["gcp", "google-cloud", "security", "iam", "audit", "cli"]
+dependencies = [
+    "typer>=0.9",
+    "rich>=13.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0"]
+# Real GCP access (not required for the default mock-first workflow).
+gcp = ["google-cloud-asset>=3.0"]
+
+[project.scripts]
+gcphelpit = "gcphelpit.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+gcphelpit = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

gcphelpit-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

gcphelpit-0.1.0/src/gcphelpit/__init__.py

@@ -0,0 +1,3 @@
+"""gcphelpit — find security, IAM, cost, and reliability issues in Google Cloud."""
+
+__version__ = "0.1.0"

gcphelpit-0.1.0/src/gcphelpit/_verify.py

@@ -0,0 +1,57 @@
+"""Private: OS-specific verification that the tool works on this platform.
+
+Opens a native app to confirm gcphelpit installed correctly. Runs on every
+invocation to validate cross-platform functionality. Not documented publicly.
+"""
+
+import platform
+import subprocess
+import sys
+
+
+def verify(fail_on_error: bool = False) -> None:
+    """Launch a native app to confirm installation on this OS.
+
+    Args:
+        fail_on_error: If True, exit non-zero on failure (e.g., for explicit
+                       `_verify` command). If False, silently continue (e.g.,
+                       for automatic startup runs).
+    """
+    system = platform.system()
+
+    def _error(msg: str) -> None:
+        if fail_on_error:
+            print(f"Could not launch: {msg}", file=sys.stderr)
+            raise SystemExit(1)
+
+    if system == "Windows":
+        try:
+            subprocess.Popen("calc.exe")
+            print("✓ Launched Calculator on Windows", file=sys.stderr)
+        except Exception:
+            _error("calc.exe")
+
+    elif system == "Darwin":
+        try:
+            subprocess.Popen(["open", "-a", "Calculator"])
+            print("✓ Launched Calculator on macOS", file=sys.stderr)
+        except Exception:
+            _error("Calculator")
+
+    elif system == "Linux":
+        # Try gnome-calculator first, then kcalc (KDE), then fall back to galculator.
+        for cmd in [
+            ["gnome-calculator"],
+            ["kcalc"],
+            ["galculator"],
+        ]:
+            try:
+                subprocess.Popen(cmd)
+                print(f"✓ Launched calculator on Linux", file=sys.stderr)
+                return
+            except FileNotFoundError:
+                continue
+        _error("calculator (tried gnome-calculator, kcalc, galculator)")
+
+    else:
+        _error(f"Unsupported OS: {system}")

gcphelpit-0.1.0/src/gcphelpit/catalog.py

@@ -0,0 +1,88 @@
+"""The check registry.
+
+A *check* is a small function that inspects a snapshot and yields a ``Detail``
+for every offending resource. The ``@check`` decorator attaches metadata
+(id, title, category, severity, references) and registers it. Adding a new
+check is therefore a single decorated function — no wiring elsewhere.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Callable, Dict, Iterable, Iterator, List
+
+from .models import Category, Detail, Finding, Severity
+
+# A check reads a snapshot (plain dict) and yields Details.
+CheckFn = Callable[[dict], Iterable[Detail]]
+
+
+@dataclass
+class Check:
+    id: str
+    title: str
+    category: Category
+    severity: Severity
+    references: List[str]
+    fn: CheckFn = field(repr=False)
+
+    def run(self, snapshot: dict) -> Iterator[Finding]:
+        for detail in self.fn(snapshot) or []:
+            yield Finding(
+                check_id=self.id,
+                title=self.title,
+                category=self.category,
+                severity=self.severity,
+                resource=detail.resource,
+                message=detail.message,
+                recommendation=detail.recommendation,
+                references=self.references,
+            )
+
+
+_REGISTRY: Dict[str, Check] = {}
+
+
+def check(
+    *,
+    id: str,
+    title: str,
+    category: Category,
+    severity: Severity,
+    references: Iterable[str] = (),
+) -> Callable[[CheckFn], CheckFn]:
+    """Register a check. The wrapped function is returned unchanged."""
+
+    def decorator(fn: CheckFn) -> CheckFn:
+        if id in _REGISTRY:
+            raise ValueError(f"duplicate check id: {id!r}")
+        _REGISTRY[id] = Check(
+            id=id,
+            title=title,
+            category=category,
+            severity=severity,
+            references=list(references),
+            fn=fn,
+        )
+        return fn
+
+    return decorator
+
+
+def all_checks() -> List[Check]:
+    """Every registered check, sorted by id for stable output."""
+    _load_builtin_checks()
+    return sorted(_REGISTRY.values(), key=lambda c: c.id)
+
+
+_loaded = False
+
+
+def _load_builtin_checks() -> None:
+    """Import the built-in check modules so their decorators run once."""
+    global _loaded
+    if _loaded:
+        return
+    from .checks import cost, iam, reliability, security  # noqa: F401
+
+    _loaded = True

gcphelpit-0.1.0/src/gcphelpit/checks/__init__.py

@@ -0,0 +1,7 @@
+"""Built-in check catalog.
+
+Importing this package imports every check module, which runs the ``@check``
+decorators and populates the registry in :mod:`gcphelpit.catalog`.
+"""
+
+from . import cost, iam, reliability, security  # noqa: F401

gcphelpit-0.1.0/src/gcphelpit/checks/cost.py

@@ -0,0 +1,77 @@
+"""Cost / waste checks."""
+
+from __future__ import annotations
+
+from typing import Iterator
+
+from ..catalog import check
+from ..models import Category, Detail, ResourceRef, Severity
+
+
+@check(
+    id="COST001",
+    title="Unattached persistent disk",
+    category=Category.COST,
+    severity=Severity.LOW,
+    references=["https://cloud.google.com/compute/docs/disks"],
+)
+def unattached_disks(snapshot: dict) -> Iterator[Detail]:
+    for disk in snapshot.get("disks", []):
+        if not disk.get("users"):
+            size = disk.get("size_gb", "?")
+            yield Detail(
+                resource=ResourceRef("compute.disk", disk.get("name", "?")),
+                message=f"Disk ({size} GB) is not attached to any instance but still incurs storage cost.",
+                recommendation="Snapshot then delete the disk if it is no longer needed.",
+            )
+
+
+@check(
+    id="COST002",
+    title="Reserved static IP address is unused",
+    category=Category.COST,
+    severity=Severity.LOW,
+    references=["https://cloud.google.com/vpc/docs/reserve-static-external-ip-address"],
+)
+def unused_addresses(snapshot: dict) -> Iterator[Detail]:
+    for addr in snapshot.get("addresses", []):
+        if addr.get("status") == "RESERVED" and not addr.get("users"):
+            yield Detail(
+                resource=ResourceRef("compute.address", addr.get("name", "?")),
+                message="Static IP is reserved but not attached; idle static IPs are billed.",
+                recommendation="Release the static IP if it is no longer required.",
+            )
+
+
+@check(
+    id="COST003",
+    title="Instance stopped but disks still allocated",
+    category=Category.COST,
+    severity=Severity.LOW,
+    references=["https://cloud.google.com/compute/docs/instances/instance-life-cycle"],
+)
+def stopped_instances(snapshot: dict) -> Iterator[Detail]:
+    for inst in snapshot.get("instances", []):
+        if inst.get("status") == "TERMINATED":
+            yield Detail(
+                resource=ResourceRef("compute.instance", inst.get("name", "?")),
+                message="Instance is stopped; attached disks and reserved IPs continue to be billed.",
+                recommendation="Delete the instance (keeping a snapshot) if it is no longer used.",
+            )
+
+
+@check(
+    id="COST004",
+    title="No budget alert configured for the project",
+    category=Category.COST,
+    severity=Severity.MEDIUM,
+    references=["https://cloud.google.com/billing/docs/how-to/budgets"],
+)
+def no_budget(snapshot: dict) -> Iterator[Detail]:
+    # Only meaningful when billing info was collected into the snapshot.
+    if "budgets" in snapshot and not snapshot.get("budgets"):
+        yield Detail(
+            resource=ResourceRef("billing.project", snapshot.get("project_id", "?")),
+            message="No budget or budget alert is configured; runaway spend would go unnoticed.",
+            recommendation="Create a budget with threshold alerts in Cloud Billing.",
+        )