Manage API Firewall configuration

After you have configured and deployed API Protection for your API, you can update the protection configuration if your API changes, add or remove protection tokens, or change how API Firewall behaves.

View the API Firewall configuration status

You can quickly check if your API has an API Firewall instance protecting it and when the protection configuration was last updated.

  1. In 42Crunch Platform, go to the API collection you want.
  2. Check the icons in the Firewall column. These tell you the status of API Firewall for that API, for example:
    • If the API has an active API Firewall instance protecting it.
    • If the API has a protection configuration but there is no active instance of API Firewall currently running and protecting it.
    • If the API does not yet have a protection configuration.

    The example screenshot shows the Firewall column from an API collection page. The collection has six APIs that showcase the six possible statuses for the firewall instance: active, active with a failed configuration attempt, error preventing the firewall from starting, inactive but configured, not configured, and inactive but configured with a failed configuration attempt.

  3. If an icon has on it, this means that the last attempt to update the protection configuration has failed. This does not mean that your API is no longer protected: the running API Firewall instances are using the last successful protection configuration from before the failed update attempt.
  4. If you hover on an icon, you can see when the protection configuration that API Firewall is using was last updated and, in case of failed updates, when the update attempt failed.
  5. If there is ERROR in the Firewall status column, this means that the Firewall cannot start at all because an error was encountered when compiling the protection configuration. To view the details of the compilation error, click on the status to go to the Protection tab.

Reconfigure API Protection

If your API has changed, you can reconfigure its protection configuration. Any active API Firewall instances protecting the API are automatically restarted to run the new configuration.

  1. Find the API you want, and click to view the API summary. The quickest way to find API definitions in 42Crunch Platform is to click Find API in the main menu.
  2. Under Protection, click the reconfigure button.
  3. Confirm reconfiguration, and click Reconfigure.

A new protection configuration is created based on the API definition, and running API Firewall instances are reconfigured. Reconfiguration is graceful, meaning that ongoing transactions are completed without interruption, while new transactions will be serviced using the new configuration.

In the rare case that an API Firewall instance receives a configuration that is not valid and cannot be run, the instance and its Kubernetes pod immediately exit and this is logged in your Kubernetes logs. You can also see this in the details of the API, both in the API collection view and on the Protection tab of the API.

When you reconfigure the protection configuration, the existing associated protection token is not regenerated but stays the same. To change a protection token for an API, you must create the new token manually.

Create or revoke protection tokens manually

You can create more than one protection token for your API, and use them to manage deployments in multiple environments independently of one another. You can also revoke protection tokens that are no longer needed.

If you have several APIs and several environments, it can be difficult to keep track of where each protection token is used. To stay on top of things, in addition to giving descriptive names to protection tokens, use descriptive names for your stored secrets as well, for example, in Kubernetes secrets. We recommend that you include the name of the token and the name or API UUID of the API in the name of the secret. For example, in a Kubernetes secret generic-pixi-protection-token, generic is the name entered for the token when it was created and pixi is the name of the API the token was created for.

  1. On the Protection tab of the API, click Protection Tokens.

    The Protection tab of an API showing the menu on the left.

  2. Click Create Token.
  3. Enter a unique name for the protection token, and click Generate Token.
  4. Copy the token value and add it to your secrets.
  5. To revoke a protection token, click the Revoke button on the token.

If you want to change a protection token that is used in running API Firewall instances, you must reconfigure the firewall instances and redeploy them so that they run the correct protection configuration.

Set API Firewall connect to the platform through a HTTPS proxy

When API Firewall instance starts, an agent component connects to 42Crunch Platform to fetch the protection configuration. During runtime, the same agent also uploads transaction logs to the platform, if you have not changed this default behaviour.

Connecting to the platform is not an issue as long as the firewall instance has direct internet access, but if this connection must go through a proxy, some additional configuration is needed.

  1. Open the file for configuring the API-specific API Firewall variables. Where this is done depends on the environment of your deployment. For more details, see Deploy API Firewall for your own APIs.
  2. Add the environment variable HTTPS_PROXY, and enter the address of your proxy server.

    The env var HTTP_PROXY is not supported, the connection must use TLS.

  3. Save the file, and redeploy the API Firewall instance.

Set API Firewall blocking level

By default, active API Firewall instances protecting an API block any transactions that are in violation of the API contract. However, if needed, you can control the blocking level in API Protection and choose what exactly API Firewall blocks.

Changing the blocking level in the API Firewall instance also decreases the level of protection it gives to your API and can leave your API unprotected! The instance continues to execute security policies normally but does not block any transactions, it only reports what would have been blocked. Proceed with caution, and only change the blocking level when absolutely necessary.

If you selected level 0—4 or level 6 without any controls, we recommend you reconfigure the blocking level and return API Firewall to normal operation mode as soon as possible.

Switch log destination for API Firewall logs

By default, API Firewall publishes transaction logs to 42Crunch Platform. You can switch the log destination to a separate directory you mount in your deployment, or to set logs to be written as standard output.

An example screenshot showing two active instances for the Pixi API.

  1. Open the file for configuring the API-specific API Firewall variables. Where this is done depends on the environment of your deployment. For more details, see Deploy API Firewall for your own APIs.
  2. Add the environment variable LOG_DESTINATION, choose of the following possible values, and save the file:
  3. Value Impact
    PLATFORM

    Transaction logs are published to 42Crunch Platform.

    Error logs and access logs are written to the file system of the API Firewall container.

    This is the default value.

    FILES

    All transaction, error, and access logs are written to a directory that you mount to your deployment as a volume for /opt/guardian/logs/${GUARDIAN_INSTANCE_NAME}.

    STDOUT All transaction, error, and access logs are written as standard output (STDOUT) to console.
    FILES+STDOUT

    All transaction, error, and access logs are written to a directory that you mount to your deployment as a volume for /opt/guardian/logs/${GUARDIAN_INSTANCE_NAME} and as standard output to console.

    PLATFORM+STDOUT

    Transaction logs are published to 42Crunch Platform and written as standard output to console.

    Error logs and access logs are written to the file system of the API Firewall container and as standard output to console.

    Log destination PLATFORM (alone or with STDOUT) is not suitable for firewall instances running in production environment due to the volume of logs produced. We recommend setting the log destination to FILES or STDOUT (or both) in production or for performance testing.

    Using the default size for the container file system is fine for testing, or when you can be sure that the logs volume stays low. However, the volume of logs can rapidly increase, especially in production, so if you want to use PLATFORM or FILES (alone or with STDOUT), you must plan for this growth to avoid running out of disk space in your API Firewall container. Either reserve enough disk space, or mount an external disk as a volume.

    If you use only STDOUT, then all logs are pushed out of the container, and container disk space is not a concern.

    Depending on the nature of your API, transaction logs could include personally identifiable information that falls under, for example, GDPR regulations. To facilitate the requirements from these regulations, such as the right to forget, it is possible to delete transaction logs from 42Crunch Platform. See Delete transaction logs.

  4. If you set the destination to FILES or FILES+STDOUT, mount the directory where you want to publish logs as a volume for /opt/guardian/logs/${GUARDIAN_INSTANCE_NAME} in your deployment. For more details on the variable {GUARDIAN_INSTANCE_NAME}, see API Firewall environment variables.
  5. Redeploy API Firewall. The logs are now published to your chose destination.

If you switch the log destination away from 42Crunch Platform, you can no longer monitor the real-time traffic there. For more details, see API monitoring.

If you want switch back and publish the logs to 42Crunch Platform again, in addition to changing the LOG_DESTINATION property, you must also unmount the directory you added for the logs. Otherwise, API Firewall might not start correctly.

Stop API Firewall from serving traffic without logs

By default, API Firewall sends transaction logs to 42Crunch Platform. If API Firewall for some reason loses the connection to the platform, it keeps trying to reconnect while continuing to serve API traffic normally to keep your API accessible to your API consumers. However, without the connection it cannot write transaction logs on that traffic.

If you want to send transaction logs to the platform but prevent API Firewall serving API traffic if transaction logs cannot be written, you can do this with the environment variable LOG_STRATEGY.

LOG_STRATEGY is ignored if you have specified in LOG_DESTINATION that transaction logs do not go to 42Crunch Platform.

  1. Open the file for configuring the API-specific API Firewall variables. Where this is done depends on the environment of your deployment. For more details, see Deploy API Firewall for your own APIs.
  2. Add the environment variable LOG_STRATEGY=KILL_ON_PLTF_LOST, and save the file.
  3. Redeploy API Firewall. The API Firewall instance will now automatically stop if it loses the connection to 42Crunch Platform.

Configure health check for API Firewall

API Firewall instances provide a dedicated endpoint /hc for health check calls that, for example, load balancers can use to check that the instance is up and running. By default, the health check calls are over HTTP and use the port 8880, but you can also configure health check calls to use HTTPS connection, in which case they use the port 8843. The API Firewall container (or AWS task) must expose the used port, while the load balancer must not expose it.

Configure health checks over HTTP connection

Health check over HTTP is the simplest option to configure.

  • Docker: To check that a container is healthy and the firewall instance is running properly, use the following command as the CMD/CMD_SHELL argument:
    "echo $'GET /hc HTTP/1.0\r\n\r\n' | nc 127.0.0.1 8880"

    For more details, see the Docker documentation.

  • Kubernetes: To configure Kubernetes probes, add the following to your Kubernetes deployment file:
     containers:
          - name: apifirewall
            image: '42crunch/apifirewall:latest'  # replace latest by proper tag in prod environment.
            imagePullPolicy: Always
            livenessProbe:
              httpGet:
                path: /hc
                port: 8880
              initialDelaySeconds: 2
              periodSeconds: 5

    For more details on Kubernetes probes, see the Kubernetes documentation.

  • Load balancer: Configure your load balancer to make health checks using the following settings:
    • Protocol: HTTP
    • Port: 8880
    • Path: /hc
    • Return code: 200

    The settings may vary depending on your load balancer, for more details, see the documentation of your load balancer. The following shows is an example of configuring the health check in AWS:

    You call the health check endpoint from the load balancer with http://<firewall hostname>:8880/hc.

Configure health check over HTTPS connection

You can change the HTTP health check configuration to use HTTPS connection instead.

  1. Open the file for configuring API Firewall environment variables. Where this is done depends on the environment of your deployment. For more details, see Deploy API Firewall for your own APIs.
  2. Add the environment variable HEALTHCHECK_SSL and set it to on to switch the health check to use HTTPS connection.
  3. Add environment variables to configure the SSL connection, and save your changes:
    • HEALTHCHECK_SSL_CERT: The filename of the public certificate you have mounted in the directory /opt/guardian/conf/ssl/
    • HEALTHCHECK_SSL_KEY: The filename of the private certificate key you have mounted in the directory/opt/guardian/conf/ssl/

    The values for HEALTHCHECK_SSL_CERT and HEALTHCHECK_SSL_KEY may be the same as for LISTEN_SSL_CERT and LISTEN_SSL_KEY.

    By default, API Firewall uses localhost:8443 as the CN/hostname for the health check, and this should ideally be the same as your certificate CN and the DNS name your health check client connects to. If needed, you can add the environment variable HEALTHCHECK_SSL_SERVERNAME to specify a different CN/hostname in API Firewall configuration.

  4. Change your health check client to connect to the port 8843 over HTTPS.
  5. Redeploy the API Firewall instance.

You can now call the health check endpoint from the load balancer with https://<firewall hostname>:8843/hc.

Switch API Firewall to use HTTP connections

By default, the listener interface of API Firewall only accepts HTTPS connections, and you must specify the variables LISTEN_SSL_CERT and LISTEN_SSL_KEY. If you want to use HTTP connections instead, you can add the variable LISTEN_NO_TLS to your API Firewall configuration.

  1. Open the file for configuring the API-specific API Firewall variables. Where this is done depends on the environment of your deployment. For more details, see Deploy API Firewall for your own APIs.
  2. Add the environment variable LISTEN_NO_TLS and a value to it (for example, LISTEN_NO_TLS=ON, LISTEN_NO_TLS=TRUE, or LISTEN_NO_TLS=1). This variable does not need a specific value, simply adding the variable name is enough, but deploying the configuration fails if a value is not defined.
  3. Save the file, and redeploy the API Firewall instance.

The listener interface of API Firewall now accepts HTTP connections instead of HTTPS connections. The TLS setup is ignored, so you do not need to specify LISTEN_SSL_CERT and LISTEN_SSL_KEY. If you have, you do not need to remove them, these variables are just ignored.

To switch API Firewall back to its default behavior and accept only HTTPS connections, remove LISTEN_NO_TLS from the configuration file, and make sure that the TLS setup is correctly defined, then redeploy API Firewall.

To switch back to HTTPS, you must completely remove the variable LISTEN_NO_TLS from the API Firewall configuration. Changing the value to false does nothing.

Handle CORS requests in a generic way

Cross-origin resource sharing (CORS) allows a server to indicate to browsers to load resources from another origin (such as domain or port) than the one that the server itself exposes. As part of CORS, browsers can send an OPTIONS request to query the supported methods before sending the actual request to access the resources. To handle these OPTIONS calls without having to explicitly define the OPTIONS method in your OpenAPI definition, you can use the extension x-42c-forward-options (see x-42c-forward-options).

  1. Open your OpenAPI definition for editing, either on the Security Editor tab of the API in 42Crunch Platform or in the editor of your choice.
  2. To set API Firewall to allow OPTIONS calls to always pass through, add the extension on the global level of your API:
    {
      "openapi: "3.0.0",
      "x-42c-forward-options": true,
      "info": {
        "version": "1.0.0",
        ...
  3. If you want API Firewall to allow OPTIONS calls to pass through only on some API operations and not on others, add the extension on the operations you want:
    post:
        description: Creates a new pet in the store. Duplicates are allowed.
        operationId: createPets
        x-42c-forward-options: true
        tags:
            - pets
        # ...
  4. When you are ready, save the API definition.
  5. Reconfigure the protection for the API and redeploy the API Firewall instance for the change to take effect.

Declare caseless file paths

Different systems take different approach to the case of paths in a file system:

  • If file paths are case-sensitive, this means paths like /Sample, /sample, and /SAMPLE are all treated as three separate paths.
  • If file paths are caseless (not case-sensitive), this means that /Sample, /sample, and /SAMPLE are treated as one and the same path.

If your API exposes caseless paths of a file system (for example, client-side, server-side, or from a cdn) in its OpenAPI definition, you can add the extension x-42c-caseless-paths (see x-42c-caseless-paths) in your API definition to indicate to API Firewall how the case in file paths should be treated.

  1. Open your OpenAPI definition for editing, either on the Security Editor tab of the API in 42Crunch Platform or in the editor of your choice.
  2. Add the extension x-42c-caseless-paths on the global level of your API:
    {
      "openapi: "3.0.0",
      "x-42c-caseless-paths": true,
      "info": {
        "version": "1.0.0",
        ...

    Depending of the value of this property, API Firewall treats the paths in this API definition either case-sensitive or not:

    • If set to false, API Firewall considers file paths in the API to be case-sensitive. This is the default option.
    • If set to true, API Firewall considers file paths in the API to be caseless.
  3. When you are ready, save the API definition.
  4. Reconfigure the protection for the API and redeploy the API Firewall instance for the change to take effect.