From dd71c6c5d5926cd02033ce877bcf49c4d2248f5f Mon Sep 17 00:00:00 2001 From: Vikram Ruppa-Kasani Date: Wed, 3 Jun 2026 16:18:33 -0700 Subject: [PATCH 1/2] Add security-assessment skill docs and custom IAM role --- PERMISSIONS.md | 119 ++++++++++++++++++++ README.md | 173 +++++++++++++++++++++++++++++- gcs-security-assessment-role.yaml | 19 ++++ 3 files changed, 309 insertions(+), 2 deletions(-) create mode 100644 PERMISSIONS.md create mode 100644 gcs-security-assessment-role.yaml diff --git a/PERMISSIONS.md b/PERMISSIONS.md new file mode 100644 index 0000000..d7983a1 --- /dev/null +++ b/PERMISSIONS.md @@ -0,0 +1,119 @@ +# GCS Skills Permissions Guide + +This guide documents the Google Cloud IAM permissions used by the skills in this +repository. All access is **read-only**—the skills never mutate your resources. +More skills (and their permission requirements) will be added here over time. + +## Security Assessment Skill + +The Security Assessment skill performs a **read-only** security posture +assessment of Google Cloud Storage projects and buckets. It reads bucket and +object state via Storage Insights → BigQuery and gathers project-level posture +via REST. It never mutates target resources. + +### Required + +The skill requires an authenticated gcloud session. Run **both**: + +```bash +gcloud auth login +gcloud auth application-default login +``` + +* **`gcloud auth application-default login`** is required — the skill's + scripts use Application Default Credentials (ADC) to generate access tokens + for GCP API calls (the preflight `adc` check). +* **`gcloud auth login`** is required for the agent to run `gcloud` commands + during the assessment. + +These are authentication requirements, not specific IAM permissions. Any +authenticated identity can run the skill; with no roles it still runs, but every +signal it cannot read is reported as `UNKNOWN`. There is no IAM permission in +the required tier. + +### Recommended Permissions + +Grant the read-only roles below for a complete assessment. All permissions are +read-only. + +> [!IMPORTANT] +> **Permission scope:** Most permissions are granted at the +> **project** level, but three are **organization-scoped** and must be granted +> at the org level: `accesscontextmanager.policies.list`, +> `accesscontextmanager.servicePerimeters.list`, and +> `resourcemanager.folders.get`. Without an org-level grant, VPC Service +> Controls and org-hierarchy checks report `UNKNOWN`. The +> [custom role](#recommended-bundle-into-one-custom-role) below shows how to +> grant these at the org level. + +#### Group A — Full bucket & object assessment (Storage Insights telemetry) + +Without these, the assessment degrades to project-level only. + +Permission | Purpose | Read-only role +:------------------------------------ | :------------------------------------ | :------------- +`storageinsights.datasetConfigs.list` | Discover/validate SI dataset configs | `roles/storageinsights.viewer` +`bigquery.datasets.get` | Read the linked SI BigQuery dataset | `roles/bigquery.dataViewer` +`bigquery.tables.getData` | Read the SI telemetry view/table data | `roles/bigquery.dataViewer` +`bigquery.jobs.create` | Run the read-only telemetry query job | `roles/bigquery.jobUser` + +#### Group B — Project-level posture + +Used by the project posture evaluation. A missing permission marks that signal +`UNKNOWN`; the assessment continues. + +Permission | Purpose | Read-only role +:-------------------------------------------- | :------------------------------------------------------- | :------------- +`resourcemanager.projects.get` | Resolve project number/parent | `roles/browser` +`resourcemanager.folders.get` | Traverse folder hierarchy to resolve org ID (for VPC-SC) | `roles/browser` +`resourcemanager.projects.getIamPolicy` | Read Data Access audit-log config | `roles/iam.securityReviewer` +`orgpolicy.policy.get` | Read effective org policies (location/TLS/HTTP/HMAC) | `roles/orgpolicy.policyViewer` +`accesscontextmanager.policies.list` | Find the org's access policy | `roles/accesscontextmanager.policyReader` +`accesscontextmanager.servicePerimeters.list` | Check if project is in a VPC-SC perimeter | `roles/accesscontextmanager.policyReader` +`modelarmor.floorSettings.get` | Read Model Armor floor settings | `roles/modelarmor.floorSettingsViewer` +`modelarmor.templates.list` | Enumerate Model Armor templates | `roles/modelarmor.viewer` +`serviceusage.services.use` | Use a quota project for API requests | `roles/serviceusage.serviceUsageConsumer` + +#### Notes + +* `bigquery.jobs.create` looks like a write but only creates a **read-only** + query job. There is no read-only alternative for querying the Storage + Insights views. +* `accesscontextmanager.*` is evaluated at the **organization** level. Grant + it there, or VPC Service Controls will report `UNKNOWN`. + +### Recommended: Bundle into One Custom Role + +Rather than granting individual roles, we recommend defining a single read-only +custom role from +[`gcs-security-assessment-role.yaml`](./gcs-security-assessment-role.yaml). + +Create the role at the **organization** level so the VPC-SC checks resolve: + +```bash +gcloud iam roles create gcsSecurityAssessmentReader \ + --organization=ORG_ID --file=gcs-security-assessment-role.yaml +``` + +Grant it on the **project** (telemetry, IAM/audit, org policy, Model Armor, +quota project): + +```bash +gcloud projects add-iam-policy-binding PROJECT_ID \ + --member="user:ASSESSOR@EXAMPLE.COM" \ + --role="organizations/ORG_ID/roles/gcsSecurityAssessmentReader" +``` + +Also grant it on the **organization** (VPC-SC access policies are org-scoped): + +```bash +gcloud organizations add-iam-policy-binding ORG_ID \ + --member="user:ASSESSOR@EXAMPLE.COM" \ + --role="organizations/ORG_ID/roles/gcsSecurityAssessmentReader" +``` + +**Scope caveat:** a project-only grant works for everything except the +org-scoped permissions noted above. If org-level access isn't available, drop +the `accesscontextmanager.*` and `resourcemanager.folders.get` lines and create +the role with `--project=PROJECT_ID`; VPC Service Controls and org-hierarchy +checks will then report `UNKNOWN`. diff --git a/README.md b/README.md index e76f0b2..5691b56 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,172 @@ -# Google Cloud Storage Extension +# Google Cloud Storage Skills -> Documentation is being updated. Content coming soon. +[![Install via skills.sh](https://img.shields.io/badge/skills.sh-install-green)](https://skills.sh/gemini-cli-extensions/google-cloud-storage) + +This repository contains [Agent Skills](https://agentskills.io/home) for +[Google Cloud Storage](https://cloud.google.com/storage). These skills deliver +vetted GCS expertise directly into your coding agent, letting you use natural +language prompts in your preferred CLI or IDE to work with your storage +resources. + +> [!NOTE] +> This repository is under active development. More skills will be added +> over time. + +> [!IMPORTANT] +> **We Want Your Feedback!** Please share your thoughts with us by +> opening an issue on +> [GitHub](https://github.com/gemini-cli-extensions/google-cloud-storage/issues). +> Your input is invaluable and helps us improve the project for everyone. + +## Contents + +- [Installation](#installation) +- [Available Skills](#available-skills) +- [Prerequisites](#prerequisites) +- [Security Assessment Skill](#security-assessment-skill) + - [Required Permissions](#required-permissions) + - [Authentication](#authentication) + - [Usage Examples](#usage-examples) +- [Security Reminder: Agent Environment Hardening](#security-reminder-agent-environment-hardening) +- [Support](#support) +- [Contributing](#contributing) +- [License](#license) + +## Installation + +```bash +npx skills add gemini-cli-extensions/google-cloud-storage +``` + +From the `npx` install command, you can select the specific skills from this +repo to install. The skills work with any compatible coding agent, including +Gemini CLI, Claude Code, Codex, and Antigravity CLI. + +## Available Skills + +- [**Security Assessment**](#security-assessment-skill) — Assesses the + security posture of Google Cloud Storage projects and buckets, identifying + toxic combinations of vulnerabilities and checking SAIF compliance. + +## Prerequisites + +Ensure you have the following: + +* **A Google Cloud project** with the resources you want to work with. +* **Google Cloud SDK (gcloud CLI):** + [Install and initialize](https://cloud.google.com/sdk/docs/install) the + gcloud CLI and ensure + [Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/provide-credentials-adc) + are configured. +* **A compatible coding agent**, such as Gemini CLI, Claude Code, Codex, or + Antigravity CLI. + +## Security Assessment Skill + +The Security Assessment skill is grounded in Google's +[Secure AI Framework (SAIF)](https://saif.google/secure-ai-framework/saif-map). +Rather than emitting isolated static alerts, it correlates real telemetry +signals gathered from your project to surface **toxic combinations** of +vulnerabilities—scenarios where individually low-risk configurations combine to +create a critical exposure—and provides actionable, verified remediation. + +> [!TIP] +> For the best analysis, we highly recommend being a +> [Storage Intelligence](https://docs.cloud.google.com/storage/docs/storage-intelligence/overview) +> customer. When Storage Intelligence is enabled, the skill can query your +> Storage Insights datasets to perform deep, bucket-level and object-level +> assessments. Without it, the skill falls back to a project-level assessment +> only. + +### Required Permissions + +The only hard requirement is working **Application Default Credentials** (see +[Authentication](#authentication)). There is no required IAM permission—any +authenticated identity can run the skill, though signals it cannot read are +reported as `UNKNOWN`. + +For a complete assessment, grant the recommended **read-only** roles covering +Storage Insights telemetry (bucket/object analysis) and project-level posture +(IAM and audit config, org policies, VPC Service Controls, and Model Armor). See +**[PERMISSIONS.md](./PERMISSIONS.md)** for the full permission tables and a +ready-to-apply custom IAM role +([`gcs-security-assessment-role.yaml`](./gcs-security-assessment-role.yaml)). + +### Authentication + +Before running an assessment, authenticate with Google Cloud so the agent can +read your project telemetry and run any remediation you approve. It is +recommended to run **both** of the following commands: + +```bash +gcloud auth login +gcloud auth application-default login +``` + +* **`gcloud auth application-default login`** is **required**: the skill's + scripts use Application Default Credentials (ADC) to generate access tokens + for GCP API calls. +* **`gcloud auth login`** allows the agent (or you) to run standard `gcloud` + commands to explore configurations or dig deeper into specific resources + beyond what the skill scripts cover. + +### Usage Examples + +Interact with your coding agent using natural language: + +* **Assess an entire project:** `Assess the security posture of project + [PROJECT_ID]` +* **Assess a specific subset of buckets:** `Assess the security posture of + buckets [BUCKET_1], [BUCKET_2] in project [PROJECT_ID]` +* **Follow-up investigation:** After an assessment, ask the agent to drill + into a finding—for example, "Explain why the `ml-training-data` bucket is + flagged as a toxic combination" or "Show me the exact command to remediate + the public access finding." + +The agent works through a fixed, auditable sequence of phases—discovering scope +and gathering telemetry, classifying buckets, evaluating baseline security, +analyzing toxic combinations, and producing a formatted report—so you can trace +every finding back to a signal it actually collected. + +## Security Reminder: Agent Environment Hardening + +Your agent can execute tools and commands on your behalf. Protect your Google +Cloud resources by enforcing **The Principle of Least Privilege** across all +CLIs, MCP servers and other resources available to your agents. + +* **Service Accounts:** Use + [service accounts](https://docs.cloud.google.com/docs/authentication/use-service-account-impersonation) + instead of end user credentials to access Google Cloud resources. +* **Limited Permissions:** Assign roles with + [limited permissions](https://docs.cloud.google.com/iam/docs/roles-overview) + to the service account that you're using for authentication. +* **Principal Access Boundaries:** Prevent unwanted cross-org agent access by + using + [Principal Access Boundary policies](https://docs.cloud.google.com/iam/docs/principal-access-boundary-policies#use-case-one-project) + to scope your agent to projects you intend it to access. +* [Include a condition in the policy binding](https://docs.cloud.google.com/iam/docs/principal-access-boundary-policies#use-case-one-project) + to ensure that the policy only applies to the service accounts that you + intend to restrict. + +You can read more +[here](https://docs.cloud.google.com/data-cloud-extension/vs-code/prompt-injection-risk) +on how to mitigate prompt injection attacks with Google Cloud MCP. + +## Support + +If you need help or encounter issues with these skills, search for existing +issues or open a new one in the +[GitHub Issue Tracker](https://github.com/gemini-cli-extensions/google-cloud-storage/issues). + +## Contributing + +We welcome contributions to improve these skills. You can help by: + +* [Reporting bugs or inaccuracies](https://github.com/gemini-cli-extensions/google-cloud-storage/issues) + in the skill files. +* Suggesting new skills to add to this repository by filing a feature request. + +## License + +You are free to copy, modify, and distribute these skills under the terms of the +Apache 2.0 license. See the `LICENSE` file for details. diff --git a/gcs-security-assessment-role.yaml b/gcs-security-assessment-role.yaml new file mode 100644 index 0000000..20d74b9 --- /dev/null +++ b/gcs-security-assessment-role.yaml @@ -0,0 +1,19 @@ +title: "GCS Security Assessment (Read-Only)" +description: "Read-only access for the GCS security-assessment skill." +stage: "GA" +includedPermissions: + # Bucket & object assessment (Storage Insights telemetry) + - storageinsights.datasetConfigs.list + - bigquery.datasets.get + - bigquery.tables.getData + - bigquery.jobs.create + # Project-level posture + - resourcemanager.projects.get + - resourcemanager.folders.get + - resourcemanager.projects.getIamPolicy + - orgpolicy.policy.get + - accesscontextmanager.policies.list + - accesscontextmanager.servicePerimeters.list + - modelarmor.floorSettings.get + - modelarmor.templates.list + - serviceusage.services.use From 63a047c8cea76b363b49594d88af8dc72436c591 Mon Sep 17 00:00:00 2001 From: Vikram Ruppa-Kasani Date: Wed, 3 Jun 2026 16:30:35 -0700 Subject: [PATCH 2/2] Add note on serviceusage.services.use scope --- PERMISSIONS.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/PERMISSIONS.md b/PERMISSIONS.md index d7983a1..97b2f01 100644 --- a/PERMISSIONS.md +++ b/PERMISSIONS.md @@ -81,6 +81,9 @@ Permission | Purpose Insights views. * `accesscontextmanager.*` is evaluated at the **organization** level. Grant it there, or VPC Service Controls will report `UNKNOWN`. +* `serviceusage.services.use` is a very broad permission that allows the + principal to use services/quota for any project in the org. Consider adding + this directly to the allowed project. ### Recommended: Bundle into One Custom Role