DEPRECATED

The Security Insights feature is deprecated and will no longer be supported. Please migrate to new SDK https://github.com/IBM/scc-go-sdk

IBM Cloud Security Advisor GO SDK

This repository contains the released GO client SDK for IBM Cloud Security Advisor services. Check out our listed below for more details.

• Findings API : https://cloud.ibm.com/apidocs/security-advisor/findings
• Notifications API : https://cloud.ibm.com/apidocs/security-advisor/notifications

Table of Contents

• IBM Cloud Security Advisor GO SDK
  • Overview
  • Prerequisites
  • Installation
    • go get command
    • Go modules
    • dep dependency manager
  • Authentication
    • Supplying the IAM API key:
  • Sending request headers
  • Error Handling
    • Findings
    • Notifications
  • Sample Code
    • Findings
    • Notifications
  • Tests
    • Run unit tests:
    • Run integration tests:
  • License
  • Open Issues

Overview

The IBM Cloud Security Advisor GO SDK allows developers to programmatically interact with the ibm cloud security advisor findings and notifications api.

Service Name	Package name
Findings Service	findingsapiv1
Notifications Service	notificationsapiv1

Prerequisites

• An IBM Cloud account.
• An IAM API key to allow the SDK to access your account. Create one here.
• Go version 1.12 or above.

Installation

The current version of this SDK: v3.0.0

There are a few different ways to download and install the Findings API Go SDK project for use by your Go application:

go get command

Use this command to download and install the SDK to allow your Go application to use it:

go get -u github.com/ibm-cloud-security/security-advisor-sdk-go

Go modules

If your application is using Go modules, you can add a suitable import to your Go application, like this:

import (
  "github.com/ibm-cloud-security/security-advisor-sdk-go/v3/findingsapiv1"
  "github.com/ibm-cloud-security/security-advisor-sdk-go/v3/notificationsapiv1"
)

then run go mod tidy to download and install the new dependency and update your Go application's go.mod file.

dep dependency manager

If your application is using the dep dependency management tool, you can add a dependency to your Gopkg.toml file. Here is an example:

[[constraint]]
  name = "github.com/ibm-cloud-security/security-advisor-sdk-go"
  version = "v3.0.0"

then run dep ensure.

Authentication

Security Advisor Findings API GO SDK 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.

To provide credentials to the SDK, you supply either an IAM service API key or an access token:

• Use the API key to have the SDK manage the lifecycle of the access token. The SDK requests an access token, ensures that the access token is valid, and refreshes it if necessary.
• Use the access token if you want to manage the lifecycle yourself. For details, see Authenticating with IAM tokens.

Supplying the IAM API key:

import (
  "github.com/IBM/go-sdk-core/v5/core"
  "github.com/ibm-cloud-security/security-advisor-sdk-go/v3/findingsapiv1"
  "github.com/ibm-cloud-security/security-advisor-sdk-go/v3/notificationsapiv1"
)

authenticator := &core.IamAuthenticator{
	ApiKey: apiKey,
	URL:    URL, //Required only if you are targetting Dev/Preprod environment
}

findingsService, err := findingsapiv1.NewFindingsApiV1(&findingsapiv1.FindingsApiV1Options{
  Authenticator: authenticator, 
})

Sending request headers

Custom headers can be passed in any request in the form of a map[string]string as:

headers := make(map[string]string)
	headers["Custom-Header"] = "custom_value"

For example, to send a header called Custom-Header to a call in notificationsapiv1, pass the headers parameter as:

import (
  "github.com/IBM/go-sdk-core/v5/core"
  "github.com/ibm-cloud-security/security-advisor-sdk-go/v3/notificationsapiv1"
)

authenticator := &core.IamAuthenticator{
	ApiKey: apiKey,
	URL:    URL, //Required only if you are targetting Dev/Preprod environment
}
service, err := notificationsapiv1.NewNotificationsApiV1(&notificationsapiv1.NotificationsApiV1Options{
  Authenticator: authenticator,
})

var deleteOptions = service.NewDeleteNotificationChannelOptions(accountID, channelID)
deleteOptions.SetHeaders(headers)

Error Handling

The security-advisor-findings-sdk-go generates an error for any unsuccessful method invocation. If the method receives an error response from an API call to the service, it will generate an error which is sent has the last return value of the function. It also returns a DetailedResponse structure which consists further details about the response.

Error can be handled in the following way.

Findings

import (
 "fmt"

 "github.com/IBM/go-sdk-core/v5/core"
 "github.com/ibm-cloud-security/security-advisor-sdk-go/v3/findingsapiv1"
)

providerID := "providerID" //Invalid provider id
noteID := "custom-note" //invalid note id

authenticator := &core.IamAuthenticator{
  ApiKey: apiKey,
  URL:    url, //use for dev/preprod env
}
service, _ := findingsapiv1.NewFindingsApiV1(&findingsapiv1.FindingsApiV1Options{
  Authenticator: authenticator,
  URL:           "https://us-south.secadvisor.cloud.ibm.com/findings", //Specify url or use default
})

getNotesOptions := service.NewGetNoteOptions(accountID, "providerID", noteID)

result, response, err := service.GetNote(getNotesOptions)

if err != nil {
  fmt.Println(err) //Prints: "Not Found"
  fmt.Println(response.StatusCode) //Prints: 404
  fmt.Println(response.Result) //See Expected Response section below for details
}

Expected Response for the above case case would be. This is of type map[string]interface {}-

map[
  detail: Document not found: <AccountID>/providers/providerID/notes/custom-note 
  instance: <AccountID>/providers/providerID/notes/custom-note 
  status: 404 
  title: Not Found 
  type: about:blank
]

Notifications

import (
 "fmt"

 "github.com/IBM/go-sdk-core/v5/core"
 "github.com/ibm-cloud-security/security-advisor-sdk-go/v3/notificationsapiv1"
)

channelID := "channel" //invalid channel id

authenticator := &core.IamAuthenticator{
  ApiKey: apiKey,
  URL:    url, //use for dev/preprod env
}
service, _ := notificationsapiv1.NewNotificationsApiV1(&notificationsapiv1.NotificationsApiV1Options{
  Authenticator: authenticator,
  URL:           "https://us-south.secadvisor.cloud.ibm.com/notifications", //Specify url or use default
})

getChannelOptions := service.NewGetNotificationChannelOptions(accountID, channelID)

result, response, err := service.GetNotificationChannel(getChannelOptions)

if err != nil {
  fmt.Println(err) //Prints: "Internal Server Error"
  fmt.Println(response.StatusCode) //Prints: 500
  fmt.Println(response.Result) //See Expected Response section below for details
}

Expected Response for the above case case would be. This is of type map[string]interface {}-

map[
  code:NOTIFICATIONS-CHANNELS-API-ERR500-01 
  message:Internal Server Error
]

Sample Code

Findings

Example	http method
post_graph	POST /v1/{account_id}/graph
list_providers	GET /v1/{account_id}/providers
create_finding_note	POST /v1/{account_id}/providers/{provider_id}/notes
create_card_note	POST /v1/{account_id}/providers/{provider_id}/notes
create_note_with_kpi	POST /v1/{account_id}/providers/{provider_id}/notes
create_note_with_section	POST /v1/{account_id}/providers/{provider_id}/notes
list_provider_notes	GET /v1/{account_id}/providers/{provider_id}/notes
get_note	GET /v1/{account_id}/providers/{provider_id}/notes
get_occurrence_note	GET /v1/{account_id}/providers/{provider_id}/occurrences/{occurrence_id}/note
update_note	PUT /v1/{account_id}/providers/{provider_id}/notes/{note_id}
delete_note	DELETE /v1/{account_id}/providers/{provider_id}/notes/{note_id}
create_finding_occurrence	POST /v1/{account_id}/providers/{provider_id}/occurrences
create_kpi_occurrence	POST /v1/{account_id}/providers/{provider_id}/occurrences
update_occurrence	PUT /v1/{account_id}/providers/{provider_id}/occurrences/{occurrence_id}
delete_occurrence	DELETE /v1/{account_id}/providers/{provider_id}/occurrences/{occurrence_id}
get_occurrence	GET /v1/{account_id}/providers/{provider_id}/occurrences/{occurrence_id}
list_note_occurrences	GET /v1/{account_id}/providers/{provider_id}/notes/{note_id}/occurrences
list_provider_occurrences	GET /v1/{account_id}/providers/{provider_id}/occurrences

Notifications

Example	http method
list_channels	GET /v1/{account_id}/notifications/channels
create_channel	POST /v1/{account_id}/notifications/channels
bulk_delete_channel	DELETE /v1/{account_id}/notifications/channels
delete_channel	DELETE /v1/{account_id}/notifications/channels/{channel_id}
get_channel	GET /v1/{account_id}/notifications/channels/{channel_id}
update_channel	PUT /v1/{account_id}/notifications/channels/{channel_id}
test_connection	GET /v1/{account_id}/notifications/channels/{channel_id}/test
get_public_key	GET v1/{account_id}/notifications/public_key

Tests

Run unit tests:

go test ./...

Get code coverage for each test suite:

go test -coverprofile=unit.out ./...
go tool cover -html=unit.out

Run integration tests:

go test ./... -tags=integration

Get code coverage for each test suite:

go test -coverprofile=integration.out ./... -tags=integration
go tool cover -html=integration.out

License

The ibm-cloud-security-advisor-sdk-go is released under the Apache 2.0 license. The license's full text can be found in LICENSE.

Open Issues

Currently if go get is used as mode to download the module - GOPATH might face issues related to IBM SDK core module. Advised method is to use go mdoules.