Skip to content

Application Firewall Definition

Jump to bottom
Giuliano Bellini edited this page Sep 4, 2025 · 3 revisions

This page lists the requirements to be satisfied by the interface when defining firewall rules, and is also a reference to how AppGuard firewall is designed.

Complete firewall example (JSON format).

Requirements

  • A firewall is characterised by a timeout (an integer), a default policy (“allow” or “deny”), a cache (true or false), and an array of expressions

  • Each expression includes a policy (“allow” or “deny”), and an array of tokens

  • Each token can be either a parenthesis (“open” or “close”), an operator (“and” or “or”), or a predicate

  • Each predicate includes a condition, a field, and optionally a direction (“in” or “out”)

  • The condition can be one of the following:

    • “equal”, “not_equal”, “greater_than”, “lower_than”, “greater_equal”, “lower_equal”, “contains”, “not_contains”, “starts_with”, “not_starts_with”, “ends_with”, “not_ends_with”

  • The field is composed of a key consisting in the field name, and of a value consisting in an array of values

  • The field name can be one of the following:

    • “source_ip”, “destination_ip”, “source_port”, “destination_port”, “protocol”, “country”, “asn”, “org”, “continent”, “city”, “region”, “postal”, “timezone”, “http_request_url”, “http_request_method”, “http_request_query”, “http_request_cookie”, “http_request_header”, “http_request_body”, “http_request_body_len”, “http_request_user_agent”, “http_response_size”, “http_response_code”, “http_response_header”

  • The array of values consists of strings, except for some fields:

    • Array of integers for the following fields: “source_port”, “destination_port”, “http_request_body_len”, “http_response_size”, “http_response_code” 

    • Map in the form {“header_name”: [“header_val_1”, “header_val_2”, “...”]} for the following fields: “http_request_query”, “http_request_header”, “http_response_header”

 

Further remarks about the optional direction field:

  • For fields whose name is in the form “http_request_*” the direction must be grayed-out and fixed to “in” (can be omitted from the JSON for simplicity)

  • For fields whose name is in the form “http_response_*” the direction must be grayed-out and fixed to “out” (can be omitted from the JSON for simplicity)

  • For other fields the direction should be selectable, defaulting to a standard value indicating that both directions “in” and “out” are selected

  • The direction field is omitted from the JSON representation to indicate that both directions “in” and “out” are selected (AppGuard will handle it consistently)

The frontend must be able not only to visually define expression respecting this structure, but also to produce a compatible JSON definition to be sent to the /appguard/api/v1/update_client_firewall HTTP POST endpoint of the server associated with the ID of the device for which the firewall is being defined (the body must be a payload with fields “device_id” and “firewall”).

Clone this wiki locally