Add security-assessment skill docs and custom IAM role

PERMISSIONS.md

@@ -0,0 +1,122 @@
+# 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`.
+*   `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
+
+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`.

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.

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