# Panther SDK
The Panther SDK module allows you to configure detections for your [Panther](https://panther.com) instance.
## Getting Started
### Install
The Panther SDK can be installed using PIP.
```sh
pip3 install panther-sdk==0.0.24
```
### Writing a detection
You can use the `detection` module in Panther SDK to configure detections. The example below shows a detection that processing an HTTP log.
Assuming we have a log type `Internal.HTTP.Traffic` that has the following shape:
```json
{
"method": "POST",
"useSSL": false,
"path": "/api/some/endpoint",
"host": "internal.megacorp.com"
}
```
We can write a detection to check for insecure `POST` and `PUT` requests:
```python
# import the "detection" module, as we'll be creating a rule.
from panther_sdk import detection
# The next four functions are used in the detection definition that follows. Panther
# detections allow for parts of a detection to be defined with custom Python code.
# "filter_insecure" is an example of python function that will be used to create
# a detection.PythonFilter that only matches insecure events. The event argument will
# have a python dict object corresponding to the JSON event.
def filter_insecure(event, params):
return event["useSSL"] == False
# "filter_http_methods" is a slightly more complicated python function that we will use
# to create a detection.PythonFilter later. This function uses the second "params" argument
# to make the function's logic reusable.
def filter_http_methods(event, params):
allowed_methods = params["methods"]
actual_method = event["method"]
return actual_method in allowed_methods
# "reference_generator" is another example where we will use some python code to dynamically
# change the information Panther presents on an Alert resulting from a Detection match. In
# this example, we're populating a query param with some relevant information from
# the contextual event.
def reference_generator(event):
origin = event["origin"]
return f"https://wiki.internal.megacorp.com/hosts_db?host={origin}"
# "make_context" will be used to attach arbitrary data to the resulting Alert. This
# can be used to simply change how data is presented or be used to push machine readable information
# to a downstream Alert Destination.
def make_context(event):
# The Panther SDK's hooks to arbitrary python come with some restrictions. When the
# detection is saved, the Panther backend will capture the source of provided function to use
# in realtime log data processing and other backend processes. Because of this, functions used
# to define a detection must not have references that are not local to the function body. Therefore,
# imports targeting any of the below _must_ be included in the function body:
#
# - The python standard library
# - Libraries that are enabled on your Panther instance
# - Panther "Global Helpers" that you have configured on your instance
import fnmatch
path = event["path"]
return {
"is_api_path": fnmatch.fnmatch(path, "/api/*")
}
# "pick_severity" is a custom function we are using to define the severity of Alerts based on
# the data present in the current log. The detection.Rule declaration below shows how this method
# is registered with the definition of our Rule.
def pick_severity(event) -> str:
from panther_sdk import detection # required. see notes in comment above "make_context"
if event["origin"] != "internal.megacorp.com":
return detection.SeverityInfo
return detection.SeverityInfo
# Declare a rule. Every call to "detection.Rule" in your repo will create a Rule in the Panther backend.
# This example uses a subset of the fields available to define a Rule. See "Full Dataclass API" for
# all the available fields.
detection.Rule(
# Give the Rule an id. This name must be unique on your Panther
# instance. Dot separated names following "namespace" pattern is recommended.
rule_id="Internal.HTTP.Traffic.Insecure",
# Pick a human friendly name for the rule. This will be used
# to present the Rule in the Panther Console UI
name="Detect insecure internal HTTP traffic",
# Specify one or more log types for your Rule. This setting is what
# tells the Panther backend to run this Rule against the log data depicted above.
log_types=["Internal.HTTP.Traffic"],
# Specify an enabled state for the Rule. Detections can be uploaded in a
# disabled state and will not begin processing log data until enabled.
enabled=True,
# Optionally, you can specify a list of tags to associate with the detection.
tags=["internal"],
# The "filters" list defines the sequence of matching logic that an event
# will be tested against to determine whether there is a match. Returning "True" proceeds to the
# next check. If the final check returns "True", there is a match.
filters=[
# If the HTTP transaction was secure, we're not interested in that log in this detection.
# Therefore, the first filter uses the "filter_insecure" function we defined to filter to only
# events that have useSSL set to "false".
detection.PythonFilter(func=filter_insecure),
# For now, we're only interested in getting alerted for insecure POST and PUT requests.
# We therefore define the second filter step using "filter_http_methods". Unlike "filter_insecure",
# we pass some parameters to this function.
detection.PythonFilter(func=filter_http_methods, params={'methods': ["POST", "PUT"]}),
],
# On this line, we're defining the severity that should be associated with any resulting alerts.
# We have the option of defining a static severity (simply: severity="INFO") but, in this case, we want
# to make the severity dynamic based on data from the event. To do this, we reference the "pick_severity"
# function we defined at the top of the file. We also provide a fallback value in case the dynamic function
# cannot be processed. This fallback will also be the Severity value displayed in the Panther Console UI
severity=detection.DynamicStringField(
func=pick_severity,
fallback=detection.SeverityInfo,
),
# Below we specify the "reference" field. This optional field is used to attach a link to any Alerts
# resulting from this detection. Similar to "severity" we can make this field dynamic based on
# event data. There is also a fallback value specified.
reference=detection.DynamicStringField(
func=reference_generator,
fallback="https://wiki.internal.megacorp.com/hosts_db",
),
# Fields like "runbook" and "description" are also available to further customize how any
# resulting Alerts will be displayed. These can have dynamic handlers defined, but in this
# example static string values will work just fine.
runbook="Optional runbook content",
description="A helpful description",
# Finally, we use the optional "alert_context" field to tell the Panther backend to use our
# "make_context" function to generate custom data that will be attached to any resulting Alerts.
alert_context=make_context,
)
```
There is support for override behavior that can be very helpful for writing factory functions for your detections.
You can provide defaults for your detection while letting customizations be set when the function is called. For example:
```python
from panther_sdk import detection
# This is an example of a factory rule function that might live in panther_detections or your own library of detections.
# This function accepts an optional overrides object, which is passed through to the Rule instantiation. Any attributes
# set on the RuleOverrides object will override the attributes defined for the rule.
def factory_rule_func(overrides: Optional[detection.RuleOverrides] = None) -> detection.Rule:
return detection.Rule(
rule_id="default.rule.id",
filters=[...],
log_types=["AWS.ALB"],
severity=detection.SeverityMedium,
overrides=overrides,
)
# Here is an example of using the rule factory function.
def make_detections() -> None:
# We can pass no overrides at all, and it will be the default rule the function creates
r = factory_rule_func()
print(r)
# We can override the id and severity to create a more customized rule using our function from above
r = factory_rule_func(overrides=detection.RuleOverrides(
rule_id="not.important.rule",
severity=detection.SeverityInfo,
))
print(r)
r = factory_rule_func(overrides=detection.RuleOverrides(
rule_id="very.important.rule",
severity=detection.SeverityHigh,
))
print(r)
# Now we call our main detection making function to execute it when running this python script
make_detections()
```
Similar to overrides, you have the ability to add extensions to your Panther content.
These can be used the same way as overrides on fields that have lists.
```python
from panther_sdk import detection
# This is an example of a factory rule function that might live in panther_detections or your own library of detections.
# This function accepts an optional extensions object, which is passed through to the Rule instantiation. Any attributes
# set on the RuleExtensions object will override the attributes defined for the rule.
def factory_rule_func(extensions: Optional[detection.RuleExtensions] = None) -> detection.Rule:
return detection.Rule(
rule_id="default.rule.id",
filters=[...],
log_types=["AWS.ALB"],
severity=detection.SeverityMedium,
extensions=extensions,
)
# Here is an example of using the rule factory function.
def make_detections() -> None:
# We can pass no extensions at all, and it will be the default rule the function creates
r = factory_rule_func()
print(r)
# We can extend filters to add logic to the rule
r = factory_rule_func(extensions=detection.RuleExtensions(
filters=[detection.PythonFilter(func=my_very_important_filter)],
))
print(r)
# Now we call our main detection making function to execute it when running this python script
make_detections()
```
## Full Dataclass API
## detection module
### DynamicStringField
Make a field dynamic based on the detection input
| Field | Description | Type |
| ----- | ---- | ----------- |
| `fallback` | Fallback value in case the dynamic handler fails | `str` |
| `func` | Dynamic handler | `Optional[Callable[[PantherEvent], str]]` |
### DynamicDestinations
Make destinations dynamic based on the detection input
| Field | Description | Type |
| ----- | ---- | ----------- |
| `fallback` | Fallback value in case the dynamic handler fails | `Optional[List[str]]` |
| `func` | Dynamic handler | `Callable[[PantherEvent], List[str]]` |
### AlertGrouping
Configuration for how an alert is grouped
| Field | Description | Type |
| ----- | ---- | ----------- |
| `period_minutes` | How long should matches be grouped into an alert after the first match | `int` |
| `group_by` | Function to generate a key for grouping matches | `Optional[Callable[[PantherEvent], str]]` |
### PythonFilter
Create a filter by referencing a python function
| Field | Description | Type |
| ----- | ---- | ----------- |
| `func` | Provide a function whose python source will be used as the filter definition | `Callable[[PantherEvent], bool]` |
### UnitTestMock
Mock for a unit test
| Field | Description | Type |
| ----- | ---- | ----------- |
| `name` | name of the object to mock | `str` |
| `return_value` | string to assign as the return value for the mock | `str` |
### JSONUnitTest
Unit test with json content
| Field | Description | Type |
| ----- | ---- | ----------- |
| `name` | name of the unit test | `str` |
| `expect_match` | whether the data should match and trigger an alert | `bool` |
| `data` | json string | `str` |
| `mocks` | list of mocks to use in the test | `Optional[List[UnitTestMock]]` |
### Policy
Define a Policy-type detection to execute against log data in your Panther instance
| Field | Description | Type |
| ----- | ---- | ----------- |
| `policy_id` | ID for the Policy | `str` |
| `ignore_patterns` | Patterns of resource ids to ignore for the policy | `Optional[Union[str, List[str]]]` |
| `destinations` | Alert destinations for the policy | `Optional[Union[str, List[str], DynamicDestinations]]` |
| `filters` | Define event filters for the policy | `Union[Union[PythonFilter], List[Union[PythonFilter]]]` |
| `enabled` | Whether the policy is enabled or not | `bool` |
| `resource_types` | What resource types this policy will apply to | `Union[str, List[str]]` |
| `severity` | What severity alerts generated from this policy get assigned | `Union[str, DynamicStringField]` |
| `name` | What name to display in the UI and alerts. The PolicyID will be displayed if this field is not set. | `Optional[str]` |
| `description` | Description for the policy | `Optional[Union[str, DynamicStringField]]` |
| `reference` | The reason this policy exists, often a link to documentation | `Optional[Union[str, DynamicStringField]]` |
| `reports` | A mapping of framework or report names to values this policy covers for that framework | `Optional[Dict[str, List[str]]]` |
| `runbook` | The actions to be carried out if this policy fails, often a link to documentation | `Optional[Union[str, DynamicStringField]]` |
| `tags` | Tags used to categorize this policy | `Optional[Union[str, List[str]]]` |
| `unit_tests` | Unit tests for this policy | `Optional[Union[Union[JSONUnitTest], List[Union[JSONUnitTest]]]]` |
| `alert_title` | Title to use in the alert | `Optional[Callable[[PantherEvent], str]]` |
| `alert_context` | Optional JSON to attach to alerts generated by this policy | `Optional[Callable[[PantherEvent], Dict[str, Any]]]` |
| `alert_grouping` | Configuration for how an alert is grouped | `Optional[AlertGrouping]` |
### Rule
Define a Rule-type detection to execute against log data in your Panther instance
| Field | Description | Type |
| ----- | ---- | ----------- |
| `rule_id` | ID for the rule | `str` |
| `severity` | Severity for the rule | `Union[str, DynamicStringField]` |
| `threshold` | Number of matches received before an alert is triggered | `int` |
| `name` | Display name for the rule | `Optional[str]` |
| `log_types` | Log Types to associate with this rule | `Union[str, List[str]]` |
| `filters` | Define event filters for the rule | `Union[Union[PythonFilter], List[Union[PythonFilter]]]` |
| `enabled` | Whether the rule is enabled or not | `bool` |
| `unit_tests` | Define event filters for the rule | `Optional[Union[Union[JSONUnitTest], List[Union[JSONUnitTest]]]]` |
| `tags` | Tags for the rule | `Optional[Union[str, List[str]]]` |
| `reference` | Reference for the rule | `Optional[Union[str, DynamicStringField]]` |
| `runbook` | Runbook for the rule | `Optional[Union[str, DynamicStringField]]` |
| `description` | Description for the rule | `Optional[Union[str, DynamicStringField]]` |
| `summary_attrs` | Summary Attributes for the rule | `Optional[List[str]]` |
| `reports` | Report mappings for the rule | `Optional[Dict[str, List[str]]]` |
| `destinations` | Alert destinations for the rule | `Optional[Union[str, List[str], DynamicDestinations]]` |
| `alert_title` | Title to use in the alert | `Optional[Callable[[PantherEvent], str]]` |
| `alert_context` | Optional JSON to attach to alerts generated by this rule | `Optional[Callable[[PantherEvent], Dict[str, Any]]]` |
| `alert_grouping` | Configuration for how an alert is grouped | `Optional[AlertGrouping]` |
### ScheduledRule
Define a ScheduledRule-type detection to execute against query results in your Panther instance
| Field | Description | Type |
| ----- | ---- | ----------- |
| `rule_id` | ID for the scheduled rule | `str` |
| `severity` | What severity alerts generated from this scheduled rule get assigned | `Union[str, DynamicStringField]` |
| `threshold` | Number of matches received before an alert is triggered | `int` |
| `name` | Display name for the scheduled rule | `Optional[str]` |
| `scheduled_queries` | Scheduled queries to associate with this scheduled rule | `Union[str, List[str]]` |
| `filters` | Define event filters for the scheduled rule | `Union[Union[PythonFilter], List[Union[PythonFilter]]]` |
| `enabled` | Short description for the scheduled rule | `bool` |
| `unit_tests` | Define event filters for the scheduled rule | `Optional[Union[Union[JSONUnitTest], List[Union[JSONUnitTest]]]]` |
| `tags` | Tags for the scheduled rule | `Optional[Union[str, List[str]]]` |
| `reference` | Reference for the scheduled rule | `Optional[Union[str, DynamicStringField]]` |
| `runbook` | Runbook for the scheduled rule | `Optional[Union[str, DynamicStringField]]` |
| `description` | Description for the scheduled rule | `Optional[Union[str, DynamicStringField]]` |
| `summary_attrs` | Summary Attributes for the scheduled rule | `Optional[List[str]]` |
| `reports` | Report mappings for the scheduled rule | `Optional[Dict[str, List[str]]]` |
| `destinations` | Alert destinations for the scheduled rule | `Optional[Union[str, List[str], DynamicDestinations]]` |
| `alert_title` | Title to use in the alert | `Optional[Callable[[PantherEvent], str]]` |
| `alert_context` | Optional JSON to attach to alerts generated by this rule | `Optional[Callable[[PantherEvent], Dict[str, Any]]]` |
| `alert_grouping` | Configuration for how an alert is grouped | `Optional[AlertGrouping]` |
## query module
### CronSchedule
Cron expression based schedule definition for a query
| Field | Description | Type |
| ----- | ---- | ----------- |
| `expression` | Defines how often queries using this schedule run | `str` |
| `timeout_minutes` | Defines the timeout applied to queries with this schedule | `int` |
### IntervalSchedule
Interval based schedule definition for a query
| Field | Description | Type |
| ----- | ---- | ----------- |
| `rate_minutes` | Defines how often queries using this schedule run | `int` |
| `timeout_minutes` | Defines the timeout applied to queries with this schedule | `int` |
### Query
A saved or scheduled query
| Field | Description | Type |
| ----- | ---- | ----------- |
| `name` | Unique name for the query | `str` |
| `description` | Short description for the query | `str` |
| `default_database` | Default database for the query | `str` |
| `sql` | SQL statement | `str` |
| `enabled` | Whether the query is enabled or not | `bool` |
| `tags` | Tags for the query | `Optional[Union[str, List[str]]]` |
| `schedule` | Schedule attached to the query | `Optional[Union[IntervalSchedule, CronSchedule]]` |
## schema module
### DataModelMapping
| Field | Description | Type |
| ----- | ---- | ----------- |
| `name` | Name of the data model field. This will be the name used when accessing the field from within detections. | `str` |
| `path` | Path to the target value in the Panther Event. This can be a simple field name or complete JSON path starting with a `$`. JSON path syntax must be compatible with the [jsonpath-ng](https://pypi.org/project/jsonpath-ng/) Python package. | `Optional[str]` |
| `func` | A Python function to access the target value. The input is the Panther Event and output is the target value in the Panther Event. | `Optional[Callable[[PantherEvent], Any]]` |
### DataModel
Data Models provide a way to configure a set of unified fields across all log types.
| Field | Description | Type |
| ----- | ---- | ----------- |
| `data_model_id` | The unique identifier of the data model. | `str` |
| `name` | What name to display in the UI and alerts. The `data_model_id` will be displayed if this field is not set. | `Optional[str]` |
| `enabled` | Whether this data model is enabled. | `Optional[bool]` |
| `log_type` | What log type this data model will apply to. | `str` |
| `mappings` | Mapping from source field name or method to unified data model field name. | `Union[DataModelMapping, List[DataModelMapping]]` |
Raw data
{
"_id": null,
"home_page": "https://panther.com",
"name": "panther-sdk",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "",
"keywords": "security detection",
"author": "Panther Labs Inc.",
"author_email": "support@panther.io",
"download_url": "https://files.pythonhosted.org/packages/50/82/69b068c129049f52c872fd55d4004c4229b48d5e821ca986d355c8b1f727/panther_sdk-0.0.24.tar.gz",
"platform": null,
"description": "# Panther SDK\nThe Panther SDK module allows you to configure detections for your [Panther](https://panther.com) instance.\n\n## Getting Started\n\n### Install\nThe Panther SDK can be installed using PIP.\n\n```sh\npip3 install panther-sdk==0.0.24\n```\n\n### Writing a detection\nYou can use the `detection` module in Panther SDK to configure detections. The example below shows a detection that processing an HTTP log.\n\nAssuming we have a log type `Internal.HTTP.Traffic` that has the following shape:\n```json\n{\n \"method\": \"POST\",\n \"useSSL\": false,\n \"path\": \"/api/some/endpoint\",\n \"host\": \"internal.megacorp.com\"\n}\n```\n\nWe can write a detection to check for insecure `POST` and `PUT` requests:\n```python\n# import the \"detection\" module, as we'll be creating a rule.\nfrom panther_sdk import detection\n\n# The next four functions are used in the detection definition that follows. Panther \n# detections allow for parts of a detection to be defined with custom Python code.\n\n\n# \"filter_insecure\" is an example of python function that will be used to create\n# a detection.PythonFilter that only matches insecure events. The event argument will\n# have a python dict object corresponding to the JSON event.\ndef filter_insecure(event, params):\n return event[\"useSSL\"] == False\n\n\n# \"filter_http_methods\" is a slightly more complicated python function that we will use\n# to create a detection.PythonFilter later. This function uses the second \"params\" argument\n# to make the function's logic reusable.\ndef filter_http_methods(event, params):\n allowed_methods = params[\"methods\"]\n actual_method = event[\"method\"]\n return actual_method in allowed_methods\n\n\n# \"reference_generator\" is another example where we will use some python code to dynamically\n# change the information Panther presents on an Alert resulting from a Detection match. In\n# this example, we're populating a query param with some relevant information from \n# the contextual event.\ndef reference_generator(event):\n origin = event[\"origin\"]\n return f\"https://wiki.internal.megacorp.com/hosts_db?host={origin}\"\n\n\n# \"make_context\" will be used to attach arbitrary data to the resulting Alert. This\n# can be used to simply change how data is presented or be used to push machine readable information\n# to a downstream Alert Destination.\ndef make_context(event):\n # The Panther SDK's hooks to arbitrary python come with some restrictions. When the\n # detection is saved, the Panther backend will capture the source of provided function to use\n # in realtime log data processing and other backend processes. Because of this, functions used\n # to define a detection must not have references that are not local to the function body. Therefore,\n # imports targeting any of the below _must_ be included in the function body:\n #\n # - The python standard library\n # - Libraries that are enabled on your Panther instance\n # - Panther \"Global Helpers\" that you have configured on your instance\n \n import fnmatch \n \n path = event[\"path\"]\n return {\n \"is_api_path\": fnmatch.fnmatch(path, \"/api/*\")\n }\n\n\n# \"pick_severity\" is a custom function we are using to define the severity of Alerts based on\n# the data present in the current log. The detection.Rule declaration below shows how this method\n# is registered with the definition of our Rule.\ndef pick_severity(event) -> str:\n from panther_sdk import detection # required. see notes in comment above \"make_context\"\n \n if event[\"origin\"] != \"internal.megacorp.com\":\n return detection.SeverityInfo\n\n return detection.SeverityInfo\n\n\n# Declare a rule. Every call to \"detection.Rule\" in your repo will create a Rule in the Panther backend.\n# This example uses a subset of the fields available to define a Rule. See \"Full Dataclass API\" for\n# all the available fields.\ndetection.Rule(\n # Give the Rule an id. This name must be unique on your Panther \n # instance. Dot separated names following \"namespace\" pattern is recommended. \n rule_id=\"Internal.HTTP.Traffic.Insecure\",\n \n # Pick a human friendly name for the rule. This will be used\n # to present the Rule in the Panther Console UI\n name=\"Detect insecure internal HTTP traffic\",\n \n # Specify one or more log types for your Rule. This setting is what\n # tells the Panther backend to run this Rule against the log data depicted above.\n log_types=[\"Internal.HTTP.Traffic\"],\n \n # Specify an enabled state for the Rule. Detections can be uploaded in a\n # disabled state and will not begin processing log data until enabled.\n enabled=True,\n \n # Optionally, you can specify a list of tags to associate with the detection.\n tags=[\"internal\"],\n\n # The \"filters\" list defines the sequence of matching logic that an event\n # will be tested against to determine whether there is a match. Returning \"True\" proceeds to the\n # next check. If the final check returns \"True\", there is a match.\n filters=[\n # If the HTTP transaction was secure, we're not interested in that log in this detection.\n # Therefore, the first filter uses the \"filter_insecure\" function we defined to filter to only\n # events that have useSSL set to \"false\". \n detection.PythonFilter(func=filter_insecure),\n \n # For now, we're only interested in getting alerted for insecure POST and PUT requests.\n # We therefore define the second filter step using \"filter_http_methods\". Unlike \"filter_insecure\",\n # we pass some parameters to this function. \n detection.PythonFilter(func=filter_http_methods, params={'methods': [\"POST\", \"PUT\"]}),\n ],\n\n # On this line, we're defining the severity that should be associated with any resulting alerts.\n # We have the option of defining a static severity (simply: severity=\"INFO\") but, in this case, we want\n # to make the severity dynamic based on data from the event. To do this, we reference the \"pick_severity\"\n # function we defined at the top of the file. We also provide a fallback value in case the dynamic function\n # cannot be processed. This fallback will also be the Severity value displayed in the Panther Console UI\n severity=detection.DynamicStringField(\n func=pick_severity,\n fallback=detection.SeverityInfo,\n ),\n\n # Below we specify the \"reference\" field. This optional field is used to attach a link to any Alerts \n # resulting from this detection. Similar to \"severity\" we can make this field dynamic based on \n # event data. There is also a fallback value specified.\n reference=detection.DynamicStringField(\n func=reference_generator,\n fallback=\"https://wiki.internal.megacorp.com/hosts_db\",\n ),\n \n # Fields like \"runbook\" and \"description\" are also available to further customize how any \n # resulting Alerts will be displayed. These can have dynamic handlers defined, but in this \n # example static string values will work just fine.\n runbook=\"Optional runbook content\",\n description=\"A helpful description\",\n \n # Finally, we use the optional \"alert_context\" field to tell the Panther backend to use our \n # \"make_context\" function to generate custom data that will be attached to any resulting Alerts.\n alert_context=make_context,\n)\n```\n\nThere is support for override behavior that can be very helpful for writing factory functions for your detections.\nYou can provide defaults for your detection while letting customizations be set when the function is called. For example:\n```python\nfrom panther_sdk import detection\n\n# This is an example of a factory rule function that might live in panther_detections or your own library of detections.\n# This function accepts an optional overrides object, which is passed through to the Rule instantiation. Any attributes\n# set on the RuleOverrides object will override the attributes defined for the rule.\ndef factory_rule_func(overrides: Optional[detection.RuleOverrides] = None) -> detection.Rule:\n return detection.Rule(\n rule_id=\"default.rule.id\",\n filters=[...],\n log_types=[\"AWS.ALB\"],\n severity=detection.SeverityMedium,\n overrides=overrides,\n )\n\n\n# Here is an example of using the rule factory function.\ndef make_detections() -> None:\n # We can pass no overrides at all, and it will be the default rule the function creates\n r = factory_rule_func()\n print(r)\n\n # We can override the id and severity to create a more customized rule using our function from above\n r = factory_rule_func(overrides=detection.RuleOverrides(\n rule_id=\"not.important.rule\",\n severity=detection.SeverityInfo,\n ))\n print(r)\n\n r = factory_rule_func(overrides=detection.RuleOverrides(\n rule_id=\"very.important.rule\",\n severity=detection.SeverityHigh,\n ))\n print(r)\n\n\n# Now we call our main detection making function to execute it when running this python script\nmake_detections()\n```\n\nSimilar to overrides, you have the ability to add extensions to your Panther content.\nThese can be used the same way as overrides on fields that have lists.\n```python\nfrom panther_sdk import detection\n\n# This is an example of a factory rule function that might live in panther_detections or your own library of detections.\n# This function accepts an optional extensions object, which is passed through to the Rule instantiation. Any attributes\n# set on the RuleExtensions object will override the attributes defined for the rule.\ndef factory_rule_func(extensions: Optional[detection.RuleExtensions] = None) -> detection.Rule:\n return detection.Rule(\n rule_id=\"default.rule.id\",\n filters=[...],\n log_types=[\"AWS.ALB\"],\n severity=detection.SeverityMedium,\n extensions=extensions,\n )\n\n\n# Here is an example of using the rule factory function.\ndef make_detections() -> None:\n # We can pass no extensions at all, and it will be the default rule the function creates\n r = factory_rule_func()\n print(r)\n\n # We can extend filters to add logic to the rule\n r = factory_rule_func(extensions=detection.RuleExtensions(\n filters=[detection.PythonFilter(func=my_very_important_filter)],\n ))\n print(r)\n\n\n# Now we call our main detection making function to execute it when running this python script\nmake_detections()\n```\n\n## Full Dataclass API\n\n\n## detection module\n\n### DynamicStringField\nMake a field dynamic based on the detection input\n\n| Field | Description | Type |\n| ----- | ---- | ----------- |\n| `fallback` | Fallback value in case the dynamic handler fails | `str` |\n| `func` | Dynamic handler | `Optional[Callable[[PantherEvent], str]]` |\n\n\n### DynamicDestinations\nMake destinations dynamic based on the detection input\n\n| Field | Description | Type |\n| ----- | ---- | ----------- |\n| `fallback` | Fallback value in case the dynamic handler fails | `Optional[List[str]]` |\n| `func` | Dynamic handler | `Callable[[PantherEvent], List[str]]` |\n\n\n### AlertGrouping\nConfiguration for how an alert is grouped\n\n| Field | Description | Type |\n| ----- | ---- | ----------- |\n| `period_minutes` | How long should matches be grouped into an alert after the first match | `int` |\n| `group_by` | Function to generate a key for grouping matches | `Optional[Callable[[PantherEvent], str]]` |\n\n\n### PythonFilter\nCreate a filter by referencing a python function\n\n| Field | Description | Type |\n| ----- | ---- | ----------- |\n| `func` | Provide a function whose python source will be used as the filter definition | `Callable[[PantherEvent], bool]` |\n\n\n### UnitTestMock\nMock for a unit test\n\n| Field | Description | Type |\n| ----- | ---- | ----------- |\n| `name` | name of the object to mock | `str` |\n| `return_value` | string to assign as the return value for the mock | `str` |\n\n\n### JSONUnitTest\nUnit test with json content\n\n| Field | Description | Type |\n| ----- | ---- | ----------- |\n| `name` | name of the unit test | `str` |\n| `expect_match` | whether the data should match and trigger an alert | `bool` |\n| `data` | json string | `str` |\n| `mocks` | list of mocks to use in the test | `Optional[List[UnitTestMock]]` |\n\n\n### Policy\nDefine a Policy-type detection to execute against log data in your Panther instance\n\n| Field | Description | Type |\n| ----- | ---- | ----------- |\n| `policy_id` | ID for the Policy | `str` |\n| `ignore_patterns` | Patterns of resource ids to ignore for the policy | `Optional[Union[str, List[str]]]` |\n| `destinations` | Alert destinations for the policy | `Optional[Union[str, List[str], DynamicDestinations]]` |\n| `filters` | Define event filters for the policy | `Union[Union[PythonFilter], List[Union[PythonFilter]]]` |\n| `enabled` | Whether the policy is enabled or not | `bool` |\n| `resource_types` | What resource types this policy will apply to | `Union[str, List[str]]` |\n| `severity` | What severity alerts generated from this policy get assigned | `Union[str, DynamicStringField]` |\n| `name` | What name to display in the UI and alerts. The PolicyID will be displayed if this field is not set. | `Optional[str]` |\n| `description` | Description for the policy | `Optional[Union[str, DynamicStringField]]` |\n| `reference` | The reason this policy exists, often a link to documentation | `Optional[Union[str, DynamicStringField]]` |\n| `reports` | A mapping of framework or report names to values this policy covers for that framework | `Optional[Dict[str, List[str]]]` |\n| `runbook` | The actions to be carried out if this policy fails, often a link to documentation | `Optional[Union[str, DynamicStringField]]` |\n| `tags` | Tags used to categorize this policy | `Optional[Union[str, List[str]]]` |\n| `unit_tests` | Unit tests for this policy | `Optional[Union[Union[JSONUnitTest], List[Union[JSONUnitTest]]]]` |\n| `alert_title` | Title to use in the alert | `Optional[Callable[[PantherEvent], str]]` |\n| `alert_context` | Optional JSON to attach to alerts generated by this policy | `Optional[Callable[[PantherEvent], Dict[str, Any]]]` |\n| `alert_grouping` | Configuration for how an alert is grouped | `Optional[AlertGrouping]` |\n\n\n### Rule\nDefine a Rule-type detection to execute against log data in your Panther instance\n\n| Field | Description | Type |\n| ----- | ---- | ----------- |\n| `rule_id` | ID for the rule | `str` |\n| `severity` | Severity for the rule | `Union[str, DynamicStringField]` |\n| `threshold` | Number of matches received before an alert is triggered | `int` |\n| `name` | Display name for the rule | `Optional[str]` |\n| `log_types` | Log Types to associate with this rule | `Union[str, List[str]]` |\n| `filters` | Define event filters for the rule | `Union[Union[PythonFilter], List[Union[PythonFilter]]]` |\n| `enabled` | Whether the rule is enabled or not | `bool` |\n| `unit_tests` | Define event filters for the rule | `Optional[Union[Union[JSONUnitTest], List[Union[JSONUnitTest]]]]` |\n| `tags` | Tags for the rule | `Optional[Union[str, List[str]]]` |\n| `reference` | Reference for the rule | `Optional[Union[str, DynamicStringField]]` |\n| `runbook` | Runbook for the rule | `Optional[Union[str, DynamicStringField]]` |\n| `description` | Description for the rule | `Optional[Union[str, DynamicStringField]]` |\n| `summary_attrs` | Summary Attributes for the rule | `Optional[List[str]]` |\n| `reports` | Report mappings for the rule | `Optional[Dict[str, List[str]]]` |\n| `destinations` | Alert destinations for the rule | `Optional[Union[str, List[str], DynamicDestinations]]` |\n| `alert_title` | Title to use in the alert | `Optional[Callable[[PantherEvent], str]]` |\n| `alert_context` | Optional JSON to attach to alerts generated by this rule | `Optional[Callable[[PantherEvent], Dict[str, Any]]]` |\n| `alert_grouping` | Configuration for how an alert is grouped | `Optional[AlertGrouping]` |\n\n\n### ScheduledRule\nDefine a ScheduledRule-type detection to execute against query results in your Panther instance\n\n| Field | Description | Type |\n| ----- | ---- | ----------- |\n| `rule_id` | ID for the scheduled rule | `str` |\n| `severity` | What severity alerts generated from this scheduled rule get assigned | `Union[str, DynamicStringField]` |\n| `threshold` | Number of matches received before an alert is triggered | `int` |\n| `name` | Display name for the scheduled rule | `Optional[str]` |\n| `scheduled_queries` | Scheduled queries to associate with this scheduled rule | `Union[str, List[str]]` |\n| `filters` | Define event filters for the scheduled rule | `Union[Union[PythonFilter], List[Union[PythonFilter]]]` |\n| `enabled` | Short description for the scheduled rule | `bool` |\n| `unit_tests` | Define event filters for the scheduled rule | `Optional[Union[Union[JSONUnitTest], List[Union[JSONUnitTest]]]]` |\n| `tags` | Tags for the scheduled rule | `Optional[Union[str, List[str]]]` |\n| `reference` | Reference for the scheduled rule | `Optional[Union[str, DynamicStringField]]` |\n| `runbook` | Runbook for the scheduled rule | `Optional[Union[str, DynamicStringField]]` |\n| `description` | Description for the scheduled rule | `Optional[Union[str, DynamicStringField]]` |\n| `summary_attrs` | Summary Attributes for the scheduled rule | `Optional[List[str]]` |\n| `reports` | Report mappings for the scheduled rule | `Optional[Dict[str, List[str]]]` |\n| `destinations` | Alert destinations for the scheduled rule | `Optional[Union[str, List[str], DynamicDestinations]]` |\n| `alert_title` | Title to use in the alert | `Optional[Callable[[PantherEvent], str]]` |\n| `alert_context` | Optional JSON to attach to alerts generated by this rule | `Optional[Callable[[PantherEvent], Dict[str, Any]]]` |\n| `alert_grouping` | Configuration for how an alert is grouped | `Optional[AlertGrouping]` |\n\n## query module\n\n### CronSchedule\nCron expression based schedule definition for a query\n\n| Field | Description | Type |\n| ----- | ---- | ----------- |\n| `expression` | Defines how often queries using this schedule run | `str` |\n| `timeout_minutes` | Defines the timeout applied to queries with this schedule | `int` |\n\n\n### IntervalSchedule\nInterval based schedule definition for a query\n\n| Field | Description | Type |\n| ----- | ---- | ----------- |\n| `rate_minutes` | Defines how often queries using this schedule run | `int` |\n| `timeout_minutes` | Defines the timeout applied to queries with this schedule | `int` |\n\n\n### Query\nA saved or scheduled query\n\n| Field | Description | Type |\n| ----- | ---- | ----------- |\n| `name` | Unique name for the query | `str` |\n| `description` | Short description for the query | `str` |\n| `default_database` | Default database for the query | `str` |\n| `sql` | SQL statement | `str` |\n| `enabled` | Whether the query is enabled or not | `bool` |\n| `tags` | Tags for the query | `Optional[Union[str, List[str]]]` |\n| `schedule` | Schedule attached to the query | `Optional[Union[IntervalSchedule, CronSchedule]]` |\n\n## schema module\n\n### DataModelMapping\n\n\n| Field | Description | Type |\n| ----- | ---- | ----------- |\n| `name` | Name of the data model field. This will be the name used when accessing the field from within detections. | `str` |\n| `path` | Path to the target value in the Panther Event. This can be a simple field name or complete JSON path starting with a `$`. JSON path syntax must be compatible with the [jsonpath-ng](https://pypi.org/project/jsonpath-ng/) Python package. | `Optional[str]` |\n| `func` | A Python function to access the target value. The input is the Panther Event and output is the target value in the Panther Event. | `Optional[Callable[[PantherEvent], Any]]` |\n\n\n### DataModel\nData Models provide a way to configure a set of unified fields across all log types.\n\n| Field | Description | Type |\n| ----- | ---- | ----------- |\n| `data_model_id` | The unique identifier of the data model. | `str` |\n| `name` | What name to display in the UI and alerts. The `data_model_id` will be displayed if this field is not set. | `Optional[str]` |\n| `enabled` | Whether this data model is enabled. | `Optional[bool]` |\n| `log_type` | What log type this data model will apply to. | `str` |\n| `mappings` | Mapping from source field name or method to unified data model field name. | `Union[DataModelMapping, List[DataModelMapping]]` |\n\n\n",
"bugtrack_url": null,
"license": "",
"summary": "",
"version": "0.0.24",
"split_keywords": [
"security",
"detection"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "508269b068c129049f52c872fd55d4004c4229b48d5e821ca986d355c8b1f727",
"md5": "39e7ef24efa05be600fe3d61fabf8442",
"sha256": "30fb1c9d4931fb741cffaed23f611943288e26de82daa15cf8f27e41124008af"
},
"downloads": -1,
"filename": "panther_sdk-0.0.24.tar.gz",
"has_sig": false,
"md5_digest": "39e7ef24efa05be600fe3d61fabf8442",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 34901,
"upload_time": "2023-02-07T16:55:59",
"upload_time_iso_8601": "2023-02-07T16:55:59.589227Z",
"url": "https://files.pythonhosted.org/packages/50/82/69b068c129049f52c872fd55d4004c4229b48d5e821ca986d355c8b1f727/panther_sdk-0.0.24.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-02-07 16:55:59",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "panther-sdk"
}
JSON