Documentation
Guides
HomePortalStatus
Start typing to search…

Policies

Policies are used to control who has access to what Sockets and under what conditions. Think of policies as advanced, Identity-, application-aware, and context-aware firewall rules. Unlike traditional firewalls or access control list (ACL) rules, Border0 policies allow you to define access rules based on Identity, time of day, application type, and location.

Each time a user tries to access a Socket through Border0, our platform will evaluate all policies that are attached to the Socket. The verdict is the cumulative result of all policies. If no policies match or no policies are attached to a Socket, no access will be granted.

📘

Organization wide policies and regular policies

A policy can, optionally, be marked as an Organization-wide policy, meaning it will automatically apply to all Sockets in your organization. Regular policy must be explicitly linked to a Socket.

How Policies Work

A policy consists of two main sections: condition and permissions. Each section plays a vital role in determining the scope and applicability of the policy.

For more details on policies, also check out this demo video

And this Tutorial: Using Policies for Granular Application access control


Permissions

The permissions section details the actions that are permitted under the policy. It covers various protocols and services such as databases, HTTP, RDP, SSH, TLS, VNC, and VPN. Each subsection can specify more detailed permissions. All fields are optional, and some can be defined as empty hashes, indicating they are enabled but have no specific configuration items.

network

If enabled, this means the user will have permission to use the subnet-router resources as well as exit-node resources. This has to be enabled for VPN use-cases, ie making subnet routes available to users.

ssh

If defined this allows SSH access. Accepted properties are:

  • max_session_duration_seconds
    Maximum duration of an SSH session in seconds (e.g., 3600).
  • allowed_usernames
    List of usernames allowed for SSH access. This is enforced only if defined. An empty list disallows all usernames. It is only used when the upstream username is not defined in the socket configuration (e.g., ["root"]).
  • shell
    Allows SSH shell access. (empty hash if defined).
  • exec
    Allows SSH command execution.
    • commands
      Specific commands allowed for execution. These are evaluated as regular expressions. For example, defining "ls" would also match "lsof", while "^ls$" would match only "ls" without arguments (e.g., ["^ls -la$"]).
  • sftp
    Allows SFTP access (empty hash if defined).
  • tcp_forwarding
    Allows TCP forwarding.
    • allowed_connections
      List of allowed connections. The address in destination_address must match the address used when setting up the forwarding. Using "*" would allow all addresses and/or ports (e.g., [{"destination_address": "google.com", "destination_port": "443"}]).
  • kubectl_exec
    Allows Kubernetes command execution.
    • allowed_namespaces
      List of allowed namespaces. Using "*" would allow all namespaces. If pod_selector is defined, all labels specified must match (logical AND) (e.g., [{"namespace": "", "pod_selector": {"app": "nginx"}}]).
  • docker_exec
    Allows Docker container execution.
    • allowed_containers
      List of allowed Docker containers (e.g., ["ubuntu"]).

database

If defined this allows database access. Accepted properties are:

  • max_session_duration_seconds
    Maximum duration of a database session in seconds (e.g., 3600).
  • allowed_databases
    List of allowed databases with query types, if not defined all databases and queries are allowed.
    • database
      The name of the database (e.g., "books" or "*" for all databases).
    • allowed_query_types
      Types of queries allowed (e.g., ["ReadOnly", "ReadWrite"]).

http

Allows HTTP access (empty hash if defined).

tls

Allows TLS access (empty hash if defined).

vnc

Allows VNC access (empty hash if defined).

rdp

Allows Remote Desktop Protocol (RDP) access (empty hash if defined).

Condition

Conditions control under what conditions the action is allowed. This policy component is divided into 3 sections.

  1. Who
  2. Where
  3. When

All condition sections are individually evaluated using the rules outlined below. All properties in the Condition section are optional. All Sections need to match before a user is allowed in, i.e. this is a logical AND.

Who

The who section defines what identities have access to the Socket service. You can specify zero or more email address, group or service_account values. During the policy evaluation, these values are evaluated as a Logical OR. This means at least one of the emails or domains needs to match the user's identity to pass this section.

🚧

Define at least one property in the Who section

If no email, group or service_account is defined, no one will be able to access your Sockets.

Where

The where section allows you to control where the user should be located. This can be either a list of IP addresses, countries, or countries that are not allowed.
Accepted properties are:

  • allowed_ip
    This is a list of IP addresses in the CIDR format.
  • country
    This is a list of two-letter country codes. The country code will be evaluated based on GEO IP values. Adding a country code means the user must come from that country to be allowed in.
  • country_not
    This is a list of two-letter country codes. The country code will be evaluated based on GEO IP values. Adding a value as a country_not means that access will be denied if the user visits from that country.

All properties in the Where section are optional. You can leave them all empty or use one or two.
All properties in the Where section with a value need to match before a user is allowed in, i.e. this is a logical AND.

When

The when section allows an admin to control between which dates or what time of day access is permitted.
The following properties are supported:

  • after
    during evaluation, we compare the current time and date against the date in the after value. The current time should be after the value defined here. This allows you to create only valid policies after a specific date.
  • before
    during evaluation, we compare the current time and date against the date in the before value. The current time should be before the value defined here. This allows you to create policies that are valid before a specific date. Effectively, giving a policy an end or expiry date.
  • time_of_day_after
    using the time_of_day_after property, you can control the time of day users have access. During evaluation, we compare the current time against the time in the time_of_day_after value. The current time should be after the value defined here.
  • time_of_day_before
    using the time_of_day_before property, you can control the time of day users have access. During the evaluation, we compare the current time against the time in the time_of_day_before value. The current time should be before the value defined here.

You can control when a policy is active using the before and after properties. These properties are optional; you can define none, one, or both.

Using the time of day properties, administrators can control during what time of day users have access. For example, the following values will allow users access only between 7 am and 6 pm UTC.

        "time_of_day_after": "07:00:00 UTC",
        "time_of_day_before": "18:00:00 UTC"

These properties are optional, and you can define none, one, or both.

All properties in the When section are optional. You can leave them all empty or use one or two.
All properties in the When section with a value need to match before a user is allowed access, i.e., this is a logical AND.

Valid date examples

📘

Time and Date format

We're fairly liberal in accepting date and time formats and will do our best to parse and guess the correct values. Below are a few examples of valid date and time formats we accept

+-------------------------------------------------------+-----------------------------------------+
| User Input                                            | Will result in                          |
+-------------------------------------------------------+-----------------------------------------+
| May 8, 2009 5:57:51 PM                                | 2009-05-08 17:57:51 +0000 UTC           |
| oct 7, 1970                                           | 1970-10-07 00:00:00 +0000 UTC           |
| oct 7, '70                                            | 1970-10-07 00:00:00 +0000 UTC           |
| oct. 7, 1970                                          | 1970-10-07 00:00:00 +0000 UTC           |
| oct. 7, 70                                            | 1970-10-07 00:00:00 +0000 UTC           |
| Mon Jan  2 15:04:05 2006                              | 2006-01-02 15:04:05 +0000 UTC           |
| Mon Jan  2 15:04:05 MST 2006                          | 2006-01-02 15:04:05 +0000 MST           |
| Mon Jan 02 15:04:05 -0700 2006                        | 2006-01-02 15:04:05 -0700 -0700         |
| Monday, 02-Jan-06 15:04:05 MST                        | 2006-01-02 15:04:05 +0000 MST           |
| Mon, 02 Jan 2006 15:04:05 MST                         | 2006-01-02 15:04:05 +0000 MST           |
| Tue, 11 Jul 2017 16:28:13 +0200 (CEST)                | 2017-07-11 16:28:13 +0200 +0200         |
| Mon, 02 Jan 2006 15:04:05 -0700                       | 2006-01-02 15:04:05 -0700 -0700         |
| Mon 30 Sep 2018 09:09:09 PM UTC                       | 2018-09-30 21:09:09 +0000 UTC           |
| Mon Aug 10 15:44:11 UTC+0100 2015                     | 2015-08-10 15:44:11 +0000 UTC           |
| Thu, 4 Jan 2018 17:53:36 +0000                        | 2018-01-04 17:53:36 +0000 UTC           |
| Fri Jul 03 2015 18:04:07 GMT+0100 (GMT Daylight Time) | 2015-07-03 18:04:07 +0100 GMT           |
| Sun, 3 Jan 2021 00:12:23 +0800 (GMT+08:00)            | 2021-01-03 00:12:23 +0800 +0800         |
| September 17, 2012 10:09am                            | 2012-09-17 10:09:00 +0000 UTC           |
| September 17, 2012 at 10:09am PST-08                  | 2012-09-17 10:09:00 -0800 PST           |
| September 17, 2012, 10:10:09                          | 2012-09-17 10:10:09 +0000 UTC           |
| October 7, 1970                                       | 1970-10-07 00:00:00 +0000 UTC           |
| October 7th, 1970                                     | 1970-10-07 00:00:00 +0000 UTC           |
| 12 Feb 2006, 19:17                                    | 2006-02-12 19:17:00 +0000 UTC           |
| 12 Feb 2006 19:17                                     | 2006-02-12 19:17:00 +0000 UTC           |
| 14 May 2019 19:11:40.164                              | 2019-05-14 19:11:40.164 +0000 UTC       |
| 7 oct 70                                              | 1970-10-07 00:00:00 +0000 UTC           |
| 7 oct 1970                                            | 1970-10-07 00:00:00 +0000 UTC           |
| 03 February 2013                                      | 2013-02-03 00:00:00 +0000 UTC           |
| 1 July 2013                                           | 2013-07-01 00:00:00 +0000 UTC           |
| 2013-Feb-03                                           | 2013-02-03 00:00:00 +0000 UTC           |
| 06/Jan/2008:15:04:05 -0700                            | 2008-01-06 15:04:05 -0700 -0700         |
| 06/Jan/2008 15:04:05 -0700                            | 2008-01-06 15:04:05 -0700 -0700         |
| 3/31/2014                                             | 2014-03-31 00:00:00 +0000 UTC           |
| 03/31/2014                                            | 2014-03-31 00:00:00 +0000 UTC           |
| 08/21/71                                              | 1971-08-21 00:00:00 +0000 UTC           |
| 8/1/71                                                | 1971-08-01 00:00:00 +0000 UTC           |
| 4/8/2014 22:05                                        | 2014-04-08 22:05:00 +0000 UTC           |
| 04/08/2014 22:05                                      | 2014-04-08 22:05:00 +0000 UTC           |
| 4/8/14 22:05                                          | 2014-04-08 22:05:00 +0000 UTC           |
| 04/2/2014 03:00:51                                    | 2014-04-02 03:00:51 +0000 UTC           |
| 8/8/1965 12:00:00 AM                                  | 1965-08-08 00:00:00 +0000 UTC           |
| 8/8/1965 01:00:01 PM                                  | 1965-08-08 13:00:01 +0000 UTC           |
| 8/8/1965 01:00 PM                                     | 1965-08-08 13:00:00 +0000 UTC           |
| 8/8/1965 1:00 PM                                      | 1965-08-08 13:00:00 +0000 UTC           |
| 8/8/1965 12:00 AM                                     | 1965-08-08 00:00:00 +0000 UTC           |
| 4/02/2014 03:00:51                                    | 2014-04-02 03:00:51 +0000 UTC           |
| 03/19/2012 10:11:59                                   | 2012-03-19 10:11:59 +0000 UTC           |
| 03/19/2012 10:11:59.3186369                           | 2012-03-19 10:11:59.3186369 +0000 UTC   |
| 2014/3/31                                             | 2014-03-31 00:00:00 +0000 UTC           |
| 2014/03/31                                            | 2014-03-31 00:00:00 +0000 UTC           |
| 2014/4/8 22:05                                        | 2014-04-08 22:05:00 +0000 UTC           |
| 2014/04/08 22:05                                      | 2014-04-08 22:05:00 +0000 UTC           |
| 2014/04/2 03:00:51                                    | 2014-04-02 03:00:51 +0000 UTC           |
| 2014/4/02 03:00:51                                    | 2014-04-02 03:00:51 +0000 UTC           |
| 2012/03/19 10:11:59                                   | 2012-03-19 10:11:59 +0000 UTC           |
| 2012/03/19 10:11:59.3186369                           | 2012-03-19 10:11:59.3186369 +0000 UTC   |
| 2014:3:31                                             | 2014-03-31 00:00:00 +0000 UTC           |
| 2014:03:31                                            | 2014-03-31 00:00:00 +0000 UTC           |
| 2014:4:8 22:05                                        | 2014-04-08 22:05:00 +0000 UTC           |
| 2014:04:08 22:05                                      | 2014-04-08 22:05:00 +0000 UTC           |
| 2014:04:2 03:00:51                                    | 2014-04-02 03:00:51 +0000 UTC           |
| 2014:4:02 03:00:51                                    | 2014-04-02 03:00:51 +0000 UTC           |
| 2012:03:19 10:11:59                                   | 2012-03-19 10:11:59 +0000 UTC           |
| 2012:03:19 10:11:59.3186369                           | 2012-03-19 10:11:59.3186369 +0000 UTC   |
| 2014年04月08日                                        | 2014-04-08 00:00:00 +0000 UTC           |
| 2006-01-02T15:04:05+0000                              | 2006-01-02 15:04:05 +0000 UTC           |
| 2009-08-12T22:15:09-07:00                             | 2009-08-12 22:15:09 -0700 -0700         |
| 2009-08-12T22:15:09                                   | 2009-08-12 22:15:09 +0000 UTC           |
| 2009-08-12T22:15:09.988                               | 2009-08-12 22:15:09.988 +0000 UTC       |
| 2009-08-12T22:15:09Z                                  | 2009-08-12 22:15:09 +0000 UTC           |
| 2017-07-19T03:21:51:897+0100                          | 2017-07-19 03:21:51.897 +0100 +0100     |
| 2019-05-29T08:41-04                                   | 2019-05-29 08:41:00 -0400 -0400         |
| 2014-04-26 17:24:37.3186369                           | 2014-04-26 17:24:37.3186369 +0000 UTC   |
| 2012-08-03 18:31:59.257000000                         | 2012-08-03 18:31:59.257 +0000 UTC       |
| 2014-04-26 17:24:37.123                               | 2014-04-26 17:24:37.123 +0000 UTC       |
| 2013-04-01 22:43                                      | 2013-04-01 22:43:00 +0000 UTC           |
| 2013-04-01 22:43:22                                   | 2013-04-01 22:43:22 +0000 UTC           |
| 2014-12-16 06:20:00 UTC                               | 2014-12-16 06:20:00 +0000 UTC           |
| 2014-12-16 06:20:00 GMT                               | 2014-12-16 06:20:00 +0000 UTC           |
| 2014-04-26 05:24:37 PM                                | 2014-04-26 17:24:37 +0000 UTC           |
| 2014-04-26 13:13:43 +0800                             | 2014-04-26 13:13:43 +0800 +0800         |
| 2014-04-26 13:13:43 +0800 +08                         | 2014-04-26 13:13:43 +0800 +0800         |
| 2014-04-26 13:13:44 +09:00                            | 2014-04-26 13:13:44 +0900 +0900         |
| 2012-08-03 18:31:59.257000000 +0000 UTC               | 2012-08-03 18:31:59.257 +0000 UTC       |
| 2015-09-30 18:48:56.35272715 +0000 UTC                | 2015-09-30 18:48:56.35272715 +0000 UTC  |
| 2015-02-18 00:12:00 +0000 GMT                         | 2015-02-18 00:12:00 +0000 UTC           |
| 2015-02-18 00:12:00 +0000 UTC                         | 2015-02-18 00:12:00 +0000 UTC           |
| 2015-02-08 03:02:00 +0300 MSK m=+0.000000001          | 2015-02-08 03:02:00 +0300 +0300         |
| 2015-02-08 03:02:00.001 +0300 MSK m=+0.000000001      | 2015-02-08 03:02:00.001 +0300 +0300     |
| 2017-07-19 03:21:51+00:00                             | 2017-07-19 03:21:51 +0000 UTC           |
| 2014-04-26                                            | 2014-04-26 00:00:00 +0000 UTC           |
| 2014-04                                               | 2014-04-01 00:00:00 +0000 UTC           |
| 2014                                                  | 2014-01-01 00:00:00 +0000 UTC           |
| 2014-05-11 08:20:13,787                               | 2014-05-11 08:20:13.787 +0000 UTC       |
| 2020-07-20+08:00                                      | 2020-07-20 00:00:00 +0800 +0800         |
| 3.31.2014                                             | 2014-03-31 00:00:00 +0000 UTC           |
| 03.31.2014                                            | 2014-03-31 00:00:00 +0000 UTC           |
| 08.21.71                                              | 1971-08-21 00:00:00 +0000 UTC           |
| 2014.03                                               | 2014-03-01 00:00:00 +0000 UTC           |
| 2014.03.30                                            | 2014-03-30 00:00:00 +0000 UTC           |
| 20140601                                              | 2014-06-01 00:00:00 +0000 UTC           |
| 20140722105203                                        | 2014-07-22 10:52:03 +0000 UTC           |
| 171113 14:14:20                                       | 2017-11-13 14:14:20 +0000 UTC           |
| 1332151919                                            | 2012-03-19 10:11:59 +0000 UTC           |
| 1384216367189                                         | 2013-11-12 00:32:47.189 +0000 UTC       |
| 1384216367111222                                      | 2013-11-12 00:32:47.111222 +0000 UTC    |
| 1384216367111222333                                   | 2013-11-12 00:32:47.111222333 +0000 UTC |
+-------------------------------------------------------+-----------------------------------------+

Example

{
  "permissions": {
    "ssh": {
      "max_session_duration_seconds": 3600,
      "allowed_usernames": [
        "root"
      ],
      "shell": {},
      "exec": {
        "commands": [
          "^ls -la$"
        ]
      },
      "sftp": {},
      "tcp_forwarding": {
        "allowed_connections": [
          {
            "destination_address": "google.com",
            "destination_port": "443"
          }
        ]
      },
      "kubectl_exec": {
        "allowed_namespaces": [
          {
            "namespace": "*",
            "pod_selector": {
              "app": "nginx"
            }
          }
        ]
      },
      "docker_exec": {
        "allowed_containers": [
          "ubuntu"
        ]
      }
    },
    "database": {
      "max_session_duration_seconds": 3600,
      "allowed_databases": [
        {
          "database": "*",
          "allowed_query_types": [
            "ReadOnly"
          ]
        },
        {
          "database": "books",
          "allowed_query_types": [
            "SELECT",
            "REPLACE",
            "INSERT",
            "DELETE",
            "BEGIN",
            "COMMIT",
            "ROLLBACK",
            "SET",
            "DDL",
            "UPDATE",
            "ReadWrite",
            "SHOW",
            "USE",
            "OTHER"
          ]
        }
      ]
    },
    "http": {},
    "tls": {},
    "vnc": {},
    "rdp": {},
    "vpn": {}
  },
  "condition": {
    "who": {
      "email": [
        "[email protected]"
      ],
      "group": [
        "6738f781-77dd-4351-8058-504e6ee8cea7"
      ],
      "service_account": [
        "test-sa"
      ]
    },
    "where": {
      "allowed_ip": [
        "0.0.0.0/0",
        "::/0"
      ],
      "country": [
        "NL"
      ],
      "country_not": [
        "CA"
      ]
    },
    "when": {
      "after": "2022-02-02T22:22:22Z",
      "before": "2024-05-28T10:37:25+02:00",
      "time_of_day_after": "09:00 UTC",
      "time_of_day_before": "17:00 UTC"
    }
  }
}

This example policy applies under specific conditions and grants various permissions accordingly.

Conditions

This policy would apply to a user who meets any of the following criteria:

  • The user’s email is[email protected]
  • The user is a member of the group with the ID 6738f781-77dd-4351-8058-504e6ee8cea7.
  • The user is using the service account test-sa.

Regarding location, access is permitted only if both of the following conditions are met:

  • The connection originates from any IP address (both IPv4 0.0.0.0/0 and IPv6 ::/0).
  • The user’s location is geolocated from the Netherlands (country code NL).

However, access is explicitly denied if:

  • The user’s location is geolocated from Canada (country code CA).

The policy is valid during specific timeframes:

  • It is active from February 2, 2022, until May 28, 2024.
  • Daily, the policy is enforced from 9:00 AM to 5:00 PM UTC.

Permissions

When the above conditions are met, the following permissions are granted:

  1. SSH Access:
  • Users can start SSH sessions lasting up to 1 hour.
  • Only the "root" user is allowed (if the upstream username is not defined in the socket configuration).
  • Shell access is enabled, allowing users to open an interactive shell.
  • Users can execute the ls -la command exactly as written, with no additional arguments allowed.
  • SFTP access is enabled, permitting file transfers over SSH.
  • TCP forwarding is allowed, specifically to the address google.com on port 443.
  • Kubernetes commands can be executed in any namespace, but only on pods with the label app=nginx.
  • Docker commands can be run in the "ubuntu" container.
  1. Database Access:
  • Users can access database sessions for up to 1 hour.
  • All databases are accessible for read-only queries, allowing users to view data but not modify it.
  • The "books" database allows a wide range of queries, including select, insert, update, delete, and more, granting users comprehensive interaction with the database.
  1. HTTP, TLS, VNC, RDP, and VPN Access:
  • Access is granted for HTTP, TLS, VNC, RDP, and VPN protocols, enabling users to connect and interact using these methods without additional restrictions.

Updated 13 days ago