Package: ibm-cloud-security-advisor
ibm_cloud_security_advisorThis repository contains the released python client SDK for IBM Cloud Security Advisor Findings and Notifications APIs . Check out below for more details.Findings API :https://cloud.ibm.com/apidocs/security-advisor/findingsNotifications API :https://cloud.ibm.com/apidocs/security-advisor/notificationsNoticeSupport for Python versions 2.x and versions <= 3.4 is deprecated and will be officially dropped in the next major release, which is expected to be end of December, 2019. Referhttps://github.com/IBM/python-sdk-coreOverviewThe  ibm_cloud_security_advisor allows developers to programmatically interact with the ibm cloud security advisor findings and notifications apiPrerequisitesAnIBM Cloudaccount.An IAM API key to allow the SDK to access your account. Create onehere.An installation of Python >=3.5 on your local machine.InstallationTo install, usepiporeasy_install:pipinstall--upgrade"ibm_cloud_security_advisor>=1.1.0"oreasy_install--upgrade" ibm_cloud_security_advisor>=1.1.0"Authenticationibm_cloud_security_advisor uses token-basedIdentity 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 serviceAPI keyor anaccess 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, seeGenerating bearer tokens using the IAM API keyandSupplying the access tokensectionSupplying the IAM API key:fromibm_cloud_security_advisorimportFindingsApiV1fromibm_cloud_sdk_core.authenticatorsimportIAMAuthenticatorauthenticator=IAMAuthenticator('apikey')findings_service=FindingsApiV1(authenticator=authenticator)Generating bearer tokens using the IAM API key:fromibm_cloud_sdk_core.authenticatorsimportIAMAuthenticator# In your API endpoint use this to generate new bearer tokensiam_token_manager=IAMAuthenticator('<apikey>')token=iam_token_manager.get_token()Supplying the access token:#FINDINGSfromibm_cloud_security_advisorimportFindingsApiV1fromibm_cloud_sdk_core.authenticatorsimportBearerTokenAuthenticator# in the constructor, assuming control of managing the tokenauthenticator=BearerTokenAuthenticator('your token')findings_service=FindingsApiV1(authenticator=authenticator)#NOTIFICATIONSfromibm_cloud_security_advisorimportNotificationsApiV1fromibm_cloud_sdk_core.authenticatorsimportBearerTokenAuthenticator# in the constructor, assuming control of managing the tokenauthenticator=BearerTokenAuthenticator('your token')notifications_service=NotificationsApiV1(authenticator=authenticator)Using the SDKThe  ibm_cloud_security_advisor Python SDK supports only synchronous (blocking) execution of service methods. The return value from all service methods is a DetailedResponse object. Use this SDK to perform the basic  ibm_cloud_security_advisor creation operation as follows, with the installation and initialization instructions from above:#Findingsfromibm_cloud_security_advisorimportFindingsApiV1fromibm_cloud_sdk_core.authenticatorsimportIAMAuthenticatorauthenticator=IAMAuthenticator('your apikey')ibm_cloud_security_advisor_findings_service=FindingsApiV1(authenticator=authenticator)response=ibm_cloud_security_advisor_findings_service.<Methodhere<>>print(response)#Notificationsfromibm_cloud_security_advisorimportNotificationsApiV1fromibm_cloud_sdk_core.authenticatorsimportIAMAuthenticatorauthenticator=IAMAuthenticator('your apikey')ibm_cloud_security_advisor_notifications_service=NotificationsApiV1(authenticator=authenticator)response=ibm_cloud_security_advisor_notifications_service.<Methodhere<>>print(response)This would give an output ofDetailedResponsefrom which you can use theget_result(),get_headers(), andget_status_code()to return the result, headers, and status code respectively.Sending request headersCustom headers can be passed in any request in the form of adictas:headers={'Custom-Header':'custom_value'}For example, to send a header calledCustom-Headerto a call in  ibm_security_advisor_findings_api_sdk, pass the headers parameter as:fromibm_cloud_security_advisorimportFindingsApiV1fromibm_cloud_sdk_core.authenticatorsimportIAMAuthenticatorauthenticator=IAMAuthenticator('your apikey')ibm_security_advisor_findings_api_sdk_service=FindingsApiV1(authenticator=authenticator)response=ibm_security_advisor_findings_api_sdk_service.<<METHODHERE>>(headers={'Custom-Header':'custom_value'}).get_result()Error HandlingThe  ibm_cloud_security_advisor Python SDK generates an exception for any unsuccessful method invocation.
If the method receives an error response from an API call to the service, it will generate anApiExceptionwith the following fields.NAMEDESCRIPTIONcodeThe HTTP response code that is returned.messageA message that describes the error.infoA dictionary of additional information about the error.ApiExceptioncan be handled this way.fromibm_cloud_sdk_core.api_exceptionimportApiExceptiontry:response=ibm_cloud_security_advisor_findings_service.create_note(account_id="<<Account ID here>>",**data)exceptApiExceptionaserr:try:# err.code  gives status codeexcep_resp=err.http_response.json()print(excep_resp)except:print(err)excep_resp would be-{"detail":"Document already exists: abc/providers/sdktest/notes/sdk_note_id1","instance":"abc/providers/sdktest/notes/sdk_note_id1","status":409,"title":"Conflict","type":"about:blank"}Error log levelBy default, error log level is disabled, so user will not see any error/exception logged bylogger.errorandlogger.exceptionbut will see other error/exception.
To enable it, user can passenable_error_log=True.ibm_cloud_security_advisor_findings_service=FindingsApiV1(authenticator=authenticator,enable_error_log=True)Sample CodeFindings APIExamplehttp methodpost_graphPOST /v1/{account_id}/graphlist_providersGET /v1/{account_id}/providerscreate_findingPOST /v1/{account_id}/providers/{provider_id}/notescreate_cardPOST /v1/{account_id}/providers/{provider_id}/notescreate_note_with_kpiPOST /v1/{account_id}/providers/{provider_id}/notescreate_note_with_reporterPOST /v1/{account_id}/providers/{provider_id}/notescreate_note_with_sectionPOST /v1/{account_id}/providers/{provider_id}/noteslist_notesGET /v1/{account_id}/providers/{provider_id}/notesdelete_noteDELETE /v1/{account_id}/providers/{provider_id}/notes/{note_id}create_occurrencePOST /v1/{account_id}/providers/{provider_id}/occurrencescreate_occurrence_with_contextPOST /v1/{account_id}/providers/{provider_id}/occurrencescreate_occurrence_with_kpiPOST /v1/{account_id}/providers/{provider_id}/occurrenceslist_occurrencesGET /v1/{account_id}/providers/{provider_id}/occurrencesdelete_occurrenceDELETE /v1/{account_id}/providers/{provider_id}/occurrences/{occurrence_id}list_note_occurrencesGET /v1/{account_id}/providers/{provider_id}/notes/{note_id}/occurrencesNotifications APIExamplehttp methodcreate channelPOST /v1/{account_id}/notifications/channelslist channelsGET /v1/{account_id}/notifications/channelsget channelGET /v1/{account_id}/notifications/channels/{channel_id}delete bulk channelsDELETE /v1/{account_id}/notifications/channelsdelete channelDELETE /v1/{account_id}/notifications/channels/{channel_id}update channelPUT /v1/{account_id}/notifications/channels/{channel_id}test channelGET /v1/{account_id}/notifications/channels/{channel_id}/testget public keyGET /v1/{account_id}/notifications/public_keyDocumentationSeeFindings API doc.SeeNotifications API doc.Integration testTo run pytest, create virtual env and then run. Otherwise you might see below errorissue -https://github.com/pytest-dev/pytest/issues/2287Traceback:
test/integration/test_note.py:26: in <module>
    from ibm_cloud_security_advisor import FindingsApiV1
   ModuleNotFoundError: No module named 'ibm_cloud_security_advisor'Install dev modules.python3-mvenvenv#(for python3)sourceenv/bin/activatecdibm-coud-security-advisor-sdk-python
pipinstall-rrequirements-dev.txtPrereq variables, either by exporting all the variables directly or provide in file-Make sureAPI_KEYhas enough permission to perform findings api operations.export env varsexportAPI_KEY=<YOUR_API_KEY>exportACCOUNT_ID=<YOUR_ACCOUNT_ID>exportFINDING_API_ENDPOINT=<FINDING_API_ENDPOINT>exportNOTIFICATION_API_ENDPOINT=<NOTIFICATION_API_ENDPOINT>#optional. Use it for dev/preprod iam endpointexportIAM_ENDPOINT=<IAM_ENDPOINT>provide in/integration/input/cred/ibm-credentials.envfile or export your own.envcredential file with full path including filename.exportIBM_CREDENTIALS_FILE=<file_path>To run test-python-mpytesttest/integration--html=report.html--json-report--json-report-summaryOnce run is completed, html report and .report.json will be generated in the same directory and it will look like thisLicenseThe ibm_cloud_security_advisor Python SDK is released under the Apache 2.0 license. The license's full text can be found inLICENSE.