@passmarked/malware/README.md

Rules that check if the page or linked pages on the same domain (or external) contain any unwanted software,malware or reported phishing attacks

# @passmarked/malware 

![NPM](https://img.shields.io/npm/dt/@passmarked/malware.svg) [![Build Status](https://travis-ci.org/passmarked/malware.svg)](https://travis-ci.org/passmarked/malware)

[Passmarked](http://passmarked.com?source=github&report=malware) is a suite of tests that can be run against any page/website to identify issues with parity to most online tools in one package.

The [Terminal Client](http://npmjs.org/package/passmarked) is intended for use by developers to integrate into their workflow/CI servers but also integrate into their own application that might need to test websites and provide realtime feedback.

All of the checks on [Passmarked](http://passmarked.com?source=github&report=malware) can be voted on importance and are [open-sourced](http://github.com/passmarked/suite), to encourage community involvement in fixing and adding new rules. We are building the living Web Standard and love any [contributions](#contributing).

## Synopsis

The module checks various services to see if a link has been tag as either `phishing`, `malware` or hosting `unwanted software`. All the links found from the internal site, along with links to external sites, are checked

This is done by checking a few services online by either a API call or through a primed cache. The services checked are:

* [Safe Browsing](https://developers.google.com/safe-browsing/) by [Google](https://google.com)
* [Phishtank](https://www.phishtank.com/)

If the module is run without prepping it will never identify any broken rules. Services not configured will not crash or cause a error to allow users to pick services they want to enable. 

Following the sections to prep your environment so these checks can be run. 

After prep the following rules will be produced if any issues are detected from enabled/configured services:

* **page.unwanted** - The page itself was tagged as hosting **Unwanted Software**
* **page.malware** - The page itself was tagged as hosting **Malware**
* **page.phishing** - The page itself was tagged as a **Phishing attack** 
* **link.internal.unwanted** - Link on the page heading to the same origin was tagged as hosting **Unwanted Software**.
* **link.internal.malware** - Link on the page heading to the same origin was tagged as hosting **Malware**.
* **link.internal.phishing** - Link on the page heading to the same origin was tagged as a **Phishing attack**.
* **link.external.unwanted** - External url linked by page was tagged as hosting **Unwanted Software**
* **link.external.malware** - External url linked by page was tagged as hosting **Malware**
* **link.external.phishing** - External url linked by page was tagged as a **Phishing Attack**.

#
## General

To protect again abuse there is a default upper limit of 50 per page. When running locally this limit can be upped to any number using the environment variable:

```bash
PASSMARKED_MALWARE_LINK_LIMIT=1000
```

### Safe Browsing

The [Safe Browsing API](https://developers.google.com/safe-browsing/) from [Google](https://google.com) also requires API keys. Head over to the console and generate a API key, once done the keys can be configured:

```bash
SAFEBROWSING_API_KEY=<API for Safe Browsing API>
SAFEBROWSING_CLIENT=<Client string for Safe Browsing API>
```

> Note on a live service like [passmarked.com](https://passmarked.com?source=github&repo=malware) it is best to override the cache from the payload and handle actual caching with services like [Redis](http://redis.io) to reduce the amount of lookups against the API. The module is configured to save results with the following key structure in cache: **passmarked:safebrowsing:<sha256-of-url>** containing a comma-delimated list of either `malware`, `unwanted` or `phishing`.

### Phishtank

The module requires a primed cache of sites from [Phishtank](https://www.phishtank.com/) to report back on those. The module itself does not call Pishtank opting instead into simply reading from a service like [Redis](http://redis.io).

The module expects to find keys from the cache in the following format:

```bash
passmarked:phishtank:<sha256-of-url>
```

each of these keys would contain a comma delimited list specifying the type of issues on the link, namely `unwanted`, `malware` or `unwanted`.

To prime the cache, head over to [www.phishtank.com/developer_info.php](https://www.phishtank.com/developer_info.php) where the entire database of [Phishtank](https://www.phishtank.com/) can be downloaded, parsed and loaded into the cache of choice.

> The online service at [passmarked.com](https://passmarked.com?source=github&repo=malware) parses and loads the database in once a day to keep it fresh as new threats present themselves.

## Running

The rules are checked everytime a url is run through Passmarked or our API. To run using the hosted system head to [passmarked.com](http://passmarked.com?source=github&report=malware) or our [Terminal Client](http://npmjs.org/package/passmarked) use:

```bash
npm install -g passmarked
passmarked --filter=malware example.com
```

The hosted version allows free runs from our homepage and the option to register a site to check in its entirety.
Using the Passmarked npm module (or directly via the API) integrations are also possible to get running reports with all the rules in a matter of seconds.

## Running Locally

All rules can be run locally using our main integration library. This requires installing the package and any dependencies that the code might have such as a specific version of Openmalware, see [#dependencies](#dependencies)

First ensure `passmarked` is installed:

```bash
npm install passmarked
npm install @passmarked/malware
```

After which the rules will be runnable using promises:

```javascript
passmarked.createRunner(
  require('@passmarked/malware'), // this package
  require('@passmarked/malware') // to test malware
).run({
  url: 'http://example.com',
  body: 'body of page here',
  har: {log: {entries: []}}
}).then(function(payload) {
  if (payload.hasRule('secure')) {
    console.log('better check that ...');
  }
  var rules = payload.getRules();
  for (var rule in rules) {
    console.log('*', rules[rule].getMessage());
  }
}).catch(console.error.bind(console));
```

Alternatively, callbacks are also available:

```javascript
passmarked.createRunner(
  require('@passmarked/malware'),
  require('@passmarked/malware'),
  require('@passmarked/inspect')
).run({
  url: 'http://example.com',
  body: 'body of page here',
  har: {log: {entries: []}}
}, function(err, payload) {
  if (payload.hasRule('secure')) {
    console.log("better check that ...");
  }
  var rules = payload.getRules();
  for (var rule in rules) {
    console.log('*', rules[rule].getMessage());
  }
});
```

## Dependencies

The module does not require any dependencies to run but does require some work to prepare the environment before starting to provide actual results.

## Rules

Rules represent checks that occur in this module, all of these rules have a **UID** which can be used to check for specific rules. For the structure and more details see the [Wiki](https://github.com/passmarked/passmarked/wiki) page on [Rules](https://github.com/passmarked/passmarked/wiki/Create).

> Rules also include a `type` which could be `critical`, `error`, `warning` or `notice` giving a better view on the importance of the rule.

## Contributing

```bash
git clone git@github.com:passmarked/malware.git
npm install
npm test
```

Pull requests have a prerequisite of passing tests. If your contribution is accepted, it will be merged into `develop` (and then `master` after staging tests by the team) which will then be deployed live to [passmarked.com](http://passmarked.com?source=github&report=malware) and on NPM for everyone to download and test.

## About

To learn more visit:

* [Passmarked](http://passmarked.com)
* [Terminal Client](https://www.npmjs.com/package/passmarked)
* [NPM Package](https://www.npmjs.com/package/@passmarked/malware)
* [Slack](http://passmarked.com/chat?source=github&repo=malware) - We have a Slack team with all our team and open to anyone using the site to chat and figure out problems. To join head over to [passmarked.com/chat](http://passmarked.com/chat?source=github&repo=malware) and request a invite.

## License

Copyright 2016 Passmarked Inc

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.