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. Fill in a name for the cluster and add one environment (e.g. dev) and click Create
5. Click 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 \
-e ENVIRONMENT_NAME=dev \
--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 2375:2375 \
public.ecr.aws/bifrostsec/bifrost-agent:0.9.9

Change ENVIRONMENT_NAME value to the environment name chosen during cluster create in step 1.

3. Set DOCKER_HOST environment variable

export DOCKER_HOST=tcp://localhost: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 2375:2375 \
public.ecr.aws/bifrostsec/bifrost-agent:0.9.9

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.9
  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:
  - 2375:2375

Operation

Configure docker client

Set environment variable DOCKER_HOST=tcp://localhost: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.environment.name=dev \
--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

Some defaults (environment name and profile mode) can be set/overridden by setting environment variables for bifrost-agent and these values will apply for all containers deployed. Settings these defaults together with deploying named containers enables bifrost on any deployed container.

Run bifrost-agent with these extra environment variables:

-e ENVIRONMENT_NAME=dev
-e PROFILE_MODE=audit

Deploy named container with no labels:

docker run --name nginx nginx:1.27.4

Privileges for bifrost-agent

The agent needs to run with some 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.

Container labels

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