> For the complete documentation index, see [llms.txt](https://coldbox-security.ortusbooks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://coldbox-security.ortusbooks.com/get-started/how-the-firewall-works.md).

# How the Firewall Works

How cbsecurity decides if a request can run, and what happens when it cannot.

The firewall wraps the `preProcess` interception point, the first thing that runs in a ColdBox request. It asks a **validator** whether the request is allowed and acts on the answer.

## How Validation Happens

You register a validator (the `firewall.validator` setting) that implements two functions from `cbsecurity.interfaces.ISecurityValidator`:

* `ruleValidator()` evaluates your [security rules](https://coldbox-security.ortusbooks.com/secure-your-app/security-rules.md).
* `annotationValidator()` evaluates the [security annotations](https://coldbox-security.ortusbooks.com/secure-your-app/security-annotations.md) on your handlers and actions.

[Route middleware](https://coldbox-security.ortusbooks.com/secure-your-app/route-middleware.md) calls the same validator for the secured route. Rules run before annotations, and you can use any mix of the three.

The validator answers one of three things: allowed, or not allowed with a type, **authentication** or **authorization**. A validator can also tell the firewall to block the request.

> `Authentication` is when a user is NOT logged in.
>
> `Authorization` is when a user is logged in but does not have the right permissions or roles.

{% hint style="info" %}
A validator can also challenge the user to log in. The `BasicAuthValidator` does this by sending a header that prompts the browser for credentials.
{% endhint %}

## When Access Is Denied

When the validator says no, the firewall does the following, whether the check came from a rule, an annotation or middleware:

* Logs the blocked request with LogBox, including the IP and extra metadata.
* Logs the block to the database when [firewall logs](https://coldbox-security.ortusbooks.com/get-started/configuration/firewall.md) are on, so the [visualizer](https://coldbox-security.ortusbooks.com/get-started/configuration/visualizer.md) can show it.
* When the action is a redirect, flashes the requested URL as `_securedURL`, so you can send the user back after login.
* Stores the matched rule in `prc.cbSecurity_matchedRule` (rules only) and the validator results in `prc.cbSecurity_validatorResults`.
* Announces `cbSecurity_onInvalidAuthentication` or `cbSecurity_onInvalidAuthorization` depending on the type. See [Interceptions](https://coldbox-security.ortusbooks.com/reference/interceptions.md).
* Runs the default action for that type.

## The Default Actions

Each type has its own action, set by these four settings. The action is always one of three outcomes: relocate to another event or URL, override the event, or answer with a firewall `401 Not Authorized` block.

| Setting                       | Default    | Description                                                      |
| ----------------------------- | ---------- | ---------------------------------------------------------------- |
| `invalidAuthenticationEvent`  | none       | The event, URI or URL to go to when a user is not logged in.     |
| `defaultAuthenticationAction` | `redirect` | `redirect`, `override` or `block` when a user is not logged in.  |
| `invalidAuthorizationEvent`   | none       | The event, URI or URL to go to when a user lacks permissions.    |
| `defaultAuthorizationAction`  | `redirect` | `redirect`, `override` or `block` when a user lacks permissions. |

A rule can set its own `action`, `redirect` and `overrideEvent`, which win over these defaults.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://coldbox-security.ortusbooks.com/get-started/how-the-firewall-works.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
