open-appsec
WebsiteManagement PortalPlaygroundGitHub
  • open-appsec Documentation
  • What is open-appsec?
  • open-appsec Video Tutorials
  • Release Notes
  • Getting started
    • Getting Started
    • Start With Kubernetes
      • Install Using Interactive CLI Tool (Ingress NGINX)
      • Configuration Using Interactive CLI Tool
      • Install Using Helm
      • Install Using Helm - new flow (beta)
      • Configuration Using CRDs
      • Configuration Using CRDs - v1beta2
      • Configuration using CRDs - special options for Large Scale Deployments
        • Using appsec class for assigning separate custom resources to specific deployments
        • Using namespace-scoped custom resources
      • Monitor Events
    • Start With Linux
      • Install open-appsec for Linux
      • Using the open-appsec-ctl Tool
      • Configuration Using Local Policy File (Linux)
      • Local Policy File (Advanced)
      • Local Policy File v1beta2 (beta)
      • Monitor Events
    • Start with Docker
      • Install With Docker (Centrally Managed)
      • Install With Docker (Locally Managed)
      • Deploy With Docker-Compose (Beta)
      • Configuration Using Local Policy File (Docker)
      • Local Policy File (Advanced)
    • Using the Web UI (SaaS)
      • Sign-Up and Login to Portal
      • Agents Deployment
      • Connect Deployed Agents to SaaS Management Using Tool (K8s & Linux)
      • Connect Deployed Agents to SaaS Management Using Helm (K8s)
      • Connect Deployed Agents to SaaS Management (Docker)
      • Create a Profile
      • Protect Additional Assets
      • Monitor Events
    • Using the Advanced Machine Learning Model
  • Concepts
    • Agents
    • Management & Automation
    • Security Practices
    • Contextual Machine Learning
  • SETUP INSTRUCTIONS
    • Setup Web Application Settings
    • Setup Custom Rules and Exceptions
    • Setup Web User Response Pages
    • Setup Log Triggers
    • Setup Behavior Upon Failure
    • Setup Agent Upgrade Schedule
  • Additional Security Engines
    • Anti-Bot
    • API Schema Enforcement
    • Data Loss Prevention (DLP) Rules
    • File Security
    • Intrusion Prevention System (IPS)
    • Rate Limit
  • Snort Rules
    • Import Snort Rules
    • Write Snort Signatures
  • HOW TO
    • Configuration and Learning
      • Track Learning and Move From Learn/Detect to Prevent
      • Configure Contextual Machine Learning for Best Accuracy
      • Track Learning and Local Tuning in Standalone Deployments
      • Move From Detect to Prevent in K8s With Many Ingress Rules
  • Deployment and Upgrade
    • Load the Attachment in Proxy Configuration
    • Upgrade Your Reverse Proxy/API Gateway When an Agent is Installed
    • Integration in GitOps CD (K8s)
    • Build open-appsec Based on Source Code
  • Management Web UI
    • Track Agent Status
    • Delete or Reset Management Tenant (SaaS)
    • Disconnect an open-appsec agent from Central Management
  • Integrations
    • About Integrations With 3rd Party Solutions
    • CrowdSec
      • CrowdSec Bouncer Support
      • CrowdSec Intelligence Sharing Using open-appsec Parser/Scenario
    • NGINX Proxy Manager
      • Install NGINX Proxy Manager with open-appsec managed from NPM WebUI
      • Install NGINX Proxy Manager with open-appsec managed from central WebUI (SaaS)
      • Frequently Asked Questions
      • How to Migrate from an Existing NGINX Proxy Manager Deployment and Keep Configuration
    • NPMplus
    • Docker SWAG
      • Install Docker SWAG with open-appsec (locally managed)
      • How to connect locally managed Docker SWAG with open-appsec to WebUI
      • Install Docker SWAG with open-appsec (centrally managed)
      • Deploy Docker SWAG with docker-compose (beta)
      • Frequently Asked Questions
  • Troubleshooting
    • Troubleshooting
    • Troubleshooting Guides
      • Configuration contains ingress/asset with URL which already has asset attached to it in your tenant
      • HTTP Request to Port 80 Not Returning as Expected
      • Agent Fails to Recognize HTTP Transactions with NGINX
      • Agent Not Recognizing Initial HTTP Requests
      • Handling Large Requests (413 Responses)
      • open-appsec on Docker HTTP Transaction Handler Is Set To Ready
      • Traffic Recognition Issue on Single-Core Machine/Connection Timed Out
      • Installing open-appsec on CentOS 7
      • SELinux: checking status and disabling
      • Deploy open-appsec directly on the web server hosting the application to protect
      • object is locked or remote, and therefore cannot be modified
      • Failed to Register to Fog
  • references
    • Agent CLI
    • Event Query Language
    • Events/Logs Schema
    • WAF Comparison Project
Powered by GitBook
On this page
  • Prerequisites
  • Instructions:

Was this helpful?

  1. Getting started
  2. Using the Web UI (SaaS)

Connect Deployed Agents to SaaS Management (Docker)

PreviousConnect Deployed Agents to SaaS Management Using Helm (K8s)NextCreate a Profile

Last updated 2 months ago

Was this helpful?

Prerequisites

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

  • 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:

  • 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:

Optional: Perform One-Time Upload of Your Existing Local Configuration to Central WebUI If You Want to Maintain It (relevant for Central Management Mode Only)

If you want to maintain your existing local, declarative configuration after connecting to central WebUI, so that it will become the initial starting point for the central management configuration (requires WebUI deployment profile set to "This management"), follow these optional steps to perform a one time upload of your existing local, declarative configuration to the central management (SaaS).

This option is not relevant when you want to connect to a deployment profile in central management WebUI set to "Declarative configuration", as in that case WebUI will continuously show the current, declarative configuration, which you will still manage locally.

If you do not perform this step and have the deployment profile set to "This management" you will start with a new clean (empty) central configuration for your existing deployment.

Step 1: Download the mgmt-connect-linux tool

Run the following command to download and prepare the mgmt-connect-linux tool inside the existing, running agent container:

docker exec -it open-appsec-agent bash -c "wget https://downloads.openappsec.io/scripts/mgmt-connect-linux && chmod +x mgmt-connect-linux"

Step 2: Perform one-time upload of the existing local configuration

Use the token generated in your deployment profile during the prerequisites to upload the policy. Replace <TOKEN> with your actual deployment profile token:

docker exec -it open-appsec-agent bash -c "./mgmt-connect-linux --token <TOKEN> --config-upload-only"

Notes:

  • The container name for the agent container in your environment could have been changed based on your original deployment, in that case adjust open-appsec-agent in the commands above with your own agent container name.

If you deployed open-appsec using docker-compose command with .env file):

Step 1: Add the deployment profile's token to your .env file:

  • Locate the APPSEC_AGENT_TOKEN= key in your .env file.

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

Example .env file snippet, make sure to do the above change in your own .env file and provide your own deployment profile token copied from the Web UI for <your-agent-token>:

## To connect your deployment to central open-appsec WebUI provide the token for a profile
## which you created in open-appsec WebUI at https://my.openappsec.io
## Example: APPSEC_AGENT_TOKEN=111-22222-111
APPSEC_AGENT_TOKEN=<your-agent-token>

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 provided in the .env file: 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.

If you deployed open-appsec using docker-compose command (without using a .env file):

Step 1: Add the deployment profile's token to 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 providing your own deployment profile token copied from the Web UI for <your-agent-token>:

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.

If you deployed open-appsec using docker run command:

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 again providing the WebUI deployment profile token as value for the AGENT_TOKEN key:

Here's a docker run command example for nginx, you would have to replace <your-agent-token> with the relevant deployment profile token copied from WebUI.

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, and didn't upload the policy:

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:

Sign-Up and Login to Portal
Create a Profile
Protect Additional Assets