url-safety-scanner v1.0.4

Url Safety Scanner

Small Node.js utility to check for the safety of URLs.

Installation

npm install url-safety-scanner

or

yarn add url-safety-scanner

Usage

This library is based on Google Safe Browsing, so it requires a free Google API Key, get one here.

Import the library and initialize the Scanner object:

import Scanner from "url-safety-scanner";

// With updated threat list 
const myScanner = await Scanner({
		apiKey:  #GOOGLE_API_KEY (required),
		clientId:  #UNIQUE_IDENTIFIER (required),
		clientVersion: #CLIENT_VERSION (optional)
	}, true)

// With default threat list
const myScanner = Scanner({
	apiKey:  #GOOGLE_API_KEY (required),
	clientId:  #UNIQUE_IDENTIFIER (required),
	clientVersion: #CLIENT_VERSION (optional)
})

API

• Scanner

Scanner(config: Object, updateThreatInfo:boolean = false) => ScannerConstructor || Promise(ScannerConstructor)

Constructor for the Scanner object. If updateThreatInfo is true, returns a Promise.

Parameters

config Configuration object.

const config = {
	apiKey:  #GOOGLE_API_KEY (required),
	clientId:  #UNIQUE_IDENTIFIER (required),
	clientVersion: #CLIENT_VERSION (optional)
}

updateThreatInfo Should the constructor update the threat info list with the latest information? Defaults to false. See Google Safe Browsing Docs for infos about the Threat List.

const config = {
	apiKey:  #GOOGLE_API_KEY (required),
	clientId:  #UNIQUE_IDENTIFIER (required),
	clientVersion: #CLIENT_VERSION (optional)
}

Default Threat List:

The default Threat List includes everything:

THREAT_INFO = {
	threatTypes: [
		"MALWARE",
		"SOCIAL_ENGINEERING",
		"POTENTIALLY_HARMFUL_APPLICATION",
		"UNWANTED_SOFTWARE",
	],
	platformTypes: [
		"LINUX",
		"OSX",
		"IOS",
		"WINDOWS",
		"CHROME",
		"ALL_PLATFORMS",
		"ANY_PLATFORM",
		"ANDROID",
	],
	threatEntryTypes: ["URL"],
};

• isSafe

isSafe(url: String) => Promise<boolean> 

isSafe returns an Promise which resolves to true if the url is safe.

Parameters

url A String of the url to scan.

Returns

Promise<boolean> True if url is safe.

Example:

myScanner.isSafe("github.com")
	.then(safe => console.log(safe));
	// true
	
myScanner.isSafe("badwebsite.com")
	.then(safe => console.log(safe));
	// false

• scan

scan(urls: Array(String)) => Promise<Array> 

scan returns an Promise of urls considered malicious.

Parameters

urls An Array of urls to scan.

Returns

Promise<Array> An Array of urls considered malicious.

Example:

myScanner.scan(["github.com"])
	.then(data => console.log(data));
	// [] 
	
myScanner.scan(["github.com", "badwebsite.com"])
	.then(data => console.log(data));
	// ["badwebsite.com"] 

• getSafeUrls

getSafeUrls(urls: Array<String>) => Promise<Array>

getSafeUrls returns an Promise of urls considered safe.

Parameters

urls An Array of urls to scan.

Returns

Promise<Array> An Array of urls considered safe.

Example:

myScanner.getSafeUrls(["github.com", "badwebsite.com"])
	.then(data => console.log(data));
	// ["github.com"] 

License

MIT License Alessio Franceschi