Last updated
Was this helpful?
Last updated
Was this helpful?
One method you can use to leverage Panther-managed Python detections within your is to create a private cloned repo of .
If your organization wishes to keep your body of detections and other associated Panther configurations private, a private cloned repo of is the best option. In a private cloned repo, your local repository settings control who has access to the content inside the repo.
Once you have configured your private cloned repo as described below, you can create branches and leverage Pull Requests to bring in customizations to your body of detections.
For information on creating a public fork of the repo, see .
The following is the configuration we recommend based on currently supported functionality.
Create a private repository in GitHub.
For instructions, see . When setting the repository's visibility, select Private.
Keep the default settings - do not initialize your repository with any content.
Clone and use git push --mirror to seed your private cloned repo with upstream's git content and history.
gh repo clone panther-labs/panther-analysis
cd panther-analysis
git checkout main
git push --mirror https://github.com/your_org/your_private_repo.git
For more information about maintaining a mirror of a repository, see .
Enable correct workflow permissions for the repository in GitHub.
Within your private repository, navigate to Settings > Actions > General.
Make the following selections in the Workflow permissions section:
Toggle Read and write permissions on.
Check Allow GitHub Actions to create and approve pull requests.
Click Save.
Locally, clone your private repository, make a new branch, and create a directory for your local detection content within the existing rules/ directory:
git checkout -b feat/my_first_branch
mkdir rules/my_local_rules
Add a sample rule:
Under templates/, locate example_rule.py and example_rule.yml.
Copy them into rules/my_local_rules/.
cp templates/example_rule.* rules/my_local_rules
Run make venv then run make test to set up your local Python environment and run the test suite.
If you made no changes to the files, you should see an error similar to the following: Key 'LogTypes' error: LOG_TYPE_REGEX does not match 'LogType.Name'
Resolve the errors that appeared after the previous step:
Change LogType to a known log source in Panther, such as AWS.CloudTrail in example_rule.yml
Change Filename inside example_rule.yml to example_rule.py.
Commit your changes to your remote from the current branch. (git rev-parse –abbrev-ref HEAD provides the current branch, you can also opt to provide this value yourself.)
git add rules/my_local_rules
git commit -m "feat: new example rules"
git push origin `git rev-parse --abbrev-ref HEAD`
This command provides a link in the output.
Use the link from the output of the previous step's git push to create a pull request for your branch.
Merge your pull request and optionally delete your branch.
Create a GitHub token with the following permissions:
Administration - Read
Contents - Read and write
Metadata - Read
Pull Requests - Read and write
Workflows - Read and write
In your forked repository, add a new secret named PANTHER_SYNC_UPSTREAMand set its value as the token you created in the previous step.
If you skip this step, each time the upstream repository has changes within the .github/workflows directory, the Action will fail to open a PR.
To trigger the Action for the first time, syncing your fork with the upstream repository, in your repository in GitHub, click Actions > Sync Panther Analysis from Upstream.
Click Run Workflow > Run workflow.
Once the action is complete, you will see a green circle next to the workflow run. If there are changes, you should see a new open pull request authored by GitHub Actions. If there are no changes, you should see a message similar to “Local repo already synced to latest release.”
The Sync Panther Analysis from Upstream Action is configured to run on a cron schedule every Tuesday at 15:00Z. You can modify this schedule on line 6 of .github/workflows/sync-from-upstream.yml.
Merge the pull request into your primary branch, as you would with a normal pull request.
Your repository will reflect the merge as your latest change, and you will be able to view both your private repo and panther-analysis git histories.
You can create your own GitHub Action to upload detection content to your Panther instance, and it can be configured to run automatically on each merged pull request to your repo.
Customers are encouraged to contribute content back upstream to panther-analysis. However, making a Pull Request back upstream is only possible from a public repository. If you use a private repo and would like to contribute content, please reach out to the Panther Support team.
We recommend that you leverage Panther's GitHub Action to stay in sync with upstream changes:
If you run into issues with merge conflicts or see an error that states "all jobs have failed," please see this troubleshooting article:
After you clone the repo, you can integrate Panther detections into your CI/CD workflow. Panther offers documentation for and .
See for more information.