Package: cerbeyra-api
Welcome to Cerbeyra API Client’s docs!THIS IS A BETA RELEASE!This library provides a high level interface for interacting with Cerbeyra’s APIs and retrieving cyber-threat’s
information from them. Through such API’s, it is possible to get clues regarding vulnerability assessments, cyber
feeds, governance, threat intelligence and much more.To use the Cerbeyra’s API you need to start with the creation of a CerbeyraApi object. IN order to do that you must have
access to your account's username and password.Once a CerbeyraApi has been instantiated, you may start using the python object for requesting Cerbeyra’s resources and
getting responses over HTTP protocol. All the HTTP Cerbeyra’s responses are encapsulated in classes specifically
designed to facilitate their manipulation.Getting started:First install the packagepython-mpipinstallcerbeyra-api# orpipinstallcerbeyra-apiSimple Usage# Usage as a Cerbeyra ClientfromcerbeyraimportCerbeyraApiwithCerbeyraApi(username='my@email.it',password='my-password')asca:ci=ca.get_cerbeyra_index()print(f"Your Cerbeyra Index is{ci.index}({ci.risk_level})")# ouput:# Successfully connected to https://areaclienti.cerbeyra.com# Your Cerbeyra Index is B (medium)##################################################### Use as Ubiqum ClientfromcerbeyraimportUbiqumApiwithUbiqumApi(username='my@email.it',password='my-password')asca:ci=ca.get_ubiqum_index()print(f"Your Ubiqum Index is{ci.index}({ci.risk_level})")# ouput:# Successfully connected to https://areaclienti.ubiqum.ch# Your Ubiqum Index is B (medium)APIget_cerbeyra_index(client_id: int = None) -> CerbeyraIndexReturns theCerbeyra Indexof the logged user.For Partners Only:you can specify the client_id to obtain the Cerbeyra Index of a specific client.classCerbeyraIndex:index:strrisk_level:strexplain:dictget_ubiqum_index(client_id:int None) -> UbiqumIndexAs a Ubiqum Client, you can create aUbiqumApiinstance to access the API at the proper endpointget_report_network(columns: list[str] = None, client_id: int = None) -> NetworkReportGets the list of every vulnerability detected on your account on every network host.
Each vulnerability information (e.g., host, threat, solution, vulnerability description) is collected in a va_item.VAItem object as key-value pair.
You can select a list of columns using the Enum class : types.NetworkReportFields, otherwise the API will return a default set of column.For Partners Only:you can specify a client_id to obtain the information about one of your client.classNetworkReport:defiterate_entries(self)->Generator[VAItem,Any,None]:# provides a generator over report entries.defgroup_by_threat(self)->Dict[str,List[VAItem]]:# groups report items that have the same threat level.defget_distinct_hosts(self)->Set[str]:# gets the list of all scanned network hosts.defcount_by_threat(self)->Dict[str,int]:# counts the number of report items for each threat level.defsave_csv(self,path):# saves the network report in a .csv file.defsave_xls(self,path):# saves the network report in a .xls fileclassVAItem(dict):defget_field(self,name:str)->str|None:# gets a report item value based on its field name.classNetworkReportFields(Enum):asset='asset'host='host'hostname='hostname'vulnerability='vulnerability'description='description'threat='threat'solution='solution'vuln_id='vuln_id'last_detection='last_detection'first_detection='first_detection'protocol='protocol'port='port'cvss='cvss'summary='summary'insight='insight'impact='impact'affected='affected'references='references'get_report_web(columns: list[str] = None, client_id: int = None) -> WebReportGets the list of every vulnerability detected on your account on every web host.
Each vulnerability information (e.g., host, threat, solution, vulnerability description) is collected in a va_item.VAItem object as key-value pair.
You can select a list of columns using the Enum class : types.WebReportFields, otherwise the API will return a default set of column.For Partners Only:you can specify a client_id to obtain the information about one of your client.classWebReport:defiterate_entries(self)->Generator[VAItem,Any,None]:# provides a generator over report entries.defgroup_by_threat(self)->Dict[str,List[VAItem]]:# groups report items that have the same threat level.defget_distinct_hosts(self)->Set[str]:# gets the list of all scanned web hosts.defget_distinct_urls(self)->Set[str]:# gets the list of all scanned web urls.defcount_by_threat(self)->Dict[str,int]:# counts the number of report items for each threat level.defsave_csv(self,path):# saves the web report in a .csv file.defsave_xls(self,path):# saves the web report in a .xls fileclassVAItem(dict):defget_field(self,name:str)->str|None:# gets a report item value based on its field name.classWebReportFields(Enum):asset='asset'host='host'hostname='hostname'vulnerability='vulnerability'description='description'threat='threat'solution='solution'vuln_id='vuln_id'last_detection='last_detection'first_detection='first_detection'other='other'param='param'attack='attack'evidence='evidence'response='response'request='request',family='family'url='url'method='method'get_all_clients(active: bool = None) -> List[Client]For Partners Only:gets the list of all clients. You can specify the active param to filter away inactive clients.classClient:client_id:intname:strsurname:stremail:strcompany:stractive:boolexpiration_date:str=Noneget_all_probes(status: str = None) -> List[Probe]For Partners Only:gets the list of all probes.
You can specify a status(ALIVE, WARNING, DANGER)to filter away the probes you are not interested in.classProbe:name:strprobe_id:strstatus:IoTStatuslast_update:strclient:ClientclassIoTStatus(Enum):ALIVE='ALIVE'WARNING='WARNING'DANGER='DANGER'get_all_sensors(status: str = None) -> List[Sensor]For Partners Only:gets the list of all IoT sensors.
You can specify a status(ALIVE, WARNING, DANGER)to filter away the sensors you are not interested in.classSensor:name:strprobe_gateway:strstatus:IoTStatusalarm:strlast_update:strclient:Clientthresholds:list=NoneclassIoTStatus(Enum):ALIVE='ALIVE'WARNING='WARNING'DANGER='DANGER'get_probes(status: str = None) -> List[Probe]gets the list of all probes.
You can specify a status(ALIVE, WARNING, DANGER)to filter away the probes you are not interested in.For Partners Only:you can specify a client_id to obtain the information about one of your client.classProbe:name:strprobe_id:strstatus:IoTStatuslast_update:strclassIoTStatus(Enum):ALIVE='ALIVE'WARNING='WARNING'DANGER='DANGER'get_sensors(status: str = None) -> List[Sensor]gets the list of all IoT sensors.
You can specify a status(ALIVE, WARNING, DANGER)to filter away the sensors you are not interested in.For Partners Only:you can specify a client_id to obtain the information about one of your client.classSensor:name:strprobe_gateway:strstatus:IoTStatusalarm:strlast_update:strthresholds:list=NoneclassIoTStatus(Enum):ALIVE='ALIVE'WARNING='WARNING'DANGER='DANGER'get_all_assets(client_id: int = None, search: str = None, visibility: str = None, perimeter: str = None, types: list[str] = None)) -> AssetCollectiongets the collection of all your assets.
You can specify some parameters to filter away the assets you are not interested in by using these parameters: search string, visibility(included, excluded), perimeter(public, private), and types(Array[network | web | domain]).For Partners Only:you can specify a client_id to obtain the information about one of your client.classAssetCollection:@propertydefassets(self)->list[Asset]:# gets the asset in the collection.defgroup_by_type(self,aggr:bool=False,aggr_method:str='count'):# groups assets that have the same type. If aggr is specified, then the number of asset in each group is returned.defgroup_by_perimeter(self,aggr:bool=False,aggr_method:str='count'):# groups assets that have the same perimeter. If aggr is specified, then the number of asset in each group is returned.deffilter_by_type(self,asset_type:str)->AssetCollection:# filter away assets with type != asset_typedeffilter_by_perimeter(self,perimeter:str)->AssetCollection:# filter away assets with perimeter != perimeterdefsave_csv(self,path:str=None):# export the AssetCollection as .csv file.classAsset:asset_id:intasset_name:strtarget:list[str]|strperimeter:strtype:strexcluded:boolget_all_hosts(client_id: int = None, search: str = None, visibility: str = None, perimeter: str = None, types: list[str] = None)) -> AssetCollectiongets the collection of all your hosts.
You can specify some parameters to filter away the hosts you are not interested in by using these parameters: search string, visibility(included, excluded), perimeter(public, private), and types(Array[network | web]).For Partners Only:you can specify a client_id to obtain the information about one of your client.classHostCollection:@propertydefhosts(self)->List[Host]:# gets the hosts in the collection.defgroup_by_asset(self,aggr:bool=False,aggr_method:str='count'):# groups hosts that have the same asset_id. If aggr is specified, then the number of host in each group is returned.defgroup_by_perimeter(self,aggr:bool=False,aggr_method:str='count'):# groups hosts that have the same perimeter. If aggr is specified, then the number of host in each group is returned.defgroup_by_index(self,aggr:bool=False,aggr_method:str='count'):# groups hosts that have the same index. If aggr is specified, then the number of host in each group is returned.defgroup_by_visibility(self,aggr:bool=False,aggr_method:str='count'):# groups hosts that have the same asset_id. If aggr is specified, then the number of host in each group is returned.deffilter_by_asset(self,asset_id:int):# filter away hosts with asset_id != @asset_id.deffilter_by_perimeter(self,perimeter:str):# filter away hosts with perimeter != @perimeter.deffilter_by_index(self,index:str):# filter away hosts with index != @index.deffilter_by_visibility(self,visibility:str):# filter away hosts with visibility != @visibility.classHost:asset_id:intasset_name:strhost_id:inthost:strperimeter:strtype:strhost_excluded:strasset_excluded:strhost_label:str=Noneindex:str=Noneget_network_vulns(self, client_id: int = None, asset_id: int = None, host_id: int = None, threat: list = None, exclusion: bool = None, host_visibility: str = None, asset_visibility: str = None, detail: int = None) -> NetworkVulnCollection:gets the collection of all the network vulnerabilities associated to your account. If you are interested in specific assets or specific hosts you can specify them by passing a host_id and/or an asset_id.
Additionally, you can specify some parameters to filter away the vulnerabilities you are not interested in: threat(Array [high | medium | low | log]), exclusion, hostVisibility(included, excluded), assetVisibility(included, excluded), detailLevel(BASE, DETAILED, THOROUGH).For Partners Only:you can specify a client_id to obtain the information about one of your client.classNetworkVulnCollection:@propertydefvulns(self):# gets the network vulnerabilities in the collection.defgroup_by_threat(self,aggr:bool=False,aggr_method:str='count'):# groups vulnerabilities that have the same threat. If aggr is specified, then the number of vulnerabilities in each group is returned.defgroup_by_vuln(self,aggr:bool=False,aggr_method:str='count'):# groups vulnerabilities that have the same vuln_id. If aggr is specified, then the number of vulnerabilities in each group is returned.defgroup_by_asset(self,aggr:bool=False,aggr_method:str='count'):# groups vulnerabilities that have the same asset_id. If aggr is specified, then the number of vulnerabilities in each group is returned.deffilter_by_threat(self,threat:str):# filter away vulnerabilities with threat != @threat.deffilter_by_vuln(self,vuln_id:int):# filter away vulnerabilities with vuln_id != @vuln_id.deffilter_by_asset(self,asset_id:int):# filter away vulnerabilities with vuln_id != @vuln_id.classNetworkHostVuln:asset_id:intasset_name:strhost_id:inthost:strport:strprotocol:strvuln_id:intvulnerability:strthreat:strcvss:floatvuln_excluded:boolhost_excluded:boolasset_excluded:boollast_detection:strfirst_detection:str=Nonehost_label:str=Nonehostname:str=Nonefamily:str=Nonesummary:str=Nonedescription:str=Nonesolution:str=Noneinsight:str=Noneimpact:str=Noneaffected:str=Nonereferences:list[str]=Nonecve:list[str]=Noneget_web_vulns(self, client_id: int = None, asset_id: int = None, host_id: int = None, threat: list = None, exclusion: bool = None, host_visibility: str = None, asset_visibility: str = None, detail: int = None) -> NetworkVulnCollection:gets the collection of all the detected web vulnerabilities. If you are interested in specific assets or specific hosts you can specify them by passing a host_id and/or an asset_id.
Additionally, you can specify some parameters to filter away the vulnerabilities you are not interested in: threat(Array [high | medium | low | log]), exclusion, hostVisibility(included, excluded), assetVisibility(included, excluded), detailLevel(BASE, DETAILED, THOROUGH).For Partners Only:you can specify a client_id to obtain the information about one of your client.classNetworkVulnCollection:@propertydefvulns(self):# gets the network vulnerabilities in the collection.defgroup_by_threat(self,aggr:bool=False,aggr_method:str='count'):# groups vulnerabilities that have the same threat. If aggr is specified, then the number of vulnerabilities in each group is returned.defgroup_by_vuln(self,aggr:bool=False,aggr_method:str='count'):# groups vulnerabilities that have the same vuln_id. If aggr is specified, then the number of vulnerabilities in each group is returned.defgroup_by_asset(self,aggr:bool=False,aggr_method:str='count'):# groups vulnerabilities that have the same asset_id. If aggr is specified, then the number of vulnerabilities in each group is returned.deffilter_by_threat(self,threat:str):# filter away vulnerabilities with threat != @threat.deffilter_by_vuln(self,vuln_id:int):# filter away vulnerabilities with vuln_id != @vuln_id.deffilter_by_asset(self,asset_id:int):# filter away vulnerabilities with vuln_id != @vuln_id.classWebHostVuln:asset_id:intasset_name:strhost_id:inthost:strvuln_id:intvulnerability:strthreat:strvuln_excluded:boolhost_excluded:boolasset_excluded:boollast_detection:strfirst_detection:str=Nonelabel:str=Nonefamily:str=Nonedescription:str=Nonesolution:str=Noneaffected_url_count:int=Noneevidence:str=Noneattack:str=Noneparam:str=Noneother:str=Noneaffected_urls:list[str]=Noneget_technical_info(self, client_id: int = None, days: int = None) -> Trendgets the trend corresponding to the lastdays. The Trend object will include a list of objects containing your data (i.e., index and risk level) over time.For Partners Only:you can specify a client_id to obtain the information about one of your client.classCerbeyraIndex:index:strrisk_level:strexplain:dictclassHistoryInfo:from_date:strto_date:strindex_trend:list[dict]anomalies:dictclassTechnicalInfo:history:HistoryInfoindex:CerbeyraIndexvulnerability_assessment:dictget_network_scans(client_id: int = None, asset_id: int = None, search: str = None, perimeter: str = None, probe: str = None, include_excluded: bool = None, status: str = None, from_date: str = None, to_date: str = None) -> NetworkScanResultCollectiongets the list of all the network scans processed by the platform.For Partners Only:you can specify a client_id to obtain the information about one of your client.classNetworkScanResult:asset_id:intasset_name:strtarget:listtype:str='network'perimeter:strvulns:dictstatus:strstart_at:strend_at:strprobe_id:int=NoneclassNetworkScanResultCollection(list[NetworkScanResult]):defgroup_by_asset(self,aggr:Union[bool,AggregationMethods,None]=None):# group the scans by asset, aggr = True it counts the resultsdefgroup_by_status(self,aggr:Union[bool,AggregationMethods,None]=None):# group the scans by status, aggr = True it counts the resultsdefgroup_by_perimeter(self,aggr:Union[bool,AggregationMethods,None]=None):# group the scans by perimeter, aggr = True it counts the resultsdeffilter_by_asset(self,asset_id:int):# filter the scans by asset iddeffilter_by_status(self,status:str):# filter the scans by statusdeffilter_by_perimeter(self,perimeter:str):# filter the scans by perimeterget_web_scans(client_id: int = None, asset_id: int = None, search: str = None, perimeter: str = None, probe: str = None, include_excluded: bool = None, status: str = None, from_date: str = None, to_date: str = None) -> WebScanResultCollectiongets the list of all the web scans processed by the platform.For Partners Only:you can specify a client_id to obtain the information about one of your client.classWebScanResult:asset_id:intasset_name:strtarget:listtype:str='web'perimeter:strvulns:dictstatus:strstart_at:strend_at:strprobe_id:int=NoneclassWebScanResultCollection(list[WebScanResult]):defgroup_by_asset(self,aggr:Union[bool,AggregationMethods,None]=None):# group the scans by asset, aggr = True it counts the resultsdefgroup_by_status(self,aggr:Union[bool,AggregationMethods,None]=None):# group the scans by status, aggr = True it counts the resultsdefgroup_by_perimeter(self,aggr:Union[bool,AggregationMethods,None]=None):# group the scans by perimeter, aggr = True it counts the resultsdeffilter_by_asset(self,asset_id:int):# filter the scans by asset iddeffilter_by_status(self,status:str):# filter the scans by statusdeffilter_by_perimeter(self,perimeter:str):# filter the scans by perimeterSome typical use cases would befromcerbeyraimportCerbeyraApifromcerbeyra.src.typesimportNetworkReportFields,WebReportFieldsusername="your_cerbeyra_username"password="your_cerbeyra_password"network_columns=[NetworkReportFields.host.value,NetworkReportFields.threat.value]withCerbeyraApi(username=username,password=password)ascerbeyra_api:clients=cerbeyra_api.get_all_clients(active=True)forclientinclients:net_report=cerbeyra_api.get_report_network(columns=network_columns,client_id=client.client_id)csv_path=f"/path/to/report/cilent_{client.client_id}.csv"net_report.save_csv(csv_path)# email_report_to(email=client.email, path=csv_path)fromcerbeyraimportCerbeyraApiusername="your_cerbeyra_username"password="your_cerbeyra_password"withCerbeyraApi(username=username,password=password)ascerbeyra_api:clients=cerbeyra_api.get_all_clients(active=True)forclientinclients:host_collection=cerbeyra_api.get_all_hosts(client.client_id)index_grouped=host_collection.group_by_index()bad_hosts=index_grouped.get('F')# or host_collection.filter_by_index(index='F')ifbad_hosts:print(f'Exporting client ({client.client_id}) hosts ({",".join([host.hostforhostinbad_hosts])}) to .csv')bad_hosts.save_csv(path=f'/path/to/report/cilent_{client.client_id}.csv')