Metadata-Version: 2.1
Name: pypanther
Version: 0.1.1a48
Summary: 
License: AGPL-3.0-only
Keywords: Security,CLI
Author: Panther Labs Inc
Author-email: pypi@runpanther.io
Requires-Python: ==3.11.*
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Requires-Dist: aiohttp (>=3.9.5,<3.10.2)
Requires-Dist: ast-comments (>=1.2.2,<2.0.0)
Requires-Dist: boto3 (>=1.34.99,<2.0.0)
Requires-Dist: colorama (>=0.4.6,<0.5.0)
Requires-Dist: dynaconf (>=3.2.5,<4.0.0)
Requires-Dist: gql (>=3.5.0,<4.0.0)
Requires-Dist: jsonpath-ng (>=1.6.1,<2.0.0)
Requires-Dist: panther-core (>=0.10,<1.0)
Requires-Dist: panther-detection-helpers (>=0.4.0,<0.5.0)
Requires-Dist: policyuniverse (>=1.5.1.20231109,<2.0.0.0)
Requires-Dist: prettytable (>=3.10.0,<4.0.0)
Requires-Dist: pydantic (>=2.7.1,<3.0.0)
Requires-Dist: ruamel-yaml (>=0.18.6,<0.19.0)
Description-Content-Type: text/markdown

# pypanther

**pypanther** is a Python library for building Panther analysis content for the Panther cybersecurity product.
It provides a simple and intuitive interface for creating, managing, and deploying detections to enhance your security posture.
Included is a `pypanther` CLI tool to interact with your content and upload it to the Panther web app.

## Features

- **Rule Creation**: Easily create rules using Python classes and inheritance.
- **Management**: Organize and manage rules efficiently with native Python.
- **Deployment**: Upload detections and more to Panther for real-time detection.

## Installation

To install **pypanther**, use pip:

```bash
pip install pypanther
```

## Prerequisites

- Python 3.11 or higher
- [Panther](https://panther.com) account and API access

## Usage

1. **Import pypanther**: Start by importing pypanther into your Python script.
2. **Create Rules**: Subclass the `Rule` class to define new rules.
3. **Register Rules**: Register your custom rules and Panther managed rules inside your `main.py` file.
4. **Test Rules**: Test all your registered rules using `pypanther test`.
5. **Upload Rules**: Upload all registered rules with your Panther deployment using the CLI tool (`pypanther upload`).

## Getting Started

Here is a simple example to get you started:

```python
from pypanther import Rule, register, LogType, Severity


# Create a new rule
class MyRule(Rule):
    id = "MyRule"
    default_severity = Severity.HIGH
    log_types = [LogType.OKTA_SYSTEM_LOG]

    def rule(self, event):
        return event.get("status") == "breached"


# register the rule
register(MyRule)
```

Check out the [pypanther-starter-kit](https://github.com/panther-labs/pypanther-starter-kit) for more examples on how to use `pypanther`.

You can view detailed docs on the package and CLI tool on the [panther docs]().

## Local Development

We use [Poetry](https://python-poetry.org/) for dependency management and packaging. Poetry makes it easy to set up a consistent and
isolated development environment.

### Setting Up for Local Development

1. **Install Poetry**: Follow the instructions on the [Poetry website](https://python-poetry.org/docs/#installation) to install Poetry.

2. **Clone the repository**: Clone the `pypanther` repository to your local machine.

    ```bash
    git clone git@github.com:panther-labs/pypanther.git
    cd pypanther
    ```

3. **Install dependencies**: Use Poetry to install the project's dependencies.

    ```bash
    poetry install
    ```

   This will create a virtual environment and install all necessary dependencies specified in the `pyproject.toml` file.

4. **Activate the virtual environment**: You can activate the virtual environment created by Poetry using:

    ```bash
    poetry shell
    ```

5. **Testing Locally**: You can create a `main.py` file within the `pypanther` directory to test commands and functionality
   locally. This file can be used to run test commands or interact with `pypanther` features.

    - **Create a `main.py` file**: Here is an example main file. Assumes you have a folder called `custom_rules` with all your test rules.

        ```python
        # pypanther/main.py

        from pypanther import register, get_panther_rules, get_rules
        import custom_rules
      
      
        register(get_panther_rules())
        register(get_rules(custom_rules))
        ```

    - **Running the CLI**: Use the following command to run `main.py` with Poetry:

        ```bash
        poetry run python ./pypanther/main.py <cmd>
        ```

      Replace `<cmd>` with any specific commands you want to test (e.g. `test` and `upload`)

6. **Adding Dependencies**: If you need to add new dependencies, use the following command:

    ```bash
    poetry add <package-name>
    ```

   This will update the `pyproject.toml` file with the new dependency.

## Contributing

We welcome contributions! Please fork the repository and submit a pull request for review. For major changes, please open an issue first to
discuss what you would like to change.

## Issues

If you encounter any issues or have questions, please open a support ticket.

## License

**pypanther** is released under the [GNU Affero General Public License](LICENSE.txt).

