cyrating 1.0.18

Python wrapper for https://www.cyrating.com

python-cyrating

A python wrapper for Cyrating https://www.cyrating.com.

Installation

pip install cyrating

Then in your application root directory use the following command to set up your configuration including your Cyrating token which is provided in your user interface:

echo -e "[cyrating]\ntoken: cyratingtoken" > cyrating.ini

Usage example

>>> import cyrating
>>> cr = cyrating.init()

The init method takes into account 2 optional parameters:

• token: the Cyrating token
• proxies: the list of proxies to use when making a request. See requests docs for more information

Additional methods listed below are available

Method	Description
main_company	returns the structure of the main company
entities	returns a list of entities
suppliers	returns a list of suppliers
competitors	returns a list of competitors
domains	returns a list of domains for a company
assets	returns a list of assets for a given company
technologies	returns a list of identified technologies for a given company
set_tags	sets tags to a given domain (require admin privileges)
facts	returns the results of best practices controls
events	returns a list of active reputation events
certificate	returns a certificate of a given company
members	returns a list of members, including child subscriptions' ones (require admin privileges)
rating_history	returns a list of the last 52 ratings numbers for a given company
scope	returns a list of the last 52 scopes (domain names) taking into account for rating of a given company
scope_trends	returns a list of the last applied scope updates including added and removed domains
add_asset	request to add an asset to the rating's scope for a given company
remove_asset	request to remove an asset from the rating's scope for a given company
cancel_update	request to cancel a request of a scope update an asset
scope_updates	returns a list of the requested added and removed domains for a given compnany

Examples

Get info of the main company The method main_company returns a company identified as the main company.

>>> cr.main_company()
[...]

Get the list of entities The method entities returns the list of companies identified as entities.

>>> cr.entities()
[...]

Get the list of suppliers The method suppliers returns the list of companies identified as suppliers.

>>> cr.suppliers()
[...]

Get the list of competitors The method competitors returns the list of companies identified as competitors.

>>> cr.suppliers()
[...]

Tag a domain or an AS Number The method set_tags affects a list of tags to a domain name or an AS Number. All assets related with this domain name or with this AS Number will be updated too.

>>> cr.set_tags('example.com', ['tag1', 'tag2'])
[...]
>>> cr.set_tags('ASXXXXX', ['tag3'])
[...]

Get the list of assets

The method assets returns a list of assets with tags and type attributes. Each key of this dictionary represents an asset and is linked to the following attributes:

• asset: the asset name
• type: type of the asset, may be 'domain', 'host' or 'ip'
• country: geolocation data for IP assets only
• entities: list of entities linked with the asset. Entities are the ones included in the subscription.
• tags: list of tags linked with the asset
• related: list of assets linked with the asset
• domains: list of domains linked with the asset

>>> cr.assets(main_company)
[...]

Get the list of detected technologies

The method technologies returns a list of detected technologies for a given company. assets parameter is optional and is needed to provide tags association

Each item of the detected technologies includes the following attributes:

• name: name of the detected technology
• category: name of the technology category
• asset: name of the asset supporting the detected technology
• domain: domain name / AS Number linked with the asset
• entities: list of entities linked with the asset. Entities are the ones included in the subscription.
• tags: list of tags linked with the asset

>>> main_company = cr.main_company()
>>> cr.technologies(main_company, assets=cr.assets(main_company))
[...]

Get the results of best practices controls

The method facts returns the results of best practices controls. assets parameter is optional and is needed to provide tags association. extra_filter is also an optional to filter results server-side.

Each item of the results includes the following attributes:

• domain: domain name / AS Number linked with the asset
• category: name of the best practice's category
• entities: list of entities linked with the asset. Entities are the ones included in the subscription.
• tags: list of tags linked with the asset
• type: type of the asset, may be 'domain', 'host' or 'ip'
• name: name of the resource
• results: raw results of the control
• grade: unitary score of the control
• impact: impact on rating of controls which lead to a downgrade.

>>> main_company = cr.main_company()
>>> cr.facts(main_company, assets=cr.assets(main_company))
[...]

Get the list of active reputation events

The method events returns a list of active reputation events. assets parameter is optional and is needed to provide tags association.

An active reputation event includes the following attributes:

• name: name of the asset concerned
• category: name of the reputation's category
• domains: list of domains / AS Numbers linked with the asset
• entities: list of entities linked with the asset. Entities are the ones included in the subscription.
• tags: list of tags linked with the asset
• type: type of the asset, may be 'domain', 'host' or 'ip'
• source: a dictionary with the tag and the url of the reputation source
• occurrences: dates of occurrences of the event
• score: deprecated, replaced by impact
• impact: impact on rating of the company. Please note that Cyrating algorithm streamlines this score by resource and reputation's category

>>> main_company = cr.main_company()
>>> cr.events(main_company, assets=cr.assets(main_company))
[...]

Returns certificate of a given company

>>> main_company = cr.main_company()
>>> cr.certificate(main_company)

Save the certificate of a given company to a file

>>> main_company = cr.main_company()
>>> cr.certificate(main_company, filename='Cyrating - Certificate of {}.pdf'.format(main_company['name']))

Get the list of members

>>> cr.members()
[...]

Get a list of the last 52 ratings for a given company

>>> main_company = cr.main_company()
>>> cr.rating_history(main_company)
[...]

Get a list of the last 52 scopes for a given company

The method scope returns a list of the last 52 scopes for a given company. A scope is a list of domain names taking into account for rating of a given company

A scope includes the following attribute:

• domainnames: list of domains names supporting our rating

>>> main_company = cr.main_company()
>>> cr.scope(main_company)
[...]

Get a list of scope trends

An additional method is available to get scope trends for a given company including added domains and removed domains between several ratings.

A scope includes the following attributes:

• added: domains added to a rating scope
• removed: domains removed from a rating scope
• date: date of rating

>>> main_company = cr.main_company()
>>> scope = cr.scope(main_company)
>>> updates = cr.scope_trends(scope)
[...]

Ask to add an asset

The method add_asset ask to add an asset to current scope for a specific company. You can define the type of the asset to add ('domain', 'subdomain') and optionnal tags related to the asset.

>>> cr.add_asset(company=main_company, name="domainname_to_add", type="domain", tags=['tag1', 'tag2'])

Ask to remove an asset

The method remove_asset ask to remove an asset from current scope for a specific company.

>>> cr.remove_asset(company=main_company, name="domainname_to_remove", type="domain")

Cancel a requested scope update

The method cancel_update is to cancel a requested scope update for a specific company.

>>> cr.cancel_update(company=main_company, name="domainname_to_remove")

Get the list of requested scope updates

The method scope_updates returns the list of requested scope updates to cancel for a specific company.

>>> cr.scope_updates(company=main_company)
[...]

Regression

After version 1.0.15, the method assets returns a list instead of a dictionary. After version 1.0.18, the method scope_updates have been renamed scope_trends. A new method scope_updates return the current requested scope updates.

Meta

Cyrating – @cyrating – [e-mail]

Distributed under the ISCL licence. See LICENSE for more information.

Contributing

1. Send issues to [e-mail]