CyberCNS API Documentation
- Vrushali Parkar
- Vrushali
- Malathi Latha
CyberCNS APIs are available for partners to integrate CyberCNS with different systems.
API Documentation
Navigate to API Documentation as shown using the CyberCNS portal.
It redirects to FastAPI for CyberCNS.
Navigate to required section. Eg. Company as below to GET Company ID.
Description: String, skip, limit, sort
String: Filter query to be executed against the database.
Skip: It specifies the number of pages to skip.
Eg: when the skip is set to 0 and the limit is set to 10, it will process the entire dataset by splitting it into 10 pages. The data from the first page will be returned, and for the second page, the skip will be 1, and the limit will be 10, returning the next 10 data.Limit: It limits the number of returned values. The default limit is 100.
Sort: It specifies the sorting order based on the 'severity.keyword' field in descending order.
Sample Script (Vulnerability)
Refer to the Sample Script to get vulnerability, refer below example.
import jsonsess_cookie = api.get_cookie() def get_vulns(sess_cookie, params, limit, skip=0): resp = requests.get( "https://portaluswest2.mycybercns.com/api/vulnerability/", headers={ "content-type": "application/json" }, params={"q": json.dumps(params), "limit": limit, "skip": skip}, cookies=sess_cookie, ) return resp.json() params = { "query": { "bool": { "must": [ { "match": { "severity.keyword": "High" }, } ], } } } # dict_keys(['data', 'total', 'count', 'scroll_id']) vulns = get_vulns(sess_cookie, params, 5, 0) print(params["query"]["bool"]["must"][0]['match'])print(f"Total: {vulns['total']}")
CyberCNS Collections and Queries
Below are the CyberCNS Collections and Queries which can be used to get required information.
Collection | Query | Enum | Must Example | Explanation |
Company | {"query": {"bool": {"must": [{"exists": {"field": "description"}}], "must_not": [{"exists": {"field": "companyRef"}}]}}} |
|
|
|
Agents | {"query": {"bool": {"must": [ {"exists": {"field": "agent_type"}}]}}} | enumData = ['LinuxX86', 'Windows', 'Darwin', 'LinuxArm']; | must :- {"match": {"companyRef.id.keyword": "<CompanyID>"} | This should be used wherever Company ID reference is required |
Assets | {"query": {"bool": {"must": [{"exists": {"field": "host.importance"}}], "must_not": [{"match": {"isdeprecated": true}}]}}} |
| for agent level must :- {"match": {"agentRef.id.keyword": "<AgentID>"} | For all agent related queries. Also as agents are company specific in case you need company reference, Company ID reference is required |
Deprecated Assets | {"query": {"bool": {"must": [{"exists": {"field": "host.importance"}}, {"match": {"isdeprecated": true}}]]}}} |
|
|
|
Ports | {"query": {"bool": {"must": [{"exists": {"field": "port"}}, {"exists": {"field": "service"}}]}}} |
| must :- {"match": {"assetRef.id.keyword": "<AssetID>"} | For all asset details related data like ports, interfaces AssetID must be used |
Interfaces | {"query": {"bool": {"must": [{"exists": {"field": "interface"}}, {"exists": {"field": "mac"}}]}}} |
|
|
|
Users | {"query": {"bool": {"must": [{"exists": {"field": "uid"}}, {"exists": {"field": "username"}}]}}} |
|
|
|
Storage | {"query": {"bool": {"must": [{"exists": {"field": "mountpoint"}}, {"exists": {"field": "device"}}]}}} |
|
|
|
InstalledPrograms | {"query": {"bool": {"must": [{"exists": {"field": "publisher"}}, {"exists": {"field": "version"}}]}}} |
|
|
|
Vulnerability | {"query": {"bool": {"must": [{"exists": {"field": "vul_id"}}, {"exists": {"field": "score"}}]}}} |
|
|
|
Vulnerability Auth | {"query": {"bool": {"must": [{"exists": {"field": "vul_id"}}, {"exists": {"field": "score.base_score"}}, {"range": {"score.base_score": {"gt": 0}}}]}}} |
|
|
|
Vulnerability NoAuth | {"query": {"bool": {"must": [{"exists": {"field": "vul_id"}}, {"exists": {"field": "score.cvss_score"}}, {"exists": {"field": "port"}}, {"range": {"port": {"gt": 0}}}}]}}} |
|
|
|
Compliance | {"query": {"bool": {"must": [{"exists": {"field": "complaince_id"}}]}}} |
|
|
|
Compliance For individual | {"query": {"bool": {"must": [{"exists": {"field": "complaince_id"}}, {"exists":{"field": "benchmarks.<ComplianceType>"}}]}}} |
|
|
|
ComplianceChecks | {"query": {"bool": {"must": [{"exists": {"field": "filename"}}, {"exists": {"field": "isApplicable"}}]}}} |
|
|
|
Remediation | {"query": {"bool": {"must": [{"exists": {"field": "remediation_status"}}]}}} |
|
|
|
RemediationSuppression | {"query": {"bool": {"must": [{"exists": {"field": "remediationdays"}}]}}} |
|
|
|
Jobs | {"query": {"bool": {"must": [{"exists": {"field": "job_data"}}]}}} |
|
|
|
DiscoverySettings | {"query": {"bool": {"must": [{"exists": {"field": "discovery_type"}}]}}} |
|
|
|
AssetCredentials | {"query": {"bool": {"must": [{"exists": {"field": "cred_type"}}, {"exists": {"field": "hostname"}}, {"match": {"hostname.keyword": ""}}], "must_not": [{"exists": {"field": "assetid.keyword"}}]}}} |
|
|
|
ADCredentials | {"query": {"bool": {"must": [{"exists": {"field": "cred_type"}}, {"exists": {"field": "hostname"}}], "must_not": [{"match": {"hostname.keyword": ""}}]}}} |
|
|
|
RegistryMisConfiguration | {"query": {"bool": {"must": [{"exists": {"field": "hive"}}, {"exists": {"field": "found"}}]}}} |
|
|
|
AssetBestPractices | {"query": {"bool": {"must": [{"exists": {"field": "practice_type"}}]}}} |
|
|
|
AssetFirewallPolicy | {"query": {"bool": {"must": [{"exists": {"field": "policytype"}}]}}} |
|
|
|
SNMPv2 | {"query": {"bool": {"must": [{"match": {"snmp_version.keyword": "v2"}}, {"exists": {"field": "community"}}]}}} |
|
|
|
SNMPv3 | {"query": {"bool": {"must": [{"exists": {"field": "securityName"}}]}}} |
|
|
|
AssetTimeStats | {"query": {"bool": {"must": [ {"exists": {"field": "vul_stats"}}]}} |
|
|
|
AD OU | {"query": {"bool": {"must": [{"match": {"object_type.keyword": "ad_ou"}}, {"exists": {"field": "object_type"}}]}}} |
|
|
|
AD Users | {"query": {"bool": {"must": [{"match": {"object_type.keyword": "ad_users"}}, {"exists": {"field": "object_type"}}]}}} |
|
|
|
AD Groups | {"query": {"bool": {"must": [{"match": {"object_type.keyword": "ad_groups"}}, {"exists": {"field": "object_type"}}]}}} |
|
|
|
AD Computers | {"query": {"bool": {"must": [{"match": {"object_type.keyword": "ad_computers"}}, {"exists": {"field": "object_type"}}]}}} |
|
|
|
AD GPO | {"query": {"bool": {"must": [{"match": {"object_type.keyword": "ad_gpo"}}, {"exists": {"field": "object_type"}}]}}} |
|
|
|
AD Password Policy | {"query":{"bool":{"should":[{"exists":{"field":"maxPasswordAge"}},{"exists":{"field":"minPasswordAge"}}]}}} |
|
|
|
ExternalScan Agent | {"query": {"bool": {"must": [{"match": {"agent_type": 4}}, {"exists": {"field": "agent_type"}}], "must_not": [{"exists": {"field": "companyRef.id.keyword"}}]}}} |
|
|
|
SslScanTimeseries | ": <External Scan Asset ID>}}]}} |
|
|
|
VulnerabilityTimeseries | {"query": {"bool": {"must": [ {"exists": {"field": "uniqueid"}}, {"exists": {"field": "vul_id"}}]}}} |
|
|
|
External Scan Assets | {"query": {"bool": {"must": [{"match": {"discoveredProtocols.keyword": "EXTERNALSCAN"}}, {"exists": {"field": "host.importance"}}]}}} |
|
|
|
Computers Not loggedIn From 30 Days | {"query": {"bool": {"must": [{"match": {"object_type.keyword": "ad_computers"}}, {"match": {"enabled": true}}, {"exists": {"field": "object_type"}}, {"range": {"lastLogonDate": {"lte": "now-30d"}}}]}}} |
|
|
|
Users Not loggedIn From 30 Days | {"query": {"bool": {"must": [{"match": {"object_type.keyword": "ad_users"}}, {"match": {"enabled": true}}, {"exists": {"field": "object_type"}}, {"range": {"lastLogonDate": {"lte": "now-30d"}}}]}}} |
|
|
|
Groups Critical Objects | {"query": {"bool": {"must": [{"match": {"object_type.keyword": "ad_groups"}}, {"match": {"isCriticalSystemObj": true}}, {"exists": {"field": "object_type"}}]}}} |
|
|
|
Groups Non Critical Objects | {"query": {"bool": {"must": [{"match": {"object_type.keyword": "ad_groups"}}, {"match": {"isCriticalSystemObj": false}}, {"exists": {"field": "object_type"}}]}}} |
|
|
|
Groups Empty | {"query": {"bool": {"must": [{"match": {"object_type.keyword": "ad_groups"}}, {"match": {"empty": false}}, {"exists": {"field": "object_type"}}]}}} |
|
|
|
GPO Active | {"query": {"bool": {"must": [{"match": {"object_type.keyword": "ad_gpo"}}, {"match": {"linkedTo": true}}, {"exists": {"field": "object_type"}}]}}} |
|
|
|
GPO In Active | {"query": {"bool": {"must": [{"match": {"object_type.keyword": "ad_gpo"}}, {"exists": {"field": "object_type"}}], "must_not": [{"exists": {"field": "linked"}}]}}} |
|
|
|
GetAll Integration Credentials | {"query": {"bool": {"must": [ {"exists": {"field": "params"}}, {"exists": {"field": "integrationName"}}]}}} |
|
|
|
Get Single Integration Credentials | {"query": {"bool": {"must": [ {"exists": {"field": "params"}}, {"exists": {"field": "integrationName"}}, {"match": {"integrationName.keyword": "<Integration Name>"}}]}}} |
|
|
|
Integration Mappings | {"query": {"bool": {"must": [ {"exists": {"field": "integrationRef.integrationName"}}]}}} |
|
|
|
Single Integration Mappings | {"query": {"bool": {"must": [ {"exists": {"field": "integrationRef.integrationName"}}, {"match": {"integrationRef.integrationName.keyword": "<Integration Name>"}}]}}} |
|
|
|
Integration Mappings based on compay map | {"query": {"bool": {"must": [ {"exists": {"field": "integrationRef.integrationName"}}, {"match": {" companyRef.id .keyword": "<Company ID>"}}]}}} |
|
|
|
Global Integrations | {"query": {"bool": {"must": [{"match": {"sourceCompanyId.keyword": "*"}}, {"match": {"destCompanyId.keyword": "*"}}]}}} |
|
|
|
TableSettings | {"query": {"bool": {"must": [ {"exists": {"field": "tableId"}}, {"exists": {"field": "columns"}}]}}} |
|
|
|
Alerts | {"query": {"bool": {"must": [{"exists": {"field": "description"}}, {"exists": {"field": "name"}}, {"exists": {"field": "status"}}], "should": [{"match": {"status.keyword": "Open"}}, {"match": {"status.keyword": "Closed"}}], "must_not": [{"exists": {"field": "alertsRef"}}]}}} |
|
|
|
Events | {"query": {"bool": {"must": [{"exists": {"field": "description"}}, {"exists": {"field": "name"}}, {"exists": {"field": "status"}}, {"exists": {"field": "alertsRef"}}], "should": [{"match": {"status.keyword": "Open"}}, {"match": {"status.keyword": "Closed"}}]}}} |
|
|
|
ApplicationBaseLine | {"query": {"bool": {"should": [{"exists": {"field": "mandatoryApplications"}}, {"exists": {"field": "deniedApplications"}}]}}} |
|
|
|
Scheduler | {"query": {"bool": {"must": [{"exists": {"field": "scantype"}}, {"exists": {"field": "settings"}}]}}} |
|
|
|
NotificationRules | {"query": {"bool": {"must": [{"exists": {"field": "integrationRule"}}, {"exists": {"field": "alertRules"}}]}}} |
|
|
|
Port Modification Events | {"query": {"bool": {"must": [{"exists": {"field": "description"}}, {"exists": {"field": "name"}}, {"exists": {"field": "status"}}, {"exists": {"field": "alertsRef"}}, {"terms": {"ruleReference.eventId.keyword": ["CCNS-PORTS-CREATE-EVENT-00001", "CCNS-PORTS-DELETE-EVENT-00001"]}}]}}} |
|
|
|
Custom Report Builder | {"query": {"bool": {"must": [{"exists": {"field": "customReportName"}}]}}} |
|
|
|
Custom Report Generated | {"query": {"bool": {"must": [{"exists": {"field": "customreportbuilderRef"}}]}}} |
|
|
|
ApplicationBaseLine Results | {"query": {"bool": {"should": [{"exists": {"field": "is_mandatory_application"}}, {"exists": {"field": "is_denied_application"}}]}}} |
|
|
|
Firewall Assets | {"query":{"bool":{"must":[{"exists":{"field":"host.importance"}},{"match":{"os.product_type.keyword":"firewall"}}]}}} |
|
|
|
Below is an example to show how to query based on created date and updated date.
Collection | Query |
Based on created date for asset
Asset created between 01-01-2020 - 0 Hours UTC to now | {"query": {"bool": {"must": [{"exists": {"field": "host.importance"}},{"range": {"c": {"gte": "2020-01-01T00:00:00","lte": "now"}}}], "must_not": [{"match": {"isdeprecated": true}}]}}} |
Based on last updated date for asset
Asset last updated between 01-01-2020 - 0 Hours UTC to now | {"query": {"bool": {"must": [{"exists": {"field": "host.importance"}},{"range": {"u": {"gte": "2020-01-01T00:00:00","lte": "now"}}}], "must_not": [{"match": {"isdeprecated": true}}]}}} |
Below is the explanation of Enum values to be used for which options ( Type of Agent & OS platform)
Enum | Value to use | For |
enumData = ['LinuxX86', 'Windows', 'Darwin', 'LinuxArm']; | enumData = 1 | LinuxX86 |
| enumData = 2 | Windows |
| enumData = 3 | Darwin |
| enumData = 4 | LinuxArm |
agentEnum = ['Probe', 'Lightweight Agent', 'Lightweight Agent Installed', 'ExternalScanAgent']; | agentEnum = 1 | Probe |
| agentEnum = 2 | Lightweight Agent |
| agentEnum = 3 | Lightweight Agent Installed |
| agentEnum = 4 | ExternalScanAgent |
Sample query to get Asset Details
Navigate to Assets section.
Use below query to get Asset Details for a particular Company
{"query": {"bool": {"must": [{"exists": {"field": "host.importance"}}, {"match": {"companyRef.id.keyword": "bab8d50a-4f59-4c9b-bcab-303650facd24"}}], "must_not": [{"match": {"isdeprecated": true}}]}}}
The highlighted query part is adding a reference of the company (companyid) which is a part of regular Asset query ( available in the document shared earlier) used with company reference.
Note: The company ID used above is for reference only.
API Authorization
CyberCNS helps with header-based API Authorization.
This will work as per the User Role and Companies allow for the User.
Please use your Client ID and Client Secret as Username and Password respectively.
Along with Authorization, the headers need to be passed.
The Tenant/Domain name will be passed against the Customer ID.
In basic authentication, please include the tenant's name in the header section. Alternatively, one can use login session cookies to access the data for queries.
Ensure that the environment variable has been updated and the 'get login' operation has been performed first. Afterward, all the necessary information can be retrieved. Be sure to add the tenant name to the header."
Below is the set of APIs you can use to get external scan-related information.
To get a list of scanned IPs with OS details:
Endpoint: "https://portaluseast2.mycybercns.com/api/externalscanosinfo/"
payload : {"q": {"customerDomain":"<cybercns domain>","companyId":<cybercns companyId>}, "skip": 0, "limit" : 10, "sort": {"updated":-1}}
To get a list of open ports:
Endpoint : "https://portaluseast2.mycybercns.com/api/externalscanportsinfo/"
payload : {"q": {"customerDomain":"<cybercns domain>","companyId":<cybercns companyId>, "state":"open"}, "skip": 0, "limit" : 10, "sort": {"updated":-1}}
To get a list of vulnerabilities:
Endpoint : "https://portaluseast2.mycybercns.com/api/externalscannsescriptsinfo/"
payload : {"q": {"customerDomain":"<cybercns domain>","companyId":<cybercns companyId>, "osId":<_id obetend from first api call externalscanosinfo>}, "skip": 0, "limit" : 10, "sort": {"updated":-1}}
Sample python file with scroll_id value shown below,
import json
import time
import base64
import requests
def run_scroll_api():
client_id = "<ClientID>"
client_secret = "<ClientSecret>"
headers = {"Authorization": f'Basic {base64.b64encode(f"{client_id}:{client_secret}".encode()).decode()}',
"customerid": "<Tenant Name>"}
query = {"query": {"bool": {"must": [{"exists": {"field": "vul_id"}}, {"exists": {"field": "score"}}]}}}
scroll_id = "start"
final_data = []
limit = 10000
page = 0
base_url = "https://<BaseURL>/api/vulnerability/" # Ex:- "https://portaluseast2.mycybercns.com"
start_time = time.time()
while True:
resp = requests.get(base_url, params={"q": json.dumps(query), "limit": limit,
"skip": page, "scroll_id": scroll_id,
"fields": json.dumps(['vul_id'])}, headers=headers)
if resp.status_code != 200:
print(f"Error in getting response {resp.status_code} {resp.content}")
break
else:
resp = resp.json()
if len(resp['data']) > 0:
final_data.extend(resp["data"])
scroll_id = resp.get("scroll_id")
page += 1
print(f"{limit} {len(resp['data'])}, {resp['total']} {resp['count']} {scroll_id}, time elaspsed {time.time() - start_time}")
else:
print("Empty data, ")
break
# time.sleep(10)
print(len(final_data))
NOTE:
The KRoles and KUsers APIs are related to KeyCloak. All CyberCNS APIs will work with IDs, but for KeyClock, we are using the name of the role or user in the API endpoint for better communication between the UI and KeyCloak.
This completes the API Documentation.