CBSecurity 3.4.3 is a maintenance release that addresses ColdBox 7 compatibility requirements.

ColdBox 7 Compliance

View Rendering Method Update

The primary change in this release addresses a breaking change in ColdBox 7:

• Fixed: Renamed renderView() to view() to be ColdBox 7 compliant

• This change ensures CBSecurity works properly with ColdBox 7's updated view rendering methods

• Maintains backward compatibility with earlier ColdBox versions

System Requirements

• ColdBox Framework: 6+ (ColdBox 7 compliant)

• CFML Engines: Adobe ColdFusion 2018+, Lucee 5+

• CommandBox: 5.0+

Compatibility Notes

This release maintains full backward compatibility with existing CBSecurity 3.x installations while ensuring forward compatibility with ColdBox 7.

Migration Notes

No migration steps are required for this release. Simply update your CBSecurity module dependency:

Related Resources

CBSecurity 3.5.0 is a significant modernization release that brings enhanced platform support, improved development workflows, and comprehensive AI assistance capabilities.

BoxLang Certification

CBSecurity 3.5.0 has been fully certified for BoxLang, the modern dynamic JVM language. This includes:

• Complete compatibility testing with BoxLang runtime

In this section you will find the release notes for each version we release under this major version. If you are looking for the release notes of previous major versions use the version switcher at the top left of this documentation book. Here is a breakdown of our major version releases.

Version 3.0

Version 3 is a major rewrite of this module. It drops Adobe 2016 support and enhances the way the firewall is configured. It also add major capabilities for security headers, csrf settings and much more.

It also introduces the ability for the firewall to do 401 response blocks as actions for security rules. The CBSecurity visualizer is also a major addition that allows a developer or manager to visualize the performance of the firewall and visualize all the configurations necessary for operation.

CBSecurity 3.4.2 is a maintenance release that addresses database compatibility issues and improves documentation standards.

Database Compatibility Improvements

Oracle Database Support

Added

• Added guest() method to CBSecurity model and Authorizable delegate

CBSecurity is a comprehensive security framework for ColdBox applications, providing enterprise-grade authentication, authorization, and protection mechanisms. It combines multiple security modules into a cohesive, easy-to-use security platform that helps developers build secure applications with minimal effort.

🎯 Core Security Capabilities

CBSecurity provides a multi-layered security approach with the following key capabilities:

🔐 Authentication & Authorization

• Security Firewall - Rule-based request protection using security rules engine and handler annotations

• Authentication Manager (cbauth) - Pluggable authentication system compatible with any authentication provider

• Basic Authentication - Built-in HTTP Basic Auth support with credential storage and browser challenge handling

🎫 Token Management

• JWT Services (jwtcfml) - Complete JSON Web Token implementation with generation, decoding, and validation

• Access & Refresh Tokens - Native support for JWT-based authentication flows

• Token Storage - Flexible token storage with multiple backend options

🛡️ Security Protections

• CSRF Protection (cbcsrf) - Cross-Site Request Forgery protection for form submissions

• Security Headers - Industry-standard HTTP response headers (CSP, HSTS, X-Frame-Options, XSS Protection)

• Password Generator - Cryptographically secure random password generation

📊 Management & Monitoring

• Security Visualizer - Graphical interface for monitoring firewall activity and managing security configurations

• Rule Engine - Flexible security rules supporting XML, JSON, database, and model-based configurations

• Module Integration - Allows modules to contribute their own security rules and validation logic

🧩 Module Composition

CBSecurity is built on a modular architecture that integrates several specialized security modules:

The framework leverages cbstorages for flexible storage backends and seamlessly integrates with the ColdBox ecosystem to provide comprehensive security coverage across your entire application.

⭐ Key Features

📋 Flexible Security Rules

• Multiple Storage Options - Define rules in XML, JSON, databases, or ColdBox models

• Regular Expression Support - Use regex patterns or simple string matching for rule definitions

• Modular Rules - Modules can contribute their own security rules with custom validation logic

• Dynamic Rule Loading - Load and unload security rules at runtime from contributing modules

🔒 Advanced Authorization

• Annotation-Driven Security - Secure handlers and actions using ColdBox annotations

• Cascading Security - Hierarchical security rules from global to handler to action level

• Functional API - Injectable security service for authorization checks in any application layer

• Custom Validators - Each module can define its own security validator implementation

🔑 Authentication Flexibility

• Multiple Authentication Providers - Works with cbauth, ColdFusion native authentication, or custom providers

• Provider Agnostic - Implements standard interfaces allowing any authentication system integration

• Basic Authentication - Built-in HTTP Basic Auth with credential storage

⚡ Security Response Handling

• Granular Control - Distinguish between authentication failures and authorization denials

• Customizable Actions - Configure different responses for invalid authentication vs. authorization

• Event-Driven - Hook into security events for custom logging, monitoring, or response handling

📜 License

CBSecurity is open-source software licensed under the .

📚 Resources

📖 Documentation & Support

• Documentation -

• Source Code -

• Issue Tracker -

• Community Forum -

💬 Getting Help

The ColdBox community is active and ready to help:

• Community Forum - Ask questions and share knowledge with other developers

• GitHub Issues - Report bugs and request features

• Professional Support - Enterprise support available through Ortus Solutions

🏢 Professional Open Source

CBSecurity is professionally developed and supported by , a leader in CFML consulting and development.

🚀 Enterprise Services

Ortus Solutions offers comprehensive professional services for CBSecurity and the ColdBox Platform:

• 🛠️ Custom Development - Tailored security solutions for your specific requirements

• 👨‍🏫 Professional Support & Mentoring - Expert guidance from the creators of ColdBox

• 📚 Training - Official ColdBox and security training programs

• 🔍 Architecture & Code Reviews - Expert evaluation of your security implementation

🙏 HONOR GOES TO GOD ABOVE ALL

Because of His grace, this project exists. If you don't like this, then don't read it; it's not for you.

"Therefore being justified by faith, we have peace with God through our Lord Jesus Christ: By whom also we have access by faith into this grace wherein we stand, and rejoice in hope of the glory of God." Romans 5:5

CBSecurity 3.4.1 is a targeted maintenance release that addresses a specific database compatibility issue with Microsoft SQL Server.

Database Compatibility Fix

Microsoft SQL Server Support

• Fixed: Added proper parenthesis on TOP statements for Microsoft SQL Server in the DBLogger

• This fix resolves SQL syntax errors that were occurring when using CBSecurity's database logging features with MSSQL Server

• Thanks to @irvirv for identifying and helping resolve this issue

System Requirements

• ColdBox Framework: 6+

• CFML Engines: Adobe ColdFusion 2018+, Lucee 5+

• CommandBox: 5.0+

• Database: Any supported database (MSSQL Server compatibility enhanced)

Compatibility Notes

This release maintains full backward compatibility with existing CBSecurity 3.x installations while fixing a specific SQL syntax issue affecting Microsoft SQL Server users.

Migration Notes

No migration steps are required for this release. Simply update your CBSecurity module dependency:

Microsoft SQL Server Users

If you're using Microsoft SQL Server and experiencing SQL syntax errors in the DBLogger, this update will resolve those issues. No manual database changes are required.

Related Resources

Added

• Official Adobe 2023 Support

• Gitflows for testing all engines and all versions of ColdBox

CBSecurity 3 is a major release and it will require some updates in order for you to fully upgrade your previous versions.

Adobe 2016, 2018 Support Dropped

These engines are no longer supported

Added

• Migrations table for security logs

• New bootsrap icons + css + js

• New github support files

Fixed

• getActionsReport() was not defaulting the type's structure, so exceptions would arise when there was no data in the visualizer

Added

• Added a new helper: createPassword() on the CBSecurity model to generate secure, random passwords with letters, symbols, and numbers.

• cbcsrf Upgraded to version 3, which we missed in the previous release.

You can also use our handy event.secureView() method in the request context to pivot between views according to user permissions.

event.secureView( permissions, successView, failView )

This will allow you to set the successView if the user has the permissions or the failView if they don't.

This validator will challenge users with browser-based basic authentication. It will use whatever authentication system and user service you have configured.

If you don't change the default settings, then CBSecurity will switch to using the BasicAuthUserService which allows you to store user credentials in your configuration file. You can check out our Basic Authentication section for further information.

cbsecurity = {

    firewall : {
        validator = "BasicAuthValidator@cbsecurity"
    }

}

ColdBox security ships with this validator that knows how to talk to the authentication service and validate authentication and authorization via permissions and roles. All you need to do is use the WireBox ID of AuthValidator@cbsecurity in your validator setting:

cbsecurity = {

    firewall : {
        validator = "AuthValidator@cbsecurity"
    }

}

There are also times where you need to validate custom conditions and block access to certain areas. This way, you can implement your own custom security logic and leverage cbSecurity for blockage. You will accomplish this via the secureWhen() method. If the context evaluates to true then it will throw a NotAuthorized exception for you.

The context can be a closure/lambda/udf or a boolean evaluation:

The closure/udf will receive the currently authenticated user as the first argument.

You can also use the message argument to send your own message to the exception that's throw.

You can leverage the CBSecurity model to get insight into some aspects of the authentication process or do authentication via the configured authentication service if needed.

Configured Services

• getAuthService() - Get access to the configured authentication service

• getUserService() - Get access to the configured user service

Authentication Context

• authenticate( username, password ) - Authenticate a request

• getUser() - Get the authenticated user of the current request

• guest() - Verify if the users is NOT logged in, but a guest

CBSecurity ships with a basic User object that already implements the auth and JWT interfaces and gives you basic properties.

cbsecurity.models.auth.User

This powerful component provides a comprehensive representation of users, with robust authorization and JSON Web Token (JWT) capabilities. With this basic user, you can effortlessly manage your application's user authentication and access control. It offers a user-friendly interface for handling user profiles, permissions, and JWT generation, ensuring a secure and seamless experience for developers and end-users.

Check out the ColdBox REST Starter Templates to see it in action.

coldbox create app name=restapp skeleton=rest

Luis Fernando Majano Lainez

Luis Majano is a Computer Engineer who has been developing and designing software systems since 2000. He was born in in the late 70s, during a period of economical instability and civil war. He lived in El Salvador until 1995 and then moved to Miami, Florida where he completed his Bachelor of Science in Computer Engineering at .

He is the CEO of , a consulting firm specializing in web development, ColdFusion (CFML), Java development, and all open-source professional services under the ColdBox and ContentBox stack. He is the creator of ColdBox, ContentBox, WireBox, CommandBox, LogBox, and anything “BOX” and contributes to many open-source ColdFusion/Java projects. You can read his blog at

You can place all your security rules inside of an XML file and then tell CBSecurity where they are:

Then your XML file can look like this:

CBSecurity also allows you to store your security rules in a database as long as all the columns match the keys of the rules as we saw in the

You will use the db as the source and fill out the available db properties:

• The dsn property is the name of the datasource to use

The source code for this book is hosted on GitHub: . You can freely contribute to it and submit pull requests. The contents of this book are copyrighted by and cannot be altered or reproduced without the author's consent. All content is provided "As-Is" and can be freely distributed.

• The majority of code examples in this book are done in cfscript.

• The majority of code generation and running of examples are done via CommandBox: The ColdFusion (CFML) CLI, Package Manager, REPL - ​

The CBSecurity visualizer is a tool that will allow you to visualize all of your configuration settings, firewall logs, and much more. By default, the visualizer is disabled.

If enabled, you can visit the /cbsecurity entry point, and you will get the visualizer rendered.

If you prefer to store your rules your way, CBSecurity can talk to any WireBox ID or model and get the rules from them by using the model source in the rule provider.

• The model property is any WireBox ID or classpath

• The method property is the name of the method to call to get an array of rules back

You will configure the authentication and user services in the authentication area of CBSecurity. CBSecurity ships with the module that can provide you with a robust authentication service, session/request storage, interceptions, and much more. However, you can use any security authentication service as long as it matches our interface: cbsecurity.interfaces.ISecurityValidator.

Explicit Authorizations

The cbSecurity model is a specialized service that will allow you to do explicit authorizations in any layer of your ColdBox application.

Sometimes, you will need authorization checks outside of the incoming request rules or the handler annotations. This can be from within interceptors, models, layouts, or views. For this, we have provided the cbSecurity model so you can do explicit authorization checks anywhere you like.

If you just want to validate if a user has certain permissions or maybe no permissions at all or if a passed user is the same as the logged in user, then you can use the following boolean methods that only do verification.

These are great to have a unified and abstracted way to verifying permissions or if the passed user is the same as the logged in user. Here are some examples:

View Layer

The CBSecurity model also has some methods that assist developers in their security needs

Generating Passwords

You can use the createPassword( length:32, letters:true, numbers:true, symbols:true )

You can place all your security rules inside of a JSON file and then tell CBSecurity where they are:

// CB Security
cbSecurity : {
  firewall : {
    rules : {
      provider : {
        "source" : "config/security.json.cfm"
      }
    }
  }
}

Then your file can be something like this:

[
    {
        "whitelist": "user\\.login,user\\.logout,^main.*",
        "securelist": "^user\\.*, ^admin",
        "match": "event",
        "roles": "admin",
        "permissions": "",
        "redirect": "user.login",
        "useSSL": false
    },
    {
        "whitelist": "",
        "securelist": "^shopping",
        "match": "url",
        "roles": "",
        "permissions": "shop,checkout",
        "redirect": "user.login",
        "useSSL": true
    }
]

The security module has the concept of a secured URL which is the actual URL that got intercepted and relocated because of a security exception. This is stored in the request collection as rc._securedURL and in the ColdBox flash memory as _securedURL.

So always remember to use this variable to provide a seamless login experience to your users. You can easily place it in the login form as a hidden field:

#html.startForm( action=prc.xehDoLogin, name="loginForm" )#
    
    <!--- Store the _securedURL so we can use it to relocate -->
    #html.hiddenField( name="_securedURL", value=event.getValue('_securedURL','') )#

    #html.textfield(name="username",label="Username: ",size="40",required="required",class="textfield",value=prc.rememberMe)#
    #html.passwordField(name="password",label="Password: ",size="40",required="required",class="textfield")#

    <div id="loginButtonbar">
        #html.checkBox(name="rememberMe",value=true,checked=(len(prc.rememberMe)))# 
        #html.label(field="rememberMe",content="Remember Me  ",class="inline")#
        #html.submitButton(value="  Log In  ",class="buttonred")#
    </div>

    <br/>
    <img src="#prc.cbRoot#/includes/images/lock.png" alt="lostPassword" />
    <a href="#event.buildLink( prc.xehLostPassword )#">Lost your password?</a> 

#html.endForm()#

In your login action you can use the secured URL and relocate appropriately:

function doLogin( event, rc, prc ){

   if( cbSecure().authenticate( rc.username, rc.password ) ){
      
      rc._securedURL.len() ? relocate( url : rc._securedURL ) : relocate( "admin.dashboard" )
      
   }

}

CBSecurity ships with the cbsrf module and can be configured in line with the cbsecurity key.

EnableAutoVerifier

By default, this setting is turned off. If you turn it on, then every non-GET request will be verified that it contains a valid incoming csrf token via a header or the incoming rc.

VerifyExcludes

A list of regex patterns that will match against the incoming event. If matched, then that event will be excluded from the auto-verifier.

RotationTimeout

All csrf tokens have a life span of 30 minutes. But you can control how long they live with this setting.

EnableEndpoint

This setting enables the GET /cbcsrf/generate endpoint to generate csrf tokens for secured users. You can use this endpoint to generate user tokens via AJAX or UI-only applications. Please note that you can pass an optional /:key URL parameter that will generate the token for that specific key.

CacheStorage

The WireBox ID to use for storing the tokens. The default is the CacheStorage@cbstorages object. However, you can use any ColdBox storage or your own as long as it matches the CBStorages API: .

EnableAuthTokenRotator

This setting is enabled by default and what it does is that it will rotate a user's secret keys when they login/logout via any authentication service registered with CBSecurity.

Compatibility

• Dropped Adobe ColdFusion 2016

• New JwtAuthValidator instead of mixing concerns with the JwtService. You will have to update your configuration to use this validator instead of the JwtService

• All settings have changed. They are not single-level anymore. They are now grouped by functionality. Please see the area for the new approach.

Added

• New ability for the firewall to log all action events to a database table.

• If enabled, a new visualizer can visualize all settings and firewall events via the log table.

• New Basic Auth validator and basic auth user credentials storage system. This will allow you to secure apps where no database interaction is needed or required.

Fixed

• Disable lastAccessTimeouts for JWT CacheTokenStorage BOX-128

• Fix spelling of property datasource on queryExecute that was causing a read issue.

Leverage CommandBox to install into your ColdBox app:

System Requirements

CFML Engines

• BoxLang 1+ (Preferred)

• Lucee 5+

• Adobe 2023+

Additional Requirements

• A database for optional firewall logging

• ColdBox 7+ for delegates and basic auth support only

Mixins

The following mixins are registered once the module is installed:

Configuration Settings

By default cbsecurity is configured to work with cbauth as the authentication service. You only need to provide a user service class that knows how to connect to your database to retrieve and validate credentials. You can also use the in-built basic authentication users as well.

The basicAuth key is used to store user credentials that will be used with Basic Authentication and how the passwords are stored in memory.

HashAlgorithm

This is the default algorithm used when hashing the user storage passwords in memory. The default is SHA-512

hashAlgorithm  : "SHA-256",

HashIterations

Iterates the number of times the hash is computed to create a more computationally intensive hash. The default is 5

Users

This is the in-memory user storage system. It's a struct and each key represents a unique username in the storage system. Each user can then have the following attributes, but in reality, you can add as many attributes as you want.

• password - The only mandatory attribute.

• firstName

• lastName

Now that we have all the pieces in place for JWT, we can now register the JWT validator as our validator of choice: JwtAuthValidator@cbsecurity.

The validator will inspect the incoming requests for valid JWT authorization headers. It will verify their expiration, their required claims, and the user it represents. Once done, it goes in the same rule/annotation security flow that cbsecurity leverages.

Module Override

Each module can also override its validator via its configuration setting cbsecurity.validator. So if the global validator is something other than JWT but your module REQUIRES JWT validation, then add it in your ModuleConfig.cfc

JWT Token Discovery

The JWT validator will discover the incoming JWT token from 3 sources:

1. authorization header using the bearer token approach

2. Custom header configured in your settings: cbsecurity.customAuthHeader

3. Incoming rc variable with the same name as cbsecurity.customAuthHeader

Token Scopes & Permissions

If your rules have the permissions element or your secure annotations have context, then we will treat those as the scopes/permissions to check the user/token must have at validation.

Validator Process

The validator will have the following validation process:

• Verify the JWT exists via the authorization header or custom header x-auth-token or incoming rc[ 'x-auth-token' ]

• Verify we can decode it

• Verify if it has not expired from the token itself

That's it! You can create your rules and annotations just like you used to, but now the validator will ensure valid JWT tokens are passed for those requests.

CBSecurity comes bundled with the following delegate objects that you can use in your user objects and provide them with security capabilities.

Auth@cbsecurity

This delegate enables your application objects to deal with authentication features via delegation.

• jwtAuth()

• cbSecure()

• auth()

Authorizable@cbsecurity

This delegate adds authorization capabilities to your objects.

• hasPermission()

• hasRole()

• isLoggedIn()

JwtSubject@cbsecurity

This delegate adds JWT Subject methods to a target.

• getJWTCustomClaims()

• getJWTScopes()

CBSecurity also allows you to secure your events via annotations instead of security rules. The setting that controls this security feature is called handlerAnnotationSecurity , which can be set in the

The security module has a tiered approach to annotation security as it will check the handler component first and then the requested action method second. You can apply different security contexts to each level as you see fit.

See the diagram below for inspecting security based on annotations:

The secure() Methods

Now that you have access to the model, you can use the following method to verify explicit permissions and authorize access. This method will throw an exception if the user does not validate the incoming permissions context (NotAuthorized).

Login Interceptions

The security firewall will announce some interception events when invalid access or authorizations occur within the system:

• cbSecurity_onInvalidAuthentication

• cbSecurity_onInvalidAuthorization

You will receive the following data in the interceptData struct in each interception call:

• ip : The offending IP address

• rule : The security rule intercepted or empty if annotations

• settings : The firewall settings

With these interceptions you can build a nice auditing system, login tracking and much more.

Stop Processing Actions

The received event data has a Boolean key called processActions which defaults to true. This Boolean indicator tells the firewall to process the invalid authentication/authorization procedures. If you change this value to false, then the firewall will do NOTHING because it is expecting for YOU to have done the actions.

JWT Interceptions

If you are using our , then we will announce the following interceptions during JWT usage:

• cbSecurity_onJWTCreation

• cbSecurity_onJWTInvalidation

• cbSecurity_onJWTValidAuthentication

Check them all out in our .

CBAuth Interceptions

cbauth announces several custom interception points.

• preAuthentication

• postAuthentication

• preLogin

You can use these interception points to change request data or add additional values to session or request scopes. The preAuthentication and postAuthentication events fire during the standard authenticate() method call with a username and password. The preLogin and postLogin events fire during the login() method call. The preLogout and postLogout events fire during the logout() method call.

You can always find the latest interception points here:

ColdBox security has had this security validator since version 1, in which it will talk to the ColdFusion engine's security methods to authenticate and authorize users using roles.

All you need to do is use the WireBox ID of CFValidator@cbsecurity in your validator setting:

ColdFusion Security Functions

You can enable token storage in cbsecurity via the tokenStorage setting. By default it is enabled and leverages CacheBox's default cache using a key prefix of cbjwt_ + the token's unique identifier claim of jti.

Registration

In order to register your own custom security validator just open the config/Coldbox.cfc and add the validator key with the value being a WireBox ID that points to your object that will provide the validation.

CBSecurity supports the concept of HTTP in your ColdBox applications. Please note that this is a quick and easy way to provide security, but not the safest by any means. You have been warned!

What is Basic Authentication?

In the context of an transaction, basic access authentication is a method for an (e.g. a ) to provide a username and password when making a request. In basic HTTP authentication, a request contains a header field in the form of Authorization: Basic <credentials>, where credentials is the

Global Configuration

Here is the default configuration for our JSON Web Tokens integration:

issuer

ColdBox Security supports the concept of refresh tokens alongside the normal JWT access tokens. Let's start exploring this feature in detail.

What Is a Refresh Token?

A refresh token is a credential artifact that lets a client application get new access tokens without having to ask the user to log in again. Access tokens may be valid for a short amount of time. Once they expire, client applications can use a refresh token to "refresh" the access token.

The client application can get a new access token as long as the refresh token is valid and unexpired. Consequently, a refresh token that has a very long lifespan could theoretically give infinite power to the token bearer to get a new access token to access protected resources anytime. The bearer of the refresh token could be a legitimate user or a malicious user.

The JWT Services will announce some key events for you to listen to

• cbSecurity_onJWTCreation - Whenever a new token is generated for a user

• cbSecurity_onJWTInvalidation - Whenever an invalidation occurs for a token

• cbSecurity_onJWTValidAuthentication - Whenever a valid JWT token is parsed, tested and authenticated with the authentication services

• cbSecurity_onJWTInvalidUser - When trying to find the token's subject and the user service returns null or not a valid user

• cbSecurity_onJWTInvalidClaims - When the parsed token does not adhere to the required claims

• cbSecurity_onJWTExpiration - When the parsed token has expired

• cbSecurity_onJWTStorageRejection - When the parsed token is valid but cannot be found in the permanent storage

• cbSecurity_onJWTValidParsing - When the parsed token has passed all validation procedures but has NOT been authenticated yet.

cbSecurity_onJWTCreation

This event has the following data in the interceptData struct

cbSecurity_onJWTInvalidation

This event has the following data in the interceptData struct

cbSecurity_onJWTValidAuthentication

This event has the following data in the interceptData struct

cbSecurity_onJWTInvalidUser

This event has the following data in the interceptData struct

cbSecurity_onJWTInvalidClaims

This event has the following data in the interceptData struct

cbSecurity_onJWTExpiration

This event has the following data in the interceptData struct

cbSecurity_onJWTStorageRejection

This event has the following data in the interceptData struct

cbSecurity_onJWTValidParsing

This event has the following data in the interceptData struct

Example

We have seen by now that rules can be defined in disk, databases, or created at runtime. These security rules all share a common anatomy and processing; let's explore it.

Rule Anatomy

A struct models each rule with keys in it internally in CBSecurity. So no matter where these rules come from, at the end of the day, they are registered as an array of structs internally.

The only required key is the secureList which is what you are trying to secure. The rest are optional.

Rule Elements

Rules processing

When processing rules, it is essential to realize these rules are stored as an array that will be processed in order, so make sure your more specific rules will be processed before the more generic ones.

Rule Overrides

As we saw from the overview and our configuration sections. We can declare the default actions for authorizations and authentication issues and to which events/URLs to go if that happens. There can be a time when you can override those global/module settings directly within a rule. Let's explore these overrides:

Redirect

If you add a redirect element, then you will explicitly override the global/module setting, and if a match is made, a redirect will occur for the event registered.

OverrideEvent

If you add an overrideEvent element, then you will explicitly override the global/module setting, and an event override will occur.

Action

If you add an action element, then you will be explicitly overriding the global/module setting, and the action will be based on this value (override or event or block)

More on White Lists

If a rule has a white list, then it means that you can declare what are the exceptions to ALLOW if the incoming URL/event was matched against the securedList. This is a great way to say, hey, secure all but allow the following events:

Sometimes you want to make sure ALL events are secured, except for the ones specified, such as login events. If you add new functionality to your app it is easy to forget a new rule. To prevent unwanted access you could specify a LAST rule, which matches ALL event but NO permission at all. In that case you have to add a whitelist for all events which should still pass, for example:

CBSecurity comes bundled with tons of security response features to help developers be secure-minded about their applications. Here are the defaults for configuring the security headers in CBSecurity.

TrustUpstream

This boolean flag tells CBSecurity whether to inspect x-forwarded- headers FIRST instead of traditional host/IP headers. If you trust your proxies, then turn this setting to true.

ContentSecurityPolicy

The Content Security Policy (CSP) is an added layer of security that helps to detect and mitigate certain types of attacks, including Cross-Site Scripting (XSS) and data injection attacks. These attacks are used for data theft, site defacement, and malware distribution.

By default, this policy is disabled as it requires a custom policy to be written according to your needs. Once you have a policy available, you can add it to the configuration.

ContentTypeOptions

The X-Content-Type-Options response HTTP header is a marker used by the server to indicate that the MIME types advertised in the Content-Type headers should be followed and not be changed. This produces the following header => X-Content-Type-Options: nosniff

CustomHeaders

You can fill out this struct with the custom headers you would like to send out on EVERY request. The header value can be a simple value to return always or a closure/lambda that will be executed at runtime and the value sent on every request.

Please note that the closure accepts the incoming event, rc, and prc variables.

FrameOptions

The X-Frame-Options response header can be used to indicate whether or not a browser should be allowed to render a page in a , , or . Sites can use this to avoid attacks by ensuring that their content is not embedded into other sites. The default value ColdBox uses is SAMEORIGIN which allows iframes and embeds from the same origin. The available values are: SAMEORIGIN OR DENY.

HSTS - HTTP Strict Transport Security

The HTTP Strict-Transport-Security response header (often abbreviated as HSTS) informs browsers that the site should only be accessed using HTTPS and that any future attempts to access it using HTTP should automatically be converted to HTTPS. Here are the defaults we use in CBSecurity:

HostHeaderValidation

This configuration setting can restrict access to your application for ONLY a specific list of hosts. This prevents host spoofing. If an invalid host is detected, a 401 Not Authorized response will be sent back to the user. This setting is disabled by default.

IPValidation

This configuration setting can restrict access to your application for ONLY a specific list of IP addresses. This prevents IP spoofing. If an invalid IP is detected, then a 401 Not Authorized response will be sent back to the user. This setting is disabled by default.

ReferrerPolicy

The Referrer-Policy HTTP header controls how much referrer information (sent with the Referer header) should be included with requests. Aside from the HTTP header, you can set this policy in HTML. This setting is enabled by default with a policy of same-origin.

Here are some available policies:

SecureSSLRedirects

Detect if the incoming requests are NON-SSL and redirect with SSL alongside any incoming query strings and host information if enabled. By default, this setting is disabled.

XSSProtection

Some browsers have built-in support for filtering out reflected XSS attacks. Not foolproof, but it assists in XSS protection. By default, it is enabled and a block mode is produced.

Since version 2.4.x we have added the cbcsrf module as a dependency of cbSecurity. Below is how you can use it:

Settings

Below are the settings you can use for this module. Remember you must create the cbcsrf struct in your ColdBox.cfc under the moduleSettings structure:

Mixins

This module will add the following UDF mixins to handlers, interceptors, layouts and views:

• csrfToken() : To generate a token, using the default or a custom key

• csrfVerify() : Verify a valid token or not

• csrf() : To generate a hidden field (csrf

Here are the method signatures:

Mappings

The module also registers the following mapping in WireBox: @cbcsrf so you can call our service model directly.

Automatic Token Expiration

By default, the module is configured to rotate all user csrf tokens every 30 minutes. This means that every token that gets created has a maximum life-span of {rotationTimeout} minutes. If you do NOT want the tokens to EVER expire during the user's logged in session, then use the value of 0 zero.

It is recommended to rotate your keys often, in case your token get's compromised.

Token Rotation

We have provided several methods to rotate or clear out all of a user's tokens. If you are using cbAuth as your module of choice for authentication, then we will listen to logins and logouts and rotate the keys for you if you have enabled the enableAuthTokenRotator setting.

If you are NOT using cbAuth then we recommend you leverage the csrfRotate() mixin or the cbsrf.rotate() method on the @cbsrf model and do the manual rotation yourself.

Simple Example

Below is a simple example of manually verifying tokens in your handlers:

Automatic Token Verifier

We have included an interceptor that if loaded will verify all incoming requests to make sure the token has been passed or it will throw an exception.

The settings for this feature are:

You can also register an array of regular expressions that will be tested against the incoming event and if matched, it will allow the request through with no verification.

The verification process is as follows:

• If we are doing an integration test, then skip verification

• If the incoming HTTP Method is a get,options or head skip verification

• If the incoming event matches any of the verifyExcludes setting, then skip verification

Please note that this verifier will check the following locations for the token:

1. The request collection (rc) via the cbcsrf key

2. The request HTTP header (x-csrf-token) key

skipCsrf Annotation

You can also annotate your event handler actions with a skipCsrf annotation and the verifier will also skip the verification process for those actions.

/cbcsrf/generate Endpoint

This module also allows you to turn on the generation HTTP endpoint via the enableEndpoint boolean setting. When turned on the module will register the following route: GET /cbcsrf/generate/:key?. You can use this endpoint to generate tokens for your users via AJAX or UI only applications. Please note that you can pass an optional /:key URL parameter that will generate the token for that specific key.

This endpoint should be secured, so we have annotated it with a secured annotation so if you are using cbSecurity or cbGuard this endpoint will only be available to logged in users.