Shield WAF reference

Arcjet Shield WAF protects your application against common attacks, including the OWASP Top 10.

Configuration

Shield is configured by specifying which mode you want it to run in.

The arcjet client can be configured with one or more Shield rules, which are constructed with the shield(options: ShieldOptions) function and configured by ShieldOptions:

1
type ShieldOptions = {
2
  mode?: ArcjetMode | undefined;
3
};

1
type ArcjetMode = "LIVE" | "DRY_RUN";

Decision

Arcjet provides a single protect function that is used to execute your protection rules. This requires a RequestEvent property which is the event context as passed to the request handler.

This function returns a Promise that resolves to an ArcjetDecision object. This contains the following properties:

id (string) – The unique ID for the request. This can be used to look up the request in the Arcjet dashboard. It is prefixed with req_ for decisions involving the Arcjet cloud API. For decisions taken locally, the prefix is lreq_.
conclusion (ArcjetConclusion) – The final conclusion based on evaluating each of the configured rules. If you wish to accept Arcjet’s recommended action based on the configured rules then you can use this property.
reason (ArcjetReason) – An object containing more detailed information about the conclusion.
results (ArcjetRuleResult[]) – An array of ArcjetRuleResult objects containing the results of each rule that was executed.
ip (ArcjetIpDetails) – An object containing Arcjet’s analysis of the client IP address. For more information, see the SDK reference.

To check whether a shield rule returned a deny conclusion, use decision.isDenied() and decision.reason.isShield() (JS) / decision.is_denied() and decision.reason_v2.type == "SHIELD" (Python).

You can iterate through the results and check whether a shield rule was applied:

JavaScript / TypeScript
Python

1
for (const result of decision.results) {
2
  console.log("Rule Result", result);
3
}

for result in decision.results:
    print("Rule Result", result)

This example logs the full result as well as the shield rule:

import logging
import os

from arcjet import Mode, arcjet_sync, fixed_window, shield
from flask import Flask, jsonify, request

app = Flask(__name__)

logger = logging.getLogger(__name__)

aj = arcjet_sync(
    key=os.environ["ARCJET_KEY"],  # Get your site key from https://console.arcjet.com
    rules=[
        fixed_window(mode=Mode.LIVE, window=3600, max=60),
        shield(mode=Mode.LIVE),
    ],
)


@app.get("/")
def index():
    decision = aj.protect(request)

    for result in decision.results:
        logger.info("Rule Result %s", result)

        if result.reason_v2.type == "RATE_LIMIT":
            logger.info("Rate limit rule %s", result)

        if result.reason_v2.type == "SHIELD":
            logger.info("Shield rule %s", result)

    if decision.is_denied():
        if decision.reason_v2.type == "RATE_LIMIT":
            return jsonify(error="Too Many Requests"), 429
        return jsonify(error="Forbidden"), 403

    return jsonify(message="Hello world")

Error handling

Arcjet is designed to fail open so that a service issue or misconfiguration does not block all requests. The SDK also times out and fails open after 2000 ms by default. However, in most cases, the response time is less than 20 ms to 30 ms.

If there is an error condition when processing the rule, Arcjet returns an ERROR result for that rule and you can check the message property on the rule’s error result for more information.

If all other rules that were run returned an ALLOW result, then the final Arcjet conclusion is ERROR.

import logging
import os

from arcjet import Mode, arcjet_sync, shield
from flask import Flask, jsonify, request

app = Flask(__name__)

logger = logging.getLogger(__name__)

aj = arcjet_sync(
    key=os.environ["ARCJET_KEY"],  # Get your site key from https://console.arcjet.com
    rules=[
        shield(mode=Mode.LIVE),  # Blocks requests. Use Mode.DRY_RUN to log only
    ],
)


@app.get("/")
def index():
    decision = aj.protect(request)
    logger.info("Arcjet decision %s", decision)

    # You can manually iterate all errors for things like logging or debugging
    for result in decision.results:
        if result.reason_v2.type == "ERROR":
            # Fail open by logging the error and continuing
            logger.warning("Arcjet error: %s", result.reason_v2.message)
            # You could also fail closed here for very sensitive routes:
            # return jsonify(error="Service unavailable"), 503

    if decision.is_denied():
        return jsonify(error="Forbidden"), 403

    return jsonify(message="Hello world")

Testing

Arcjet runs the same in any environment, including locally and in CI. You can use the mode set to DRY_RUN to log the results of rule execution without blocking any requests.

We have an example test framework you can use to automatically test your rules. Arcjet can also be triggered based using a sample of your traffic.

For details, see the Testing section of the docs.