Docker (Engine)

Docker is a widely used containerization platform that allows you to build, run, and manage containers. It provides a simple and efficient way to package applications and their dependencies into portable containers.

How it works

The bifrost agent supports running on Docker and enables auditing and securing containers deployed directly on Docker Engine. The agent is deployed as a container on Docker to enable the usual features (reading Linux Kernel audit events and loading/unloading security profiles). To enable automatic detection of containers being deployed the agent also works as a Docker API proxy and intercepts container create requests.

Prerequisites

• Docker Engine installed on a host machine that has AppArmor enabled (like Ubuntu and Debian) and 64bit x86 or arm CPU architecture.
• Access to Docker API either via Unix socket (default) or TCP socket from commandline.
• Account in bifrost portal and an AGENT_KEY for a registered cluster there.

Quickstart

1. Get an AGENT_KEY for deployment

1. Login to bifrost portal
2. Click Clusters in the left menu.
3. Click Register new cluster button in the top left corner.
4. Click the copy icon next to “Agent key” text on the cluster overview page and store it somewhere safe.

2. Deploy bifrost-agent on Docker

Set the AGENT_KEY environment variable to the value you copied in step 1.

export AGENT_KEY=<your-agent-key>

Then run the bifrost agent container with the following command:

docker run -d --name bifrost-agent \
-e SECURITY_FS_PATH=/host/sys/kernel/security \
-e AGENT_KEY=$AGENT_KEY \
-e PROFILE_MODE=audit \
--cap-add NET_BROADCAST \
--cap-add AUDIT_READ \
--cap-add MAC_ADMIN \
-v /sys/kernel/security/apparmor:/host/sys/kernel/security/apparmor \
-v /var/run/docker.sock:/var/run/docker.sock \
-p 127.0.0.1:2375:2375 \
public.ecr.aws/bifrostsec/bifrost-agent:0.9.11

Note that in this example the Docker API port is only exposed on localhost to avoid it being reachable from outside the host.

3. Set DOCKER_HOST environment variable

export DOCKER_HOST=tcp://127.0.0.1:2375

4. Start a container audited by bifrost

docker run --name nginx nginx:1.27.4

Don’t forget to use the --name flag to set a name for the container, otherwise bifrost will not be able track it.

5. Check container behaviour in bifrost portal

Click Services in the left menu in the bifrost portal and you should see a service listed there with name matching the container you just deployed.

Detailed deployment

bifrost portal

1. Create a new cluster in the bifrost portal.
2. Register new cluster in portal.
3. Copy the AGENT_KEY from the cluster details page.

Docker CLI

To deploy the bifrost agent using the Docker CLI, you can use the following command:

docker run -d --name bifrost-agent \
-e SECURITY_FS_PATH=/host/sys/kernel/security \
-e AGENT_KEY=$AGENT_KEY \
--cap-add NET_BROADCAST \
--cap-add AUDIT_READ \
--cap-add MAC_ADMIN \
-v /sys/kernel/security/apparmor:/host/sys/kernel/security/apparmor \
-v /var/run/docker.sock:/var/run/docker.sock \
-p 127.0.0.1:2375:2375 \
public.ecr.aws/bifrostsec/bifrost-agent:0.9.11

Docker Compose

To make it easier to deploy the bifrost agent, you can use Docker Compose.

docker-compose up -d

With the following docker-compose.yaml file:

name: bifrost-agent
services:
bifrost-agent:
  image: public.ecr.aws/bifrostsec/bifrost-agent:0.9.11
  environment:
    - AGENT_KEY=$AGENT_KEY
    - SECURITY_FS_PATH=/host/sys/kernel/security
  cap_add:
    - NET_BROADCAST
    - AUDIT_READ
    - MAC_ADMIN
  volumes:
    - type: bind
      source: /sys/kernel/security/apparmor
      target: /host/sys/kernel/security/apparmor
    - type: bind
      source: /var/run/docker.sock
      target: /var/run/docker.sock
  ports:
  - 127.0.0.1:2375:2375

Operation

Configure docker client

Set environment variable DOCKER_HOST=tcp://127.0.0.1:2375 to use the bifrost agent as a Docker API proxy.

Deploy container with labels

Deploy your container you want to audit and use labels to configure how bifrost-agent will handle it.

Example:

docker run \
--label com.bifrostsec.profile.mode=audit \
--label com.bifrostsec.service.name=nginx \
--label com.bifrostsec.service.version=1.27.4 \
nginx:1.27.4

Deploy container without labels

Default profile mode can be set/overridden by setting environment variable PROFILE_MODE for bifrost-agent and this mode will apply for all containers deployed. Setting this together with deploying named containers enables bifrost on any deployed container.

Run bifrost-agent with this extra environment variable:

-e PROFILE_MODE=audit

Deploy named container with no labels:

docker run --name nginx nginx:1.27.4

Required privileges

The agent requires som extra capabilities (AUDIT_READ, NET_BROADCAST, MAC_ADMIN) same as when deployed on Kubernetes) and bind mounting the host path /var/run/docker.sock and /sys/kernel/security/apparmor to the container.

Tuning Kernel Audit subsystem

To avoid losing audit events when there is a high load of events being generated on the host, you may need to tune the Linux Kernel Audit subsystem by altering the rate limit and adding some audit filter rules. The agent supports for doing this automatically by running it as a one-off container:

docker run -it --rm --name bifrost-agent-init \
-e KERNEL_AUDIT_INIT=true \
--pid=host \
--cap-add NET_BROADCAST \
--cap-add AUDIT_READ \
--cap-add AUDIT_CONTROL \
public.ecr.aws/bifrostsec/bifrost-agent:0.9.11

Container labels

Container label	Env var override	Default value
com.bifrostsec.profile.mode	PROFILE_MODE	(none)
com.bifrostsec.environment.name	ENVIRONMENT_NAME	(none)
com.bifrostsec.service.name	(none)	from container name (if set during deploy)
com.bifrostsec.service.version	(none)	from container image tag