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
  • Prometheus
  • 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
  • Location of the declarative configuration file
  • Basic configuration
  • Applying a changed local declarative configuration file

Was this helpful?

  1. Getting started
  2. Start with Docker

Configuration Using Local Policy File (Docker)

For deployments of open-appsec on Docker the configuration can be done in a declarative way using a single YAML file which holds all the relevant configuration objects. This way it is fully compatible for integration in GitOps CD-based processes.

Alternatively management can also be done centrally via the central open-appsec WebUI (SaaS).

Location of the declarative configuration file

On Docker the declarative configuration file for the open-appsec Agent is typically provided to the agent container via a volume mount.

In your docker-compose.yaml or the docker run command which you used for your current deployment you can find the specific folder on the docker host which gets mounted to /ext/appsec in the open-appsec agent container. This is the folder which should contain your local_policy.yaml file. (Note that this folder then gets mounted internally to /etc/cp/policy/local_policy.yaml which is where the agent looks for the actual local policy to apply, but on Docker you should always manage the file in /ext/appsec file location)

You can show and edit the full default declarative configuration file with the following command:

From within the appsec-agent container:

vi /ext/appsec/local_policy.yaml

or by using the interactive CLI tool open-appsec-ctl : Using the open-appsec-ctl Tool

From the docker host:

(replace "appsec-agent" with your own agent container name, if you adjusted it):

docker exec -it appsec-agent vi /ext/appsec/local_policy.yaml

Basic configuration

The default policy within the default configuration file, which is deployed during the installation, contains the following setting which sets the mode to detect-learn for all web resources provided by the NGINX or Kong Gateway:

policies.default.mode: detect-learn

If you want attacks instead to be prevented by default for all web resources you can change this as follows:

policies.default.mode: prevent-learn

The specific rules section policies.specific-rules (v1beta1) / policies.specificRules (v1beta2) allows you to create specific rule entries for specific hostnames, hostname-path combinations or paths which override the default policy.

The mode settings defined in the policy for default or specific-rules will only have an effect on the actual enforcement for specific security features when the override-mode setting in the referenced practice is set to as-top-level as this will cause it to inherited the mode setting from the policy.

It is recommended to configure a specific rule for each of your protected web applications and web APIs assets (starting with detect-learn mode, later move to prevent-learn). This allows you to apply a separate enforcement mode setting for each of these protected assets as well as to customize many other settings like selecting the logging configuration, the threat prevention and access control (introduced in v1beta2) practices configuration or selecting a custom-response like a specific response code or a custom block page.

Also the real-time contextual machine learning will be done individually per each configured specific rule representing a protected asset. Note that these settings are all configured by referencing other elements which are defined separately in the configuration file as well, so that you can reuse them multiple times in a kind of object-oriented way, see examples below:

policies:
  default:
  ...
  ...
  specific-rules:
  - host: "www.my-specific-host.com/my-specific-path"
    triggers:
    - appsec-default-log-trigger
    mode: detect-learn
    practices:
    - webapp-default-practice
    custom-response: appsec-default-web-user-response

It is recommended that once sufficient confidence was gained in detect-learn mode for an asset which has a specific rule (review the logs) to change the mode for this specific rule to prevent-learn mode:

policies:
  default:
  ...
  ...
  specific-rules:
  - host: "www.my-specific-host.com/my-specific-path"
    triggers:
    - appsec-default-log-trigger
    mode: prevent-learn
    practices:
    - webapp-default-practice
    custom-response: appsec-default-web-user-response
policies:
  default:
  ...
  ...
  specificRules:
  - host: "www.my-specific-host.com/my-specific-path"
    triggers:
    - appsec-default-log-trigger
    mode: detect-learn
    threatPreventionPractices:
    - webapp-default-practice
    accessControlPractices:
    - webapp-default-practice
    customResponse: appsec-default-web-user-response

It is recommended that once sufficient confidence was gained in detect-learn mode for an asset which has a specific rule (review the logs) to change the mode for this specific rule to prevent-learn mode:

policies:
  default:
  ...
  ...
  specificRules:
  - host: "www.my-specific-host.com/my-specific-path"
    triggers:
    - appsec-default-log-trigger
    mode: prevent-learn
    threatPreventionPractices:
    - webapp-default-practice
    accessControlPractices:
    - webapp-default-practice
    customResponse: appsec-default-web-user-response

Applying a changed local declarative configuration file

Once you did any changes to the local declarative configuration file local_policy.yaml there's two ways how you can get those changes applied:

  1. By using the open-appsec-ctl tool to apply the changes in the policy:

  • From inside the Agent container:

open-appsec-ctl --apply-policy
  • From the docker host:

docker exec -it appsec-agent open-appsec-ctl --apply-policy

Replace appsec-agent with your agent container name, if it has a different name.

  1. By configuring the agent to automatically apply all changes in the local_policy.yaml file in /ext/appsec once you save any changes within the file: Activate automatic policy load for the open-appsec agent by setting the following environment variable to true in your docker-compose.yaml or docker run command: autoPolicyLoad=true This is especially useful in CI/CD-style deployments that have a continuous deployment process in place.

PreviousDeploy With Docker-Compose (Beta)NextLocal Policy File (Advanced)

Last updated 3 months ago

Was this helpful?