Connect Deployed Agents to SaaS Management (Docker)

Prerequisites

• Access to a SaaS tenant on my.openappsec.io (WebUI for SaaS management) Follow the instructions available here:

Sign-Up and Login to Portal

• Agent profile created for open-appsec Docker deployment in SaaS tenant Follow the instructions available bellow, once done, don't forget to copy the profile token after policy installation as this is needed in the installation steps further below:

Create a Profile

• Linux machine with:

  • Docker software installed (or similar compatible Container runtime)

  • Root Permissions

• Existing open-appsec WAF deployment on Docker which is:

  • locally managed

  • not connected to the central WebUI yet

Instructions:

Docker Compose (SWAG / NPM)

Step 1: Update your docker-compose.yaml file:

• Locate the AGENT_TOKEN key in your docker-compose.yaml file.

• Copy the Token from your WebUI Docker Profile (as described in the prerequisites) and paste it as the value for the AGENT_TOKEN key.

Example docker-compose.yaml snippet, make sure to do the above change in your own docker-compose.yaml file:

version: '3'
services:
  openappsec-agent:
    image: ghcr.io/openappsec/agent:latest
    container_name: open-appsec-agent
    environment:
      - registered_server=NGINX Server
      - user_email=<add-your-email-here>
      - https_proxy=<user:password@proxy-address:port>
      - autoPolicyLoad=false
      - AGENT_TOKEN=<your-agent-token>
    volumes:
      - <path-to-persistent-location-for-agent-config>:/etc/cp/conf
      - <path-to-persistent-location-for-agent-data-files>:/etc/cp/data
      - <path-to-persistent-location-for-agent-debugs-and-logs>:/var/log/nano_agent
      - <path-to-persistent-location-for-local-configuration-file>:/ext/appsec
    ipc: host

If you chose "“Declarative configuration” management make sure to keep the agent local configuration file volume mount which gets mounted to /ext/appsec inside the agent container.

If you chose "This Management" then the above mentioned volume mount is no longer needed, and can be removed.

Step 2: Apply the adjusted Docker Compose configuration: Run the following commands to recreate the agent container based on the adjusted Docker Compose file which now includes the AGENT_TOKEN specification for connecting to Management WebUI (SaaS):

docker-compose up -d

Step 3: Verify the connection:

• Log in to the Web UI and check if your agent is connected.

Docker Run (NGINX / Kong)

Step 1: Stop and remove the current open-appsec agent container:

docker stop open-appsec-agent
docker rm open-appsec-agent

Step 2: Run the open-appsec Docker container with the updated AGENT_TOKEN replace <your-agent-token> with the actual token copied from the Web UI.

Command example:

docker run --name=open-appsec-agent \
--ipc=host \
-v <path-to-persistent-location-for-agent-config>:/etc/cp/conf \
-v <path-to-persistent-location-for-agent-data-files>:/etc/cp/data \
-v <path-to-persistent-location-for-agent-debugs-and-logs>:/var/log/nano_agent \
-v <path-to-persistent-location-for-local-configuration-file>:/ext/appsec \
-e registered_server='NGINX Server' \
-e user_email=<add-your-email-here> \
-e https_proxy=<user:password@proxy-address:port> \
-e autoPolicyLoad=false \
-e AGENT_TOKEN=<your-agent-token> \
-it -d ghcr.io/openappsec/agent:latest /cp-nano-agent

If you chose "“Declarative configuration” management make sure to keep the agent local configuration policy mount.

If you chose "This Management" this is no longer needed, and can be removed.

This is an example of a docker run command. Depending on your deployment (e.g., different environments, volume paths, or server configurations), you may need to adjust the paths and parameters.

Step 3: Verify the connection: Log in to the Web UI and confirm that your agent is listed as connected.

If you chose “This management” management mode:

Step 4: Create one or more assets in the Web UI, make sure to connect the asset to the profile you have created in the Prerequisites:

Protect Additional Assets