We are incredibly excited to release CBSecurity 3. This is a significant release with over six months of work invested in it. We have completely revamped our security module to make ColdBox applications secure, flexible, and ready for the upcoming ColdBox 7 release. The first major announcement for this release is that we have a brand-new logo!

In this blog post, we will explore the major features around this release and get you ready to upgrade as well.

What is CBSecurity

The ColdBox CBSecurity module is a collection of modules to help secure your ColdBox applications. The significant areas of concern are:

• A security authentication/authorization firewall which can secure your application based on the following:
  • Security rules and a rule engine for validation of incoming events or URL patterns
  • Handler and method annotations
• A security service can be used to provide user authentication and authorization contexts via a fluent language approach.
• A JWT generator, decoder, and authentication services
• Cross-Site Request Forgery (CSRF) Protection
• An authentication manager which can be plug-and-play with your authentication service or third-party services
• HTTP Basic-Authentication services that provide basic user credential storage and browser challenges
• A graphical user interface for visualizing the firewall and operational settings we lovingly call the CBSecurity Visualizer
• Industry-standard response headers to protect against XSS, clickjacking, frame busting, and much more

Getting Started

You can easily add security to your ColdBox applications by installing the module via CommandBox. Out of the box, it will secure your application using several industry standards headers and approaches. However, you will have to configure which authentication and authorization system it will use. Check out our new security overview guide: https://coldbox-security.ortusbooks.com/getting-started/overview

# Install
install cbsecurity

# Update
update cbsecurity

What's New With 3.0.0

New Documentation

The documentation has been rewritten to express a more straightforward approach to configuring security in your ColdBox applications.

New Configuration

The previous CBSecurity configuration was a flat struct with tons of configuration settings. It needed to be shorter and more verbose. In this version, we have created logical groupings:

• Authentication
• Basic Auth
• CSRF
• Firewall
• Security Headers
• Visualizer

You can check out the new configuration structures here: https://coldbox-security.ortusbooks.com/getting-started/configuration

// Module Settings
moduleSettings = {
    cbauth = {
	// This is the path to your user object that contains the credential validation methods
	userServiceClass = ""
    },

    cbsecurity = {
	/**
	 * --------------------------------------------------------------------------
	 * Authentication Services
	 * --------------------------------------------------------------------------
	 * Here you will configure which service is in charge of providing authentication for your application.
	 * By default we leverage the cbauth module which expects you to connect it to a database via your own User Service.
	 *
	 * Available authentication providers:
	 * - cbauth : Leverages your own UserService that determines authentication and user retrieval
	 * - basicAuth : Leverages basic authentication and basic in-memory user registration in our configuration
	 * - custom : Any other service that adheres to our IAuthService interface
	 */
	authentication : {
		// The WireBox ID of the authentication service to use which must adhere to the cbsecurity.interfaces.IAuthService interface.
		"provider"        : "authenticationService@cbauth",
		// WireBox ID of the user service to use when leveraging user authentication, we default this to whatever is set
		// by cbauth or basic authentication. (Optional)
		"userService"     : "",
		// The name of the variable to use to store an authenticated user in prc scope on all incoming authenticated requests
		"prcUserVariable" : "oCurrentUser"
	},

	/**
	 * --------------------------------------------------------------------------
	 * Basic Auth
	 * --------------------------------------------------------------------------
	 * These settings are used so you can configure the hashing patterns of the user storage
	 * included with cbsecurity.  These are only used if you are using the `BasicAuthUserService` as
	 * your service of choice alongside the `BasicAuthValidator`
	 */
	basicAuth : {
		// Hashing algorithm to use
		hashAlgorithm  : "SHA-512",
		// Iterates the number of times the hash is computed to create a more computationally intensive hash.
		hashIterations : 5,
		// User storage: The `key` is the username. The value is the user credentials that can include
		// { roles: "", permissions : "", firstName : "", lastName : "", password : "" }
		users          : {}
	},

	/**
	 * --------------------------------------------------------------------------
	 * CSRF - Cross Site Request Forgery Settings
	 * --------------------------------------------------------------------------
	 * These settings configures the cbcsrf module. Look at the module configuration for more information
	 */
	csrf : {
		// By default we load up an interceptor that verifies all non-GET incoming requests against the token validations
		enableAutoVerifier     : false,
		// A list of events to exclude from csrf verification, regex allowed: e.g. stripe\..*
		verifyExcludes         : [],
		// By default, all csrf tokens have a life-span of 30 minutes. After 30 minutes, they expire and we aut-generate new ones.
		// If you do not want expiring tokens, then set this value to 0
		rotationTimeout        : 30,
		// Enable the /cbcsrf/generate endpoint to generate cbcsrf tokens for secured users.
		enableEndpoint         : false,
		// The WireBox mapping to use for the CacheStorage
		cacheStorage           : "CacheStorage@cbstorages",
		// Enable/Disable the cbAuth login/logout listener in order to rotate keys
		enableAuthTokenRotator : true
	},
	/**
	 * --------------------------------------------------------------------------
	 * Firewall Settings
	 * --------------------------------------------------------------------------
	 * The firewall is used to block/check access on incoming requests via security rules or via annotation on handler actions.
	 * Here you can configure the operation of the firewall and especially what Validator will be in charge of verifying authentication/authorization
	 * during a matched request.
	 */
	firewall : {
		// Auto load the global security firewall automatically, else you can load it a-la-carte via the `Security` interceptor
		"autoLoadFirewall"            : true,
		// The Global validator is an object that will validate the firewall rules and annotations and provide feedback on either authentication or authorization issues.
		"validator"                   : "CBAuthValidator@cbsecurity",
		// Activate handler/action based annotation security
		"handlerAnnotationSecurity"   : true,
		// The global invalid authentication event or URI or URL to go if an invalid authentication occurs
		"invalidAuthenticationEvent"  : "",
		// Default Auhtentication Action: override or redirect when a user has not logged in
		"defaultAuthenticationAction" : "redirect",
		// The global invalid authorization event or URI or URL to go if an invalid authorization occurs
		"invalidAuthorizationEvent"   : "",
		// Default Authorization Action: override or redirect when a user does not have enough permissions to access something
		"defaultAuthorizationAction"  : "redirect",
		// Firewall database event logs.
		"logs" : {
			"enabled"    : false,
			"dsn"        : "",
			"schema"     : "",
			"table"      : "cbsecurity_logs",
			"autoCreate" : true
		}
		// Firewall Rules, this can be a struct of detailed configuration
		// or a simple array of inline rules
		"rules"                       : {
			// Use regular expression matching on the rule match types
			"useRegex" : true,
			// Force SSL for all relocations
			"useSSL"   : false,
			// A collection of default name-value pairs to add to ALL rules
			// This way you can add global roles, permissions, redirects, etc
			"defaults" : {},
			// You can store all your rules in this inline array
			"inline"   : [],
			// If you don't store the rules inline, then you can use a provider to load the rules
			// The source can be a json file, an xml file, model, db
			// Each provider can have it's appropriate properties as well. Please see the documentation for each provider.
			"provider" : { "source" : "", "properties" : {} }
		}
	},

	/**
	 * --------------------------------------------------------------------------
	 * Security Visualizer
	 * --------------------------------------------------------------------------
	 * This is a debugging panel that when active, a developer can visualize security settings and more.
	 * You can use the `securityRule` to define what rule you want to use to secure the visualizer but make sure the `secured` flag is turned to true.
	 * You don't have to specify the `secureList` key, we will do that for you.
	 */
	visualizer : {
		"enabled"      : false,
		"secured"      : false,
		"securityRule" : {}
	},

	/**
	 * --------------------------------------------------------------------------
	 * Security Headers
	 * --------------------------------------------------------------------------
	 * This section is the way to configure cbsecurity for header detection, inspection and setting for common
	 * security exploits like XSS, ClickJacking, Host Spoofing, IP Spoofing, Non SSL usage, HSTS and much more.
	 */
	securityHeaders                     : {
		// Master switch for security headers
		"enabled" : true,
		// If you trust the upstream then we will check the upstream first for specific headers
		"trustUpstream"         : false,
		// Content Security Policy
		// 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 everything from data theft, to
		// site defacement, to malware distribution.
		// https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP
		"contentSecurityPolicy" : {
			// Disabled by defautl as it is totally customizable
			"enabled" : false,
			// The custom policy to use, by default we don't include any
			"policy"  : ""
		},
		// 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 => X-Content-Type-Options: nosniff
		// https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Content-Type-Options
		"contentTypeOptions" : { "enabled" : true },
		"customHeaders"      : {
			// Name : value pairs as you see fit.
		},
		// Disable Click jacking: X-Frame-Options: DENY OR SAMEORIGIN
		// https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options
		"frameOptions" : { "enabled" : true, "value" : "SAMEORIGIN" },
		// HTTP Strict Transport Security (HSTS)
		// 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.
		// https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security,
		"hsts"         : {
			"enabled"           : true,
			// The time, in seconds, that the browser should remember that a site is only to be accessed using HTTPS, 1 year is the default
			"max-age"           : "31536000",
			// See Preloading Strict Transport Security for details. Not part of the specification.
			"preload"           : false,
			// If this optional parameter is specified, this rule applies to all of the site's subdomains as well.
			"includeSubDomains" : false
		},
		// Validates the host or x-forwarded-host to an allowed list of valid hosts
		"hostHeaderValidation" : {
			"enabled"      : false,
			// Allowed hosts list
			"allowedHosts" : ""
		},
		// Validates the ip address of the incoming request
		"ipValidation" : {
			"enabled"    : false,
			// Allowed IP list
			"allowedIPs" : ""
		},
		// 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.
		// https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy
		"referrerPolicy"     : { "enabled" : true, "policy" : "same-origin" },
		// Detect if the incoming requests are NON-SSL and if enabled, redirect with SSL
		"secureSSLRedirects" : { "enabled" : false },
		// Some browsers have built in support for filtering out reflected XSS attacks. Not foolproof, but it assists in XSS protection.
		// https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-XSS-Protection,
		// X-XSS-Protection: 1; mode=block
		"xssProtection"      : { "enabled" : true, "mode" : "block" }
	},

	/**
	 * --------------------------------------------------------------------------
	 * Json Web Tokens Settings
	 * --------------------------------------------------------------------------
	 * Here you can configure the JWT services for operation and storage.  In order for your firewall
	 * to leverage JWT authentication/authorization you must make sure you use the `JwtAuthValidator` as your
	 * validator of choice; either globally or at the module level.
	 */
	jwt                          : {
		// The issuer authority for the tokens, placed in the `iss` claim
		"issuer"                  : "",
		// The jwt secret encoding key, defaults to getSystemEnv( "JWT_SECRET", "" )
		"secretKey"               : getSystemSetting( "JWT_SECRET", "" ),
		// by default it uses the authorization bearer header, but you can also pass a custom one as well.
		"customAuthHeader"        : "x-auth-token",
		// The expiration in minutes for the jwt tokens
		"expiration"              : 60,
		// If true, enables refresh tokens, longer lived tokens (not implemented yet)
		"enableRefreshTokens"     : false,
		// The default expiration for refresh tokens, defaults to 30 days
		"refreshExpiration"          : 10080,
		// The Custom header to inspect for refresh tokens
		"customRefreshHeader"        : "x-refresh-token",
		// If enabled, the JWT validator will inspect the request for refresh tokens and expired access tokens
		// It will then automatically refresh them for you and return them back as
		// response headers in the same request according to the customRefreshHeader and customAuthHeader
		"enableAutoRefreshValidator" : false,
		// Enable the POST > /cbsecurity/refreshtoken API endpoint
		"enableRefreshEndpoint"      : true,
		// encryption algorithm to use, valid algorithms are: HS256, HS384, and HS512
		"algorithm"               : "HS512",
		// Which claims neds to be present on the jwt token or `TokenInvalidException` upon verification and decoding
		"requiredClaims"          : [] ,
		// The token storage settings
		"tokenStorage"            : {
			// enable or not, default is true
			"enabled"       : true,
			// A cache key prefix to use when storing the tokens
			"keyPrefix"     : "cbjwt_",
			// The driver to use: db, cachebox or a WireBox ID
			"driver"        : "cachebox",
			// Driver specific properties
			"properties"    : {
				"cacheName" : "default"
			}
		}
	}
};

HTTP Basic Authentication

CBSecurity now sports its own HTTP Basic Authentication Validator and User Service, allowing you to easily add basic authentication to your applications with no database needed: https://coldbox-security.ortusbooks.com/usage/basic-authentication. We even include a /cbsecurity/logout entry point to facilliate logouts for you.

New Blocking Rule

All security rules can now include a new action: block. This will block the incoming request with a 401 Unauthorized page.

CSRF Settings

In CBSecurity 3, you can configure the cross-site request forgery module within cbsecurity. We will take care of passing all the configurations to the cbcsrf module: https://coldbox-security.ortusbooks.com/getting-started/configuration/csrf

Security Headers

We have done our homework and have analyzed over 100 security headers that we could tap into to secure your ColdBox applications further. By default, CBSecurity will enable several policies to make your applications more secure, and you can also fully configure each area of concern: https://coldbox-security.ortusbooks.com/getting-started/configuration/security-headers

• Trusted upstreams
• Content security policies
• Content type options
• Custom security headers
• Frame options
• HSTS - HTTP Strict Transport Security
• Host header validation
• IP validation
• Referrer Policies
• Secure SSL redirects
• XSS Mitigations

Firewall Logs

CBSecurity now has a new setting that will allow it to store firewall events in a database of your choice. We will automatically create the tables and configure them for you.

// Firewall database event logs.
"logs" : {
	"enabled"    : false,
	"dsn"        : "",
	"schema"     : "",
	"table"      : "cbsecurity_logs",
	"autoCreate" : true
}

Security Visualizer

We have built a security visualizer UI that will assist you in the following areas:

• Visualize configuration settings
• Firewall rules visualizer
• Firewall rules simulator, where it can simulate an incoming URI/Event and let you know which rule it would fire
• Firewall activity charts and reports
• Much More...

New Event: cbsecurity_onFirewallBlock

This new event will fire when the firewall blocks an incoming event. You can listen to the event and act accordingly.

Smart Configurations

We do the configurations for you in this release. By default, it comes pre-wired for using cbauth as your authentication service, and you don't need to configure it if needed.

We will also auto-detect if you use the Basic Auth validator and configure the appropriate user service.

Allowed IPs

Every security rule can now declare which IPs are allowed.

Allowed HTTP Methods

Every security rule can now declare which HTTP methods are allowed.

Fixes and More Updates

Check out our complete release notes to see all the fixes and minor updates this release accomplishes.

Roadmap

3.1 is already planned and more features are coming your way:

• Per Module Authentication Services for true HMVC security hierarchies
• Logstach integration of firewall events
• Two Factor Authentication Framework
• Single Sign On Integrations
• Mucho mas!