Configuring policies for Proxy

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 Proxy 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 proxy 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.

Go to the Policies tab and click 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 Proxy. This policy enables administrators to customize and configure how policies react to certain rules set.

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 similar 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": "Proxy Policy Template",
  "description": "Template showing all available proxy policy options",
  "isActive": true,
  "conditions": {
    "any": [
      {
        "fact": "headers",
        "path": "host",
        "operator": "equal",
        "value": "your-proxy-url-domain"
      },
      {
        "fact": "emailAddress",
        "operator": "equal",
        "value": "user@example.com"
      },
      {
        "fact": "endpoint",
        "operator": "matchRegex",
        "value": "/rest/api/2/issue/*"
      },
      {
        "fact": "method",
        "operator": "equal",
        "value": "GET"
      }
    ],
    "all": []
  },
  "actions": [
    "LogRequest",
    "BlockRequest",
    "TriggerJiraAutomation"
  ],
  "payload": {
    "jiraAutomation": [
      {
        "webhookUrl": "https://automation.atlassian.com/pro/hooks/your-webhook-id"
      }
    ]
  }
}

When crafting the policy remove the helper text sentences with your chosen elements or values.

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 of the policy 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 Proxy policies are:

Fact	Description
`headers`	The request’s header.
`endpoint`	The endpoint provided in the `path` query parameter.
`emailAddress`	The email address of the requester, extracted from the authentication header.
`method`	The method of the request.

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`	To check if a string matches a given regular expression pattern. Useful for pattern-based string validation.
`stringContains`	Checks if a string value exists within another string or an array of strings/objects. This operator performs a case-sensitive search.

Value

This is the specific data of the fact stated in the policy.

Example

In the example use case below, the policy filters for a specific email address. (Therefore, the fact is emailAddress, and the value should be an email address. In this case, myemail@servicerocket.com.)

CODE

  {
    "fact": "emailAddress",
    "operator": "equal",
    "value": "myemail@servicerocket.com"
  }

Actions

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' }
```

TriggerJiraAutomation: Trigger a Jira automation rule via webhook. Requires payload configuration:

CODE

"actions": [
  "TriggerJiraAutomation"
],
"payload": {
  "jiraAutomation": [
    {
      "webhookUrl": "https://automation.atlassian.com/pro/hooks/your-webhook-id"
    },
    {
      "webhookUrl": "https://automation.atlassian.com/pro/hooks/your-webhook-id"
    }
  ]
}

Next step

Integrating with third-party platforms