ibm-security-advisor/notifications-api/v1.d.ts

Client library to use the IBM Security Advisor

/**
 * (C) Copyright IBM Corp. 2021.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/// <reference types="node" />
import { IncomingHttpHeaders, OutgoingHttpHeaders } from 'http';
import { BaseService, UserOptions } from 'ibm-cloud-sdk-core';
/**
 * notifications-api
 */
declare class NotificationsApiV1 extends BaseService {
    static DEFAULT_SERVICE_URL: string;
    static DEFAULT_SERVICE_NAME: string;
    /*************************
     * Factory method
     ************************/
    /**
     * Constructs an instance of NotificationsApiV1 with passed in options and external configuration.
     *
     * @param {UserOptions} [options] - The parameters to send to the service.
     * @param {string} [options.serviceName] - The name of the service to configure
     * @param {Authenticator} [options.authenticator] - The Authenticator object used to authenticate requests to the service
     * @param {string} [options.serviceUrl] - The URL for the service
     * @returns {NotificationsApiV1}
     */
    static newInstance(options: UserOptions): NotificationsApiV1;
    /**
     * Construct a NotificationsApiV1 object.
     *
     * @param {Object} options - Options for the service.
     * @param {string} [options.serviceUrl] - The base url to use when contacting the service. The base url may differ between IBM Cloud regions.
     * @param {OutgoingHttpHeaders} [options.headers] - Default headers that shall be included with every request to the service.
     * @param {Authenticator} options.authenticator - The Authenticator object used to authenticate requests to the service
     * @constructor
     * @returns {NotificationsApiV1}
     */
    constructor(options: UserOptions);
    /*************************
     * notificationChannel
     ************************/
    /**
     * list all channels.
     *
     * list all channels under this account.
     *
     * @param {Object} params - The parameters to send to the service.
     * @param {string} params.accountId - Account ID.
     * @param {string} [params.transactionId] - The transaction id for the request in uuid v4 format.
     * @param {number} [params.limit] - Limit the number of the returned documents to the specified number.
     * @param {number} [params.skip] - The offset is the index of the item from which you want to start returning data
     * from. Default is 0.
     * @param {OutgoingHttpHeaders} [params.headers] - Custom request headers
     * @returns {Promise<NotificationsApiV1.Response<NotificationsApiV1.ChannelsList>>}
     */
    listAllChannels(params: NotificationsApiV1.ListAllChannelsParams): Promise<NotificationsApiV1.Response<NotificationsApiV1.ChannelsList>>;
    /**
     * create notification channel.
     *
     * create notification channel.
     *
     * @param {Object} params - The parameters to send to the service.
     * @param {string} params.accountId - Account ID.
     * @param {string} params.name -
     * @param {string} params.type - Type of callback URL.
     * @param {string} params.endpoint - The callback URL which receives the notification.
     * @param {string} [params.description] - A one sentence description of this `Channel`.
     * @param {string[]} [params.severity] - Severity of the notification to be received.
     * @param {boolean} [params.enabled] - Channel is enabled or not. Default is disabled.
     * @param {NotificationChannelAlertSourceItem[]} [params.alertSource] -
     * @param {string} [params.transactionId] - The transaction id for the request in uuid v4 format.
     * @param {OutgoingHttpHeaders} [params.headers] - Custom request headers
     * @returns {Promise<NotificationsApiV1.Response<NotificationsApiV1.ChannelInfo>>}
     */
    createNotificationChannel(params: NotificationsApiV1.CreateNotificationChannelParams): Promise<NotificationsApiV1.Response<NotificationsApiV1.ChannelInfo>>;
    /**
     * bulk delete of channels.
     *
     * bulk delete of channels.
     *
     * @param {Object} params - The parameters to send to the service.
     * @param {string} params.accountId - Account ID.
     * @param {string[]} params.requestBody - Body for bulk delete notification channels.
     * @param {string} [params.transactionId] - The transaction id for the request in uuid v4 format.
     * @param {OutgoingHttpHeaders} [params.headers] - Custom request headers
     * @returns {Promise<NotificationsApiV1.Response<NotificationsApiV1.ChannelsDelete>>}
     */
    deleteNotificationChannels(params: NotificationsApiV1.DeleteNotificationChannelsParams): Promise<NotificationsApiV1.Response<NotificationsApiV1.ChannelsDelete>>;
    /**
     * delete the details of a specific channel.
     *
     * delete the details of a specific channel.
     *
     * @param {Object} params - The parameters to send to the service.
     * @param {string} params.accountId - Account ID.
     * @param {string} params.channelId - Channel ID.
     * @param {string} [params.transactionId] - The transaction id for the request in uuid v4 format.
     * @param {OutgoingHttpHeaders} [params.headers] - Custom request headers
     * @returns {Promise<NotificationsApiV1.Response<NotificationsApiV1.ChannelDelete>>}
     */
    deleteNotificationChannel(params: NotificationsApiV1.DeleteNotificationChannelParams): Promise<NotificationsApiV1.Response<NotificationsApiV1.ChannelDelete>>;
    /**
     * get the details of a specific channel.
     *
     * get the details of a specific channel.
     *
     * @param {Object} params - The parameters to send to the service.
     * @param {string} params.accountId - Account ID.
     * @param {string} params.channelId - Channel ID.
     * @param {string} [params.transactionId] - The transaction id for the request in uuid v4 format.
     * @param {OutgoingHttpHeaders} [params.headers] - Custom request headers
     * @returns {Promise<NotificationsApiV1.Response<NotificationsApiV1.ChannelGet>>}
     */
    getNotificationChannel(params: NotificationsApiV1.GetNotificationChannelParams): Promise<NotificationsApiV1.Response<NotificationsApiV1.ChannelGet>>;
    /**
     * update notification channel.
     *
     * update notification channel.
     *
     * @param {Object} params - The parameters to send to the service.
     * @param {string} params.accountId - Account ID.
     * @param {string} params.channelId - Channel ID.
     * @param {string} params.name -
     * @param {string} params.type - Type of callback URL.
     * @param {string} params.endpoint - The callback URL which receives the notification.
     * @param {string} [params.description] - A one sentence description of this `Channel`.
     * @param {string[]} [params.severity] - Severity of the notification to be received.
     * @param {boolean} [params.enabled] - Channel is enabled or not. Default is disabled.
     * @param {NotificationChannelAlertSourceItem[]} [params.alertSource] -
     * @param {string} [params.transactionId] - The transaction id for the request in uuid v4 format.
     * @param {OutgoingHttpHeaders} [params.headers] - Custom request headers
     * @returns {Promise<NotificationsApiV1.Response<NotificationsApiV1.ChannelInfo>>}
     */
    updateNotificationChannel(params: NotificationsApiV1.UpdateNotificationChannelParams): Promise<NotificationsApiV1.Response<NotificationsApiV1.ChannelInfo>>;
    /**
     * test notification channel.
     *
     * test a nofication channel under this account.
     *
     * @param {Object} params - The parameters to send to the service.
     * @param {string} params.accountId - Account ID.
     * @param {string} params.channelId - Channel ID.
     * @param {string} [params.transactionId] - The transaction id for the request in uuid v4 format.
     * @param {OutgoingHttpHeaders} [params.headers] - Custom request headers
     * @returns {Promise<NotificationsApiV1.Response<NotificationsApiV1.TestChannel>>}
     */
    testNotificationChannel(params: NotificationsApiV1.TestNotificationChannelParams): Promise<NotificationsApiV1.Response<NotificationsApiV1.TestChannel>>;
    /**
     * fetch notifications public key.
     *
     * fetch public key to decrypt messages in notification payload.
     *
     * @param {Object} params - The parameters to send to the service.
     * @param {string} params.accountId - Account ID.
     * @param {string} [params.transactionId] - The transaction id for the request in uuid v4 format.
     * @param {OutgoingHttpHeaders} [params.headers] - Custom request headers
     * @returns {Promise<NotificationsApiV1.Response<NotificationsApiV1.PublicKeyGet>>}
     */
    getPublicKey(params: NotificationsApiV1.GetPublicKeyParams): Promise<NotificationsApiV1.Response<NotificationsApiV1.PublicKeyGet>>;
}
/*************************
 * interfaces
 ************************/
declare namespace NotificationsApiV1 {
    /** An operation response. */
    interface Response<T = any> {
        result: T;
        status: number;
        statusText: string;
        headers: IncomingHttpHeaders;
    }
    /** The callback for a service request. */
    type Callback<T> = (error: any, response?: Response<T>) => void;
    /** The body of a service request that returns no response data. */
    interface Empty {
    }
    /** A standard JS object, defined to avoid the limitations of `Object` and `object` */
    interface JsonObject {
        [key: string]: any;
    }
    /*************************
     * request interfaces
     ************************/
    /** Parameters for the `listAllChannels` operation. */
    interface ListAllChannelsParams {
        /** Account ID. */
        accountId: string;
        /** The transaction id for the request in uuid v4 format. */
        transactionId?: string;
        /** Limit the number of the returned documents to the specified number. */
        limit?: number;
        /** The offset is the index of the item from which you want to start returning data from. Default is 0. */
        skip?: number;
        headers?: OutgoingHttpHeaders;
    }
    /** Parameters for the `createNotificationChannel` operation. */
    interface CreateNotificationChannelParams {
        /** Account ID. */
        accountId: string;
        name: string;
        /** Type of callback URL. */
        type: CreateNotificationChannelConstants.Type | string;
        /** The callback URL which receives the notification. */
        endpoint: string;
        /** A one sentence description of this `Channel`. */
        description?: string;
        /** Severity of the notification to be received. */
        severity?: CreateNotificationChannelConstants.Severity | string[];
        /** Channel is enabled or not. Default is disabled. */
        enabled?: boolean;
        alertSource?: NotificationChannelAlertSourceItem[];
        /** The transaction id for the request in uuid v4 format. */
        transactionId?: string;
        headers?: OutgoingHttpHeaders;
    }
    /** Constants for the `createNotificationChannel` operation. */
    namespace CreateNotificationChannelConstants {
        /** Type of callback URL. */
        enum Type {
            WEBHOOK = "Webhook"
        }
        /** Severity */
        enum Severity {
            LOW = "low",
            MEDIUM = "medium",
            HIGH = "high",
            CRITICAL = "critical"
        }
    }
    /** Parameters for the `deleteNotificationChannels` operation. */
    interface DeleteNotificationChannelsParams {
        /** Account ID. */
        accountId: string;
        /** Body for bulk delete notification channels. */
        body: string[];
        /** The transaction id for the request in uuid v4 format. */
        transactionId?: string;
        headers?: OutgoingHttpHeaders;
    }
    /** Parameters for the `deleteNotificationChannel` operation. */
    interface DeleteNotificationChannelParams {
        /** Account ID. */
        accountId: string;
        /** Channel ID. */
        channelId: string;
        /** The transaction id for the request in uuid v4 format. */
        transactionId?: string;
        headers?: OutgoingHttpHeaders;
    }
    /** Parameters for the `getNotificationChannel` operation. */
    interface GetNotificationChannelParams {
        /** Account ID. */
        accountId: string;
        /** Channel ID. */
        channelId: string;
        /** The transaction id for the request in uuid v4 format. */
        transactionId?: string;
        headers?: OutgoingHttpHeaders;
    }
    /** Parameters for the `updateNotificationChannel` operation. */
    interface UpdateNotificationChannelParams {
        /** Account ID. */
        accountId: string;
        /** Channel ID. */
        channelId: string;
        name: string;
        /** Type of callback URL. */
        type: UpdateNotificationChannelConstants.Type | string;
        /** The callback URL which receives the notification. */
        endpoint: string;
        /** A one sentence description of this `Channel`. */
        description?: string;
        /** Severity of the notification to be received. */
        severity?: UpdateNotificationChannelConstants.Severity | string[];
        /** Channel is enabled or not. Default is disabled. */
        enabled?: boolean;
        alertSource?: NotificationChannelAlertSourceItem[];
        /** The transaction id for the request in uuid v4 format. */
        transactionId?: string;
        headers?: OutgoingHttpHeaders;
    }
    /** Constants for the `updateNotificationChannel` operation. */
    namespace UpdateNotificationChannelConstants {
        /** Type of callback URL. */
        enum Type {
            WEBHOOK = "Webhook"
        }
        /** Severity */
        enum Severity {
            LOW = "low",
            MEDIUM = "medium",
            HIGH = "high",
            CRITICAL = "critical"
        }
    }
    /** Parameters for the `testNotificationChannel` operation. */
    interface TestNotificationChannelParams {
        /** Account ID. */
        accountId: string;
        /** Channel ID. */
        channelId: string;
        /** The transaction id for the request in uuid v4 format. */
        transactionId?: string;
        headers?: OutgoingHttpHeaders;
    }
    /** Parameters for the `getPublicKey` operation. */
    interface GetPublicKeyParams {
        /** Account ID. */
        accountId: string;
        /** The transaction id for the request in uuid v4 format. */
        transactionId?: string;
        headers?: OutgoingHttpHeaders;
    }
    /*************************
     * model interfaces
     ************************/
    /** The providers that act as alert sources and the potential findings that can be flagged as alerts. */
    interface ChannelAlertSourceItem {
        /** The providers that you can receive alerts for. To view your available providers, you can call the
         *  /v1/{account_id}/providers endpoint of the Findings API.
         */
        provider_name?: string;
        /** The types of findings for each provider that you want to receive alerts for. Options are dependent upon the
         *  provider that you select. Depending on that selection, some available options include
         *  `image_with_vulnerabilities`, `anonym_server`, `server_suspected_ratio`, `appid`, `cos`, `expired_cert`, and
         *  `expiring_1day_cert`For a full list of available finding types, see [the docs](/docs/).
         */
        finding_types?: any[];
    }
    /** The returned response when a channel is deleted. */
    interface ChannelDelete {
        /** The ID of the deleted channel. */
        channel_id?: string;
        /** response message. */
        message?: string;
    }
    /** The returned response when get channel is run. */
    interface ChannelGet {
        /** Response including channels. */
        channel?: ChannelGetChannel;
    }
    /** Response including channels. */
    interface ChannelGetChannel {
        /** A unique ID for the channel. */
        channel_id?: string;
        name?: string;
        /** A one sentence description of this `Channel`. */
        description?: string;
        /** Type of callback URL. */
        type?: string;
        /** The severity of the notification. */
        severity?: ChannelGetChannelSeverity;
        /** The callback URL which receives the notification. */
        endpoint?: string;
        /** Whether the channel is enabled. The default is disabled. */
        enabled?: boolean;
        alert_source?: ChannelGetChannelAlertSourceItem[];
        frequency?: string;
    }
    /** The providers that act as alert sources and the potential findings that can be flagged as alerts. */
    interface ChannelGetChannelAlertSourceItem {
        /** The providers that you can receive alerts for. To view your available providers, you can call the
         *  /v1/{account_id}/providers endpoint of the Findings API.
         */
        provider_name?: string;
        /** The types of findings for each provider that you want to receive alerts for. Options are dependent upon the
         *  provider that you select. Depending on that selection, some available options include
         *  `image_with_vulnerabilities`, `anonym_server`, `server_suspected_ratio`, `appid`, `cos`, `expired_cert`, and
         *  `expiring_1day_cert`For a full list of available finding types, see [the docs](/docs/).
         */
        finding_types?: any[];
    }
    /** The severity of the notification. */
    interface ChannelGetChannelSeverity {
        /** Critical severity. */
        critical?: boolean;
        /** High severity. */
        high?: boolean;
        /** Medium severity. */
        medium?: boolean;
        /** Low severity. */
        low?: boolean;
    }
    /** The returned response when a channel is created or updated. */
    interface ChannelInfo {
        /** The ID of the created channel. */
        channel_id?: string;
        /** response code. */
        status_code?: number;
    }
    /** The severity of the notification. */
    interface ChannelSeverity {
        /** Critical severity. */
        critical?: boolean;
        /** High severity. */
        high?: boolean;
        /** Medium severity. */
        medium?: boolean;
        /** Low severity. */
        low?: boolean;
    }
    /** The returned response when more than one channel is deleted. */
    interface ChannelsDelete {
        /** response message. */
        message?: string;
    }
    /** Available channels in your account are listed. */
    interface ChannelsList {
        channels?: Channel[];
    }
    /** The alert sources. They identify the providers and their finding types which makes the findings available to Security Advisor. */
    interface NotificationChannelAlertSourceItem {
        /** Below is a list of builtin providers that you can select in addition to the ones you obtain by calling
         *  Findings API /v1/{account_id}/providers :
         *   | provider_name | The source they represent |
         *   |-----|-----|
         *   | VA  | Vulnerable image findings|
         *   | NA  | Network Insights findings|
         *   | ATA | Activity Insights findings|
         *   | CERT | Certificate Manager findings|
         *   | ALL | Special provider name to represent all the providers. Its mutually exclusive with other providers
         *  meaning either you choose ALL or you don't|.
         */
        provider_name: string;
        /** An array of the finding types of the provider_name or "ALL" to specify all finding types under that provider
         *  Below is a list of supported finding types for each built in providers
         *  | provider_name | Supported finding types |
         *  |-----|-----|
         *  | VA  | "image_with_vulnerabilities", "image_with_config_issues"|
         *  | NA  | "anonym_server", "malware_server", "bot_server", "miner_server", "server_suspected_ratio",
         *  "server_response", "data_extrusion", "server_weaponized_total"|
         *  | ATA | "appid", "cos", "iks", "iam", "kms", "cert", "account", "app"|
         *  | CERT | "expired_cert", "expiring_1day_cert", "expiring_10day_cert", "expiring_30day_cert",
         *  "expiring_60day_cert", "expiring_90day_cert"|
         *  | ALL | "ALL"|.
         */
        finding_types?: string[];
    }
    /** PublicKeyGet. */
    interface PublicKeyGet {
        public_key: string;
    }
    /** The returned response when a webhook is tested for a channel. */
    interface TestChannel {
        /** response status. */
        test?: string;
    }
    /** Response including channels. */
    interface Channel {
        /** A unique ID for the channel. */
        channel_id?: string;
        name?: string;
        /** A one sentence description of this `Channel`. */
        description?: string;
        /** Type of callback URL. */
        type?: string;
        /** The severity of the notification. */
        severity?: ChannelSeverity;
        /** The callback URL which receives the notification. */
        endpoint?: string;
        /** Whether the channel is enabled. The default is disabled. */
        enabled?: boolean;
        alert_source?: ChannelAlertSourceItem[];
        frequency?: string;
    }
}
export = NotificationsApiV1;