Configuring policies for Relay

Custom policy is a premium feature and is not available on the default version of the app. To unlock this feature, please contact ServiceRocket Support for assistance..

Jira administrators can manage and configure policies that dictate how the proxy handles incoming requests.

Viewing policies

Navigate to Jira top menu Settings (⚙️)> Apps > Guard Dog Relay for Jira.
Click Policies on the left sidebar, and then ensure you are on the Policies tab.
Click View JSON to see the configuration details.
Here, you can review the policies that dictate how the relay handles incoming requests. The structure of these policies aligns with the JSON Rules Engine format (rules documentation).

Uploading or creating new policies

To add the proxy policies, you must upload a JSON file defining the rules and actions for handling requests.

Start by clicking the ☁️ Upload button.
A modal will pop up where you can upload the JSON file.
1. In the modal, you'll see an option to Drop your JSON file here to upload or click Choose file to select a file from your computer.
2. Once the JSON file is selected, click Upload to proceed.
  - The system will process the file, and you can view the details and structure of the policies defined in the JSON.
If you need to create a policy from scratch, you can click Download our JSON policy template from the same modal to get a head start.

Understanding the policy structure

The following explains the structure of the policies used in Relay. This policy enables administrators to execute rules that bolster webhook security and facilitate efficient governance.

Policy template

We are using the JSON Rules Engine library to evaluate policies based on specific conditions and trigger corresponding actions.

As a result, the structure of our policies is simillar to how rules are structured in the JSON Rules Engine, as detailed in its rules documentation.

The structure of the policy is as follows:

CODE

{
  "name": "Relay Policy Template",
  "description": "Template showing all available relay policy options",
  "isActive": true,
  "conditions": {
    "any": [
      {
        "fact": "headers",
        "path": "host",
        "operator": "equal",
        "value": "your-webhook-url-domain"
      },
      {
        "fact": "body",
        "operator": "stringContains",
        "value": "your-issue-key",
        "path": "$.issue.key"
      },
      {
        "fact": "body",
        "operator": "equal",
        "value": "your-project-key",
        "path": "$.issue.fields.project.key"
      },
      {
        "fact": "userId",
        "operator": "equal",
        "value": "your-user-account-id"
      }
    ],
    "all": []
  },
  "actions": [
    "LogRequest",
    "BlockRequest"
  ]
}

Replace the helper text, such as "Relay Policy Template", "Template showing all available relay policy options" or "your-webhook-url-domain" when using this template to create your own.

Elements of the JSON policy file

A correctly formatted JSON policy file will include the following sections:

Root properties

This section describes the policy in general.

Element	Type	Description
`name`	string	Name of the policy
`description`	string	Description of the policy
`isActive`	boolean	value can only be `true` or `false`

Conditions

This section details the rules of the policy. The primary elements for this [type] include:

Boolean expressions

Each rule's conditions must have an all or any operator containing an array of conditions at its root, a not operator containing a single condition, or a condition reference. Boolean expressions can also be nested, like in this example.

The available Boolean expressions are:

Boolean expression	Description
`all`	All conditions contained within must be truthy for the rule to succeed.
`any`	Requires at least one condition to be truthy for the rule to succeed.
`not`	Negates whatever condition it contains.

Fact

Facts are pieces of data that the rules engine evaluates against predefined conditions. The available facts for Relay policies are:

Fact	Description
`headers`	The request’s header.
`userId`	The user’s Atlassian account ID that triggers the webhook. Tip: You can use go.atlassian.com/aaid to get your own `account_id` in the response.
`body`	The request body.

Operator

An operator defines how a fact should be compared against the specified value. Available operators are:

Operator	Description
JSON rules operators	Any operator natively supported by the rules engine.
`matchRegex`	Checks for a specific regex string.
`stringContains`	Checks if a string value exists within another string or an array of strings/objects. This operator performs a case-sensitive search.

Action

An action in a rules engine specifies a response that is triggered when certain conditions are met. Available actions are:

LogRequest: Log the request/response. Structure of the log is as follows:

CODE

 {
  timestamp: '2024-07-31T06:26:55.563Z',
  method: 'GET',
  forwardedFor: '14.192.209.239, 10.22.3.229',
  path: '/rest/api/2/issue/PCJSM1-138',
  userAgent: 'PostmanRuntime/7.40.0',
  status: 200,
  statusText: 'OK',
  duration: 752,
  rateLimitStatus: 0

BlockRequest: Block the request and return:
CODE
```
{ statusCode: 403, statusText: 'Forbidden' }
```

Example

Below is an example of a policy that filters a specific project key from the body of the webhook request and blocks all its requests:

CODE

      {
        "fact": "body", 
        "operator": "equal",
        "value": "PROJECT-KEY",
        "path": "$.issue.fields.project.key"
      }

The path can be obtained from the payload of the webhook response.

CODE

"issue": {
  ...
  "fields": {
    ...
    "project": {
      ...
      "key": "PROJECT-KEY",
      ...
      }
    }
    ...
  }
  ...
}

Next step

Integrating with third-party platforms