A security analytics platform built for cloud-focused security teams

panther-analysis

Panther is a security analytics platform built for cloud-focused security teams.

Panther enables teams to define detections as code and programmatically upload them to your Panther deployment.

Quick Start

# Clone the repository
git clone [email protected]:panther-labs/panther-analysis.git
cd panther-analysis

# Configure your Python environment
make install
make venv
source venv/bin/activate

# Install dependencies and run your first test!
make deps
panther_analysis_tool test --path aws_cloudtrail_rules/

Getting Started

The examples below demonstrate the local Panther workflow:

# Run detection tests
panther_analysis_tool test [-h] [--path PATH]
                                [--filter KEY=VALUE [KEY=VALUE ...]]
                                [--debug]

# Test with a specific path
panther_analysis_tool test --path cisco_umbrella_dns_rules

# Test by severity
panther_analysis_tool test --filter Severity=Critical

# Test by log type
panther_analysis_tool test --filter LogTypes=AWS.GuardDuty

# Create a zip file of detections
panther_analysis_tool zip [-h] [--path PATH] [--out OUT]
                               [--filter KEY=VALUE [KEY=VALUE ...]]
                               [--debug]

# Zip all Critical severity detections
panther_analysis_tool zip --filter Severity=Critical

# Upload detections to your Panther instance
panther_analysis_tool upload [-h] [--path PATH] [--out OUT]
                                  [--filter KEY=VALUE [KEY=VALUE ...]]
                                  [--debug]

# Important: Make sure you have access keys and region settings set for the AWS account running Panther
panther_analysis_tool upload --filter LogTypes=AWS.GuardDuty

Repo Structure

Each folder contains detections in the format of <log/resource type>_<detecton_type>:

• Rules analyze logs to detect malicious activity
• Policies represent the desired secure state of a resource to detect security misconfigurations
• Scheduled rules (coming soon) analyze output of periodically executed SQL queries

Global helper functions are defined in the global_helpers folder. This is a hard coded location and cannot change. However, you may create as many files as you'd like under this path. Simply import them into your detections by the specified GlobalID.

Additionally, groups of detections may be linked to multiple "Reports", which is a system for tracking frameworks like CIS, PCI, MITRE ATT&CK, or more.

Writing Detections

For a full reference on writing detections, read our docs!

Each detection has a Python file (.py) and a metadata file (.yml) of the same name (in the same location), for example:

Example detection rule: okta_brute_force_logins.py

def rule(event):
    return (event.get('outcome', {}).get('result', '') == 'FAILURE' and
            event.get('eventType') == 'user.session.start')


def title(event):
    return 'Suspected brute force Okta logins to account {} due to [{}]'.format(
        event.get('actor', {}).get('alternateId', 'ID_NOT_PRESENT'),
        event.get('outcome', {}).get('reason', 'REASON_NOT_PRESENT')
    )

Example detection metadata: okta_brute_force_logins.yml

AnalysisType: rule
Filename: okta_brute_force_logins.py
RuleID: Okta.BruteForceLogins
DisplayName: Okta Brute Force Logins
Enabled: true
LogTypes:
  - Okta.SystemLog
Tags:
  - Identity & Access Management
Severity: Medium
...
Threshold: 5
DedupPeriodMinutes: 15
SummaryAttributes:
  - eventType
  - severity
  - displayMessage
  - p_any_ip_addresses
Tests:
  -
    Name: Failed login
    ExpectedResult: true
    Log:
      {
        "eventType": "user.session.start",
        "actor": {
          "id": "00uu1uuuuIlllaaaa356",
          "type": "User",
          "alternateId": "[email protected]",
          "displayName": "Run Panther"
        },
        "request": {},
        "outcome": {
          "result": "FAILURE",
          "reason": "VERIFICATION_ERROR"
        }
      }

Customizing Detections

Customizing detections-as-code is one of the most powerful capabilities Panther offers. To manage custom detections, you can create a private fork of this repo.

Upon tagged releases, you can pull upstream changes from this public repo.

Follow the instructions here to learn how to get started with forks.

Getting Updates

When you want to pull in the latest changes from our this repository, perform the following steps from your private repo:

# add the public repository as a remote
git remote add panther-upstream [email protected]:panther-labs/panther-analysis.git

# Pull in the latest changes
# Note: You may need to use the `--allow-unrelated-histories`
#       flag if you did not maintain the history originally
git pull panther-upstream master

# Push the latest changes up to your forked repo and merge them
git push

GitHub

https://github.com/panther-labs/panther-analysis