ibm-security-advisor

IBM Cloud Security Advisor Node.js SDK

Node JS client library to use the IBM Cloud Security Advisor APIs. (OpenAPI compatible)

Table of Contents

• IBM Cloud Security Advisor Node.js SDK
  • Overview
  • Prerequisites
  • Installation
  • Authentication
    • Examples
      • Programmatic credentials
      • External configuration
  • Using the SDK
    • Basic Usage
    • Setting the Service URL
    • Sending request headers
      • Default headers
  • Configuring the HTTPS Agent
    • Use behind a corporate proxy
    • Sending custom certificates
    • Disabling SSL Verification - Discouraged
      • Findings Api
  • Documentation
  • IBM Security Advisor Services
    • Findings
    • Notifications
  • Questions
  • Debug
  • Tests
  • Open source @ IBM
  • Contributing
  • Featured Projects
  • License

Overview

The IBM Cloud Security Advisor Node SDK allows developers to programmatically interact with the IBM Cloud Security Advisor Service.

Prerequisites

• You need an IBM Cloud account.

• Node >=10: This SDK is tested with Node versions 10 and up. It may work on previous versions but this is not officially supported.

Installation

npm install ibm-security-advisor

Authentication

IBM Cloud Security Advisor service uses token-based Identity and Access Management (IAM) authentication.

IAM authentication uses a service API key to get an access token that is passed with the call. Access tokens are valid for a limited amount of time and must be regenerated.

Authentication is accomplished using dedicated Authenticators for each authentication scheme. Import authenticators from ibm-security-advisor/auth.

Examples

Programmatic credentials

import { IamAuthenticator } from 'ibm-security-advisor/auth';

const authenticator = new IamAuthenticator({
  apikey: '{apikey}',
});

External configuration

import { getAuthenticatorFromEnvironment } from 'ibm-security-advisor/auth';

// env vars
// FINDINGS_API_AUTH_TYPE=iam
// FINDINGS_API_APIKEY=<apikey>
const iamAuthenticator = getAuthenticatorFromEnvironment('findings-api');

To learn more about the Authenticators and how to use them with your services, see the detailed documentation.

Using the SDK

Basic Usage

All SDK methods return a Promise that either resolves with the response from the service or rejects with an Error. The response contains the body, the headers, the status code, and the status text.

const FindingsAPI =  require('ibm-security-advisor/findings-api/v1');
const { IamAuthenticator } = require('ibm-security-advisor/auth');

const findingsAPIClient = new FindingsAPI({
  authenticator: new IamAuthenticator({ apikey: '{apikey}' }),
  serviceUrl: 'https://us-south.secadvisor.cloud.ibm.com/findings',
});

findingsAPIClient
  .listNotes({accountId: "accountId", providerId: "providerId"})
  .then(
    response => {
      // handle response
      // the body is under property `result`
      console.log(JSON.stringify(response.result, null, 2));

      // access the headers
      console.log(JSON.stringify(response.headers, null, 2));

      // access the status code
      console.log(response.status);

      // access the status text
      console.log(response.statusText);
    },
    err => {
      // handle request/SDK errors
      console.log(err);
    }
  )
  .catch(err => {
    // catch errors in response handling code
    console.log(err);
  });

The examples folder has basic and advanced examples for all the services.

Setting the Service URL

You can set or reset the base URL after constructing the client instance using the setServiceUrl method: Currently there are two supported endpoints:

1. findings:
   https://eu-gb.secadvisor.cloud.ibm.com/findings
   https://us-south.secadvisor.cloud.ibm.com/findings https://eu.compliance.cloud.ibm.com/si/findings
2. notifications:
   https://eu-gb.secadvisor.cloud.ibm.com/notifications
   https://us-south.secadvisor.cloud.ibm.com/notifications https://eu.compliance.cloud.ibm.com/si/notifications

const NotificationsApi =  require('ibm-security-advisor/notifications-api/v1');
const { IamAuthenticator } = require('ibm-security-advisor/auth');

const notificationsAPIClient = new NotificationsApi({
  authenticator: new IamAuthenticator({ apikey: '{apikey}' }),
});

notificationsAPIClient.setServiceUrl('https://eu-gb.secadvisor.cloud.ibm.com/notifications');

Sending request headers

Custom headers can be passed with any request. There are two ways of setting them - setting default headers in the constructor or passing request-specific headers directly to one of the methods.

Default headers

Any headers passed in with the service client constructor will be stored and automatically added to every request made with said client.

const FindingsAPI =  require('ibm-security-advisor/findings-api/v1');
const { IamAuthenticator } = require('ibm-security-advisor/auth');

const findingsAPIClient = new FindingsAPI({
  authenticator: new IamAuthenticator({ apikey: '{apikey}' }),
  headers: {
    'X-Custom-Header': 'some value',
  },
});

findingsAPIClient.listNotes({accountId: "accountId", providerId: "providerId"}).then(res => {
  // X-Custom-Header will have been sent with the request
});

Configuring the HTTPS Agent

The SDK provides the user with full control over the HTTPS Agent used to make requests. This is available for both the service client and the authenticators that make network requests (e.g. IamAuthenticator). Outlined below are a couple of different scenarios where this capability is needed. Note that this functionality is for Node environments only - these configurtions will have no effect in the browser.

Use behind a corporate proxy

To use the SDK (which makes HTTPS requests) behind an HTTP proxy, a special tunneling agent must be used. Use the package tunnel for this. Configure this agent with your proxy information, and pass it in as the HTTPS agent in the service constructor. Additionally, you must set proxy to false in the client constructor. See this example configuration:

const tunnel = require('tunnel');
const FindingsAPI =  require('ibm-security-advisor/findings-api/v1');
const { IamAuthenticator } = require('ibm-security-advisor/auth');

const findingsAPIClient = new FindingsAPI({
  authenticator: new IamAuthenticator({ apikey: '{apikey}' }),
  httpsAgent: tunnel.httpsOverHttp({
    proxy: {
      host: 'some.host.org',
      port: 1234,
    },
  }),
  proxy: false,
});

Sending custom certificates

To send custom certificates as a security measure in your request, use the cert, key, and/or ca properties of the HTTPS Agent. See this documentation for more information about the options. Note that the entire contents of the file must be provided - not just the file name.

const tunnel = require('tunnel');
const NotificationsAPI =  require('ibm-security-advisor/notifications-api/v1');
const { IamAuthenticator } = require('ibm-security-advisor/auth');

const certFile = fs.readFileSync('./my-cert.pem');
const keyFile = fs.readFileSync('./my-key.pem');

const notificationsAPIClient = new NotificationsAPI({
  authenticator: new IamAuthenticator({
    apikey: '{apikey}',
    httpsAgent: new https.Agent({
      key: keyFile,
      cert: certFile,
    })
  }),
  httpsAgent: new https.Agent({
    key: keyFile,
    cert: certFile,
  }),
});

Disabling SSL Verification - Discouraged

The HTTP client can be configured to disable SSL verification. Note that this has serious security implications - only do this if you really mean to! ⚠️

To do this, set disableSslVerification to true in the service constructor and/or authenticator constructor, like below:

Findings Api

const FindingsAPI =  require('ibm-security-advisor/findings-api/v1');
const { IamAuthenticator } = require('ibm-security-advisor/auth');

const findingsAPIClient = new FindingsAPI({
  authenticator: new IamAuthenticator({ apikey: '<apikey>', disableSslVerification: true }), // this will disable SSL verification for requests to the token endpoint
  disableSslVerification: true, // this will disable SSL verification for any request made with this client instance
});

Documentation

You can find links to the documentation at https://cloud.ibm.com/docs/security-advisor. Click API reference.

There are also auto-generated JSDocs available at http://ibm-cloud-security.github.io/security-advisor-sdk-node

IBM Security Advisor Services

Findings

Use the IBM Cloud™ Security Advisor Findings API to post metadata and findings.

For more details checkout the api docs here.

const FindingsAPI =  require('ibm-security-advisor/findings-api/v1');
const { IamAuthenticator } = require('ibm-security-advisor/auth');

const findingsAPIClient = new FindingsAPI({
  authenticator: new IamAuthenticator({ apikey: '{apikey}' }),
  serviceUrl: 'https://us-south.secadvisor.cloud.ibm.com/findings',
});

findingsAPIClient
  .listNotes({accountId: "accountId", providerId: "providerId"})
  .then(
    response => {
      // handle response
      // the body is under property `result`
      console.log(JSON.stringify(response.result, null, 2));

      // access the headers
      console.log(JSON.stringify(response.headers, null, 2));

      // access the status code
      console.log(response.status);

      // access the status text
      console.log(response.statusText);
    },
    err => {
      // handle request/SDK errors
      console.log(err);
    }
  )
  .catch(err => {
    // catch errors in response handling code
    console.log(err);
  });

Notifications

Use the IBM Cloud™ Security Advisor Notifications API to get alerted to any reported vulnerabilities as soon as the report is available.

For more details, checkout the api docs here.

const NotificationsAPI =  require('ibm-security-advisor/notifications-api/v1');
const { IamAuthenticator } = require('ibm-security-advisor/auth');

const notificationsAPIClient = new NotificationsAPI({
  authenticator: new IamAuthenticator({ apikey: '{apikey}' }),
  serviceUrl: 'https://us-south.secadvisor.cloud.ibm.com/findings',
});

notificationsAPIClient
  .listChannels({accountId: "accountId"})
  .then(
    response => {
      // handle response
      // the body is under property `result`
      console.log(JSON.stringify(response.result, null, 2));

      // access the headers
      console.log(JSON.stringify(response.headers, null, 2));

      // access the status code
      console.log(response.status);

      // access the status text
      console.log(response.statusText);
    },
    err => {
      // handle request/SDK errors
      console.log(err);
    }
  )
  .catch(err => {
    // catch errors in response handling code
    console.log(err);
  });

Questions

If you are having difficulties using the APIs or have a question about the IBM Cloud Security Advisor offering, please ask a question at dW Answers or Stack Overflow.

Debug

This module uses the debug package for logging. Specify the desired environment variable to enable logging debug messages.

Tests

Running all the tests:

npm test

Running a specific test:

npm run jest -- '<path to test>'

Open source @ IBM

Find more open source projects on the IBM Github Page.

Contributing

See CONTRIBUTING.

Featured Projects

We love to highlight cool open-source projects that use this SDK! If you'd like to get your project added to the list, feel free to make an issue linking us to it.

License

This library is licensed under Apache 2.0. Full license text is available in LICENSE.