{
  "_args": [
    [
      {
        "raw": "snyk-policy@1.7.1",
        "scope": null,
        "escapedName": "snyk-policy",
        "name": "snyk-policy",
        "rawSpec": "1.7.1",
        "spec": "1.7.1",
        "type": "version"
      },
      "/build/npm-check-updates/pkg/npm-check-updates/usr/lib/node_modules/npm-check-updates/node_modules/snyk"
    ]
  ],
  "_from": "snyk-policy@1.7.1",
  "_id": "snyk-policy@1.7.1",
  "_inCache": true,
  "_location": "/npm-check-updates/snyk-policy",
  "_nodeVersion": "6.10.1",
  "_npmOperationalInternal": {
    "host": "packages-12-west.internal.npmjs.com",
    "tmp": "tmp/snyk-policy-1.7.1.tgz_1491288441380_0.2961472494062036"
  },
  "_npmUser": {
    "name": "snyk-admin",
    "email": "admin+snyk@snyk.io"
  },
  "_npmVersion": "2.15.12",
  "_phantomChildren": {},
  "_requested": {
    "raw": "snyk-policy@1.7.1",
    "scope": null,
    "escapedName": "snyk-policy",
    "name": "snyk-policy",
    "rawSpec": "1.7.1",
    "spec": "1.7.1",
    "type": "version"
  },
  "_requiredBy": [
    "/npm-check-updates/snyk"
  ],
  "_resolved": "https://registry.npmjs.org/snyk-policy/-/snyk-policy-1.7.1.tgz",
  "_shasum": "e413b6bd4af6050c5e5f445287909e4e98a09b22",
  "_shrinkwrap": null,
  "_spec": "snyk-policy@1.7.1",
  "_where": "/build/npm-check-updates/pkg/npm-check-updates/usr/lib/node_modules/npm-check-updates/node_modules/snyk",
  "author": {
    "name": "Remy Sharp"
  },
  "bugs": {
    "url": "https://github.com/Snyk/policy/issues"
  },
  "dependencies": {
    "debug": "^2.2.0",
    "es6-promise": "^3.1.2",
    "js-yaml": "^3.5.3",
    "lodash.clonedeep": "^4.3.1",
    "semver": "^5.1.0",
    "snyk-module": "^1.8.1",
    "snyk-resolve": "^1.0.0",
    "snyk-try-require": "^1.1.1",
    "then-fs": "^2.0.0"
  },
  "description": "Snyk's policy parser and matching logic",
  "devDependencies": {
    "jscs": "^2.11.0",
    "proxyquire": "^1.7.4",
    "semantic-release": "^4.3.5",
    "sinon": "^1.17.3",
    "tap": "^5.7.0",
    "tap-only": "0.0.5"
  },
  "directories": {},
  "dist": {
    "shasum": "e413b6bd4af6050c5e5f445287909e4e98a09b22",
    "tarball": "https://registry.npmjs.org/snyk-policy/-/snyk-policy-1.7.1.tgz"
  },
  "gitHead": "fa3c2820001e15fa2bd86bef20411c3dd9310985",
  "homepage": "https://github.com/Snyk/policy#readme",
  "keywords": [
    "snyk"
  ],
  "license": "Apache-2.0",
  "main": "lib/index.js",
  "maintainers": [
    {
      "name": "remy",
      "email": "remy@leftlogic.com"
    },
    {
      "name": "snyk-admin",
      "email": "admin+snyk@snyk.io"
    }
  ],
  "name": "snyk-policy",
  "optionalDependencies": {},
  "readme": "# snyk-policy\n\n[![Build Status](https://travis-ci.org/Snyk/policy.svg?branch=master)](https://travis-ci.org/Snyk/policy) [![Coverage Status](https://coveralls.io/repos/Snyk/policy/badge.svg?branch=master&service=github)](https://coveralls.io/github/Snyk/policy?branch=master)\n\nLoads Snyk policy files, typically name `.snyk`, parses them and returns a structure policy object.\n\nFrom there, the policy object can `filter` vulnerabilities based on `vuln.id` and path (`vuln.from`) matching.\n\nPolicies can also load from multiple locations, and optionally support trusting deep policies, or ignoring all policies entirely.\n\n## How it works\n\nThe policy module is written to support future versions of policy formats, so you shouldn't need to worry about what version you're dealing with.\n\nThe policy is loaded, typically this will be a YAML file named `.snyk` (but can be loaded from another filename).\n\nThis returns an object that has the following public keys:\n\n- `ignore` Object\n- `patch` Object\n- `suggest` Object (optionally depending on the policy config)\n- `version` String\n\nThe `ignore`, `patch` and `suggest` all have similar top level structures. For example:\n\n```text\nignore: {\n  '<snyk-vuln-id>': [\n    {\n      '<module path>': { <metadata> }\n    }\n  ]\n}\n```\n\nThe metadata for ignore and suggest are the same:\n\n```js\n{\n  reason: '<string>',\n  expires: '<JSON date format>'\n}\n```\n\nThe metadata for patch is:\n\n```js\n{\n  patched: '<JSON date format>'\n}\n```\n\nFor a full example of a fully parsed policy file, see [this fixture example](https://github.com/Snyk/policy/blob/a96862bf1c14e78640611640716c05be2e4a8afd/test/fixtures/ignore/parsed.json).\n\nThe vulnerability report is passed in to the instance `.filter` function and the vulns are filtered out based on the ignore rules and the patch rules.\n\nIf there is any suggest keys on the policy a `note` property is added to the individual vulnerability it matches.\n\n### How filtering works\n\nThe filtering works on two levels:\n\n1. matches on `vuln.id`\n2. matches the `vuln.from` against the module path\n\nIf first (1) is satisfied, then (2) is checked. If ignoring, the vulnerability is stripped from the report.\n\nIf the rule is listed in the patches, the Snyk patch file is also checked to ensure it exists (this is a way to validate the patch has actually taken place - but note that this can be circumvented when the file system isn't available, see [skipping patch verification](#skipVerifyPatch).\n\nA module path is constructed by the name and then optionally the version or version range. A star rule (`*`) is also supported.\n\n### Module path rules\n\nGiven the following dependency tree, and assuming we have a known vulnerability in semver@2.3.2:\n\n```text\n.\n└─┬ @remy/protect-test@1.0.7\n  ├── semver@2.3.2\n  └─┬ snyk@0.5.0\n    ├─┬ os-name@1.0.3\n    │ └─┬ win-release@1.1.1\n    │   └── semver@5.1.0\n    ├── semver@5.1.0\n    └─┬ update-notifier@0.5.0\n      └─┬ semver-diff@2.1.0\n        └── semver@5.1.0\n```\n\nThe following are examples of module paths that could target the semver vulnerability (note that the root module name is not part of the path, represented as `.` in the tree above):\n\n```text\n@remy/protect-test > semver\n@remy/protect-test@1.0.7 > semver@2.3.2\n* > semver\n* > semver@2.x\n```\n\nThe first example rule (above) is how the policy is stored by default. However, policy files can be manually edited if desired.\n\n## Usage\n\nInstalled via npm: `npm install -S snyk-policy`. Typically loaded and applied to vulnerabilities:\n\n```js\nvar policy = require('snyk-policy');\n\nvar vulns = snyk.test('snyk-demo-app@1.0.0'); // assumes snyk is loaded\npolicy.load(process.cwd()).then(rules => {\n  console.log(rules.filter(vulns));\n});\n```\n\n## Skipping patch verification\n\nBefore the policy runs the filter, if the policy return object includes the property `skipVerifyPatch: true` then the check for the patch file will not be performed.\n\nThis is in use in the [registry (private repo)](https://github.com/Snyk/registry/blob/feat/policies/lib/snapshots.js#L112-L117) and is useful when the policy loading doesn't have local access to the file system that the packages live on.\n\n## API\n\n### policy.load(root[, options])\n\nParses and loads a given directory or directories. Returns a `promise`.\n\n#### `root`: String | Array\n\nThis can be a string pointing to a directory (if so, must include a `.snyk` file inside) or you can define the specific filename to load, i.e. `./my-policy`.\n\nIf an array is given, the first policy is the primary, and the subsequent policies will inherit the module path from the primary policy.\n\n**Important:** All secondary policy `ignore` rules are ignored and treated as suggestions, adding a `note` property on the vulnerability.\n\n#### `options`: Object\n\n- `ignore-policy: true` ignores all the policy rules and returns an empty policy (use in `snyk test --ignore-policy`)\n- `trust-policies: true` applies `ignore` rules in secondary policies (and doesn't offer them as suggestions)\n- `loose: true` do not throw an exception if the policy can't be loaded from disk\n- `skipPatchValidation\n\n### policy.loadFromText(string)\n\nParses the string and returns the policy. Returns a `promise`.\n\n#### `string`: String\n\nA raw YAML string.\n\n### policy.save(config[, root, progress]) & .save([root, progress])\n\nSave the policy to disk in the latest format, so if the original policy version was `v1` and the newest is `v2`, the policy will be upgraded.\n\nNote that this method is also available on the response object from [`.load`](#policyloadroot-options), so can be called as `res.save()` (where `res` is the loaded config).\n\nReturns a `promise`.\n\n#### `config`: Object\n\nThe structure policy object.\n\n#### `root`: String\n\nThe directory to save the policy file (`.snyk`). Defaults to CWD via `process.cwd()`.\n\n### `progress`: Promise\n\nA progress indicator, as used in [snyk cli](https://github.com/Snyk/snyk-internal/blob/0459a7b21709c6a1d3c5edeb61b4abf2103ffaf0/cli/commands/protect/wizard.js#L268).\n\n### policy.filter(config, vulns) & .filter(vulns)\n\nApplies the policy to the vulnerabilities object. The `vulns` object is expected as:\n\n```js\n{\n  ok: Boolean,\n  vulnerabilities: Array\n}\n```\n\nIf all the vulns are stripped because of the policy, then the `ok` bool is set to `true`.\n\nNote that this method is also available on the response object from [`.load`](#policyloadroot-options), so can be called as `res.filter()` (where `res` is the loaded config).\n\n\nReturns an `object` in the same structure as `vulns`.\n\n### policy.getByVuln(config, vuln)\n\nReturns any matching rule given a specific vulnerability object. The `vuln` object must contain `id` and `from` to match correctly.\n\nReturns an `object` structured as:\n\n```js\n{\n  type: String, // ignore | patch\n  id: String, // vuln.id\n  rule: Array, // array of package@version\n  reason: String, // included in ignore rules\n  expires: String, // JSON time included in ignore rules\n}\n```\n\n#### `config`: Object\n\nThe loaded policy object (from `.load`).\n\n#### `vuln`: Object\n\nSingle vulnerability object.\n\n## Sample policies\n\nNote that `<path to package>` below is the dependency chain of package names and valid versions separated by a `>` symbol.\n\nBy default, the policy file does not add versions to these packages, so a path would look like: `'jade > transformers > uglify-js'`, but it can include versions. More details and examples can be seen in the [module path rules](#module-path-rules) section.\n\n### Ignore\n\n```text\nignore:\n  '<snyk-vuln-id>':\n    - '<path to package>':\n        reason: String\n        expires: String(format: Date().toJSON())\npatch: {}\nversion: v1.0.0\n```\n\n### Patch\n\n```text\npatch:\n  '<snyk-vuln-id>':\n    - '<path to package>':\n        patched: String(format: Date().toJSON())\nversion: v1\n```\n\n\n## Misc\n\n* [CONTRIBUTING.md](.github/CONTRIBUTING.md)\n* [License: Apache License, Version 2.0](LICENSE)\n",
  "readmeFilename": "README.md",
  "repository": {
    "type": "git",
    "url": "git+https://github.com/Snyk/policy.git"
  },
  "scripts": {
    "check-tests": "! grep 'test.only' test/**/*.test.js -n",
    "cover": "tap test/**/*.test.js --cov --coverage-report=lcov",
    "env": "node -e 'console.log(process.env, process.versions)'",
    "lint": "jscs lib/**/*.js -v",
    "semantic-release": "semantic-release pre && npm publish && semantic-release post",
    "tap": "tap test/**/*.test.js --cov --timeout=60",
    "test": "npm run check-tests && npm run lint && npm run tap"
  },
  "version": "1.7.1"
}
