Quick Start
Welcome to the future of open-source cloud security - we're glad you're here!
Panther is a collection of serverless applications deployed within your AWS account. The frontend is a React application which runs in a Docker container (via ECS), and the backend is a collection of compute (Lambda), storage (DynamoDB / S3), and other supporting services.
Your data is always under your control, encrypted in transit and at rest. All infrastructure is least-privilege, modeled and deployed with AWS CloudFormation.
You can optionally use Panther alongside an existing logging platform such as Splunk or ElasticSearch. We recommend an architecture that tees traffic between both with tools such as Logstash or Fluentd.
Before we cover deployment, let's establish the terminology:
Event: A normalized log line from a sources such as CloudTrail, Osquery, or Suricata
Rule: A Python function to detect suspicious activity
Resource: A cloud entity, such as an IAM user, virtual machine, or data bucket
Policy: A Python function representing the desired secure state of a resource
Alert: A notification to the team when a policy has failed or a rule has triggered
You need an AWS account and an IAM user or role with permission to create and manage the necessary AWS resources. We provide an IAM role you can use for Panther deployment:
Terraform (source)
We recommend deploying Panther into its own AWS account via AWS Organizations. This ensures that detection infrastructure is contained within a single place.
Panther relies on dozens of AWS services, some of which are not yet available in every region. In particular, AppSync, Cognito, Athena, and Glue are newer services not available in us-gov, china, and other regions. At the time of writing, all Panther backend components are supported in the following:
ap-northeast-1(tokyo)ap-northeast-2(seoul)ap-south-1(mumbai)ap-southeast-1(singapore)ap-southeast-2(sydney)ca-central-1(canada)eu-central-1(frankfurt)eu-west-1(ireland)eu-west-2(london)us-east-1(n. virginia)us-east-2(ohio)us-west-2(oregon)
Consult the AWS region table for the source of truth about service availability in each region.
Configure your AWS credentials and deployment region:
export AWS_REGION=us-east-1 # Choose your region from the list aboveexport AWS_ACCESS_KEY_ID=...export AWS_SECRET_ACCESS_KEY=...
If you've already configured your credentials with the AWS CLI (you have a ~/.aws/credentials file), you can easily add them to the environment:
export AWS_ACCESS_KEY_ID=`aws configure get aws_access_key_id`export AWS_SECRET_ACCESS_KEY=`aws configure get aws_secret_access_key`
Remember to follow best security practices when handling access keys:
Avoid storing them in plaintext files
Use IAM roles with temporary session credentials
Rotate access keys every 90 days
Enforce MFA for key access
Tools like aws-vault can help with all of the above, check out our blog post to learn more!
Run Panther in 3 easy steps: clone the repo, install docker, and deploy!
First, clone the latest release of the Panther repo:
git clone https://github.com/panther-labs/panther --depth 1 --branch v0.3.0cd panther
Next, install Docker 17+ and start the application. You can verify the docker daemon is running by typing docker info in the console or checking the status bar:
From the repo root, start the development environment: ./dev.sh
Your AWS credentials must be exported as environment variables for the docker image running locally on your machine to find them. This also makes it easy to use temporary credential managers like aws-vault:
aws-vault exec <profile> -- ./dev.sh
You're all set! Run mage deploy
If you've made any changes to the source files or want to run tests, you may need to first install development dependencies with
mage setup:allIf you use
aws-vault, you must be authenticated with MFA. Otherwise, IAM role creation will fail withInvalidClientTokenIdThe initial deployment will take 20-30 minutes. If your credentials timeout, you can safely redeploy to pick up where you left off.
Near the end of the deploy command, you'll be prompted for your first/last name and email to setup the first Panther user account.
You'll get an email from no-reply@verificationemail.com with your temporary password. If you don't see it, be sure to check your spam folder.
Now you can sign into Panther! The URL is linked in the welcome email and also printed at the end of the deploy command.
By default, Panther generates a self-signed certificate, which will cause most browsers to present a warning page:
​
​
Your connection is encrypted, and it's generally safe to continue if the domain matches the output of the deploy command. However, the warning exists because self-signed certificates do not protect you from man-in-the-middle attacks; for this reason production deployments should provide their own ACM certificate in the deployments/panther_config.yml file.
Rather than deploying from within a docker container, you can instead configure your development environment locally. This will take more time initially but will lead to faster deployments.
Or, you can deploy from an EC2 instance with Docker and git installed (in the same region you're deploying Panther to). This is typically the fastest option since it minimizes the latency when communicating with AWS services. Instead of exporting your AWS credentials as environment variables, you will need to attach the deployment IAM role to your EC2 instance profile. Your EC2 instance needs at least 1 vCPU and 2GB of memory; the cheapest suitable instance type is a t2.small.
Now you can follow the steps below to configure alert outputs, cloud security scans, and real-time log analysis!
​Log Analysis Setup​
​Background​
​Create Policies for the supported AWS Resources​
​Report Bugs​
​Panther Blog​
​Panther Website​
