Configure a source control repository for your Splunk SOAR (On-premises) playbooks

You can save your Splunk SOAR (On-premises) playbooks in Git repositories. By default, playbooks are managed in a Git repository called local. You can create additional Git repositories as needed, so you can perform the following tasks:

  • Import and export playbooks and share facilities among Splunk SOAR (On-premises) instances. For example, you can use Git to publish playbooks from a development Splunk SOAR (On-premises) environment to a separate production environment.
  • Edit playbooks using a tool of your choice instead of the Splunk SOAR (On-premises) web interface.
Note: If you edit a playbook outside of the Visual Playbook Editor (VPE), you can no longer use drag and drop blocks in the VPE to edit that playbook. After that, you can only perform subsequent edits in the VPE by editing the full playbook. This is not recommended.

Splunk SOAR (On-premises) also uses a Git repository to publish company-authored playbooks for you to download. This repository is called the community repository and is configured on Splunk SOAR (On-premises) by default. You can restore this repository if you accidentally remove it. See Restore the community playbook repository.

You can transfer playbooks to Git using HTTP, HTTPS, or Git. Other protocols can be authenticated or anonymous if supported by the server.

Access the source control settings in Splunk SOAR (On-premises)

To access the Splunk SOAR (On-premises) source control settings, perform the following steps:

  1. From the Home menu, select Administration.
  2. Select Administration Settings, then Source Control.

You can also access the source control settings from any Playbooks page by selecting Manage source control.

Set up a playbook repository using HTTP, HTTPS, or Git

To set up a Git repository using HTTP, HTTPS, or Git protocols, perform the following steps:

  1. From the Home menu, select Administration.
  2. Select Administration Settings, then Source Control.
  3. From the Repositories list, select Configure a new repository.
  4. Provide a repository URL, repository name, and branch name. The repository name can be any name that describes your repository. If you are using a subdirectory, its path must already exist. This configuration panel does not create new subdirectories.
    For details on creating a new subdirectory, see the next section, Move playbooks to a different or new subdirectory.
  5. Provide the path to the playbooks directory within the repository. The path must end with a slash (/). To store playbooks at the root level, leave this field blank.
  6. For HTTP and HTTPS, specify a username and password. Splunk SOAR (On-premises) attempts to connect anonymously if no username or password is provided. When crafting the URI, Splunk SOAR (On-premises) converts https://server... to https://username:password@server.... The Git protocol is not authenticated and does not require a username or password.
  7. Select Save Changes.

Note the following important points:

  • You cannot edit a repository after it is added to Splunk SOAR (On-premises). If you need to make a change, for example, if you change the subdirectory where the playbooks are stored, you must create a new source control repository in Splunk SOAR (On-premises) using the process described above. Delete unused repositories, as described later in this article.
  • The repository must contain at least one commit in order to be added to Splunk SOAR (On-premises).
Note: The username and password strings are separated so that the password can be encrypted and stored and not displayed to other administrators. However, passwords are stored as clear text in the Git configuration file for that repository.

Move playbooks to a different or new subdirectory

You might choose to move your organization's playbooks to their own subdirectory, separating them from other files in a repository. This involves updating the Git repository, using any Git client. The steps below are similar to the process described in the GitHub documentation for moving a file to a new location.

Note: If you use multiple branches of the repository, repeat these steps for each branch.

To update the Git repository for your playbook storage path, follow these steps:

  1. SSH into your Splunk SOAR (On-premises) instance.
  2. Go to your repository's directory by running cd /opt/phantom/scm/git/<repo-name>.
  3. Create the new directory where you want to store playbooks, if it does not already exist in the Git repository. For example mkdir playbooks.
  4. Move all existing playbook files to the directory where you want to store them. For example, mv *.py playbooks/ followed by mv *.json playbooks/.
  5. Run git add --all.
  6. Run git commit -m "Moving playbooks to new folder".
  7. Run git push origin <branch-name>.
  8. Return to the Splunk SOAR (On-premises) Administration page.
  9. Complete the steps described in the previous section to configure a new source control repository, using the new path to the playbooks.
  10. Delete the original, now unused, source control repository, as described in the next section of this article, Delete a source control repository in Splunk SOAR (On-premises).

Delete a source control repository in Splunk SOAR (On-premises)

Delete unused source control repositories to avoid confusion and clutter.

To delete a source control repository in Splunk SOAR (On-premises), follow these steps:

  1. From the Home menu, select Administration.
  2. Select Administration Settings, then Source Control.
  3. In the Repositories list, select the repository you want to delete.
  4. Select Delete.

Git hooks and the Splunk SOAR Playbook Editor

Splunk SOAR (On-premises) does not directly support Git hooks. If you choose to use Git hooks in your system, be aware of the following:

  • There is a risk that the playbook editor will not be able to save or push changes because the Git configuration rejects a commit.
  • To avoid this issue, direct Splunk SOAR (On-premises) to push to a staging repository or branch that will not reject pushes. This prevents the playbook editor from being blocked from saving and pushing changes. Handle merge conflicts or other issues manually when pushing from the staging repository to the original repository.

If Git remote rejects your commits, causing the push to fail, you have two options:

  • Delete and recreate
    1. Delete the repository in Git and recreate it in Splunk SOAR (On-premises), using the steps described in the Set up a playbook repository using HTTP, HTTPS, or Git section of this article. . The playbook reverts to the last successful push and removes all changes made after the last successful push.
    2. Recreate your changes and try to push again.
  • Remediate the issue from the command line. Continue reading the next section.

To remediate the issue from the command line, follow the set of the instructions that matches your scenario.

Note: You must have some expertise with Git or refer to Git documentation to perform some of the steps described in this section.

Problem commit is your most recent commit

If your most recent local commit is causing the problem, and you have not made subsequent commits, choose one of the following options:
Option 1:

  1. Delete the most recent commit by running git reset --hard HEAD~1.
  2. Recreate your changes and try to push again.

Option 2:

  1. Make the necessary changes in your repository so it will pass the hook.
  2. Replace your previous commit with this current state of the repository by running git commit --amend
  3. Try to push again.

Problem commit is not your most recent commit

Choose the option that best matches your scenario:
Option 1:
If your playbook editor is blocked from pushing to the remote repository, follow these steps:

  1. Delete the repository and recreate it in Splunk SOAR (On-premises). The playbook reverts to the last successful push and removes all changes made after the last successful push.
  2. Recreate your changes and try to push again.

Option 2:

Otherwise, perform an interactive rebase in Git by following these steps:

  1. Start the interactive rebase by running git rebase -i <identifier>~1
    • The identifier refers to the working version of the branch, such as origin/master or the commit hash for the last working commit.
    • Append ~1 to start the rebase on the commit before the last working version.
  2. Git displays a file that lists all of the commits in order. Choose an option:
    • To delete the problematic commit entirely, delete the line with the commit, while keeping the subsequent commits.
    • To amend the problematic commit, modify line for that commit, replacing pick <hash> with edit <hash>. After you write and close this file, Git starts rebasing. Git pauses when it reaches that line. Then you can use git commit --amend to repair the commit.
  3. After the rebase completes successfully, push to the repository. If performing the rebase caused the commit history to diverge, you must perform a force push.

Set up a playbook repository using SSH

To set up a playbook repository using SSH, perform the following steps:

  1. From the main menu, select Administration.
  2. Select Administration Settings then select Source Control.
  3. In the Repositories field, select Configure a new repository.
  4. Provide a repository URL starting with ssh:// and including the username. For example: ssh://<username>@10.4.5.6/opt/repos
  5. Add the SSH public key from Splunk SOAR (On-premises) to your Git server's authorized keys file.
    1. Copy the contents in the SSH Public Key field.
    2. Log in to your Git server as a user with permissions to edit the Git server's authorized_keys file.
    3. Add the SSH public key to the authorized key file, such as ~/.ssh/authorized_keys.
  6. Provide a repository name and branch name. The repository name can be any name that describes your repository.

If you get the following error when setting up an external repo with SSH Auth:

Cmd('git') failed due to: exit code(128) cmdline: git fetch -v origin stderr: 'fatal: Could not read from remote repository. Please make sure you have the correct access rights and the repository exists.'
This indicates that the /home/<phantom_user>/.ssh/known_hosts file is not being updated with the external repo and ssh key info.

You can manually correct this through the CLI by running the following command as the Splunk SOAR (On-premises) user: 

ssh-keyscan -t rsa <external_repo> >> /home/<phantom_user>/.ssh/known_hosts

Establish trust with the git repository from your Splunk SOAR (On-premises) deployment

You must inform git that it can trust the remote hosts of your Splunk Phantom deployment before you can use the source repository.

On your Splunk SOAR (On-premises) instance, or in the case of a cluster, on each Splunk SOAR (On-premises) cluster node:

  1. SSH to the Splunk SOAR (On-premises) instance or cluster node. Log in as the user account that runs Splunk SOAR (On-premises). 
    ssh phantom@<phantom instance or cluster node>
  2. Run the command to establish trust with the git repository. 
    git ls-remote git@<address of the git repository>
  3. Verify that the information returned is correct. Example: 
    git ls-remote git@your-git-repository:phantom/phantom.git
  4. If the returned values are correct, enter yes.

Set up a playbook repository using HTTPS with a self-signed certificate

If your HTTPS server is using a self-signed certificate, you need to import your certificate authority (CA) file to the Splunk SOAR (On-premises) certificate store and then configure Git to use it. If you don't do this, trying to add a new playbook repository results in an error mentioning an untrusted certificate. To set up a playbook repository using HTTPS with a self-signed certificate, follow these steps:

  1. Import the CA file to the Splunk SOAR (On-premises) certificate store. See Add, remove, or replace certificates from the Splunk SOAR (On-premises) certificate store.
  2. Configure the environment variable. See Set global environment variables. Enter GIT_SSL_CAINFO as the variable name and the value as <phantom home>/etc/cacerts.pem.
  3. Configure the repository. See Set up a playbook repository using HTTP, HTTPS, or Git on this page. Git is now able to connect.

Restore the community playbook repository

The community playbook repository is a collection of playbooks vetted by the Splunk SOAR (On-premises) community. This repository is configured by default when Splunk SOAR (On-premises) is installed. Follow the procedure to restore the community repository if it is accidentally altered or deleted.

  1. From the Home menu, select Administration.
  2. Select Source Control.
  3. In the Repositories field, select Configure a new repository.
  4. In the Repo URL field, enter the URL: https://github.com/phantomcyber/playbooks.git
  5. In the Repo Name field, enter community.
  6. In the Branch Name field, enter the version of Splunk SOAR (On-premises) you are running, up to the second set of digits. For example, if you are running version 6.1.1 enter 6.1 in this field.
  7. Select the Read Only check box.
  8. Select Save Changes.