Private Clone

One method you can use to leverage Panther-managed Python detections within your CI/CD workflow is to create a private cloned repo of panther-analysis.

If your organization wishes to keep your body of detections and other associated Panther configurations private, a private cloned repo of panther-analysis 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 Public Fork.

It's recommended to pull upstream changes from panther-analysis when there is a new tagged release. You can also pull from the main branch. No other branches should be considered stable.

Configuring the private clone of the panther-analysis repo

The following is the configuration we recommend based on currently supported functionality.

1. Create a private repository in GitHub.

   • For instructions, see GitHub's documentation: Create a repo. When setting the repository's visibility, select Private.

   • Keep the default settings - do not initialize your repository with any content.

2. Clone panther-analysis and use git push --mirror to seed your private cloned repo with upstream's git content and history.

   1. gh repo clone panther-labs/panther-analysis

   2. cd panther-analysis

   3. git checkout main

   4. git push --mirror https://github.com/your_org/your_private_repo.git For more information about maintaining a mirror of a repository, see GitHub's documentation: Duplicating a repository.

3. Enable correct workflow permissions for the repository in GitHub.

   1. Within your private repository, navigate to Settings > Actions > General.

   2. 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.

   3. Click Save.

4. Locally, clone your private repository, make a new branch, and create a directory for your local detection content within the existing rules/ directory:

   1. git checkout -b feat/my_first_branch

   2. mkdir rules/my_local_rules

5. Add a sample rule:

   1. Under templates/, locate example_rule.py and example_rule.yml.

   2. Copy them into rules/my_local_rules/.

      1. cp templates/example_rule.* rules/my_local_rules

6. 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'

7. Resolve the errors that appeared after the previous step:

   1. Change LogType to a known log source in Panther, such as AWS.CloudTrail in example_rule.yml

   2. Change Filename inside example_rule.yml to example_rule.py.

8. 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.)

   1. git add rules/my_local_rules

   2. git commit -m "feat: new example rules"

   3. git push origin `git rev-parse --abbrev-ref HEAD`

      • This command provides a link in the output.

9. Use the link from the output of the previous step's git push to create a pull request for your branch.

10. Merge your pull request and optionally delete your branch.

Keeping the private clone up to date with automated updates

We recommend that you leverage our included sync-panther-analysis-from-upstream GitHub Action to stay in sync with upstream:

1. Log in to your GitHub account and navigate to your repository.

2. In the horizontal menu bar, click Actions, then click the sync-panther-analysis-from-upstream action.

3. 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.”

   • Note: 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.

4. 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.

If you run into issues with merge conflicts or see an error that states "all jobs have failed," please see this troubleshooting article: How do I resolve merge conflicts and failed syncs when using the GitHub Action sync-panther-analysis-from-upstream?

Next Steps

After you clone the repo, you can integrate Panther detections into your CI/CD workflow. Panther offers documentation for CircleCI and GitHub Actions.

GitHub Actions

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.

See Managing Content via GitHub Actions for more information.

Customer contributed content

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.