Configure a source control repository for your Splunk Phantom playbooks

You can save your Splunk Phantom playbooks in Git repositories. By default, playbooks are managed in a Git repository called local. You can create additional Git repositories as needed. Doing so enables you to perform the following tasks:

• Import and export playbooks and share facilities among Splunk Phantom instances. For example, you can use Git to publish playbooks from a development Splunk Phantom environment to a separate production environment.
• Edit playbooks using a tool of your choice instead of the Splunk Phantom web interface.

Once 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. Any subsequent edits in the VPE are only possible by editing the full playbook. This is not recommended.

In a clustered Splunk Phantom deployment, each cluster node uses the same Git repository based on the shared services server. You don't need to configure one Git repository per cluster node.

Splunk Phantom also uses a Git repository to publish company-authored playbooks for customers to download. This repository is called the community repository and is configured on Splunk Phantom 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, Git, or SSH. SSH must be authenticated. Other protocols can be authenticated or anonymous if supported by the server.

Access the source control settings in Splunk Phantom

To access the Splunk Phantom source control settings, perform the following steps:

1. From the main menu, select Administration.
2. Select Administration Settings > Source Control.

You can also access the source control settings from any Playbooks page by clicking 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 main menu, select Administration.
2. Select Administration Settings > Source Control.
3. Select Configure a new repository from the Repositories drop-down list.
4. Provide a repository URL, repository name, and branch name. The repository name can be any name that describes your repository.
   • For HTTP and HTTPS, specify a username and password.
     Splunk Phantom attempts to connect anonymously if no username or password is provided. When crafting the URI, Splunk Phantom converts https://server... to https://username:password@server.... The Git protocol is not authenticated and does not require a username or password.
   • For github, specify your personal access token rather than a plain password.
5. Click Save Changes.

A repository that is added to Splunk Phantom can't be edited. If you need to make a change, delete the repository and then add it again.

The username and password strings are separated so that Splunk Phantom can encrypt and store the password as it does with asset passwords, and not display the password to other Splunk Phantom administrators. However, due to the way Splunk Phantom interacts with and uses Git, it is stored as clear text in the Git configuration file for that repository.

Configure Git to trust your organization's self-signed certificate

By default, the Git client uses the OpenSSL certificate authority list to verify HTTPS certificates. To configure Git to trust your organization's self-signed certificate, follow these steps:

1. Import the self signed certificate into the Splunk Phantom certificate store.

   phenv python3 /opt/phantom/bin/import_cert.py -i /<path>/<cert>
   

2. Restart UWSGI.

   /opt/phantom/bin/phsvc restart uwsgi
   

3. Configure Git to trust the Splunk Phantom PEM.

   git config --file /opt/phantom/etc/gitconfig http.sslCAInfo /opt/phantom/etc/cacerts.pem
   

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 > Source Control.
3. Select Configure a new repository from the Repositories drop-down list.
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 Phantom 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 Phantom user:

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

Establish trust with the git repository from your Splunk Phantom 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 Phantom instance, or in the case of a cluster, on each Splunk Phantom cluster node:

1. SSH to the Splunk Phantom instance or cluster node. For unprivileged deployments, log in as the user account that runs Phantom.

   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, type yes.

Use repositories from the Playbooks page

You can make use of configured repositories on the Playbooks page. See View the list of configured playbooks for more information.

Restore the community playbook repository

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

1. From the main menu, select Administration.
2. Select Source Control.
3. In the Repositories drop-down list, select Configure a new repository.
4. In the Repo URL field, type the URL: https://github.com/phantomcyber/playbooks.git
5. In the Repo Name field, type community.
6. In the Branch Name field, enter the version of Splunk Phantom you are running, up to the second digit. For example, if you are running version 4.6.12345, enter 4.6 in this field.
7. Check the Read Only check box.
8. Click Save Changes.

If you have a Splunk Phantom cluster, each cluster node uses the same playbook repository. You do not need to configure the repository on each cluster node.