Skip to content

CryptoWeb/node-nimbusec

Repository files navigation

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

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