# Setting Up a Cloud Connected Panther Instance ## Overview To provision a [Cloud Connected](https://docs.panther.com/system-configuration/panther-deployment-types/cloud-connected) Panther instance, you will use the `panther-cloud-connected-setup` CLI tool, in addition to taking manual steps. Cloud Connected Panther instances are deployed in AWS and either Snowflake or Databricks. Read about the CLI tool below, then begin the setup process. {% hint style="info" %} The instructions on this page are for setting up a *new* Cloud Connected deployment. If you would like to convert an existing [Panther-hosted (SaaS)](https://docs.panther.com/system-configuration/panther-deployment-types/..#saas) instance to a Cloud Connected deployment, do not follow these steps; instead, reach out to your Panther Support team to initiate the conversion. {% endhint %} ## The `panther-cloud-connected-setup` tool Part of setting up a Cloud Connected Panther instance is running the [`panther-cloud-connected-setup` CLI tool](https://github.com/panther-labs/panther-cli). The tool performs all its operations from your local machine or within your AWS, Snowflake, or Databricks accounts, and does not share any credentials or information with Panther. ### What the tool does Running this tool: * Within your AWS account: * Deploys the `PantherDeploymentRole` IAM role * Installs the `PantherDeploymentUpdaterRole`, which keeps your `PantherDeploymentRole` up-to-date * Deploys and executes the `PantherReadinessCheck` pre-deployment tool, which verifies that you are unlikely to encounter deployment issues * Registers for SSL certificates for the following subdomains, based on the root domain you provide: * `.yourdomain.com` * `*..yourdomain.com` * (Optional) Creates DNS validation records in Route 53 for certificate validation * (If using Snowflake) Provisions Snowflake credentials in your AWS environment, using: * (Recommended) A Snowflake account and admin user Panther creates on your behalf * (Not recommended) An already created (empty) Snowflake account and admin user you provide, created according to the [instructions below](#snowflake-prerequisites). This path may appeal to you if you're unable to allow the `panther-cloud-connected-setup` tool to use a Snowflake user with the [GLOBALORGADMIN role](https://docs.snowflake.com/en/user-guide/organization-administrators#label-org-admins-globalorgadmin). (This user's credentials are never shared with Panther.) {% hint style="info" %} If you're using Databricks as your data store, the CLI tool does not perform any actions in Databricks. {% endhint %} ### How the tool stores state The `panther-cloud-connected-setup` tool stores state in the `panther-cli-state.db` file. If the tool does not successfully provision a Panther instance on first run, this file makes re-runs simpler, as it tracks the steps that have already been successfully completed. {% hint style="warning" %} This file stores sensitive information. After successfully provisioning a Panther instance, it's recommended to run `./panther-cloud-connected-setup --clean` to purge the file, or delete the file from the disk. {% endhint %} ## How to set up a Cloud Connected Panther instance ### Prerequisites #### Tool installation prerequisite Before getting started, you must install the `panther-cloud-connected-setup` tool.
Operating systemInstallation instructions
macOS and Linux

Install the panther-cloud-connected-setup tool with Homebrew by running the following commands:

brew tap panther-labs/tap https://github.com/panther-labs/homebrew-taps.git
brew install panther-labs/tap/panther-cloud-connected-setup

The first command references Panther's own GitHub repository of Homebrew taps.

WindowsInstall the panther-cloud-connected-setup tool using a package from the panther-cli respository's Releases page.
To ensure that the tool is set up correctly, run: ```bash panther-cloud-connected-setup --clean ``` This command should produce an output similar to: ``` ~ ❯❯❯ panther-cloud-connected-setup --clean ✘ 255 2025/06/17 12:46:38 Successfully cleaned state ~ ❯❯❯ ``` #### AWS prerequisites * You have an [AWS organization](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_introduction.html). * You are able to authenticate with AWS (using one of the [methods described below](#authenticating-with-aws)) using either: * (Recommended) The AWS account [root user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-user.html) (or a different IAM user with comparable permissions). * An IAM user with at least the following permissions: * Ability to deploy [CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html) templates * Ability to create certificates in [AWS Certificate Manager (ACM)](https://docs.aws.amazon.com/acm/latest/userguide/acm-overview.html) * Ability to create and invoke [Lambdas](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html) * Ability to read/write to [Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) {% hint style="info" %} If your AWS organization has [service control policies (SCPs)](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_scps.html) and [Control Tower Guardrails](https://docs.aws.amazon.com/audit-manager/latest/userguide/controltower.html) policies at the organization level, it is recommended that you have the ability to update them or create exceptions. These policies may interfere with the CLI tool's actions and prevent successful provisioning. {% endhint %}
Authenticating with AWS The `panther-cloud-connected-setup` tool supports AWS authentication with both: * An explicitly defined AWS [access key ID and secret access key](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) (and optionally a [session token](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_use-resources.html)) in your `config.yml` file * Standard environmental configuration (i.e., environment variables or the `~/.aws/config` file) When attempting to authenticate with AWS, the tool will first look in the `config.yml` file for explicitly defined credentials (`AWSConfig.AccessKeyID` and `AWSConfig.SecretAccessKey`). If credentials are found in `config.yml`, it will use these credentials to authenticate. If no credentials are found in `config.yml`, it will attempt to load the AWS credentials from the environment using the standard resolution strategy in all AWS client libraries.
#### Other prerequisites * You have a custom domain registered. * If you need help registering a custom domain and would like to use AWS as your domain registrar, follow [this Amazon Route 53 documentation](https://aws.amazon.com/getting-started/hands-on/get-a-domain/). #### (If using Snowflake) Snowflake prerequisites * You have a [Snowflake organization](https://docs.snowflake.com/en/user-guide/organizations). * (To have the `panther-cloud-connected-setup` tool provision a Snowflake account and admin user for you, which is recommended) You have a Snowflake user that: * Has the [GLOBALORGADMIN role](https://docs.snowflake.com/en/user-guide/organization-administrators#label-org-admins-globalorgadmin) attached. * The [Snowflake documentation notes that the ORGADMIN role will be eliminated](https://docs.snowflake.com/en/user-guide/organization-administrators#using-the-orgadmin-role). Before that happens, you may use a user with the ORGADMIN role instead of GLOBALORGADMIN. * Uses RSA key-pair authentication. If you need to set up an RSA key-pair, follow the [Snowflake Configuring key-pair authentication instructions](https://docs.snowflake.com/en/user-guide/key-pair-auth#configuring-key-pair-authentication). * Has matching values for `NAME` and `LOGIN_NAME`. To verify this, run the following command in a [Snowflake worksheet](https://docs.snowflake.com/en/user-guide/ui-snowsight-worksheets-gs): ```sql DESC USER ; -- update the username here SELECT "property", "value" FROM TABLE(RESULT_SCAN(LAST_QUERY_ID())) WHERE "property" = 'NAME' OR "property" = 'LOGIN_NAME'; ``` * (If you will provide an already created Snowflake account and admin user, which is not recommended) You have an empty Snowflake account and admin user created according to the instructions below. * Certain Panther features require [Snowflake Enterprise](https://docs.snowflake.com/en/user-guide/intro-editions) or higher. [Learn more here](https://docs.panther.com/search/backend/snowflake/configuration#panther-features-requiring-snowflake-enterprise-or-higher).
(Not recommended) Manually creating a new Snowflake account and user for Panther {% hint style="warning" %} It is recommended to instead allow the panther-cloud-connected-setup tool provision the Snowflake account and user for you. {% endhint %} To create the Snowflake account and user manually: 1. In your Snowflake organization, create a new, dedicated Snowflake account for Panther using the template below. `` should be one of the [supported AWS regions](https://docs.panther.com/system-configuration/panther-deployment-types/..#supported-aws-regions) (and be the same AWS [region](https://docs.snowflake.com/en/user-guide/intro-regions) where your Panther instance will eventually be deployed).\ \ This command [creates an account](https://docs.snowflake.com/en/user-guide/organizations-manage-accounts-create) as well as the first user of the account, who is assigned the `ACCOUNTADMIN` role. This user will not be provided to Panther. See full syntax guidelines for the `CREATE ACCOUNT` command [here](https://docs.snowflake.com/en/sql-reference/sql/create-account). ```sql USE ROLE ORGADMIN; CREATE ACCOUNT // Your desired Panther account name ADMIN_NAME = // This should be something OTHER than 'pantheraccountadmin' ADMIN_USER_TYPE = PERSON ADMIN_PASSWORD = '' EMAIL = '' MUST_CHANGE_PASSWORD = FALSE EDITION = // STANDARD, ENTERPRISE, or BUSINESS_CRITICAL REGION = // The AWS region your Panther instance will eventually be deployed in COMMENT = 'Panther Snowflake Cloud Connected Production Environment'; ``` 2. Construct your Snowflake account URL with the following command: ```sql SELECT LOWER(CURRENT_ORGANIZATION_NAME() || '-' || CURRENT_ACCOUNT_NAME() || '.snowflakecomputing.com') AS account_url; ``` * The URL will be in this format: `-.snowflakecomputing.com` * Store this value in a secure location; you will need it in a later step of this process. 3. Generate an RSA keypair with the following command:\ `openssl genrsa 4096 | openssl pkcs8 -topk8 -inform PEM -out panther_rsa_key.p8 -nocrypt && openssl rsa -in panther_rsa_key.p8 -pubout -out panther_rsa_key.pub` * For additional guidance, see [Snowflake's Configuring key-pair authentication documentation](https://docs.snowflake.com/en/user-guide/key-pair-auth#configuring-key-pair-authentication). 4. Assign the RSA public key to the admin user you created in step 1: ```sql ALTER USER SET RSA_PUBLIC_KEY='...'; ```
#### (If using Databricks) Databricks prerequisites * See the [Prerequisites](https://docs.panther.com/system-configuration/panther-deployment-types/databricks#prerequisites) on [databricks](https://docs.panther.com/system-configuration/panther-deployment-types/cloud-connected/databricks "mention"). ### Step 1: Create a new AWS account * In your AWS organization, [create a new account](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_accounts_create.html), if needed. (It is also possible to use an existing empty one.) {% hint style="warning" %} Your Panther instance cannot be deployed in an AWS account with existing resources. {% endhint %} ### Step 2: Request values from Panther {% hint style="info" %} This step is only required if this is your first time setting up a Panther Cloud Connected instance. If you have done so before (e.g., if you manage multiple Panther instances), you can use previous values, as they do not change. {% endhint %} * Reach out to Panther support to notify them you are deploying a Cloud Connected instance and ask for values for `CloudFormationConfig.IdentityAccountId` and `CloudFormationConfig.OpsAccountId`. You will use these values in Step 3. ### Step 3: Fill out the configuration file 1. Create a configuration file locally by copying one of the following templates: * If you're using Snowflake: * If the `panther-cloud-connected-setup` tool should provision a Snowflake account and admin user for you: [example-config-new-snowflake-acct.yml](https://github.com/panther-labs/panther-cli/blob/main/example-config-new-snowflake-acct.yml) * If you will provide an already created, empty Snowflake account and admin user: [example-config-existing-snowflake-acct.yml](https://github.com/panther-labs/panther-cli/blob/main/example-config-existing-snowflake-acct.yml) * If you're using Databricks: [example-config-databricks.yml](https://github.com/panther-labs/panther-cli/blob/main/example-config-databricks.yml) 2. Update the keys' values, following the guidance in the template and taking note of the below: * When entering a value for `PantherAccountConfig.Region`, use one of the [supported AWS Panther regions](https://docs.panther.com/system-configuration/panther-deployment-types/..#supported-aws-regions). This region is where your Panther instance will be deployed. * (If you are using [example-config-new-snowflake-acct.yml](https://github.com/panther-labs/panther-cli/blob/main/example-config-new-snowflake-acct.yml)) When entering a value for `SnowflakeConfig.NewAccountConfig.SnowflakeEdition`, take note that certain Panther features require [Snowflake Enterprise](https://docs.snowflake.com/en/user-guide/intro-editions) or higher. [Learn more here](https://docs.panther.com/system-configuration/panther-deployment-types/cloud-connected/snowflake#panther-features-requiring-snowflake-enterprise-or-higher). * The `AutoRegisterValidationDomains` field allows the tool to create DNS records on your behalf to issue the required certificates. Setting this to `true` requires the AWS account used for your Panther deployment to also manage your Panther domain's DNS records. ### Step 4: Run the `panther-cloud-connected-setup` tool * Run the tool with the following command: ``` ./panther-cloud-connected-setup --config-file config.yml ``` * Additional flags that may be useful: * `--verbose`: Print verbose logging * `--snowflake-logging`: Print verbose Snowflake logging * `--force-check-certificates`: Force check certificates, even if already marked as issued {% hint style="info" %} Learn more about the tool in its [README.md](https://github.com/panther-labs/panther-cli/blob/main/README.md). {% endhint %} ### Step 5 (if necessary): Create DNS record(s) to validate certificate requests Running the `panther-cloud-connected-setup` tool in the previous step requested SSL certificates on your behalf, and, if you set `AutoRegisterValidationDomains: true` in your [configuration file](#step-3-fill-out-the-configuration-file), created DNS validation records in Route 53. If you set `AutoRegisterValidationDomains: false`, you'll need to [create the DNS validation records manually](#manual-dns-record-creation). #### **Automatic DNS record creation (if enabled)** If you set `AutoRegisterValidationDomains: true` in your [configuration file](#step-3-fill-out-the-configuration-file) and your domain is hosted in Route 53 in the same AWS account, running `panther-cloud-connected-setup` will attempt to automatically create the required DNS validation records. Check the tool output for confirmation: * If you see `Successfully created DNS validation record` messages, the DNS records were created automatically and you can skip the manual steps below. * If you see `Failed to auto-register validation domains` warnings or the certificates are marked as unissued, proceed with the manual steps below. #### **Manual DNS record creation** If you set `AutoRegisterValidationDomains: false` in your [configuration file](#step-3-fill-out-the-configuration-file) or automatic registration failed, create the DNS validation records manually: 1. A successful run of the tool will output a file with account information. In this file, locate the `panther_certificate` and `wildcard_certificate` nodes: ```json "panther_certificate": { "certificate_arn": "arn:aws:acm:us-west-2:123456789012:certificate/ad41e5b1-0681-444d-85a9-10edc4619cd2", "validation_details": { "domain_name": "panther.coolsystems.net", "record_name": "_8f65a0a68b4ca63ae9b9baa41429bf89.panther.coolsystems.net.", "record_value": "_2b5df93054bace85f6a84fb07235830d.zfyfvmchrl.acm-validations.aws.", "record_type": "CNAME" }, "is_issued": false }, "wildcard_certificate": { "certificate_arn": "arn:aws:acm:us-east-1:123456789012:certificate/5b14c5f3-867b-4420-a990-4621da85e973", "validation_details": { "domain_name": "*.panther.coolsystems.net", "record_name": "_8f65a0a68b4ca63ae9b9baa41429bf89.panther.coolsystems.net.", "record_value": "_2b5df93054bace85f6a84fb07235830d.zfyfvmchrl.acm-validations.aws.", "record_type": "CNAME" }, "is_issued": false }, ``` * Take note of whether the `validation_details.record_name` and `validation_details.record_value` values differ between the `panther_certificate` and `wildcard_certificate` notes, or are identical. 2. In AWS Route53 (or a different DNS service of your choice): * If the `validation_details.record_name` and `validation_details.record_value` values are identical in the `panther_certificate` and `wildcard_certificate` nodes, create one CNAME DNS record. * In the example output file above, because the values are identical, you'd create only one DNS record with the following: * Name: `_8f65a0a68b4ca63ae9b9baa41429bf89.panther.coolsystems.net.` * Value: `_2b5df93054bace85f6a84fb07235830d.zfyfvmchrl.acm-validations.aws.` * Type: `CNAME` * If the `validation_details.record_name` and `validation_details.record_value` values differ between the `panther_certificate` and `wildcard_certificate` nodes, create two CNAME DNS records. ### Step 6: Provide outputted file to Panther * A successful run of the tool will output a file with account information. Provide this file to Panther support.
Example output file ```json { "desired_panther_account_name": "Zac's Cool Panther Account", "panther_subdomain": "panther.coolsystems.net", "panther_edition": "ENTERPRISE", "panther_region": "us-west-2", "datalake_type": "snowflake", "admin_user_first_name": "Zac", "admin_user_last_name": "Brown", "admin_email": "zac.brown@panther.com", "snowflake_secret_arn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:panther-managed-accountadmin-secret-ok3dFA", "snowflake_account_name": "pantherlabs-zbrown_cc_provisioning_test81", "snowflake_account_url": "https://pantherlabs-zbrown_cc_provisioning_test81.snowflakecomputing.com", "snowflake_edition": "ENTERPRISE", "aws_account_id": "123456789012", "panther_certificate": { "certificate_arn": "arn:aws:acm:us-west-2:123456789012:certificate/ad41e5b1-0681-444d-85a9-10edc4619cd2", "validation_details": { "domain_name": "panther.coolsystems.net", "record_name": "_8f65a0a68b4ca63ae9b9baa41429bf89.panther.coolsystems.net.", "record_value": "_2b5df93054bace85f6a84fb07235830d.zfyfvmchrl.acm-validations.aws.", "record_type": "CNAME" }, "is_issued": false }, "wildcard_certificate": { "certificate_arn": "arn:aws:acm:us-east-1:123456789012:certificate/5b14c5f3-867b-4420-a990-4621da85e973", "validation_details": { "domain_name": "*.panther.coolsystems.net", "record_name": "_8f65a0a68b4ca63ae9b9baa41429bf89.panther.coolsystems.net.", "record_value": "_2b5df93054bace85f6a84fb07235830d.zfyfvmchrl.acm-validations.aws.", "record_type": "CNAME" }, "is_issued": false }, "deployment_status": { "aws_bootstrap_tools_deployed": true, "aws_deployment_role_deployed": true, "aws_readiness_check_succeeded": true, "aws_snowflake_bootstrap_succeeded": true } } ```
{% hint style="warning" %} Stop here, and wait for Panther to notify you that you may continue. {% endhint %} ### Step 7: Create CNAME records 1. In your AWS console, navigate to the EC2 service. 2. Locate the AWS-provided DNS name for your `web` load balancer:
1. Navigate to Route53 (or a different DNS service of your choice). 2. Create a new CNAME record that points your primary subdomain (`..com`) to this DNS name for your `web` load balancer. 3. In EC2, locate the AWS-provided DNS name for the `http-ingest-alb` load balancer:
1. Navigate to Route53 (or a different DNS service of your choice). 2. Create a new CNAME record that points your logs subdomain (`logs...com`) to this DNS name for your `http-ingest-alb` load balancer. 4. In your AWS console, navigate to the API Gateway service. 5. Click **APIs** > **Custom domain names**. 6. Click the name of the API subdomain (`api...com`). 7. In the **Endpoint Configuration** section, copy the **API Gateway domain name** value.\ ![Under an "Endpoint configuration" header, a field titled "API Gateway domain name" is circled.](https://4011785613-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LgdiSWdyJcXPahGi9Rs-2910905616%2Fuploads%2Fgit-blob-d7536ffa4822228f8bc4ebbfcfc4aa62f94db2a2%2FScreenshot%202024-11-14%20at%202.07.13%E2%80%AFPM.png?alt=media) 1. Navigate to Route53 (or a different DNS service of your choice). 2. Create a new CNAME record that points your API subdomain (`api...com`) to this **API Gateway domain name** value. 8. (Optional) Validate the three CNAME records you just created: * To validate that the primary endpoint is working: 1. In a web browser, navigate to your primary subdomain. 2. Log in to your Panther Console. * To validate that the HTTP ingest endpoint is working: * [Set up an HTTP Source in Panther by following these instructions](https://docs.panther.com/data-onboarding/data-transports/http#how-to-set-up-an-http-log-source-in-panther). * To validate that the API endpoint is working, make a call using the [Panther Analysis Tool (PAT)](https://docs.panther.com/panther-developer-workflows/detections-repo/pat): 1. [Create an API token](https://docs.panther.com/panther-developer-workflows/api#how-to-create-a-panther-api-token). 2. [Identify your GraphQL API endpoint](https://docs.panther.com/panther-developer-workflows/api/graphql#step-1-identify-your-panther-graphql-api-url). 3. Execute the following `check-connection` command:\ `pipenv run panther_analysis_tool check-connection --api-host $YOUR_GRAPHQL_ENDPOINT --api-token $YOUR_TOKEN` ### Step 8: Request API Gateway and CodeBuild quota increases * Follow [this AWS documentation](https://docs.aws.amazon.com/servicequotas/latest/userguide/request-quota-increase.html) to request the following quota increases: * [API Gateway throttle quota](https://docs.aws.amazon.com/apigateway/latest/developerguide/limits.html#apigateway-account-level-limits-table): Set at 20,000 * [CodeBuild](https://docs.aws.amazon.com/codebuild/latest/userguide/limits.html): * Concurrently running builds for ARM/Large environment (or `ARM BUILD_GENERAL1_LARGE`): Set at 2 or more * Concurrently running builds for Linux/Large environment (or `Linux BUILD_GENERAL1_LARGE`): Set at 2 or more Panther automatically submits a request for your [Lambda concurrent executions quota](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html#compute-and-storage) to be increased to 2,000. ### Step 9 (if using Databricks): Configure Databricks for Panther {% hint style="info" %} If you're using Databricks, at this stage your Panther Console will be accessible but not completely functional. {% endhint %} * Complete all instructions on [databricks](https://docs.panther.com/system-configuration/panther-deployment-types/cloud-connected/databricks "mention"). ## Post-setup recommendations ### Step 1 (recommended): Activate Panther-defined tags on AWS resources * Panther [defines these tags](https://docs.panther.com/system-configuration/panther-deployment-types/cloud-connected/..#panther-defined-tags-on-aws-resources) on the AWS resources created for your Panther deployment. Follow [this AWS documentation](https://docs.aws.amazon.com/awsaccountbilling/latest/aboutv2/activating-tags.html) to activate these tags. ### Step 2 (optional): Provide Panther your custom tags for AWS resources * In addition to the Panther-defined tags, you may wish to add [your own custom tags](https://docs.panther.com/system-configuration/panther-deployment-types/cloud-connected/..#custom-tags-on-aws-resources) on the AWS resources created for your Panther deployment. To do so, reach out to your Panther support team with the list of tag keys and values. ### Step 3 (if using Snowflake): Review Snowflake configuration recommendations for optimal query performance * See [Snowflake Configuration for Optimal Search Performance](https://docs.panther.com/search/backend/snowflake/configuration).