# 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.