Redaction policies

You can use redaction policies to hide, show, and change the properties (fields) of management artifacts such as incidents, alerts, applications, resource groups, and resources to users.

Redaction policies work alongside filtering to define the access control of data for your users. You can create, edit and duplicate direct from the profile definitions. If you need to hide or show management artifacts, as opposed to the properties of management artifacts, use restriction filters For more information, see Creating restriction filters.

Base policies are the most redactive policies, comprising the minimum set of properties every user in the system is allowed to see. Group policies act as a way of additionally including extra properties for certain users. If a user has multiple group profiles assigned with different policies then the end JSON they see will be the combination of all policies. If the base policy option is disabled it might be due to no base policy being currently enabled.

Redaction policies must be authored using Rego, a programming language created specifically for policy-based control of IT environments. You can author your policies to manipulate the end result output either by hiding or showing all the properties or reacting or modifying particular properties.

For authoring a redaction policy in the Rego policy language, you can use the authoring tools that are included with the console Profiles page. These authoring tools include syntax checking and linting capabilities to help you create your policy source. For linting error notifications in the line number margin appear with details of the error.

Redaction policies are implemented using Open Policy Agent, which is an Apache v2.0 licensed CNCF project Opens in a new tab. You can use existing Open Policy Agent documentation to help you author your own policies. For more information, see the Open Policy Agent documentation Opens in a new tab.

Note: If a custom tool or styling is being applied using specific properties, you must ensure these are included in the final payload and not redacted, as otherwise the UI will not work.

You can apply a created redaction policy to all users, or specific user groups through a profile. To apply a policy to all users, apply the policy to the Base profile. To apply a policy to one or more specific user groups, use a Group profile. For more information, see Managing profiles.

Prerequisites

To work with profiles, and their associated restriction filters and redaction policies, you must possess an administrative user account with the Manage profiles role. For more information, see Roles and permissions.

Note: In the installation resource you are using you need to set the Enable Group Profiles radio button to True.

Enable Group Profiles

Creating a redaction policy

You can create duplicate, edit, and delete redaction policies from the console Profiles page.

  1. Go to the Administration > Profiles page. Then, click the Redaction policies tab. The list of existing policies is displayed.

    Redaction policy tab
    Figure. Redaction policy tab

  2. Click Create redaction policy. The options and authoring tools for creating a New redaction policy are displayed. From this page, you can author your policy source, apply it to a particular data type, test it, and save it.

You can also reach this page when creating or editing a profile.

Redaction policy creation
Figure. Redaction policy creation

  1. Enter or select the following mandatory details for the policy:

    • Policy package name: The name must be in the form aiops.<data_type>.<policy_name>, where <data_type is either incident, alert, application, group, or resource. For example, aiops.resource.myPolicy.

      The value for the Policy package name must match the value for the package name that is include in the policy source.

    • Data type: Select the type of management artifact that the policy affects. The value can be Incidents, Alerts, Applications, Resource groups, or Resources.

      Note: If the redaction policy editor is opened when you are creating or editing a profile, you are not be able to change the data type.

    • Base policy: Select a base policy when the current policy will be included in a Group profile, and there will be a corresponding policy in the Base profile. The base policy source will be displayed above the current policy source.

      When you run a test, the test is run against the base policy and the current policy. If a base policy is not selected, tests are run against the current policy alone.

      When testing with a base policy the output includes a section called policy_results, which shows the individual contributions from each policy.

  2. (Optional) Click Load example to load an example policy and companion test data to view how a policy and test input can be structured.

    To test the example, click Test. The Test button will only be clickable once the policy has been given a valid package name. You can then view the results in the Test output area.

    Note: For a test policy the entity JSON should be placed under the entity as this will match the input format in the policy.

  3. Author your policy source within the Current policy source (Rego) area.

    For examples of how to define different filter conditions, see Example redaction policies.

  4. Click Format to properly indent each line of your policy source. A red error will show at the top of the file if formatting is required.

  5. Test your policy source. To test a policy load representative test data. You can include the JSON representation of an incident, alert, application, resource group, or resource.

    When you have your input data entered within the Test input (JSON format) area, click Test. Review the results in the Test output area.

    Note: If a base policy is selected, the base policy and the current policy are included in tests. To exclude the base policy from tests, set Base policy to None.

    The following examples show how to get test data for existing management artifacts:

    Example: Getting incident test data:

    1. Open the main menu and select Operate > Incidents.

    2. Open an appropriate incident.

    3. Click View raw.

    4. Copy the JSON code to the clipboard.

    5. In the Test input field of the redaction policy editor, include the JSON representation of the incident as an entity, for example:

      {
 "entity": {
   "id": "12345678-0005-2024-0920-025539000001",
   "state": "unassigned",
   …
  }
}

    Example: Getting alert test data:

    1. Open the main menu and select Operate > Alerts.

    2. Open an appropriate alert.

    3. In the Alert details panel, select the Raw view.

    4. Copy the JSON code to the clipboard.

    5. In the Test input field of the redaction policy editor, include the JSON representation of the alert as an entity, for example:

      {
"entity": {
  "acknowledged": false,
  "deduplicationKey": "12345678-0005-2024-0920-025539000020",
  …
 }
}

    Example: Getting application, resource groups, or resources test data:

    1. Open the main menu and select Operate > Resource management.

    2. On the Resource management page, select the Applications tab, Resource groups tab, or Resources tab.

    3. Locate an appropriate application/service, resource group, or resource and click More details.

    4. In the details window, set Show JSON to On.

    5. Copy the JSON code to the clipboard.

    6. In the Test input field of the redaction policy editor, include the JSON representation of the application/service, resource group, or resource as an entity, for example:

      {
 "entity": {
   "_id": "rSRqQX6NTVywShGIjhm-Kg",
   "businessCriticality": "Tier 1",
   …
  }
}

  6. When completed and tested, click Save policy.

    Your new policy is created and listed on the Redaction policy tab of the Administration > Profiles page.

  7. From the Redaction policies tab, click the Profiles tab and apply your created policy to one or more profiles. For more information, see Managing profiles.

Tips: If a policy is not working as expected, complete the following actions:

  • Leverage the test capabilities included in the redaction policy editor.
  • Ensure that the policy is selected and enabled in the appropriate profiles.
  • Ensure that the relevant profiles are enabled.
  • If a policy is included in one or more group profiles, ensure that the profiles include the appropriate user groups.

Viewing redaction policies

To view restriction filters go to the Administration > Profiles page. Then, click the Redaction policies tab. The list of existing policies is displayed, with the following details for each policy:

  • Policy Name
  • Data types
  • Tested
  • Created (date)
  • Created by
  • Last modified (date)
  • Last modified by

Editing a redaction policy

It is important to note that the main policy should never be modified unless done with the help of support. The main policy is responsible for combining all policies together. It also ensures that the required properties are always included, and should not be removed as they are used by the UI to render screens correctly.

  1. From the main navigation menu, go to Administration > Profiles. Click the Redaction policies tab.

  2. Find the policy that you want to edit. If needed, you can filter the list of policies to help you find a specific policy.

  3. For that policy, click the Options (3-dot) menu and click Edit selected.

  4. Complete any required changes and click Save policy.

Duplicating a redaction policy

  1. From the main navigation menu, go to Administration > Profiles. Click the Redaction policies tab.

  2. Find the policy that you want to duplicate. If needed, you can filter the list of policies to help you find a specific policy.

  3. For that policy, click the Options (3-dot) menu and click Duplicate.

  4. Change the policy as needed and click Save profile.

Deleting a redaction policy

  1. From the main navigation menu, go to Administration > Profiles. Click the Redaction policies tab.

  2. Find the policy that you want to delete. If needed, you can filter the list of policies to help you find a specific policy.

  3. For that policy, click the Options (3-dot) menu and click Delete.

    A dialog requesting you to confirm the deletion is displayed. Click Delete to confirm and delete the policy.

    Note: You cannot delete a policy if is being used in the profile.

Example redaction policies

The following code samples shows the various different ways to define code filters in Rego:

Full JSON example

{
    "entity": {
      "_id": "imSB3oo-RcWqjFhX-55Qag",
      "name": "delaware10-le4-cs29.na.test.lab",
      "tags": [
        "1.3.6.1.4.1.9.1.217",
        "B510/3D32 3rd Floor Lab",
        "CiscoCat29xx",
        "joe@ibm.com"
      ],
      "businessCriticality": "Gold",
      "manual": 0,
      "cdmType": 2,
      "sysName": "delaware10-le4-cs29.na.test.lab",
      "services": "datalink(2)",
      "uniqueId": "Example:delaware10-le4-cs29.na.test.lab",
      "className": "CiscoCat29xx",
      "sysContact": "joe@ibm.com",
      "vertexType": "resource",
      "description": "Description text here",
      "entityTypes": [
        "host",
        "switch"
      ],
      "matchTokens": [
        "delaware10-le4-cs29.na.test.lab",
        "delaware10-le4-cs29",
        "entityid.23492249"
      ],
      "sysLocation": "B510/3D32 3rd Floor Lab",
      "sysObjectId": "1.3.6.1.4.1.9.1.217",
      "cdmAdminState": 0,
      "accessProtocol": "IPv4",
      "interfaceCount": 27,
      "isIpForwarding": "not-forwarding",
      "sysDescription": "System description",
      "accessIPAddress": "172.30.238.10",
      "entityChangeTime": "2019-07-19T15:17:34.000Z",
      "entityCreateTime": "2019-07-19T15:17:34.000Z",
      "accessScopeTokens": [
        "file.observer:itnm.txt"
      ],
      "lastBroadcastTime": "2024-03-21T11:11:33.927Z",
      "entityDiscoveryTime": "2019-07-19T15:04:42.000Z"
    }
  }

Equals filter example

output := input.entity if {
    input.entity.cdmType == 2
}

Is not equal filter example

output := input.entity if {
    not input.entity.cdmType == 2
}

Contains filter example

output := input.entity if {
    contains(input.entity.name, "ware")
}

Does not contain filter example

output := input.entity if {
    not contains(input.entity.name, "ware")
}

Starts with filter example

output := input.entity if {
    startswith(input.entity.name, "del")
}

Ends with filter example

output := input.entity if {
    endswith(input.entity.name, ".lab")
}

Empty filter example

output := input.entity if {
    not input.entity.cdmType
}

Is not empty filter example

output := input.entity if {
    input.entity.cdmType
}

Matches filter example

output := input.entity if {
    regex.match(`^delaware`, input.entity.name)
}

Does not match filter example

output := input.entity if {
    not regex.match(`^delaware`, input.entity.name)
}

Check value matches a value in a set filter example

Requires knowing the criticalities to allow

output := input.entity if {
    input.entity.businessCriticality in ["Gold", "Silver", "Bronze"]
}

Includes any filter example

Check a list of provided types

output := input.entity if {
    some type in input.entity.entityTypes
    type in ["host", "otherType", "otherType2"]
}

Includes all filter example

output := input.entity if {
    every type in input.entity.entityTypes {
        type in ["host", "switch"]
    }
}

Complex combination

output := input.entity if {
    # When dealing with a host
    "host" in input.entity.entityTypes

    # Must start with del to show properties
    startswith(input.entity.name, "del")

    # Must include the tag "joe@ibm.com"
    some type in input.entity.tags
    type in ["joe@ibm.com"]
}

Complex definition to handle many different types

output := input.entity if {
    # When dealing with a host
    "host" in input.entity.entityTypes

    # Must start with del to show properties
    startswith(input.entity.name, "del")

    # Must include the tag "joe@ibm.com"
    some type in input.entity.tags
    type in ["joe@ibm.com"]
} else := input.entity if {
    # When dealing with a people
    "people" in input.entity.entityTypes

    # Must start with del to show properties
    startswith(input.entity.team, "uk_")
} else := input.entity if {
    # When dealing with a vms
    "vm" in input.entity.entityTypes

    # Must start with del to show properties
    regex.match(`^delaware`, input.entity.name)
}