Koba

Koba is a Kitura middleware for setting HTTP security headers to help mitigate vulnerabilities and protect against attackers. It contains a strict default configuration and a policy builder for designing and overriding security header values.

Secure Headers

Security Headers are HTTP response headers that, when set, can enhance the security of your web application by enabling browser security policies.

You can assess the security of your HTTP response headers at securityheaders.com or at the Mozilla Observatory

Recommendations used by Koba and more information regarding security headers can be found at the OWASP Secure Headers Project and Mozilla Web Security

Cache-control

Prevent cacheable HTTPS response
Default Value: no-cache, no-store, must-revalidate, max-age=0

Content-Security-Policy (CSP)

Prevent cross-site injections
Default Value: script-src 'self'; object-src 'self' (not included by default)

Expect-CT

Enforcement of Certificate Transparency Default Value: max-age=0 (not included by default)

Feature-Policy

Disable browser features and APIs
Default Value: accelerometer 'none'; ambient-light-sensor 'none'; autoplay 'none'; camera 'none'; encrypted-media 'none'; fullscreen 'none'; geolocation 'none'; gyroscope 'none'; magnetometer 'none'; microphone 'none'; midi 'none'; payment 'none'; picture-in-picture 'none'; speaker 'none'; sync-xhr 'none'; usb 'none'; vr 'none' (not included by default)

Strict-Transport-Security (HSTS)

Ensure application communication is sent over HTTPS
Default Value: max-age=86400; includeSubDomains

Referrer-Policy

Enable full referrer if same origin, remove path for cross origin and disable referrer in unsupported browsers
Default Value: no-referrer, strict-origin-when-cross-origin

X-Content-Type-Options (XCTO)

Prevent MIME-sniffing
Default Value: nosniff

X-Frame-Options (XFO)

Disable framing from different origins (clickjacking defense)
Default Value: SAMEORIGIN

X-XSS-Protection (XXP)

Enable browser cross-site scripting filters
Default Value: 1; mode=block

Important information

The Strict-Transport-Security (HSTS) header will tell the browser to only utilize secure HTTPS connections for the domain, and in the default configuration, including all subdomains. The HSTS header requires trusted certificates and users will unable to connect to the site if using self-signed or expired certificates. The browser will honor the HSTS header for the time directed in the max-age attribute (default = 2 years), and setting the max-age to 0 will disable an already set HSTS header. Use hsts: nil in the KobaConfig to not include the HSTS header.
The Content-Security-Policy (CSP) header can break functionality and can (and should) be carefully constructed, use the csp: CSP().default() in the KobaConfig to enable default values.

Usage

Add Koba to your Package.swift

Add to dependencies

.package(url: "https://github.com/cak/koba", from: "0.2.0"),

Add to target dependencies

.target(name: "name", dependencies: ["Koba"]),

Import package

import Koba

Default configuration:

import Kitura
import Koba

let koba = Koba()

let router = Router()
router.all(middleware: koba)

Default HTTP response headers:

X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Referrer-Policy: no-referrer, strict-origin-when-cross-origin
X-Frame-Options: SAMEORIGIN
Cache-control: no-cache, no-store, must-revalidate, max-age=0
Strict-Transport-Security: max-age=86400; includeSubDomains

Options

You can toggle the setting of headers with default values by passing an object with Header().default() or nil to remove the header. You can override default values by passing Header().set("custom") for a custom header value or using the policy builder for the following options:

cacheControl - set the Cache-control header
csp - set the Content-Security-Policy
expectCT - set the Expect-CT header
featurePolicy - set the Feature-Policy header
hsts - set the Strict-Transport-Security header
referrerPolicy - set the Referrer-Policy header
xcto - set the X-Content-Type-Options header
xfo - set the X-Frame-Options header
xxp - set the X-XSS-Protection header

Example:

import Kitura
import Koba

let config = KobaConfig(
            cacheControl: CacheControl()
                .noStore()
                .mustRevalidate()
                .proxyRevalidate(),
            csp: CSP()
                .defaultSrc(Koba.Source.none)
                .blockAllMixedContent()
                .connectSrc(Koba.Source.sameOrigin, "api.swiftserver.dev"),
            expectCT: ExpectCT()
	            .maxAge(Koba.Time.fiveMinutes)
	            .enforce(),
            featurePolicy: FeaturePolicy()
                .geolocation(Koba.Source.sameOrigin, "swiftserver.dev")
                .vibrate(Koba.Source.none),
            hsts: HSTS()
                .includeSubdomains()
                .preload()
                .maxAge(Koba.Time.oneWeek),
            referrerPolicy: ReferrerPolicy()
                .noReferrer(),
            xcto: nil,
            xfo: XFO()
                .deny(),
            xxp: XXP()
                .enabledBlock()
        )

let koba = Koba(config: config)
router.all(middleware: koba)

Referrer-Policy: no-referrer
Strict-Transport-Security: includeSubDomains; preload; max-age=604800
Cache-control: no-store, must-revalidate, proxy-revalidate
Expect-CT: max-age=300; enforce
X-XSS-Protection: 1; mode=block
Content-Security-Policy: default-src 'none'; block-all-mixed-content; connect-src 'self' api.swiftserver.dev
Feature-Policy: geolocation 'self' swiftserver.dev; vibrate 'none'
X-Frame-Options: DENY

Policy Builder

Helpers

Koba.Source

data - data:
mediastream - mediastream:
https - https:
blob - blob:
filesystem - filesystem:
none - 'none'
sameOrigin - 'self'
src - 'src'
strictDynamic - 'strict-dynamic'
unsafeEval - 'unsafe-eval'
unsafeInline - 'unsafe-inline'
wildcard - *

Koba.Time

fiveMinutes - 300
oneDay - 86400
oneWeek - 604800
oneMonth - 2592000
oneYear - 31536000
twoYears - 63072000

Example

let config = KobaConfig(
    csp: CSP().defaultSrc(Koba.Source.sameOrigin),
    hsts: HSTS().maxAge(Koba.Time.oneDay)
)

let koba = Koba(config: config)

Content-Security-Policy: default-src 'self'
Strict-Transport-Security: max-age=86400

CacheControl()

default() - script-src 'self'; object-src 'self'
custom(value) - custom value

Directives: private(), public(), immutable(), maxAge(seconds), maxStale(seconds), minFresh(seconds), mustRevalidate(), noCache(), noStore(), noTransform(), onlyIfCached(), proxyRevalidate(), sMaxage(seconds), staleIfError(seconds), staleWhileRevalidate(seconds)

Example:

let policy = CacheControl()
    .noStore()
    .mustRevalidate()
    .proxyRevalidate()

// no-store, must-revalidate, proxy-revalidate

Resources: Cache-Control | MDN

CSP()

default() - script-src 'self'; object-src 'self'
custom(value) - custom value
reportOnly() - change header to Content-Security-Policy-Report-Only

Directives: baseUri(sources), blockAllMixedContent(), connectSrc(sources), defaultSrc(sources), fontSrc(sources), formAction(sources), frameAncestors(sources), frameSrc(sources), imgSrc(sources), manifestSrc(sources), mediaSrc(sources), objectSrc(sources), pluginTypes(types), reportTo(ReportTo), reportUri(uri), requireSriFor(values), sandbox(values), scriptSrc(sources), styleSrc(sources), upgradeInsecureRequests(), workerSrc(sources)

You can check the effectiveness of your CSP Policy at the CSP Evaluator

Example:

let policy = CSP()
    .defaultSrc(Koba.Source.none)
    .baseUri(Koba.Source.sameOrigin)
    .blockAllMixedContent()
    .connectSrc(Koba.Source.sameOrigin, "api.swiftserver.dev")
    .frameSrc(Koba.Source.none)
    .imgSrc(Koba.Source.sameOrigin, "static.swiftserver.dev");

// default-src 'none'; base-uri 'self'; block-all-mixed-content; connect-src 'self' api.swiftserver.dev; frame-src 'none'; img-src 'self' static.swiftserver.dev

Reporting

Content-Security-Policy-Report-Only

Using reportOnly() will change the header to Content-Security-Policy-Report-Only

Example:

let policy = CSP()
    .defaultSrc(Koba.Source.none)
    .baseUri(Koba.Source.sameOrigin)
    .reportOnly()
    
let config = KobaConfig(csp: policy)
let koba = Koba(config: config)
router.all(middleware: koba)

Cache-control: no-cache, no-store, must-revalidate, max-age=0
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Content-Security-Policy-Report-Only: default-src 'none'; base-uri 'self'
Referrer-Policy: no-referrer, strict-origin-when-cross-origin
Strict-Transport-Security: max-age=63072000; includeSubdomains
X-Frame-Options: SAMEORIGIN

report-to

let reportToEndpoint = CSP.ReportToEndpoint(url: "https://swiftserver.dev/reports")

let reportTo = CSP.ReportTo(group: "CSP-Endpoint",
                            maxAge: Koba.Time.oneWeek,
                            endpoints: [reportToEndpoint],
                            includeSubdomains: true)

let policy = CSP()
    .defaultSrc(Koba.Source.none)
    .baseUri(Koba.Source.sameOrigin)
    .reportTo(reportTo)

// default-src 'none'; base-uri 'self'; report-to {"group":"CSP-Endpoint","endpoints":[{"url":"https:\/\/swiftserver.dev\/reports"}],"include_subdomains":true,"max_age":604800}

report-uri

let policy = CSP()
    .defaultSrc(Koba.Source.none)
    .baseUri(Koba.Source.sameOrigin)
    .reportUri("https://swiftserver.dev/reports")

// default-src 'none'; base-uri 'self'; report-uri https://swiftserver.dev/reports

ExpectCT()

default() - script-src 'self'; object-src 'self'
custom(value) - custom value

Directives: maxAge(seconds), enforce(), reportUri(uri)

Example:

let policy = ExpectCT()
    .maxAge(Koba.Time.oneDay)
    .enforce()
    .reportUri("https://swiftserver.dev")

// max-age=86400; enforce; report-uri="https://swiftserver.dev"

Resources: Expect-CT | MDN

FeaturePolicy()

default() - accelerometer 'none'; ambient-light-sensor 'none'; autoplay 'none'; camera 'none'; encrypted-media 'none'; fullscreen 'none'; geolocation 'none'; gyroscope 'none'; magnetometer 'none'; microphone 'none'; midi 'none'; payment 'none'; picture-in-picture 'none'; speaker 'none'; sync-xhr 'none'; usb 'none'; vr 'none';
custom(value) - custom value

Directives: accelerometer(allowlist), ambientLightSensor(allowlist), autoplay(allowlist), camera(allowlist), documentDomain(allowlist), encryptedMedia(allowlist), fullscreen(allowlist), geolocation(allowlist), gyroscope(allowlist), magnetometer(allowlist), microphone(allowlist), midi(allowlist), payment(allowlist), pictureInPicture(allowlist), speaker(allowlist), syncXhr(allowlist), usb(allowlist), vibrate(allowlist), vr(allowlist)

Example:

let policy = FeaturePolicy()
    .geolocation(Koba.Source.sameOrigin, "swiftserver.dev")
    .vibrate(Koba.Source.none)

// geolocation 'self' swiftserver.dev; vibrate 'none'

Resources: A new security header: Feature Policy | Scott Helme , Feature-Policy | MDN , Introduction to Feature Policy | Google Developers

HSTS()

default() - max-age=63072000; includeSubdomains
custom(value) - custom value

Directives: includeSubdomains(), maxAge(seconds), preload()

Example:

let policy = HSTS()
		.maxAge(Koba.Time.oneMonth)
    .includeSubdomains()
    .preload()

// max-age=2592000; includeSubDomains; preload

Resources: Strict-Transport-Security | MDN , HTTP Strict Transport Security Cheat Sheet | OWASP

ReferrerPolicy()

default() - no-referrer, strict-origin-when-cross-origin
custom(value) - custom value

Directives:, noReferrer(), noReferrerWhenDowngrade(), origin(), originWhenCrossOrigin(), sameOrigin(), strictOrigin(), strictOriginWhenCrossOrigin(), unsafeUrl()

Resources: A new security header: Referrer Policy | Scott Helme , Referrer-Policy | MDN

XCTO()

default() - nosniff
custom(value) - custom value

Examples:

let policy = XCTO().default()

// nosniff

Resources: X-Content-Type-Options - HTTP | MDN

XFO()

default() - SAMEORIGIN
custom(value) - custom value

Directives: allowFrom(), deny(), sameorigin()

Examples:

let policy = XFO().deny()

// DENY

Resources: X-Frame-Options | MDN

XXP()

default() - 1; mode=block
custom(value) - custom value

Directives: disabled(), enabled(), enabledBlock(), enabledReport(uri)

Examples:

let policy = XXP().enabledBlock()

// 1 mode=block

Resources: X-XSS-Protection | MDN

Contributing

Send a pull request, create an issue or discuss with me (@cak) on the the Kitura Slack.

Miscellaneous

Kob'a (ko'-bah) is the Hebrew word for helmet, a nod to Helmet.js.

Looking for security headers for Vapor? Check out Vapor Security Headers.

Resources:

Kitura
OWASP
OWASP Secure Headers Project
Mozilla Web Security

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

Koba

Secure Headers

Cache-control

Content-Security-Policy (CSP)

Expect-CT

Feature-Policy

Strict-Transport-Security (HSTS)

Referrer-Policy

X-Content-Type-Options (XCTO)

X-Frame-Options (XFO)

X-XSS-Protection (XXP)

Important information

Usage

Add Koba to your Package.swift

Options

Policy Builder

Helpers

Koba.Source

Koba.Time

CacheControl()

CSP()

Reporting

ExpectCT()

FeaturePolicy()

HSTS()

ReferrerPolicy()

XCTO()

XFO()

XXP()

Contributing

Miscellaneous

Resources:

Files

README.md

Latest commit

History

README.md

File metadata and controls

Koba

Secure Headers

Cache-control

Content-Security-Policy (CSP)

Expect-CT

Feature-Policy

Strict-Transport-Security (HSTS)

Referrer-Policy

X-Content-Type-Options (XCTO)

X-Frame-Options (XFO)

X-XSS-Protection (XXP)

Important information

Usage

Add Koba to your Package.swift

Options

Policy Builder

Helpers

Koba.Source

Koba.Time

CacheControl()

CSP()

Reporting

ExpectCT()

FeaturePolicy()

HSTS()

ReferrerPolicy()

XCTO()

XFO()

XXP()

Contributing

Miscellaneous

Resources: