npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

seespee

v3.1.0

Published

Create a Content-Security-Policy for a website based on the statically decidable relations

Downloads

12

Readme

seespee

NPM version Build Status Coverage Status Dependency Status

Generate a Content-Security-Policy header for a website. The website is crawled for scripts, stylesheets, images, fonts, application manifests etc., which will be listed by their origin. Inline scripts and stylesheets will be hashed so 'unsafe-inline' can be avoided.

Usage

seespee [--root <inputRootDirectory>] [--validate] [--level <number>]
[--ignoreexisting] [--include ...] <url|pathToHtml>

Options:
  --help             Show help                                         [boolean]
  --version          Show version number                               [boolean]
  --root             Path to your web root so seespe can resolve root-relative
                     urls correctly (will be deduced from your input files if
                     not specified)                                     [string]
  --ignore-existing  Whether to ignore the existing Content-Security-Policy
                     (<meta> or HTTP header) and start building one from scratch
                                                      [boolean] [default: false]
  --include          CSP directives to include in the policy to be generated,
                     eg. "script-src *.mycdn.com; img-src 'self'"       [string]
  --validate         Turn on validation mode, useful for CI. If non-whitelisted
                     assets are detected, a report will be output, and seespee
                     will return a non-zero status code.               [boolean]
  --level            The CSP level to target. Possible values: 1 or 2. Defaults
                     to somewhere in between so that all browsers are supported.
                                                                        [number]
  --pretty           Whether to reformat the generated CSP in a human friendly
                     way                               [boolean] [default: true]
  --user-agent       Use a specific User-Agent string when retrieving http(s)
                     resources. Useful with servers that are configured to only
                     send a Content-Security-Policy header to browsers known to
                     understand it                                      [string]

Example

$ npm install -g seespee
$ seespee https://lodash.com/
Content-Security-Policy: default-src 'none'; img-src 'self' data:; manifest-src 'self'; style-src 'self' https://unpkg.com; font-src https://unpkg.com; script-src 'self' 'sha256-85RLtUiAixnqFeQvOtsiq5HBnq4nAgtgmrVVlIrEwyk=' 'sha256-9gJ3aNComH+MFu3rw5sARPpvBPOF0VxLUsw1xjxmVzE=' 'sha256-Df4bY3tGwX4vCpgFJ2b7hL/F9h65FABZRCub2RYYOmU=' 'sha256-euGdatRFmkEGGSWO0jbpFAuN5709ZGDaFjCqNnYocQM=' 'unsafe-inline' https://embed.runkit.com https://unpkg.com
$ seespee https://github.com/
Content-Security-Policy:
  default-src 'none';
  base-uri 'self';
  block-all-mixed-content;
  child-src render.githubusercontent.com;
  connect-src 'self' api.github.com collector.githubapp.com github-cloud.s3.amazonaws.com
    github-production-repository-file-5c1aeb.s3.amazonaws.com
    github-production-upload-manifest-file-7fdce7.s3.amazonaws.com
    github-production-user-asset-6210df.s3.amazonaws.com
    status.github.com uploads.github.com wss://live.github.com www.google-analytics.com;
  font-src assets-cdn.github.com;
  form-action 'self' gist.github.com github.com;
  frame-ancestors 'none';
  img-src 'self' *.githubusercontent.com assets-cdn.github.com collector.githubapp.com
    data: github-cloud.s3.amazonaws.com identicons.github.com;
  script-src assets-cdn.github.com;
  style-src 'unsafe-inline' assets-cdn.github.com;

It also works with a website located in a directory on a file system. In that case, a --root option is supported, determing how root-relative urls are to be interpreted (if not given, it will be assumed to be the directory containing the HTML file):

$ seespee --root /path/to/my/project /path/to/my/project/main/index.html

If the website has an existing Content-Security-Policy header or a meta tag it will be detected and taken into account so all the existing directives are supported. This behavior can be disabled with the --ignoreexisting parameter.

You can also specify custom directives to include on the command line via the --include switch. The provided directives will be taken into account when adding new ones so you won't end up with redundant entries that are already whitelisted by eg. *:

$ seespee --include "default-src 'none'; style-src *" https://news.ycombinator.com/
Content-Security-Policy:
  default-src 'self';
  script-src 'self' 'unsafe-inline' https://cdnjs.cloudflare.com/ https://www.google.com/recaptcha/
    https://www.gstatic.com/recaptcha/;
  frame-src 'self' https://www.google.com/recaptcha/;
  style-src 'self' 'unsafe-inline';

Validation mode

Using the --validate flag you can test that a website has a Content-Security-Policy that covers all the assets that are used. seespee --validate <url> will exit with a non-zero status code if a violation is found, so it's easy to integrate with CI systems.

As with the CSP generation mode, remember that seespee will only consider assets that can be detected via a static analysis, so there could be JavaScript on the page that loads non-whitelisted assets at runtime.

CSP level

You can tell seespee to target a specific CSP level by passing the --level <number> switch.

The default is "somewhere in-between" -- to support as many browsers as possible, utilizing CSP 2 features that are known to fall back gracefully in browsers that only support CSP 1.

If you target CSP level 1, inline scripts and stylesheets won't be hashed. If any are present, the dreaded 'unsafe-inline' directive will be added instead. This saves a few bytes in the CSP, but sacrifices security with CSP level 2+ compliant browsers

If you target CSP level 2, the full path of will be used when the most sensitive directives (script-src, style-src, frame-src, object-src, manifest-src, and child-src) refer to external hosts, addressing the weakness pointed out by Bypassing path restriction on whitelisted CDNs to circumvent CSP protections - SECT CTF Web 400 writeup. Unfortunately this cannot be the default because it breaks in Safari 8, 9, and 9.1, which don't support the full CSP 1 source expression grammar. You can use express-legacy-csp to mitigate this.

Programmatic usage

var seespee = require('seespee');
seespee('https://github.com/').then(function (result) {
  console.log(result.contentSecurityPolicy);
  // default-src \'none\'; style-src https://assets-cdn.github.com; ...
});

You can also pass an options object with the include and ignoreMeta properties:

var seespee = require('seespee');
seespee('https://github.com/', {
  include: 'report-uri: /tell-what-happened/',
  ignoreMeta: true,
}).then(function (result) {
  // ...
});

When processing files on disc, the root option is supported as well (see above):

var seespee = require('seespee');
seespee('/path/to/my/website/main/index.html', {
  root: '/path/to/my/website/',
  include: 'report-uri: /tell-what-happened/',
  ignoreMeta: true,
}).then(function (result) {
  // ...
});

License

Seespee is licensed under a standard 3-clause BSD license -- see the LICENSE file for details.