CyberCNS API Documentation

Owned by Vrushali Parkar
Last updated: Jan 23, 2024 by Vrushali
8 min read

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

  1. String: Filter query to be executed against the database.

  2. 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.

  3. Limit: It limits the number of returned values. The default limit is 100.

  4. 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 json
    sess_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'];
agentEnum = ['Probe', 'Lightweight Agent', 'Lightweight Agent Installed'];

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 company level must :- {"match": {"companyRef.id.keyword": "<CompanyID>"}

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

{"query": {"bool": {"must": [ {"exists": {"field": "uniqueid"}}, {"exists": {"field": "ciphers"}}, {"match": {"

assetRef.id

": <External Scan Asset ID>}}]}}
fileds = ["uniqueid", "c", "u"] to get only these fields then on click we can show full results

 

 

 

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.