Built-in Panther Detections

Panther is a modern SIEM built for security operations at scale.

With Panther, teams can define detections as code and programmatically upload them to your Panther deployment. This repository contains all detections developed by the Panther Team and the Community.

We welcome all contributions! Please read the contributing guidelines before submitting pull requests.

Quick Start

Clone the repository

git clone git@github.com:panther-labs/panther-analysis.git
cd panther-analysis

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 analyze output of periodically executed SQL queries

Configure your Python environment

make install
pipenv shell # Optional, this will spawn a subshell containing pipenv environment variables. Running pipenv run before commands becomes optional after this step

Install dependencies and run your first test!

make install
pipenv run panther_analysis_tool test --path aws_cloudtrail_rules/

Run detection tests

pipenv run panther_analysis_tool test [-h] [--path PATH]
                                [--filter KEY=VALUE [KEY=VALUE ...]
                                [--debug]

Test with a specific path

pipenv run panther_analysis_tool test --path rules/cisco_umbrella_dns_rules

Test by severity

pipenv run panther_analysis_tool test --filter Severity=Critical

Test by log type

pipenv run panther_analysis_tool test --filter LogTypes=AWS.GuardDuty

Create a zip file of detections

pipenv run panther_analysis_tool zip [-h] [--path PATH] [--out OUT]
                               [--filter KEY=VALUE [KEY=VALUE ...]]
                               [--debug]

Zip all Critical severity detections

pipenv run panther_analysis_tool zip --filter Severity=Critical

Upload detections to your Panther instance

# Note: Set your AWS access keys and region env variables before running the `upload` command

export AWS_REGION=us-east-1
pipenv run panther_analysis_tool upload [-h] [--path PATH] [--out OUT]
                                  [--filter KEY=VALUE [KEY=VALUE ...]]
                                  [--debug]

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 guide!

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": "panther_labs@acme.io",
          "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 this repository, perform the following steps from your private repo:

# add the public repository as a remote
git remote add panther-upstream git@github.com: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

License

This repository is licensed under the AGPL-3.0 license.

imju/panther-analysis