The Security Insights feature is deprecated and will no longer be supported. Please migrate to new SDK https://github.com/IBM/scc-node-sdk
Node JS client library to use the IBM Cloud Security Advisor APIs. (OpenAPI compatible)
Table of Contents
The IBM Cloud Security Advisor Node SDK allows developers to programmatically interact with the IBM Cloud Security Advisor Service.
-
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.
npm install ibm-security-advisorIBM 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.
import { IamAuthenticator } from 'ibm-security-advisor/auth';
const authenticator = new IamAuthenticator({
apikey: '{apikey}',
});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.
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.
You can set or reset the base URL after constructing the client instance using the setServiceUrl method:
Currently there are two supported endpoints:
- 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 - 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');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.
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
});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.
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,
});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,
}),
});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:
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
});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
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);
});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);
});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.
This module uses the debug package for logging. Specify the desired environment variable to enable logging debug messages.
Running all the tests:
npm testRunning a specific test:
npm run jest -- '<path to test>'Find more open source projects on the IBM Github Page.
See CONTRIBUTING.
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.
This library is licensed under Apache 2.0. Full license text is available in LICENSE.