# Connector Instructions

## GCP Connector Instructions

### Custom Instructions

#### Required Permissions

**User Executing The Script:**

* Create Service Accounts (Role)
* Service Account Key Admin (Role)

**Script Permissions:**

* Reader (Project Level for all Projects)

### Manual Instructions

1. Log in to your GCP Console.
2. Select a Google Cloud Project.
3. Navigate to `IAM & Admin → Service Account → Create Service Account → Create and Continue`.
4. Grant the Service Account the `Viewer` Role and click `Done`.
5. Copy the new service account email.
6. Click the three-dot menu for the new service account and select `Manage Keys`.
7. In the **Service Account keys** screen:
   * Click `Add Key → Create New Key → Create`.
   * Save the Service Account JSON file.
8. Note down the value of `project_id` in the JSON.
9. Encode the JSON object to Base64 and note down the value.
10. In the OX Connector, enter the `project_id` and encoded JSON object.
11. Click `Connect`.

> You should receive a message that the connection was successful. If not, please repeat the steps above or contact support.

***

### Adding Multiple Projects for the Same Token

#### Step 1: Copy the Service Account Email

* Navigate to the main project (the one already selected for scan) in Google Cloud Console.
* Go to `Service Accounts` and copy the service account email.

#### Step 2: Grant Access to Multiple Projects

**For the Main Project:**

1. Navigate to `IAM & Admin → IAM`.
2. Click on `Grant Access`.
3. Add the copied Service Account email as a Participant.
4. Assign the `Viewer` Role and click `Save`.

**For Additional Projects:**

1. Navigate to the target project’s `IAM & Admin → IAM`.
2. Click on `Grant Access`.
3. Add the same copied Service Account email as a Participant.
4. Assign the `Viewer` Role and click `Save`.

> Repeat this process for each additional project.

## GCP and GKE Connector Integration Guide

OX Security supports integrations with both **GCP (Google Cloud Platform)** and **GKE (Google Kubernetes Engine)** to enhance visibility into your cloud and Kubernetes environments.

* The **GCP Connector** is primarily used to run **Prowler** for cloud misconfiguration scanning at the project level.
* The **GKE Connector** is used to ingest **Kubernetes workload data** into OX's **Cloud Graph**, helping visualize how code travels through the CI/CD pipeline into production and identify attack paths.

These connectors are independent—unlike Azure or AWS integrations, there's no dependency between the GCP and GKE connectors. Both require the same setup: a **GCP project ID** and an **API token (service account credentials)**.

***

### Prerequisites

* A GCP project with IAM permissions to:
  * Create service accounts
  * Manage service account keys
* Optional: `gcloud` CLI installed and configured
* (For GKE only) A running GKE cluster in the selected GCP project, with Kubernetes API enabled

***

### Step-by-Step Instructions

#### 1. Create a Service Account

1. Log in to the [Google Cloud Console](https://console.cloud.google.com)
2. Select your GCP project.
3. Navigate to `IAM & Admin → Service Accounts`.
4. Click **Create Service Account**.
5. Enter a descriptive name (e.g., `ox-gcp-connector-sa`) and an optional description.
6. Click **Create and Continue**.

#### 2. Assign Roles

Grant the following roles to the new service account:

* `Viewer`
* `Service Account Key Admin`
* `Service Account Creator` *(if your user account lacks permission)*

Click **Done** to complete the process.

#### 3. Generate Service Account Key

1. In the Service Accounts list, find your newly created account.
2. Click the three-dot menu → **Manage Keys**.
3. Click **Add Key → Create New Key**.
4. Choose **JSON** format and click **Create**.
5. Download and securely store the JSON key file.

***

#### 4. Collect Required Values

From the downloaded JSON key file:

* Copy the value of `project_id`
* Encode the entire JSON file contents as a Base64 string

These two values are required in OX:

* `project_id`
* `encoded_credentials` (Base64-encoded JSON)

***

#### 5. Connect in OX Security

1. In OX, go to the **Connectors** page.
2. Select **GCP** or **GKE**, depending on your target.
3. Enter:
   * `project_id`
   * Base64-encoded JSON credentials
4. Click **Connect**

You should receive a success confirmation. If not, double-check the steps or contact OX support.

***

### Optional: Add Access to Multiple GCP Projects

To use the same service account across multiple GCP projects:

1. Open the **IAM & Admin → IAM** section in each additional project.
2. Click **Grant Access**.
3. Add the same service account email.
4. Assign the **Viewer** role.
5. Click **Save**.

Repeat this process for each project you want to include.

***

### Connector Use Cases

| Connector | Purpose                                                       | Dependency |
| --------- | ------------------------------------------------------------- | ---------- |
| **GCP**   | Cloud configuration scanning using **Prowler**                | Standalone |
| **GKE**   | Workload visibility and deployment mapping in **Cloud Graph** | Standalone |

Both connectors provide data that enriches **OX Security’s attack path analysis**, helping link code commits to live workloads and identify misconfigurations or public exposures across environments.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ox.security/connector-instructions.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.