https://github.com/koajs/koa-lusca

koa version of lusca. Application security for koa.
https://github.com/koajs/koa-lusca

Last synced: 2 months ago
JSON representation

koa version of lusca. Application security for koa.

• Host: GitHub
• URL: https://github.com/koajs/koa-lusca
• Owner: koajs
• License: other
• Created: 2014-05-29T11:58:37.000Z (over 10 years ago)
• Default Branch: master
• Last Pushed: 2022-02-12T07:46:12.000Z (almost 3 years ago)
• Last Synced: 2024-05-23T05:34:34.999Z (7 months ago)
• Language: JavaScript
• Size: 117 KB
• Stars: 65
• Watchers: 6
• Forks: 9
• Open Issues: 6
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • License: LICENSE.txt
  • Security: SECURITY.md

Awesome Lists containing this project

• awesome-koa - koa-lusca - koa version of lusca. Application security for koa. (Middleware)
• awesome-koa - koa-lusca - Koa版本的lusca，用于Koa的应用安全。   (仓库 / 中间件)

README

        
# koa-lusca

[![NPM version][npm-image]][npm-url]

[![build status][travis-image]][travis-url]

[![Test coverage][coveralls-image]][coveralls-url]

[![Gittip][gittip-image]][gittip-url]

[![David deps][david-image]][david-url]

[![npm download][download-image]][download-url]

[npm-image]: https://img.shields.io/npm/v/koa-lusca.svg?style=flat-square

[npm-url]: https://npmjs.org/package/koa-lusca

[travis-image]: https://img.shields.io/travis/koajs/koa-lusca.svg?style=flat-square

[travis-url]: https://travis-ci.org/koajs/koa-lusca

[coveralls-image]: https://img.shields.io/coveralls/koajs/koa-lusca.svg?style=flat-square

[coveralls-url]: https://coveralls.io/r/koajs/koa-lusca?branch=master

[gittip-image]: https://img.shields.io/gittip/fengmk2.svg?style=flat-square

[gittip-url]: https://www.gittip.com/fengmk2/

[david-image]: https://img.shields.io/david/koajs/koa-lusca.svg?style=flat-square

[david-url]: https://david-dm.org/koajs/koa-lusca

[download-image]: https://img.shields.io/npm/dm/koa-lusca.svg?style=flat-square

[download-url]: https://npmjs.org/package/koa-lusca

Web application security middleware for koa.

Fork from [lusca](https://github.com/krakenjs/lusca), [krakenjs/lusca#26](https://github.com/krakenjs/lusca/pull/26).

## Usage

```js

var koa = require('koa');

var lusca = require('koa-lusca');

var app = koa();

app.use(lusca({

  csrf: true,

  csp: { /* ... */},

  xframe: 'SAMEORIGIN',

  p3p: 'ABCDEF',

  hsts: { maxAge: 31536000, includeSubDomains: true },

  xssProtection: true

}));

```

Setting any value to `false` will disable it. Alternately, you can opt into methods one by one:

```js

app.use(lusca.csrf());

app.use(lusca.csp({/* ... */}));

app.use(lusca.xframe({ value: 'SAMEORIGIN' }));

app.use(lusca.p3p({ value: 'ABCDEF' }));

app.use(lusca.hsts({ maxAge: 31536000 });

app.use(lusca.xssProtection();

```

## API

### lusca.csrf(options)

* `key` String - Optional. The name of the CSRF token added to the model. Defaults to `_csrf`.

* `secret` String - Optional. The key to place on the session object which maps to the server side token. Defaults to `_csrfSecret`.

* `impl` Function - Optional. Custom implementation to generate a token.

Enables [Cross Site Request Forgery](https://www.owasp.org/index.php/Cross-Site_Request_Forgery_\(CSRF\)) (CSRF) headers.

If enabled, the CSRF token must be in the payload when modifying data or you will receive a *403 Forbidden*. To send the token you'll need to echo back the `_csrf` value you received from the previous request.

### lusca.csp(options)

* `options.policy` Object - Object definition of policy.

* `options.policy` String, Object, or an Array - Object definition of policy. Valid policies examples include:

    * `{"default-src": "*"}`

    * `"referrer no-referrer"`

    * `[{ "img-src": "'self' http:" }, "block-all-mixed-content"]`

* `options.reportOnly` Boolean - Enable report only mode.

* `options.reportUri` String - URI where to send the report data

Enables [Content Security Policy](https://www.owasp.org/index.php/Content_Security_Policy) (CSP) headers.

#### Example Options

```js

// Everything but images can only come from own domain (excluding subdomains)

{

  policy: {

    'default-src': '\'self\'',

    'img-src': '*'

  }

}

```

See the [MDN CSP usage](https://developer.mozilla.org/en-US/docs/Web/Security/CSP/Using_Content_Security_Policy) page for more information on available policy options.

### lusca.xframe(value)

* `value` String - Required. The value for the header, e.g. DENY, SAMEORIGIN or ALLOW-FROM uri.

Enables X-FRAME-OPTIONS headers to help prevent [Clickjacking](https://www.owasp.org/index.php/Clickjacking).

### lusca.p3p(value)

* `value` String - Required. The compact privacy policy.

Enables [Platform for Privacy Preferences Project](http://support.microsoft.com/kb/290333) (P3P) headers.

### lusca.hsts(options)

* `options.maxAge` Number - Required. Number of seconds HSTS is in effect.

* `options.includeSubDomains` Boolean - Optional. Applies HSTS to all subdomains of the host

Enables [HTTP Strict Transport Security](https://www.owasp.org/index.php/HTTP_Strict_Transport_Security) for the host domain. The preload flag is required for HSTS domain submissions to [Chrome's HSTS preload list](https://hstspreload.appspot.com)

### lusca.xssProtection(options)

* `options.enabled` Boolean - Optional. If the header is enabled or not (see header docs). Defaults to `1`.

* `options.mode` String - Optional. Mode to set on the header (see header docs). Defaults to `block`.

Enables [X-XSS-Protection](http://blogs.msdn.com/b/ie/archive/2008/07/02/ie8-security-part-iv-the-xss-filter.aspx) headers to help prevent cross site scripting (XSS) attacks in older IE browsers (IE8)

## License

- Original License: Apache License, Version 2.0, Copyright (C) 2014 eBay Software Foundation

- Now: [MIT](LICENSE.txt)