Apiary Integration

Depending on your workflow, Apiary can be integrated with external applications and platforms using REST API Tokens and Webhooks.

Note: only Apiary project owners or platform administrators can configure integration.

Integration with Jira

To configure an integration with Jira, perform the following steps:

1. Open your project;
2. In the left menu select Projects > Settings > Integrations;

3. Click on Jira:

4. In Jira Configure window select your Jira server:

5. Depending on your Jira server settings, fill in the fields (all fields are mandatory):

   • connection via Webhooks - fill in Login, Password and Jira Connection name:
     • • if you're using HashiCorp Vault to store the user password, follow the instruction how to integrate Vault and Apiary here
   • connection via Tokens - fill in E-mail, Token and Jira Connection name (see article Manage API tokens):

   Note: you can use an API token to authenticate a script or other process with an Atlassian cloud product. You can generate the token from your Atlassian account, then copy and paste it to the script.

6. Click Next;

7. In Project field specify your Jira project;

8. In Issue type field specify type of the task that will be created for vulnerabilities in your Jira project;

   • Enable Reverse synchronization (optional) to assign issue statuses for Jira tasks;

   Note: you can assign custom issue statuses for Jira issues, but remember that custom issue statuses in Apiary are not synchronized with Hive issue statuses.

   • Enable Sync comments (optional) to synchronize issue comments in Apiary and Jira;

9. Click Save. New Jira connection will be added to the Integrations page.

Note: you can set up integration with several Jira projects in one Apiary project at the same time. In this case, you will be able to send issues to several Jira projects and read comments from different Jira projects in one issue.

Integration with HashiCorp Vault

HashiCorp Vault is a secrets management tool specifically designed to control access to sensitive credentials. It can be used to store sensitive values and at the same time dynamically generate access for specific services/applications on lease.

After you complete the Vault integration with Apiary, you will be able to connect Apiary with AD/SMTP/Jira by specifying not the plain password for the service account, but the path in Vault, where this password is stored.

If you already have HashiCorp Vault installed in your company, proceed with Apiary configuration.

If you don't have the Vault previously configured, you can use the following steps to prepare it for the integration with Hive.

Vault configuration

1. Open the console of the virtual machine, where Apiary is installed.

2. Set environment variables to be able to connect to Vault by running the commands:

   export VAULT_ADDR=<VAULT_URL>
   export VAULT_TOKEN=<VAULT_TOKEN>
   

   where

   • VAULT_ADDR - URL of the Vault server,
   • VAULT_TOKEN - token, used to access the Vault.

More info about these parameters can be found here.

3. Enable a key-value secret engine v1 or/and v2:

   vault secrets enable -path=<kv mount point> kv
   vault secrets enable -path=<kv mount point> -version=2 kv
   

   Example:

   vault secrets enable -path=test_point -version=2 kv
   

<kv mount point> can take any value, e.g. -path=test_point.
You can also remove -path parameter. In this case it will take the default value - kv

4. Set the vault policy by creating an .hcl file and adding the following setting into it:

   path "<kv mount point>/*" {
   capabilities = ["read"]
   }
   

   where <kv mount point> is the path you've created in step 3.

   Example:

   cat > test.hcl
   
   path "test_point/*" {
   capabilities = ["read"]
   }
   

5. Apply the created policy by running the command:

   vault policy write <policy_name> './<file_name>.hcl'
   

   Example:

   vault policy write test_readonly './test.hcl'
   

6. Enable and create the approle:

   vault auth enable -path=<approle mount point> approle
   vault write auth/<approle mount point>/role/<vault-approle> token_policies=<policy_name>
   

   where

   • approle mount point - name of the approle mount point (you can set any value; will be used as VAULT.AUTH.MOUNT_POINT in Apiary configuration
   • vault-approle - name of the approle itself (name of the application, for which this role is created, is usually used)
   • policy_name - name of the policy created in step 4.

   Example:

   vault auth enable -path=test_approle approle
   
   vault write auth/test_approle/role/apiary_approle token_policies="test_readonly"
   

7. Read approle id. This value will be used as VAULT_ROLE_ID variable in Apiary configuration:

   vault read auth/<approle_mount_point>/role/<vault-approle>/role-id
   

   Example:

   vault read auth/test_approle/role/apiary_approle/role-id
   

8. Read unwrapped secret id:

   vault write -f auth/<approle_mount_point>/role/<vault-approle>/secret-id
   

   Example:

   vault write -f auth/test_approle/role/apiary_approle/secret-id
   

9. Write the secret-id value in a .txt file and make note of the full path to this file.
   It will be used for VAULT.SECRET_ID.UNWRAPPED.FILE_PATH property in Apiary configuration.

10. Read wrapped secret id:

    vault write -wrap-ttl=<time_in_sec> -force auth/<approle_mount_point>/role/<vault-approle>/secret-id
    

    where wrap-ttl - timeframe in seconds, during which the token is valid.

    Example:

    vault write -wrap-ttl=360s -force auth/test_approle/role/apiary_approle/secret-id
    

11. Write the wrapping token value in a .txt file and make note of the full path to this file.
    It will be used for VAULT.SECRET_ID.WRAPPED.FILE_PATH property in Apiary configuration.

Now you can proceed with Apiary configuration.

Apiary configuration

Pre-requisites:

• JQ tool is installed on the Apiary server.

• The passwords for LDAP, SMTP and Jira admin accounts are saved as secrets in Vault as described here or via GUI.

  If you are adding the secret via CLI, make note of the path and the name of the key you created.

  These parameters will be used as path and key values accordingly when service password for LDAP, JIRA, SMTP connection is set up.

To initiate the connection, you need to do the following:

1. Open the console of the machine, where Apiary is installed.
2. Open the file /opt/hw-fh/config/user.ini for editing (root privileges required).
3. The following parameters should be added, depending on the secret type (wrapped or unwrapped) and the connection type (http or https):

Below you can find the examples of the configuration:

• if the secret is wrapped:

  vault.address = https://my-vault.example.com:8200
  vault.auth.mount_point = test_approle
  vault.role_id.value = 55cdf32b-498a-c989-a18f-ef3b4aa0eece
  vault.secret_id.unwrapped.file_path = /opt/vault_secret/unwrapped.txt
  vault.secret_id.wrapped.file_path = opt/vault_secret/wrapped.txt
  vault.secret_id.unwrap.engine_type = approle
  

• if the secret is unwrapped:

  vault.address = https://my-vault.example.com:8200
  vault.auth.mount_point = test_approle
  vault.role_id.value = 55cdf32b-498a-c989-a18f-ef3b4aa0eece
  vault.secret_id.unwrapped.file_path = /opt/vault_secret/unwrapped.txt
  

4. Save the /opt/hw-fh/config/user.ini file.

   You can check if the values are correct and applied properly by running the command:

   sudo /opt/hw-fh/bin/vault check-config
   

5. To apply changes, run the command:

   /opt/hw-fh/bin/reconfig
   

6. If you're using unwrapped secret id, proceed with the unwrap process.
   It can be done manually or with your automation tools, using the command:

   sudo /opt/hw-fh/bin/vault unwrap
   

   The process is also executed automatically every time the application restarts.

7. After that, you can connect Apiary with LDAP, SMTP and Jira using Secret ID and by replacing the service password with the path to it:

   engine=<engine_type>,mount_point=<kv mount point>,path=<secret_path>,key=<secret_name>, e.g.:

   engine=kv-v2,mount_point=test_point,path=apiary/jira,key=pass
   

   

   where:

   • engine - the type of the engine used in your Vault. kv-v1 and kv-v2 are currently supported.
   • mount_point - path to the vault secret engine. Equals to <kv mount point> set in step 3, Vault configuration.
   • path - path to the secret in Vault.
   • key - name of the secret in Vault.
     
     

   You can take path and key values from the Vault GUI:

   

8. To make sure that all fields are correct, click Test Connection.
   If the connection is successful, you can Save the configuration.
   Now the authorization in LDAP, SMTP and Jira will be executed via Vault.

See also

• Add Jira Server
• Create connection between Apiary and Hive projects
• Project Dashboard
• Issue management
• Issue statuses