Setting Up a Cloud Connected Panther Instance

Using the panther-cloud-connected-setup CLI tool

Overview

To provision a Cloud Connected Panther instance, you will use the panther-cloud-connected-setup CLI tool, in addition to taking manual steps. Read about the tool below, then begin the setup process.

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) instance to a Cloud Connected deployment, do not follow these steps; instead, reach out to your Panther Support team to initiate the conversion.

The panther-cloud-connected-setup tool (Beta)

The panther-cloud-connected-setup tool is in open beta starting with Panther version 1.113, and is available to all customers. Please share any bug reports and feature requests with your Panther support team.

Part of setting up a Cloud Connected Panther instance is running the panther-cloud-connected-setup CLI tool. The tool performs all its operations from your local machine or within your AWS or Snowflake 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

  • 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:

    • <desired panther subdomain>.yourdomain.com

    • *.<desired panther subdomain>.yourdomain.com

• Provisions Snowflake credentials in your AWS environment, using:

  • (Recommended) A Snowflake account and user named pantheraccountadmin Panther creates on your behalf

  • (Not recommended) An already created (empty) Snowflake account and pantheraccountadmin user you provide, created according to the instructions below. 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. (This user's credentials are never shared with Panther.)

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.

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.

How to set up a Cloud Connected Panther instance

Prerequisites

Snowflake prerequisites

• You have a Snowflake organization.
• (To have the panther-cloud-connected-setup tool provision a Snowflake account and user for you, which is recommended) You have a Snowflake user that:

  • Has the GLOBALORGADMIN role attached.

    • The Snowflake documentation notes that the ORGADMIN role will be eliminated. 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.
  • Has matching values for NAME and LOGIN_NAME. To verify this, run the following command in a Snowflake worksheet:

    DESC USER <your 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 user, which is not recommended) You have an empty Snowflake account and pantheraccountadmin user created according to the instructions below.

  • Certain Panther features require Snowflake Enterprise or higher. Learn more here.

(Not recommended) Manually creating a new Snowflake account and user for Panther

It is recommended to instead allow the panther-cloud-connected-setup tool provision the Snowflake account and user for you.

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. <YOUR_REGION> should be one of the supported AWS regions (and be the same AWS region where your Panther instance will eventually be deployed). This command creates an account 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.

   USE ROLE ORGADMIN;
   
   CREATE ACCOUNT <YOUR_PANTHER_ACCOUNT_NAME> // Your desired Panther account name
     ADMIN_NAME = <YOUR_ADMIN_NAME>
     ADMIN_USER_TYPE = PERSON 
     ADMIN_PASSWORD = '<string_literal>'
     EMAIL = '<your snowflake DBA email>'
     MUST_CHANGE_PASSWORD = FALSE
     EDITION = <YOUR_EDITION> // STANDARD, ENTERPRISE, or BUSINESS_CRITICAL
     REGION = <YOUR_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:

   SELECT LOWER(CURRENT_ORGANIZATION_NAME() 
   || '-' || CURRENT_ACCOUNT_NAME() 
   || '.snowflakecomputing.com') AS account_url;

   • The URL will be in this format: <org-name>-<account-name>.snowflakecomputing.com

   • Store this value in a secure location; you will need it in a later step of this process.

1. 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.
2. In the new account, create a pantheraccountadmin user and grant it administrative roles using the following commands:

USE ROLE SECURITYADMIN;

CREATE USER pantheraccountadmin
   TYPE='SERVICE'
   RSA_PUBLIC_KEY='<string_literal>';

GRANT ROLE SYSADMIN
   TO USER pantheraccountadmin;
   
GRANT ROLE SECURITYADMIN
   TO USER pantheraccountadmin;

GRANT ROLE ACCOUNTADMIN
   TO USER pantheraccountadmin;
   
ALTER USER pantheraccountadmin SET DEFAULT_ROLE = SYSADMIN;

AWS prerequisites

• You have an AWS organization.
• You are able to provide user credentials (i.e., an access key ID and secret access key), optionally with a session token, for either:

  • (Recommended) The AWS account root user (or a different IAM user with comparable permissions).
  • An IAM user with at least the following permissions:

    • Ability to deploy CloudFormation templates
    • Ability to create certificates in AWS Certificate Manager (ACM)
    • Ability to create and invoke Lambdas
    • Ability to read/write to Secrets Manager

If your AWS organization has service control policies (SCPs) and Control Tower Guardrails 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.

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.

Step 1: Create a new AWS account

• In your AWS organization, create a new account, if needed. (It is also possible to use an existing empty one.)

Your Panther instance cannot be deployed in an AWS account with existing resources.

Step 2: Request values from Panther

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.

• 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 the panther-cloud-connected-setup tool should provision a Snowflake account and user for you: example-config-new-snowflake-acct.yml
   • If you will provide an already created, empty Snowflake account and pantheraccountadmin user: example-config-existing-snowflake-acct.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. This region is where your Panther instance will be deployed.
   • (If you are using example-config-new-snowflake-acct.yml) When entering a value for SnowflakeConfig.NewAccountConfig.SnowflakeEdition, take note that certain Panther features require Snowflake Enterprise or higher. Learn more here.

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

Learn more about the tool in its README.md.

Step 5: Provide outputted file Panther

• A successful run of the tool will output a file with account information. Provide this file to Panther support.

Example output file

{
  "desired_panther_account_name": "Zac's Cool Panther Account",
  "panther_subdomain": "panther.coolsystems.net",
  "panther_edition": "ENTERPRISE",
  "panther_region": "us-west-2",
  "admin_user_first_name": "Zac",
  "admin_user_last_name": "Brown",
  "admin_email": "[e-mail]",
  "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
  }
}

Stop here, and wait for Panther to notify you that you may continue.

Step 6: 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 (<your_desired_Panther_subdomain>.<company_name>.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.<your_desired_Panther_subdomain>.<company_name>.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.<your_desired_Panther_subdomain>.<company_name>.com).

7. In the Endpoint Configuration section, copy the API Gateway domain name value.

   1. Navigate to Route53 (or a different DNS service of your choice).

   2. Create a new CNAME record that points your API subdomain (api.<your_desired_Panther_subdomain>.<company_name>.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.
   • To validate that the API endpoint is working, make a call using the Panther Analysis Tool (PAT):

     1. Create an API token.
     2. Identify your GraphQL API endpoint.
     3. Execute the following check-connection command: pipenv run panther_analysis_tool check-connection --api-host $YOUR_GRAPHQL_ENDPOINT --api-token $YOUR_TOKEN

Step 7: Request API Gateway and CodeBuild quota increases

• Follow this AWS documentation to request the following quota increases:

  • API Gateway throttle quota: Set at 20,000
  • CodeBuild:

    • 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 to be increased to 2,000.

Post-setup recommendations

Step 1 (recommended): Activate Panther-defined tags on AWS resources

• Panther defines these tags on the AWS resources created for your Panther deployment. Follow this AWS documentation 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 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.