End-of-Life (EoL)

Role-based access control for Docker Engine

Prisma Cloud lets you control access to Docker commands based on group membership.
Prisma Cloud lets you:
  • Secure access to remote Docker Engine instances.
  • Control access to Docker commands on a user-by-user basis.
After integrating Prisma Cloud with Active Directory, OpenLDAP, or SAML, you could create a group called Dev Team. Then in Console, you could grant all users in Dev Team permission to remotely run any Docker commands on hosts in the development environment, but deny permission to create, start, or stop containers on hosts in the production environment.

Securing remote access

The following diagram shows how Docker commands are routed from a user’s workstation over the network to a host protected by Defender:
The Docker client securely transmits the command over the network to Defender using the Transport Layer Security (TLS) protocol. Defender acts as a proxy to the Docker daemon. If the installed policy permits the command to be executed, it is forwarded to the Docker daemon over the UNIX socket. The UNIX socket is created when the Docker daemon first starts, and it exposes a REST API through which Docker commands can be run.

Controlling access to resources

The following sequence diagram shows how users gain access to Docker resources, and how your access policies are enforced.
In this flow, it is assumed that:
  • User Bruce has been added to the AD group Prisma Cloud Devs.
  • You have already configured your access policy rules in the Prisma Cloud Console.
  1. Bruce logs into Console with his LDAP credentials. Because Bruce is not a Prisma Cloud admin, he sees the single page user view.
  2. From the single page user view, Bruce can copy a command that will install certs on his local machine. These certs identify him as Bruce.
  3. Bruce runs the install command on his local machine. It copies the certs into the .docker directory in his home directory. He can now use TLS to communicate securely with the hosts that run Defenders.
  4. Bruce runs a docker command on DevHostA from his local machine. He specifies the hostname for DevHostA and the port number where Defender listens. By default, Defender listens for TLS traffic on port 9998.
  5. Defender acts as a gateway to the Docker daemon. Defender checks if Bruce has the right to run the docker command on DevHostA.
  6. In this case, Bruce has the right permissions to run this docker command. His command is forwarded to the docker daemon.
  7. The response from the docker daemon is routed back to Bruce through Defender.

Setting Defender’s listener type

To enforce role-based access control, Defender’s listener type must be set to TCP.
Clients connect to the Docker socket and use the Engine API to manage and control containers on a host. The best known client is the docker command line tool (docker run, docker ps, etc).
In TCP mode, Defender intercepts traffic to the Docker socket and assesses it against the policies you have installed in Console. With this setup, Defender can block Docker commands and prevent them from reaching the Docker socket for execution by the Docker daemon.
In TCP mode, Defender listens for Docker traffic on port 9998 (this value can be configured). Defender runs as a Docker client with non-exclusive access to the Docker socket. Anyone who gains direct access to the Docker daemon will be able to bypass Defender and your policies. To prevent attackers from circumventing Defender, you should lock down your hosts and harden them for least privilege access.
Docker commands should only be run from remote machines through Defender on port 9998. Any user running Docker commands on port 9998 must be authenticated and authorized. Console generates certificates for users to authenticate to Defender. Any command run against Defender must also be explicitly whitelisted. Prisma Cloud ships with a default deny-all rule that blocks all commands for all users.
You can dynamically change Defender’s listening type from Console, even after Defender is installed.
  1. Open Console, and go to
    Manage > Defenders > Manage
  2. Click on a Defender listed in the table to open a dialog with more details.
  3. In the
    Choose the socket type
    drop-down list, select
  4. Click
    . The socket type for the Defender is updated in the Defenders status table.

Authentication and identity

Prisma Cloud can authenticate users against its internal local database. The initial admin user created when you first access Console, for example, is a local user. Prisma Cloud can also authenticate users against external services, such as Active Directory or OpenLDAP directory services, or SAML Identity Providers. For more information about integrating with an external service, see the articles under Access control.
Users are identified with client certificates. These certs are automatically generated by Prisma Cloud for each user. Users log into Console with their credentials, then download a script that installs the certs on their machine. Client certs should be installed on any host that runs the docker clients.
For example, to install the initial admin user’s clients certs on your host:
  1. Open Console.
  2. Log in with your credentials.
  3. Go to
    Manage > Authentication > User Certificates
    Users without admin privileges are directed to this page by default.
  4. Install your client certs, which are used to authenticate commands sent from the Docker client through Prisma Cloud.
    Copy the curl-bash command under
    Client certificate installation
    , then run it on your host. Your client certificate, client private key, and the certificate authority certificate are installed in $HOME/.docker/.
    If you’re using custom certificates for authentication, then the above commands only install the certificate authority in the default Docker folder. The other two user certificates must must be manually copied to this location.

Configuring Docker client variables

For access control to work, all Docker commands must be routed through Defender. You can configure your environment to shorten the Docker commands that target remote hosts protected by Defender. You should have already installed your client certificates.
To access Docker daemon through Defender, explicitly specify the host and the port of the Defender. For example:
$ docker -H <defender_host_address>:9998 run alpine
To simplify and shorten the Docker command, set up the following environment variables to route management traffic to Defender by default.
$ export DOCKER_HOST=tcp://<defender_host_address>:9998 $ export DOCKER_TLS_VERIFY=1
These environment variables can be set on a local machine (such as a dev laptop) that accesses Docker daemon on some remote host (such as a corporate cloud), or they can set directly on the host that runs Defender, for users who do not have root priviledges (which should be the majority of the users on such a host).

Creating an access control rule

This procedure shows you how to block the docker ps command for a user in an AD group called Prisma Cloud Devs.
You can modify the parameters to meet your own specific requirements.
  • For the purposes of example scenario, you have integrated Prisma Cloud with Active Directory. You could also integrate with OpenLDAP or SAML, or have Prisma Cloud manage your users and groups.
  • You have created AD groups for the different types of users that need access to Docker services. This procedure assumes you have a group called Prisma Cloud Devs, and that it has at least one user.
  1. Set up a user access rule.
    1. Log into Console as an admin user.
    2. Go to
      Defend > Access > Docker
    3. Click
      Add rule
    4. Enter a name for your rule.
    5. Set
    6. Select the
      to deny.
      For example, select
      to block access to the docker ps command.
    7. In the
      field, delete the wildcard (*) and enter the AD group(s) for which this rule applies.
      For example, enter
      Prisma Cloud Devs
    8. Click
    9. Verify that your new rule is at the top of the list.
      Console ships with a default rule that blocks all Docker commands from remote clients.
      Rules are enforced according to the order that they are listed in Console. Rules at the top of the list have a higher priority than rules lower down.
  2. Verify that your policy is being enforced.
    1. If you’re logged in to Console as an admin user, log out.
    2. Log into Console as a user from your AD group.
    3. On the
      Manage> Authentication > Credentials
      page, copy the install command for the client certificate.
    4. On your local machine, paste the install command into a shell window and run it.
    5. Run the docker command that you blocked with your new rule.
      $ docker -H <HOST_IPADDR | HOST_NAME>:9998 --tlsverify ps Error response from daemon: [Prisma Cloud] The command 'container_list' denied for user 'bruce@example.com' by rule 'devs_rule'


You cannot run Docker commands
First remove Prisma Cloud from the equation. Verify that you can communicate with Docker locally without Defender in the middle. After you have verified this setup, review the parameters you pass to the docker client.
Your policies are not being properly enforced.
Verify your user is in the AD group by following the below steps on the Docker host(s) where you’re trying to execute a command:
  1. Install ldap-utils:
    $ sudo apt-get install ldap-utils
  2. Query Active Directory to verify that your user belongs to your AD group. Use the same parameters that you specified in your integration configuration.
    $ ldapsearch \ -x -H [LDAP_URL] \ -D [LDAP_ADMIN_UPN] \ -W \ -b [LDAP_SEARCH_BASE]\ -s sub (&(userPrincipalName=[UPN])(memberof=[LDAP_GROUP_DN]))

Recommended For You