README.md

Nimbusec client API library for Node.js

Installation

$ npm install nimbusec

## Usage Example

var nimbusecAPI = require('nimbusec');

var api = new nimbusecAPI('NIMBUSEC-KEY', 'NIMBUSEC-SECRET');
api.findDomains(null, function(err, domains) {

    if (err) {
        console.log('An error occured : ');
        console.log(' - code : '+ err.statusCode);
        console.log(' - message : '+ err.message);
        process.exit(1);
    }

    console.log('My domains are :');
    for (var i = 0; i < domains.length; i++) {
        console.log('  - ' + domains[i].name);
    }
});

Commands

Generate HTML documentation

$ grunt doc

Generate README.md file

$ grunt shell:generateReadme

Check the coding style

$ grunt eslint

To Do

• Implement /v2/user/* part of the API
• Implement /v2/domain//screenshot/* part of the API when available

API Reference

NimbusecAPI

Kind: global class
Access: public

• NimbusecAPI
  • new NimbusecAPI(key, secret, [options])
  • instance
    • .findBundles(filter, callback)
    • .findDomains(filter, callback)
    • .createDomain(domain, callback)
    • .updateDomain(domain, domainID, callback)
    • .deleteDomain(domainID, callback)
    • .findAgentToken(filter, callback)
    • .createAgentToken(agentToken, callback)
    • .deleteAgentToken(agentToken, callback)
    • .findInfectedDomains(filter, callback)
    • .findDomainResults(domainID, filter, callback)
    • .updateDomainResult(domainID, resultID, result, callback)
    • .getDomainMetadata(domainID, callback)
    • ._parseResponse(err, data, response, callback) ℗
    • ._get(uri, filter, callback) ℗
    • ._delete(uri, callback) ℗
    • ._post(uri, obj, callback) ℗
    • ._put(uri, obj, callback) ℗
  • inner
    • ~findBundlesCallback : function
    • ~findDomainsCallback : function
    • ~createDomainCallback : function
    • ~updateDomainCallback : function
    • ~deleteDomainCallback : function
    • ~findAgentTokenCallback : function
    • ~createAgentTokenCallback : function
    • ~deleteAgentTokenCallback : function
    • ~findInfectedDomainsCallback : function
    • ~findDomainResultsCallback : function
    • ~updateDomainResultCallback : function
    • ~getDomainMetadataCallback : function
    • ~Domain : object
    • ~DomainMetadata : object
    • ~Result : object
    • ~Package : object
    • ~Agent : object
    • ~AgentToken : object
    • ~User : object
    • ~Notification : object
    • ~CMS : object
    • ~Error : object

new NimbusecAPI(key, secret, [options])

Construct a new NimbusecAPI object.

Param	Type	Description
key	string	nimbusec API key
secret	string	nimbusec API secret
[options]	Object
options.baseURL	string	Nimbusec base URL

nimbusecAPI.findBundles(filter, callback)

Read all existing bundles depending on an optional filter.

Kind: instance method of NimbusecAPI
Access: public

Param	Type	Description
filter	string	optional filter
callback	findBundlesCallback

nimbusecAPI.findDomains(filter, callback)

Read all existing domains depending on an optional filter.

Kind: instance method of NimbusecAPI
Access: public

Param	Type	Description
filter	string	optional filter
callback	findDomainsCallback

nimbusecAPI.createDomain(domain, callback)

Create a domain from the given object.

Kind: instance method of NimbusecAPI
Access: public

Param	Type	Description
domain	Domain	domain to be created. id will be ignored.
callback	createDomainCallback

nimbusecAPI.updateDomain(domain, domainID, callback)

Update an existing domain by the given object. To modify only certain fields of the domain you can include just these fields inside of the domain object you pass. The destination path for the request is determined by the ID.

Kind: instance method of NimbusecAPI
Access: public

Param	Type	Description
domain	Domain	the domain object with the fields to be updated
domainID	integer	the domain's assigned ID (must be valid)
callback	updateDomainCallback

nimbusecAPI.deleteDomain(domainID, callback)

Delete a specific domain. The destination path for the request is determined by the ID.

Kind: instance method of NimbusecAPI
Access: public

Param	Type	Description
domainID	integer	the domain's assigned ID (must be valid)
callback	deleteDomainCallback

nimbusecAPI.findAgentToken(filter, callback)

Read all existing tokens depending on an optional filter.

Kind: instance method of NimbusecAPI
Access: public

Param	Type	Description
filter	string	optional filter
callback	findAgentTokenCallback

nimbusecAPI.createAgentToken(agentToken, callback)

Create an server agent token from the given object. In the following step this token can be used to run the server agent.

Kind: instance method of NimbusecAPI
Access: public

Param	Type	Description
agentToken	AgentToken	token to be created
callback	createAgentTokenCallback

nimbusecAPI.deleteAgentToken(agentToken, callback)

Delete a specific agent token. The destination path for the request is determined by the ID.

Kind: instance method of NimbusecAPI
Access: public

Param	Type	Description
agentToken	AgentToken	token to be created
callback	createAgentTokenCallback

nimbusecAPI.findInfectedDomains(filter, callback)

Read list of infected domains depending on an optional filter.

Kind: instance method of NimbusecAPI
Access: public

Param	Type	Description
filter	string	optional filter
callback	findInfectedDomainsCallback

nimbusecAPI.findDomainResults(domainID, filter, callback)

Read list of results of a domain depending on an optional filter.

Kind: instance method of NimbusecAPI
Access: public

Param	Type	Description
domainID	integer
filter	string	optional filter
callback	findDomainResultsCallback

nimbusecAPI.updateDomainResult(domainID, resultID, result, callback)

Update an existing DomainResult by the given object. Only status can be modified to acknowledge a specific result. The destination path for the request is determined by the ID.

Kind: instance method of NimbusecAPI
Access: public

Param	Type	Description
domainID	integer
resultID	integer	the result assigned ID (must be valid)
result	Result	the result object. Only the status field will be modified.
callback	updateDomainResultCallback

nimbusecAPI.getDomainMetadata(domainID, callback)

Retrieve domain metadata. The destination path for the request is determined by the ID.

Kind: instance method of NimbusecAPI
Access: public

Param	Type
domainID	integer
callback	getDomainMetadataCallback

nimbusecAPI._parseResponse(err, data, response, callback) ℗

Parse the HTTP response. Will get the error message in x-nimbusec-error header if present. Will parse JSON into JavaScript Object if present.

Kind: instance method of NimbusecAPI
Access: private

Param	Type	Description
err	Object	oauth requester error object
data	string	body of the HTTP response
response	Object	oauth requester response object
callback	NimbusecAPI~apiCallCallback	callback called at end of parsing

nimbusecAPI._get(uri, filter, callback) ℗

Execute a HTTP GET request on the API server.

Kind: instance method of NimbusecAPI
Access: private

Param	Type	Description
uri	string	URI of the resource
filter	string	optional filter
callback	string	callback function

nimbusecAPI._delete(uri, callback) ℗

Execute a HTTP DELETE request on the API server.

Kind: instance method of NimbusecAPI
Access: private

Param	Type	Description
uri	string	URI of the resource
callback	string	callback function

nimbusecAPI._post(uri, obj, callback) ℗

Execute a HTTP POST request on the API server.

Kind: instance method of NimbusecAPI
Access: private

Param	Type	Description
uri	string	URI of the resource
obj	Object	Object to be posted
callback	string	callback function

nimbusecAPI._put(uri, obj, callback) ℗

Execute a HTTP PUT request on the API server.

Kind: instance method of NimbusecAPI
Access: private

Param	Type	Description
uri	string	URI of the resource
obj	Object	Object to be put
callback	string	callback function

NimbusecAPI~findBundlesCallback : function

Kind: inner typedef of NimbusecAPI

Param	Type	Description
error	Error
packages	Array.<Package>	array of selected packages objects

NimbusecAPI~findDomainsCallback : function

Kind: inner typedef of NimbusecAPI

Param	Type	Description
error	Error
domains	Array.<Domain>	array of selected domain objects

NimbusecAPI~createDomainCallback : function

Kind: inner typedef of NimbusecAPI

Param	Type	Description
error	Error
domain	Domain	the created domain object

NimbusecAPI~updateDomainCallback : function

Kind: inner typedef of NimbusecAPI

Param	Type	Description
error	Error
domain	Domain	the created domain object

NimbusecAPI~deleteDomainCallback : function

Kind: inner typedef of NimbusecAPI

Param	Type
error	Error

NimbusecAPI~findAgentTokenCallback : function

Kind: inner typedef of NimbusecAPI

Param	Type	Description
error	Error
agentToken	AgentToken	array of selected agent token objects

NimbusecAPI~createAgentTokenCallback : function

Kind: inner typedef of NimbusecAPI

Param	Type	Description
error	Error
agentToken	AgentToken	the created agent token object

NimbusecAPI~deleteAgentTokenCallback : function

Kind: inner typedef of NimbusecAPI

Param	Type
error	Error

NimbusecAPI~findInfectedDomainsCallback : function

Kind: inner typedef of NimbusecAPI

Param	Type	Description
error	Error
domains	Array.<Domain>	array of selected domains

NimbusecAPI~findDomainResultsCallback : function

Kind: inner typedef of NimbusecAPI

Param	Type	Description
error	Error
results	Array.<Result>	array of selected results

NimbusecAPI~updateDomainResultCallback : function

Kind: inner typedef of NimbusecAPI

Param	Type	Description
error	Error
domain	Domain	the domain object

NimbusecAPI~getDomainMetadataCallback : function

Kind: inner typedef of NimbusecAPI

Param	Type	Description
error	Error
domainMetadata	DomainMetadata	the metadata object

NimbusecAPI~Domain : object

Kind: inner typedef of NimbusecAPI
Properties

Name	Type	Description
id	integer	unique identification of domain
bundle	string	id of assigned package
scheme	string	whether the domain uses http or https
name	string	name of domain (usually DNS name)
deepScan	string	starting point for the domain deep scan
fastScans	Array.<string>	landing pages of the domain scanned

NimbusecAPI~DomainMetadata : object

Kind: inner typedef of NimbusecAPI
Properties

Name	Type	Description
lastDeepScan	date	timestamp (in ms) of last external scan of the whole site
nextDeepScan	date	timestamp (in ms) for next external scan of the whole site
lastFastScan	date	timestamp (in ms) of last external scan of the landing pages
nextFastScan	date	timestamp (in ms) for next external scan of the landing pages
agent	date	last date server agent sent results to the domain
cms	string	detected CMS vendor and version
httpd	string	detected HTTP server vendor and version
php	string	detected PHP version
files	integer	number of downloaded files/URLs for last deep scan
size	integer	size of downloaded files for last deep scan (in byte)

NimbusecAPI~Result : object

Kind: inner typedef of NimbusecAPI
Properties

Name	Type	Description
id	integer	unique identification of a result
status	string	status of the result (1 = pending, 2 = acknowledged, 3 = falsepositive, 4 = removed)
event	string	event type of result, possible values are : webshell malware renamed-executable defacement cms-version cms-vulnerable blacklist blacklist-ref changed-file changed-template ssl-expires ssl-expired ssl-ciphersuite ssl-notrust ssl-protocol
category	string	category of result, possible values are : applications blacklist webshell text blacklist-ref configuration
severity	integer	severity level of result (1 = medium to 3 = severe)
probability	float	probability the result is critical
safeToDelete	boolean	flag indicating if the file can be safely deleted without loosing user data
createDate	date	timestamp (in ms) of the first occurrence
lastDate	date	timestamp (in ms) of the last occurrence the following fields contain more details about the result. Not all fields must be filled or present.
threatname	string	name identifying the threat of a result. meaning differs per category : malware & webshell: the virus database name of the malicious software blacklist: the name of the blacklist containing the domain Blacklist names are : Google Safe Browsing Web of Trust Malc0de Malware Domain List Phishtank Zeus Tracker
resource	string	affected resource (e.g. file path or URL)
md5	string	MD5 hash sum of the affected file
filesize	integer	filesize of the affected file
owner	string	file owner of the affected file
group	string	file group of the affected file
permission	integer	permission of the affected file as decimal integer
diff	string	diff of a content change between two scans
reason	string	reason why a domain/URL is blacklisted

NimbusecAPI~Package : object

Kind: inner typedef of NimbusecAPI
Properties

Name	Type	Description
id	string	unique identification of a bundle
name	string	given name for a bundle
startDate	date	timestamp in milliseconds when bundle was added / set active
endDatet	date	timestamp in milliseconds when bundle will expire
quota	string	maximum size of files that will be downloaded per scan
depth	integer	maximum link depth that will be followed (-1 means no limit)
fast	integer	interval of fast scans in minutes (-1 means disabled)
deep	integer	interval of deep scans in minutes (-1 means disabled)
contingent	integer	maximum number of domains that can be assigned
active	integer	number of currently assigned domain
engines	Array.<string>	list of used anti-virus engines

NimbusecAPI~Agent : object

Kind: inner typedef of NimbusecAPI
Properties

Name	Type	Description
os	string	operating system of agent (windows, macosx, linux)
arch	string	cpu architecture of agent (32bit, 64bit)
version	int	version of agent
md5	string	MD5 hash of download file
sha1	string	SHA1 hash of download file
format	string	format of downloaded file (zip)
url	string	URL were agent can be downloaded from

NimbusecAPI~AgentToken : object

Kind: inner typedef of NimbusecAPI
Properties

Name	Type	Description
id	integer	unique identification of a token
name	string	given name for a token
key	string	oauth key
secret	string	oauth secret
lastCall	date	last timestamp (in ms) an agent used the token
version	integer	last agent version that was seen for this key

NimbusecAPI~User : object

Kind: inner typedef of NimbusecAPI
Properties

Name	Type	Description
id	integer	unique identification of a user
login	string	login name of user
mail	string	e-mail contact where mail notificatins are sent to
role	string	role of an user (administrator or user)
company	string	company name of user
surname	string	surname of user
forename	string	surname of user
title	string	academic title of user
mobile	string	phone contact where sms notificatins are sent to
password	string	password of user (only used when creating or updating a user)
signatureKey	string	secret for SSO (only used when creating or updating a user)

NimbusecAPI~Notification : object

Kind: inner typedef of NimbusecAPI
Properties

Name	Type	Description
id	integer	unique identification of a notification
domain	integer	id of a domain
transport	string	type of contact (mail, sms)
serverside	integer	level for server side notifications (see result severity, >3 = disabled)
content	integer	level for content notifications (see result severity, >3 = disabled)
blacklist	integer	level for blacklist notifications (see result severity, >3 = disabled)

NimbusecAPI~CMS : object

Kind: inner typedef of NimbusecAPI
Properties

Name	Type
CpeId	string
LatestStable	string
Path	string

NimbusecAPI~Error : object

Error object passed in first argument of callbacks.

Kind: inner typedef of NimbusecAPI
Properties

Name	Type	Description
statusCode	integer	HTTP reponse status code
message	string	Error message (from X-Nimbusec-Error header)
data	object	HTTP error details
data.timestamp	integer	HTTP response date
data.status	string	HTTP reponse status code
data.error	string	short error message
data.message	string	detailed error message
data.path	string	path of the request