Management Portal

Runtime configuration of Codesealer Enterprise is possible through the Management Portal.

Access control is possible through Organizations and Users.

Organizations

An Organization is a set of configured Endpoints, and a list of users that are allowed to configure the Organization.

Administrators can create Organizations, add users to them, and define which domains (with wildcards) that the Organization is allowed to control.

Creating a new Organization

Log in as Administrator. If you do not yet have an account, refer to the Management Portal installation chapter for information on how to obtain the Maintenance Administrator credentials.

The first thing you will see is the Organizations page. This can also be reached by clicking Organizations in the side menu.

Click on New Organization, and enter an Organization name.

Allowed Domains

An Organization is only allowed to configure rules for the allowed domains. To specify allowed domains, click on the Organization as administrator.

An allowed domain can be direct, e.g. example.com, or a wildcard, *.example.com. The former gives access to only example.com, while the latter gives access only to direct subdomains of example.com such as sub.example.com.

Multiple domains can be listed, simply click the green plus button.

Users

A User is either an Administrator or belonging to an Organization.

Creating a user

Log in as Administrator. If you do not yet have an account, refer to the Management Portal installation chapter for information on how to get obtain the Maintenance Administrator credentials.

Click Users in the sidebar.
Click New User.
Enter a username for login (e.g. johndoe), a display name (e.g. John Doe), and a password.
Select the Organization the user should belong to in the drop-down, and select whether the user should be Administrator.
Click Save Changes.

Changing a user

Log in as Administrator. If you do not yet have an account, refer to the Management Portal installation chapter for information on how to obtain the Maintenance Administrator credentials.

Click Users in the sidebar.
Click on the user you wish to change.
Make the changes you wish to make, and click Save Changes.

Deleting a user

Log in as Administrator. If you do not yet have an account, refer to the Management Portal installation chapter for information on how to obtain the Maintenance Administrator credentials.

Click Users in the sidebar.
Click on the user you wish to delete.
Click Delete User.

Changing password or display name

Administrators can change passwords use the "Changing a user" method above.

A user can change their password or display name by clicking on their name in the upper right corner, and selecting Profile.

Make the changes you wish to make, and click Save Changes.

Endpoints

Endpoints specify rules for routing traffic and applying protection.

If you are logged in as an Administrator, click Organizations in the sidebar and click on the Organization you wish to add Endpoints to. If you are logged in as a user belonging to an Organization, simply click Endpoints in the side menu.

Enter the "Incoming URL", e.g. "https://example.com". When a Codesealer Worker receives a request for this URL, it will apply the rules of this Endpoint. An incoming Endpoint prefix with an asterisk for the subdomain will serve as a subdomain fallback for unknown requests that match no existing Endpoint, i.e. https://a.b.com matches https://*.b.com. An absolute fallback matches everything else, i.e. http://nil.null.com matches http://* if http://*.null.com does not exist. The scheme of the incoming request and the Endpoint must be equal in all cases, i.e. http or https.

Enter the "Outgoing URL", e.g. https://1.2.3.4. When incoming requests are matched as described above, Codesealer Enterprise will forward the request to this target and proxy responses back to the client.

In order to enable protection, either enable "Automatically protect all scripts" or specify selected scripts in the "List of scripts to protect" field.

Click Save Changes. Codesealer Enterprise should now respond to the configured incoming URL.

For a description of all options for Endpoints, see the following section.

General Settings

This section describes the main settings you will need when setting up an endpoint.

Disable

Disables Codesealer protection for this endpoint. Traffic is still forwarded, but new requests will be unprotected.

Disable Mobile

Disable only mobile protection for this endpoint. Mobile clients will revert back to sending unprotected requests. Note that the 'disable' option overrides this option.

Incoming URL

This URL should match the hostname of the Codesealer instance. The reverse proxy will only process and protect requests that match the URL defined in this option - any other requests will result in a 404 Not Found response. Allowed values are URLs of the form

://[:port]

The scheme must be either http or https. The port is optional. A single leading * wildcard is allowed in the hostname. Some examples of wildcard usage is given below:

https://* will match any URL with the https scheme.
https://*.example.com will match any subdomain of example.com, but not https://example.com itself.
https://*example.com will match example.com and any subdomain.
https://*:443 will match any URL with the https scheme and port 443.
https://*.example.com:443 will match any subdomain of example.com on port 443.
https://example.com will match the standard port https://example.com:443, but not https://example.com:1234.

Note that usage of catch-all wildcards can cause issues. For example, setting the incoming URL to https://* will result in all requests being proxied to the outgoing URL. This includes ANP requests for external resources such as scripts hosted at a CDN. In most cases, such wildcard usage will cause problems.

Outgoing URL

This is the address where Codesealer will proxy requests to. Allowed values are URLs of the form

://[:port]

The scheme must be either http or https. The port is optional.

All requests matching the Incoming URL will be sent to this address instead. The request itself will not be altered - in particular, by default the Hostname header will not be modified.

List of scripts to protect

This comma separated list of scripts will select which scripts are protected. Only scripts that occur in HTML <script> tags will be protected this way. The entries need to match the src attribute in corresponding <script> tags exactly. When "Automatically protect all scripts" is enabled, entries in this list can be prefixed with optout: to remove protection from selected scripts.

Automatically protect all scripts

When checked, all scripts that occur in HTML <script> tags are protected by Codesealer Enterprise automatically. Note that scripts inserted dynamically after page load are not protected by this option - see instead the ANP section.

Ignore Remote TLS

When checked, Codesealer will ignore any TLS errors from the backend server. This is for example useful if self-signed or otherwise internal certificates are used.

Use Let's Encrypt for TLS certificate

This option will only appear if all Codesealer Workers support Let's Encrypt certificates. By enabling this option, you agree to the at any time applicable TOS for Let's Encrypt. Note: The DNS Record for the URL specified in "Incoming URL" must point to Codesealer.

TLS Certificate & TLS Key

The TLS certificate presented by Codesealer for this endpoint. It should be in X.509 PEM format, and should contain all intermediate certificates in the correct order:

Server Leaf Certificate
Intermediate CA 1
Intermediate CA 2
...

The corresponding TLS private key for the TLS certificate should likewise be in PEM format, and must not have a passphrase. Upon saving of the settings, the server will validate the cert/key pair, and issue a warning if it could not parse either, or if the key does not match the certificate.

ANP Settings

Application Network Protection (ANP) provides a way to protect XmlHttpRequest and fetch requests, allowing for secure dynamic application content.

Scope of XmlHttpRequest Compatibility

It should be noted that ANP will not support all features of XmlHttpRequest and fetch. However, the subset of the functionality it supports should be complete, and allow for XmlHttpRequest and fetch to be replaced with ANP.

Enable ANP on XHR and fetch requests

Enabling this option, all XHR and fetch calls will be automatically replaced by corresponding ANP variants. Essentially, the following code is injected:

var XMLHttpRequest = CoreHttpRequest;
var fetch = CoreFetch;

Expose protected XHR and fetch on window object

This allows ANP XHR and fetch to be accessed on the window object. The "Enable ANP on XHR and fetch requests" option must be enabled. Essentially, the following code is injected:

window.XMLHttpRequest = CoreHttpRequest;
window.fetch = CoreFetch;

Enable ANP on dynamic content

When enabling this option, scripts inserted dynamically on head and body elements will be intercepted and independently transferred through ANP. Essentially, to protect scripts inserted with e.g. appendChild following code is injected:

document.head.appendChild = ANPAppendChildHead;
document.body.appendChild = ANPAppendChildBody;

Similarly, the functions Node.insertBefore, Node.replaceChild, Element.append, Element.prepend, Element.replaceChildren, Element.replaceWith, and Element.insertAdjacentElement are replaced with protected versions.

Enable ANP on WebSockets

Enabling this option, all WebSocket calls will be automatically replaced by corresponding ANP variants. Essentially, the following code is injected:

var WebSocket = ANPWebSocket;

Expose Application Network Protection on window object

This allows ANP WebSockets to be accessed on the window object. The "Enable ANP on WebSockets" option must be enabled. Essentially, the following code is injected:

window.WebSocket = ANPWebSocket;

List of allowed domains

A comma separated list of allowed endpoints to protect for ANP requests. If the list is empty, all domains are allowed.

List of domains that bypass ANP

A comma separated list of domains that will bypass ANP. Entries must take the exact form <scheme>://<hostname or IP>[:port].

Session Lifetime

Session lifetime for Application Network Protection. If set to 0, the default will be used.

Cache Settings

Codesealer offers a simple HTTP cache built into each worker. Enabling this cache can improve resource delivery speed. See the cache section of the Worker configuration for details on how to set up each worker to use a cache.

Enable HTTP Caching

When enabled Codesealer Workers will cache requested resources based on the defined rules.

Cache Rules

Each cache rule consists of four parts:

Content-Type: The value of the Content-Type header to match on. Both 'contentType' and 'path' has to match for the resource to be cached. The special wildcard value '*' can be used to match all content types.
Path: The path of the request to match on. Both 'contentType' and 'path' has to match for the resource to be cached. The special wildcard value '*' can be used to match all paths.
Max-Age: If this value is not zero, the expiry of the cached resource will be overriden.
Ignore no-store: When enabled, resources are cached despite 'no-store' directives.
Ignore no-cache: When enabled, resources are cached despite 'no-cache' directives.

WAF Settings

Codesealer offers a simple Web Application Firewall (WAF) built into each worker. Enabling this WAF can provide an additional security layer on top of Codesealer's protection.

Enable Web Application Firewall

This option enables WAF for all requests. More specifically it will process request headers and request body. See the WAF Configuration section for more information.

Process response headers and body

When enabled the response headers and response body payload will also be processed.

Enable Monitor Mode on Web Application Firewall

When enabled no requests will be blocked on basis of the WAF, but will instead be logged.

Advanced Settings

Codesealer Enterprise contains a number of advanced features which are described in this section.

SNI Overwrite

This will set the Server Name Indication (SNI) on proxied TLS requests to the provided value instead of the requested host. This can be useful if the installed TLS certificate on the remote server is issued to a different domain.

Hostname Overwrite

This will set the Hostname header on proxied requests to the provided value instead of the requested host. This can be useful if the backend server uses virtual hosting.

Invalid HTML compatibility mode

This option must be enabled if the backend serves HTML where <script> tags occur after the </body> or </html> tags.

Window scope compatibility mode

Codesealer will execute scripts in a local scope, which differs from the global scope javascript is normally executed in. In such a scope, variables will not automatically be set on the window object, which can make a website running through codesealer behave differently. This option will patch these scoping issues in scripts live.

`document.write` compatibility mode

When this option is enabled, Codesealer will modify document.write calls to simulate their original behavior of inserting data after the script tag of the caller without re-opening the document, until all scripts that were part of the document have been executed.

This compatibility mode does not support partial write calls, where a single HTML element is written through more than one document.write call.

publicPath compatibility mode

Some sites will have scripts that attempt detecting where they're running from. This option will inject a transient script tag while each script is executing, revealing the directory the script is running from.

Strict Session Mode

When in strict session mode, Codesealer will block HTTP requests methods other than GET, HEAD or OPTIONS from clients that do not have an active Codesealer session. This means that methods like POST and DELETE will fail.

If API calls made by clients not protected by Codesealer must work, leave this setting disabled.

Block User Agents Mode

When in block user agents mode, Codesealer will block HTTP requests from clients with user agents that are known to be malicious. The list of blocked user agents is managed by Codesealer and not currently configurable by users.

(BETA) Enabled tamper checks

If enabled, the Bootloader will perform thorough tamper checks of the JavaScript runtime environment before allowing any code to run. This can detect attacks such as prototype pollution. This incurs an overhead of about 50ms to application startup time.

(BETA) Harden runtime

If enabled, the Bootloader will harden the JavaScript runtime environment, preventing any tampering with JavaScript built-ins, effectively preventing attacks like prototype pollution. This is likely to break most applications.

App Throttling Mode

When enabled requests will be redirected to a non-interactive validation page before being redirected to the requested URL. Once the session is validated, the validation page will not be shown again, unless the session hits a rate limit. This feature can reduce the effects of Layer 7 DDoS attacks.

App Throttling Rate Limit

When app throttling is enabled this value will determine the maximum sustained number of requests per second allowed for each client.

App Throttling Burst Limit

When app throttling is enabled this value will determine the maximum burst of requests allowed for each client.

App Throttling Iterations

When app throttling is enabled this value will determine the amount of iterations performed in the PoW challenge. The more iterations, the longer the validation page will take to complete for each client.

Omit X-Forwarded-For and X-Forwarded-Host headers

This option will stop Codesealer from setting the X-Forwarded-For and X-Forwarded-Host headers.

This option is meant for testing scenarios, where adding the headers may confuse existing infrastructure. This should not be used in production scenarios.

Strip Content-Security-Policy HTTP Header

This option will actively strip the Content-Security-Policy HTTP Header from all requests that have scripts protected. A better solution is to allow eval by setting the header

Content-Security-Policy: script-src 'unsafe-eval'

Location redirect compatibility mode

This option will ensure that absolute Location header redirects for the Outgoing URL are changed to relative URLs instead.

Disable Codesealer cookies support

When using Codesealer, requests that are sent to the Worker's domain (i.e. the value in "Incoming URL") may be redirected to another domain. This could either be the value in "Outgoing URL" or a third party domain, if using ANP. In order to attach the correct cookies to these requests, Codesealer will add some extra cookies to responses.

If this option is enabled, these extra cookies will not be attached to responses. This can cause some cookies to not be set on protected requests.

Kill Switch

This option will terminate all connections to this endpoint as early as possible. For TLS, this will happen during the TLS handshake, while for non-TLS it will happen right after the endpoint is registered.

The option can be used in certain scenarios to mitigate smaller DoS attacks on multi endpoint deployments.

Proxy path filter

If API endpoints are placed under a certain path, this can be added here to block regular proxy requests from reaching these endpoints. Rules are processed firewall style, in the sense that the first matching rule will take effect. The path matching is case insensitive.

Note: This blocking is not effective if endpoint is disabled or if accessing from an IP contained in the IP Bypass list.

Protection path filter

This option will allow selective bypassing of all protection. The main settings (e.g. protect all scripts by default) will take precedence, in the sense that these rules can only cause a bypass of a script that would otherwise be protected, or force the default behavior.

The rules are parsed firewall style, and they can be set to either "Bypass" or "Default". The first rule that matches will take effect. The path matching is case insensitive.

Retain attributes on protected scripts

Protected scripts are normally replaced with empty script tags with no attributes. When enabled, this option makes protected scripts retain most of their attributes. This can be useful if the application logic relies on reading attributes of certain scripts. Note that enabling this option may reveal some internals of the application logic.

IPs that bypass protection

The IP addresses listed in this field will bypass Codesealer protection. Please note that additional configuration is needed for Codesealer to see client IPs when using proxy servers or load balancing in front of Codesealer.

Note: If the "Invert IP bypass list" option is set, only IPs that match the entries in the list will be protected.

Invert IP bypass list

Invert the behavior of the "IPs that bypass protection" option.

IPs permitted access to this endpoint

If specified, only traffic originating from IP addresses listed in this field will be allowed to access the endpoint.

JavaScript symbols to expose to window object

A comma separated list of JavaScript symbols to expose on the window object. This option essentially injects the following code for each symbol:

try {
  typeof window.symbol !== 'undefined' && (symbol = window.symbol);
} catch {}

...

try {
  window.symbol = symbol;
} catch {}

Minify ES6 module bundles

ES6 modules are bundled into a single file when served by the proxy. Enable this option to also minify the bundle.

Script preamble

This field will inject the given JavaScript code into the beginning protected scripts. This can be used in debugging scenarios, where it is not feasible to modify certain aspects of a protected application.

Script postamble

This field will inject the given JavaScript code at the end of all protected scripts. This can be used in debugging scenarios, where it is not feasible to modify certain aspects of a protected application.

Script string replace

This option will instruct Codesealer to do a simple search/replace on all JavaScript that it protects.

Metrics

Metrics show you information about traffic flowing through configured endpoints.

Accessing metrics

If you are logged in as administrator, click Organizations in the sidebar and click on the small graph logo on the right side for the organization you wish to see metrics for.

If you are logged in as a user belonging to an organization, simply click Metrics on the left hand menu.

You will see a number of graphs for each endpoint, which are explained further in the following sections.

Request Types

The request types graph counts the number of incoming HTTP requests, in Requests per Second. This is useful to estimate the transactional performance of the system, rather than simply observing the network throughput.

It is divided into the four main types of requests: Proxy, ANP, WebSocket and Mobile

Proxy

This category includes requests that are simply being forwarded by codesealer acting as a reverse proxy. That could be loading the HTML content of a site or fetching an image or css resource.

Note that these requests do not have an added layer of Codesealer encryption, unlike the other types.

ANP

This category includes XMLHttpRequest and fetch requests that have been wrapped in an extra layer of Codesealer encryption. They can be seen in the browser inspector as XHR requests destined for the endpoint /~bl/x.

For these requests to be counted, ANP on XHR and fetch has to be enabled for the endpoint.

WebSocket

This category includes WebSocket requests that have been wrapped in Codesealer encryption. It is worth noting that each WebSocket connection will only be counted once here, regardless of how long-lived the session is, or how many messages are transmitted.

For these requests to be counted, ANP on WebSockets has to be enabled for the endpoint.

Mobile

This category includes encrypted requests performed through mobile applications using the Codesealer Mobile SDK.

Request Handling Time

The request time graph shows two sub-graphs: Total and remote time.

Total time is the time it took us to read the request from the end-user, do any internal processing, and send a response to the end-user.

Remote time is the time it took us to write the request to the backend server, wait for any processing to complete, and receive the response.

If Total time is high, it may be indicative of poor network connectivity from users. If Remote time is high, it may be indicative of a slow or overloaded backend.

Suspicious Requests

This graph shows the rate of requests that have been marked as suspicious. This is divided into these sub categories:

Anonymous

Requests that are not associated with an active Codesealer session. If this is high, it can be indicative of automated scraping activity.

Blocked

Requests that have been blocked for various reasons. This includes enforcement of Proxy Path Rules, IP Access Rules, WAF rules, etc.

Suspicious User Agent

This category counts requests made with suspicious user agents. This will normally constitute requests that do not appear to be made using a regular browser. It could be command line utilities, automated hacking tools or crawler bots.

Potential Debugging

This category counts ANP requests made from a session marked as potentially having an active browser debugger running. Using the browser debugger is a normal first step for adversaries when assessing a potential target.

Totals

The graphs marked (Total) add up the total number of requests in the given query interval for each category.