- Cyware Situational Awareness Platform
- Partner Portal
- Product Documentation
- Partner Advisory Network
- Share Alerts Using Open APIs
Share Alerts Using Open APIs
As a part of the Partner Advisory Network, you can use open APIs to share alerts (advisories) with Collaborate (CSAP). The following illustration gives you an overview of sharing alerts through PAN:
Ensure you have the access ID, secret key, and base URL for the UAT PAN account. These credentials are sent to you through the invitation email when you onboard the Partner Portal.
Create an authentication signature from the access ID, secret key, and expired time in the following format:
Signature: Base64(HMAC-SHA1(secret_key, UTF-8-Encoding-Of(StringTOSign))) StringToSign: access_id + \n + expires Expires: int(current_time(Epoch Time) )+ 300 sec
Note
Expires must be an integer.
Additionally, you can use also use the following Python script or a pre-request script to generate the authentication signature.
import time import base64 import hashlib import hmac expires = int(time.time()) + 10 to_sign = "%s\n%i" % (access_id, expires) signature = base64.b64encode(hmac.new(secret_key.encode("utf-8"), to_sign.encode("utf-8"), hashlib.sha1).digest())
Note
Enter the access_id
and secret_key
that are sent are you in the invitation mail.
If you are using Postman, you can use the following Pre-Request Script to create an authentication signature. Ensure you enter the accessID
and secretKey
that are sent to you in the invitation mail:
CryptoJS = require('crypto-js'); const querystring = require('querystring'); const accessID = '8xxxxxxc-cxxc-4xx5-9xx4-7xxxxxxxxxx5'; const secretKey = 'axxxxxxc-9xx9-4xxa-9xx3-0xxxxxxxxxxa'; function signature(expires) { const toSign = `${accessID}\n${expires}`; const hmac = CryptoJS.HmacSHA1(toSign, secretKey).toString(); console.log(hmac) const buffer = Buffer.from(hmac, 'hex'); return buffer.toString('base64'); } const expires = Math.floor((Date.now() + 300 * 1000) / 1000); var params = { AccessID: accessID, Expires: expires, Signature: signature(expires) }; var requestUrl = pm.request.url.toString(); requestUrl += "?" + querystring.stringify(params); pm.request.url = requestUrl; pm.collectionVariables.set("AccessID", accessID) pm.collectionVariables.set("Expires", expires)
After successfully generating the authentication signature, you can test the connection with the Partner Portal before sending alerts. You can use the following API URL and HTTP Method to test connectivity using any application of your choice.
Update the endpoint to test connectivity with Partner Portal in the following format:
API URL: {base_url}/test_connectivity/
For {base_url}
, enter the base URL sent to you in the invitation mail.
HTTP Method: GET
Query Params:
AccessID | 10xxxxxxx-6xxb-4xx7-bxxf-8xxxxxxxxxx2 |
Signature | 100000 |
Expires | 100000 |
If you are using Postman, use Pre-Request Script (Postman)to generate an authentication signature. Ensure to enter the access ID and secret key sent to you in the invitation mail.
After a successful connection, the following response is displayed:
{ "details": "Connection Established" }
After authenticating and establishing a successful connection, you can use the following API to create and share real-time alerts with the trial Partner Portal account.
API URL: {base_url}/create_feed/
For {base_url}
, enter the base URL sent to you in the invitation mail.
HTTP Method: POST
Query Params:
AccessID | 10xxxxxxx-6xxb-4xx7-bxxf-8xxxxxxxxxx2 |
Signature | 100000 |
Expires | 100000 |
If you are using Postman, use Pre-Request Script (Postman) to generate an authentication signature. Ensure to enter the access ID and secret key sent to you in the invitation mail.
Use the following field information while creating alerts using API:
Field Name | Field Type | Description |
---|---|---|
title* | String | Title of the alert. |
description* | String | Summary of the alert. |
tlp | String | Traffic Light Protocol (TLP) of the alert. The allowed values are:
The default value is WHITE. For more information about TLP, see TLP Controls. |
published_time | Integer | The time at which the alert is published. The default value is the current time. |
indicators | JSON | Specify the indicators associated with the alert. |
tags | List | Specify the list of tags associated with the alert. |
cve | String | Common vulnerabilities and exposure (CVE) record number associated with the alert. |
exploitability | String | Specify exploitable paths within the product. |
impacted_product | List | Specify the impacted product. For example, Windows. |
impacted_version | String | Specify the impacted product versions. For example, Windows 10. |
cvss_score | String | Specify the Common Vulnerability Scoring System (CVSS) score of the alert. |
severity | String | Specify the level of severity associated with the alert. |
workarounds | String | Specify the workarounds associated with the alert. |
resolution | String | Specify the resolution associated with the alert. |
source | String | Specify the source of the alert. |
objective | String | Specify the objective of the alert. |
industries_targeted | String | Specify industries that have been targeted by the threat. |
common_infection_vectors | List | Specify a list of common infection vendors associated with the alert. For example, Remote Desktop Protocol. |
recommended_action | String | Specify the recommended action associated with the alert. |
tactic_technique_pairs | JSON | Define the pairs of tactics and techniques associated with the threat. For example, {"Credential Access":["Credentials from Browsers"]}. |
additional_info | String | Specify any additional information associated with the alert. |
references | String | Specify any references associated with the alert. |
*Mandatory fields
The following sample is of a basic alert that uses the mandatory fields only (title and description):
{ "title": "Multi-stage PowerShell based attack targets the finance industry (Sample Alert)", "description": "An alarming new cyber threat has emerged, targeting the finance industry with a sophisticated multi-stage PowerShell-based attack. The attack was first flagged by an advanced anti-malware software, which detected a series of intricate tactics utilized to deploy the notorious Cobalt Strike malware. This multi-pronged attach leverages a document lure, drawing victims into a carefully orchestrated sequence of PowerShell scripts." }
If you want to create an alert with additional details such as TLP, tags, severity, and other details, you can use the following sample:
{ "title": "Multi-stage PowerShell based attack targets the finance industry (Sample Alert)", "description": "An alarming new cyber threat has emerged, targeting the finance industry with a sophisticated multi-stage PowerShell-based attack. The attack was first flagged by an advanced anti-malware software, which detected a series of intricate tactics utilized to deploy the notorious Cobalt Strike malware. This multi-pronged attach leverages a document lure, drawing victims into a carefully orchestrated sequence of PowerShell scripts.", "tlp": "WHITE", "tags": [ "MalwareBytes", "cobaltstrike" ], "source": "Research", "recommended_action": "The embedded lnk file is obfuscated and after de-obfuscation it's observed that it used cmd.exe to call PowerShell to download and execute the first stage of the attack from the Github account", "additional_info": "<h4> Attack Process </h4><br> The attack commences with the execution of an obfuscated lnk file, which is concealed. Upon de-obfuscation, the lnk file employs cmd.exe to invoke PowerShell, initiating a complex series of techniques designed to infiltrate the victim's environment. Among the tactics employed are privilege escalation and the establishment of persistence through an autorun registry key. The attack leaves behind a trail of indicators, each offering insight into the methods and tools employed by the malicious actors.", "indicators": [ { "type": "ip", "value": [ "188.165.148.241" ] }, { "type": "sha256", "value": [ "026fcb13e9a4ea6c1348a14a5087713dd9e5", "08f096134ac934ec7b4f33a246d61" ] }, { "type": "domain", "value": [ "security-center.com" ] }, { "type": "email", "value": [ "joe@security-center.com" ] }, { "type": "url", "value": [ "center.com" ] }, { "type": "md5", "value": [ "bd08ba3c982eaad768602536fb8e1184" ] }, { "type": "sha1", "value": [ "18AF819125B70879D36378431C4E8D9BFA6A2599" ] }, { "type": "cve", "value": [ "CVE-2021-1332" ] }, { "type": "ipv4_cidr", "value": [ "10.0.0.0/24" ] } ], "severity": "medium", "exploitability": "The Cobalt Strike ShellCode is base64 encoded and XOR encrypted using 35 key. After decoding and decrypting the ShellCode it allocates it into memory using VirtualAlloc and finally execute it by calling Invoke function.", "impacted_product": [ "PowerShell" ], "impacted_version": "Powershell 2.0, Powershell 2.5", "cvss_score": "7.8", "workarounds": "No workarounds known", "resolution": "On careful analysis, it is evident that the obfuscated lnk file serves as a crucial pivot point in the attack chain. De-obfuscation reveals the use of cmd.exe, acting as a conduit to invoke PowerShell. This in turn facilitates the download and execution of the initial attack stage, sourced from a GitHub account. The emergence of this multi-stage PowerShell-based attack underscores the evolving nature of cyber threats, particularly those targeting critical sectors like finance. Organizations are urged to be vigilant, bolstering their defenses to thwart such complex and insidious assaults.", "objective": "Other than their GitHub profile, we do not have much information on the threat actor or their exact intention with this attack. However, monitoring and espionage are a likely motive.", "industries_targeted": "Finance" }
After creating the alert using API, you can review it by logging in to the Partner Portal. Alerts in the Partner Portal are refreshed every five minutes.
You can continue creating test alerts using API and evaluating them till you are ready to raise a request for the production account.
Note
Alerts (advisories) published while using the UAT account are not published to the Member Portal. Alerts are published to the Member Portal only after you get access to the production account.
After sending test alerts and viewing the alerts on the UAT account, you can request production account access.
In the Partner Portal, navigate to New and click Request for Production PAN Account.
Enter the details in the request form:
Partner name: Enter the name of the partner advisory.
About: Enter a description of the objectives or purpose of accessing the production account, along with other information regarding the partner advisory.
Allowed IP: Enter the IP address from which you will be creating alerts through API.
Estimated number of alerts per day (optional): Enter the estimated number of alerts you want to publish in a day.
Email IDs (optional): Enter the email addresses to which the invitation email will be sent. If you don't specify any email addresses, the invitation email for the production PAN account will be sent only to you. Add multiple email addresses using a comma as a separator.
Upload logo (optional): Upload the logo for the partner advisory which will be displayed in Collaborate.
Click Preview to view your request and submit the request to Collaborate administrators. Based on the review by Cyware's technical committee, you will receive an email invitation with credentials for the production PAN account.
After getting access to the production PAN account, you can start creating alerts using open APIs and publish them to Collaborate. Alerts are first reviewed by Cyware's technical committee before it is published to the Collaborate Member Portal. You can view the published alerts in the Partner Portal.
View Dashboards
To view statistics and metrics for the alerts you've shared from the PAN production account, navigate to the main menu and click Dashboards. You can also use filters to view data for a specific period. Use the following information while viewing dashboard widgets:
Total Submitted Alerts displays the number of alerts that are submitted by you to the Cyware technical committee for review.
Total Published Alerts displays the number of alerts that are published successfully to the Member Portal.
Alerts Rejected displays the number of alerts that were rejected by the Cyware technical committee.
Alerts Under Review displays the number of alerts that are submitted and being reviewed.
Communities Enabled displays the number of sharing communities or ISACs that have enabled alerts from you, as a partner.
Total Recipients displays the number of individual recipients who have received your alerts in the Member Portal.