Manage Safelists and IP Ranges

Before starting this section, ensure you have initialized, unsealed, and logged into DevOps Secrets Safe as root.

Safelists allow you to explicitly grant or deny access to specific IP addresses for all CLI commands. Safelists and IP ranges must be structured in the following way:

Safelist Model

  • Name: (Required). Name for this safelist.
  • Description: (Optional). Details about this safelist.
  • Expiry date: (Optional). Specifies a day and time when this safelist will expire.

    An empty or null value denotes no expiry.

IP Range Model

  • Name: (Required). Name for this IP range.
  • Value: (Required). Specifies a range of IP addresses.

    The supported IP range value patterns are:

    • CIDR range: 192.168.0.0/24, fe80::%lo0/10
    • Single address: 10.101.8.16, fe80::1%23
    • Begin-end range: 10.101.8.10 - 10.101.8.20, fe80::1%23 - fe80::ff%23
  • Allow: (Required). Specifies whether the defined range of IP addresses allows or denies access.
  • Description: (Optional). Details about this IP range.
  • Expiry date: (Optional). Specifies a day and time for the IP range to expire.

    An empty or null value denotes no expiry.

A safelist must have at least one IP range associated with it.

  1. Create two safelists:
    ssrun safelist create -f safelist1.txt
    ssrun safelist create -f safelist2.txt

The following examples assume there are two files, safelist1.txt and safelist2.txt, with the given contents:

safelist1.txt

			
{
   "ipRanges": [
      {
         "name": "ip_range_1",
         "value": "10.101.8.10-10.101.8.20",
         "allow": true,
         "description": "IP Range 1 Description",
         "expiryDate": "2020-06-21T11:44:31.733Z",
         "xForwardedForHeaderLimit": "2"
      }
   ],
   "name": "safelist_1",
   "description": "Safelist 1 Description",
   "expiryDate": "2020-06-21T11:44:31.733Z"
}

In the above example, the safelist is enforced only until the defined expiry date and allows only IP addresses in the range of 10.101.8.10 to 10.101.8.20.

safelist2.txt

{
   "ipRanges": [
      {
         "name": "ip_range_2",
         "value": "10.101.8.50-10.101.8.60",
         "allow": false,
         "description": "IP Range 2 Description"
      }
   ],
   "name": "safelist_2",
   "description": "Safelist 2 Description"
}

In the above example, the safelist never expires and denies IP addresses in the range of 10.101.8.50 to 10.101.8.60.

  1. View safelists and IP ranges:

    The safelist get command returns all safelists that exist.

    ssrun safelist get

    You can also limit the view by passing in the name of the safelist targeted for discovery.

    ssrun safelist get -n safelist_1

    The ip-range get command returns all the IP ranges that exist for a given safelist.

    ssrun ip-range get -n safelist_1

    You can also limit the view by passing in the name of the IP range targeted for discovery.

    ssrun ip-range get -n safelist_1 -i ip_range_1

    Views can be further modified by using the following flags:

    • -d: (Depth). Use this to define the maximum depth of the view to return.
      • A value of 0 returns only the element specified.
      • A value of 1 returns the element specified and all direct child elements
      • A value of 2 returns all child and grandchild elements of the element specified.
    • -v: (Verbose). Use this to get a full listing of safelists and/or IP range attributes; otherwise, a slim view of each safelist or IP range is returned.
  2. Update a safelist:
    ssrun safelist update -n safelist_2 -f safelist2Update.txt

    This command updates the safelist with the name safelist_2.

The following example assumes there is a file called safelist2Update.txt with the given contents:

safelist2Update.txt

{
    "description": "Safelist 2 Description Updated",
    "expiryDate": "2021-06-21T12:17:14.326Z"
}
  1. Add an IP range to a safelist:
    ssrun ip-range create -n safelist_2 -f ipRange.txt

    This command adds an IP range to the safelist with the name safelist_2.

The following example assumes there is a file called ipRange.txt with the given contents:

ipRange.txt

{
    "value": "10.101.8.70",
    "allow": false,
    "description": "IP Range 3 Description",
    "expiryDate": "2021-06-21T11:58:03.315Z"
}

In the above example, the IP range is only enforced until the defined expiry date and denies IP requests coming from the IP address 10.101.8.70.

  1. Update an IP range of a safelist:
    ssrun ip-range update -n safelist_2 -i ip_range_2 -f ipRangeUpdate.txt

    This command updates the IP range with the name ip_range_2 for the safelist with the name safelist_2.

The following example assumes there is a file called ipRangeUpdate.txt with the given contents:

ipRangeUpdate.txt

{
    "value": "10.101.8.71",
    "allow": false,
    "description": "IP Range 3 Updated",
    "expiryDate": "2021-06-21T11:58:03.315Z"
}
  1. Assign a safelist to a user:
    ssrun authorization create -p principal/internal/user/user1 -o read -a allow safelist/safelist_2/access

    This command associates the safelist with the name safelist_2 to the user with the name user1.

  2. Delete an IP range from a safelist:
    ssrun ip-range delete -n safelist_2 -i ip_range_2

    This command deletes the IP range with the name ip_range_2 from the safelist with the name safelist_2.

  3. Delete a safelist:
    ssrun safelist delete -n safelist_2

    This command deletes the safelist with the name safelist_2.