Package 'firesafety'

Description

Cross-Origin Resource Sharing (CORS) is a mechanism for servers to indicate from where it may be accessed and allows browsers to block requests that are not permitted. For security reasons, browsers limits requests initiated from JavaScript to only those for the same site. To allow requests from other sites the server needs to send the right CORS headers with the response. Read more about CORS at MDN

Details

CORS is opt-in. The security measure is already in place in browsers to limit cross-origin requests, and CORS is a way to break out of this in a controlled manner where you can indicate exactly who can make a request and what requests can be made. In general it works like this:

1. A request is being initiated from a website, either through JavaScript or another venue, to a site different than the one it originates from.

2. The browser identifies that the request is cross-origin and sends an OPTIONS request to the server with information about the request it intends to send (this is called a pre-flight request).

3. The server responds with a 204 response giving the allowed types of requests that can be made for the resource.

4. If the original request conforms to the response the browser will then send the actual request.

5. The server responds to the actual request.

6. The client gets the response, but the browser will limit what information in the response it can access based on the information provided by the server in the pre-flight response.

As can be seen, a CORS request is slightly more complex than the standard request-response you normally think about. However, the pre-flight request can be cached by the browser and so, will not happen every time a ressource is accessed. While a site may employ a CORS policy the same way across all its endpoints it does not need to. It is fine to only turn on CORS for a subset of paths. In general it is a good rule of thumb to set up resource isolation for the paths that do not have CORS enabled.

Initialization

A new 'CORS'-object is initialized using the new() method on the generator and pass in any settings deviating from the defaults

Usage

Fiery plugin

A CORS object is a fiery plugin and can be used by passing it to the attach() method of the fiery server object. Once attached all requests will be passed through the plugin and the policy applied to it

Active bindings

Methods

Public methods

• CORS$new()

• CORS$add_path()

• CORS$on_attach()

• CORS$clone()

Method new()

Initialize a CORS object

Usage

CORS$new(
  path = "/*",
  origin = "*",
  methods = c("get", "head", "put", "patch", "post", "delete"),
  allowed_headers = NULL,
  exposed_headers = NULL,
  allow_credentials = FALSE,
  max_age = NULL
)

Arguments

Method add_path()

Add CORS settings to a path

Usage

CORS$add_path(
  path = "/*",
  origin = "*",
  methods = c("get", "head", "put", "patch", "post", "delete"),
  allowed_headers = NULL,
  exposed_headers = NULL,
  allow_credentials = FALSE,
  max_age = NULL
)

Arguments

Method on_attach()

Method for use by fiery when attached as a plugin. Should not be called directly.

Usage

CORS$on_attach(app, ...)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

CORS$clone(deep = FALSE)

Arguments

Examples

# Setup CORS for a sub path allowing access from www.trustworthy.com
# Tell the browser to cache the preflight for a day
cors <- CORS$new(
  path = "/shared_assets/*",
  origin = "https://www.trustworthy.com",
  methods = c("get", "head", "post"),
  max_age = 86400
)


# Use it in a fiery server
app <- fiery::Fire$new()

app$attach(cors)

Description

This helper function exists mainly to document the possible values and prevent misspelled directives. It returns a bare list. See the header reference and the CSP section of the MDN security guide for more information on the header

Usage

csp(
  default_src = NULL,
  script_src = NULL,
  script_src_elem = NULL,
  script_src_attr = NULL,
  style_src = NULL,
  style_src_elem = NULL,
  style_src_attr = NULL,
  img_src = NULL,
  font_src = NULL,
  media_src = NULL,
  object_src = NULL,
  child_src = NULL,
  frame_src = NULL,
  worker_src = NULL,
  connect_src = NULL,
  fenced_frame_src = NULL,
  manifest_src = NULL,
  prefetch_src = NULL,
  base_uri = NULL,
  sandbox = FALSE,
  form_action = NULL,
  frame_ancestors = NULL,
  report_to = NULL,
  require_trusted_types_for = FALSE,
  trusted_types = NULL,
  upgrade_insecure_requests = FALSE
)

Arguments

Value

A bare list with the input arguments

Examples

# Default setting
csp(
  default_src = "self",
  script_src = "self",
  script_src_attr = "none",
  style_src = c("self", "https:", "unsafe-inline"),
  img_src = c("self", "data:"),
  font_src = c("self", "https:", "data:"),
  object_src = "none",
  base_uri = "self",
  form_action = "self",
  frame_ancestors = "self",
  upgrade_insecure_requests = TRUE
)

Description

This plugin uses the information provided in the ⁠Sec-Fetch-*⁠ request headers to block unwanted requests to your server coming from other sites. Setting up a strict control with which requests are allowed is an important part of preventing some cross-site leaks as well as cross-site request forgery attacks.

Details

Compared to the other security measures in firesafety, the reource isolation plugin is a server-side blocker of requests. Both CORS and CORP sends back a full response and it is then up to the browser to determine if the response becomes available to the site. In contrast, this plugin will return a 403 response if the request fails to be accepted. This is not to say that resource isolation is better than CORS, CORP or other measures. They all target different situations (or the same situation from different angles) and works best in unison. You can read more about this type of defence at MDN and XS-Leaks Wiki

How it works

Resource isolation takes advantage of the ⁠Sec-Fetch-*⁠ headers that browser send along with requests. These headers informs the server about the nature of the request. Where it comes from, what action initiated it, and how it will be used. Based on this information the server may chose to allow a request to proceed or deny it altogether. This plugin runs a request through a range of tests and if it passes any of them it proceeds:

1. Does the request have the ⁠Sec-Fetch-*⁠ headers

2. Is allow_cors == TRUE and is Sec-Fetch-Mode set to cors

3. Is Sec-Fetch-Site set to allowed_site or a more restrictive value

4. Is the request method GET, the Sec-Fetch-Mode navigation, and the Sec-Fetch-Dest not one of those given by forbidden_navigation

You can have different permissions for different paths. The default during initialization is to add it to ⁠/*⁠ so that all all paths will share the same policy, but you can strengthen or loosen up specific paths as needed. A good rule of thumb is to make the policy as restrictive as possible while allowing your application to still work as intented. Further, if you have paths that do not have a resource isolation policy in place these should have CORS enabled.

Initialization

A new 'ResourceIsolation'-object is initialized using the new() method on the generator and pass in any settings deviating from the defaults

Usage

Fiery plugin

A ResourceIsolation object is a fiery plugin and can be used by passing it to the attach() method of the fiery server object. Once attached all requests will be passed through the plugin and the policy applied to it

Active bindings

Methods

Public methods

• ResourceIsolation$new()

• ResourceIsolation$add_path()

• ResourceIsolation$on_attach()

• ResourceIsolation$clone()

Method new()

Initialize a new ResourceIsolation object

Usage

ResourceIsolation$new(
  path = "/*",
  allowed_site = "same-site",
  forbidden_navigation = c("object", "embed"),
  allow_cors = TRUE
)

Arguments

Method add_path()

Add a policy to a path

Usage

ResourceIsolation$add_path(
  path,
  allowed_site,
  forbidden_navigation = c("object", "embed"),
  allow_cors = TRUE
)

Arguments

Method on_attach()

Method for use by fiery when attached as a plugin. Should not be called directly.

Usage

ResourceIsolation$on_attach(app, ...)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

ResourceIsolation$clone(deep = FALSE)

Arguments

Examples

# Create resource isolation policy denying all navigation requests
resource_isolation <- ResourceIsolation$new(forbidden_navigation = "all")

# Allow cross-site requests on a subpath
resource_isolation$add_path(
  path = "/all_is_welcome/*",
  allowed_site = "cross-site"
)


# Use it in a fiery server
app <- fiery::Fire$new()

app$attach(resource_isolation)

Description

This plugin is inspired by Helmet.js and aids you in setting response headers relevant for security of your fiery server. All defaults are taken from Helmet.js as well, except for the max-age of the Strict-Transport-Security header that has been doubled to 2 years which is the recommendation.

Details

Web security is a complicated subject and it is impossible for this document to stay current and true at all times as well as be able to learn the user of all the intricacies of web security. It is strongly advised that you familiarise yourself with this subject if you plan on exposing a fiery webserver to the public. A good starting point is MDN's guide on web security.

This plugin concerns 14 different headers that are in one way or another implicated in security. Some of them are only relevant if you serve HTML content on the web and have no effect on e.g. a server providing a REST api. These have been marked with UI below. While you may turn these off for a pure API server (by setting them to NULL), it is advised that you only steer away from the defaults if you have a good grasp of the implications. The headers are set very efficiently so removing some unneeded ones will only have an effect on the size of the response, not the handling time.

Headers

Content-Security-Policy (UI)

This header provides finely grained control over what code can be executed on the site you provide and thus help in preventing cross-site scripting (XSS) attacks. The configuration of this header is complicated and you can read more about it at the header reference and the CSP section of the security guide

The plugin does some light validation of the data structure you provide and you can use the csp() constructure to get argument tab-completion.

Content-Security-Policy-Report-Only (UI)

This header is like Content-Security-Policy above except that it doesn't enforce the policy but rather report any violations to a URL of your choice. The reason for providing this is that setting up CSP correctly can be difficult and may lead to your site not working correctly. Therefore, if you apply CSP to an already excisting site it is often a good idea to start with using this header and monitor where issues may arise before turning on the policy fully. You provide the URL to send violation reports to with the report_to directive which should be set to a URL. You can find more information on this header at the header reference

Cross-Origin-Embedder-Policy (UI)

This header controls which resources can be embedded in a document. If set to e.g. require-corp then only resources that implements CORP or CORS can be embedded. It is not set by default in SecurityHeaders. Read more about this header at MDN

Cross-Origin-Opener-Policy (UI)

This header controls and restricts access from cross-origin windows opened from the site. It helps isolate new documents and prevent a type of attack known as XS-Leaks. Read more about this header at MDN and about XS-Leaks in the security guide

Cross-Origin-Resource-Policy

This header controls where the given response can be used. If you e.g. return an image along with Cross-Origin-Resource-Policy: same-site, then this image is blocked from being loaded by other sites. Read more about this header at MDN and about CORP in general in the security guide

Origin-Agent-Cluster (UI)

This header helps isolate documents served from the same site into separate processes. This can improve performance of other tabs if a resource intensive tab is opened but also prevent certain information from being available to code running in the tab. Read more about this header at MDN

Referrer-Policy (UI)

This header instructs what to include in the Referer header when navigating away from the document. This can potentially lead to information leakage which can be alleviated using this header. Read more about this header at MDN as well as the security implications of the Referer header

Strict-Transport-Security

This header informs a browser that the given resource should only be accessed using HTTPS. This preference is cached by the browser and the next time the resource is accessed over HTTP it is automatically changed to HTTPS before the request is made. This header should only be sent over HTTPS to prevent a manipulator-in-the-middle from alterning its settings. In order for this to happen SecurityHeaders will automatically redirect any HTTP requests to HTTPS if this header is set. Read more about this header at MDN

X-Content-Type-Options

This header instruct the client that the MIME type provided by the Content-Type should be respected and mime-type sniffing avoided. Setting this can help prevent certain XSS attacks. Read more about this header at MDN and about its security implication in the security guide

X-DNS-Prefetch-Control (UI)

This header controls DNS prefetching and domain name resolution. A browser may do this in the background when a site is loaded which can reduce latency when a user clicks a link. However, it may also leak sensitive information so turning it off may increase user privacy. Read more about this header at MDN

X-Download-Options (UI)

This is an old header only relevant to Internet Explorer 8 and below that prevents downloaded content from having access to your site's context.

X-Frame-Options (UI)

This header has been superseeded by the frame-ancestor directive in the Content-Security-Policy header but may still be good to set for older browsers. It controls whether a site is allowed to be rendered inside a frame in another document. Preventing this can prevent click-jacking attacks. Read more about this header at MDN

X-Permitted-Cross-Domain-Policies

This header controls cross-origin access of a resource from a document running in a web client such as Adobe Flash Player or Microsoft Silverlight. The demise of these technologies have made this header less important. Read more about this header at MDN

X-XSS-Protection (UI)

This header has been deprecated in favor of the more powerful Content-Security-Policy header. In fact using XSS filtering can incur a security vulnerability which is why the default for SecurityHeaders is to turn the feature off (by setting X-XSS-Protection: 0 rather than omitting the header). Read more about this header at MDN

Initialization

A new 'SecurityHeaders'-object is initialized using the new() method on the generator and pass in any settings deviating from the defaults

Usage

Fiery plugin

A SecurityHeaders object is a fiery plugin and can be used by passing it to the attach() method of the fiery server object. Once attached all requests created will be prepopulated with the given headers. Any request handler is permitted to remove one or more of the headers to opt out of them.

Active bindings

Methods

Public methods

• SecurityHeaders$new()

• SecurityHeaders$on_attach()

• SecurityHeaders$clone()

Method new()

Initialize a new SecurityHeaders object

Usage

SecurityHeaders$new(
  content_security_policy = csp(default_src = "self", script_src = "self",
    script_src_attr = "none", style_src = c("self", "https:", "unsafe-inline"), img_src =
    c("self", "data:"), font_src = c("self", "https:", "data:"), object_src = "none",
    base_uri = "self", form_action = "self", frame_ancestors = "self",
    upgrade_insecure_requests = TRUE),
  content_security_policy_report_only = NULL,
  cross_origin_embedder_policy = NULL,
  cross_origin_opener_policy = "same-origin",
  cross_origin_resource_policy = "same-origin",
  origin_agent_cluster = TRUE,
  referrer_policy = "no-referrer",
  strict_transport_security = sts(max_age = 63072000, include_sub_domains = TRUE),
  x_content_type_options = TRUE,
  x_dns_prefetch_control = FALSE,
  x_download_options = TRUE,
  x_frame_options = "SAMEORIGIN",
  x_permitted_cross_domain_policies = "none",
  x_xss_protection = FALSE
)

Arguments

Method on_attach()

Method for use by fiery when attached as a plugin. Should not be called directly.

Usage

SecurityHeaders$on_attach(app, ...)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

SecurityHeaders$clone(deep = FALSE)

Arguments

Examples

# Create a plugin that turns off UI-related security headers
security_headers <- SecurityHeaders$new(
  content_security_policy = NULL,
  cross_origin_embedder_policy = NULL,
  cross_origin_opener_policy = NULL,
  origin_agent_cluster = NULL,
  referrer_policy = NULL,
  x_dns_prefetch_control = NULL,
  x_download_options = NULL,
  x_frame_options = NULL,
  x_xss_protection = NULL
)


# Use it with a fiery server
app <- fiery::Fire$new()

app$attach(security_headers)

Description

This helper function exists mainly to document the possible values and prevent misspelled directives. It returns a bare list. See MDN for more information on the header

Usage

sts(max_age, include_sub_domains = NULL, preload = NULL)

Arguments

Value

A bare list with the input arguments

Examples

# Default settings
sts(
  max_age = 63072000,
  include_sub_domains = TRUE
)