Stations - AVDeskStation class

pyavdesk station resource described by AVDeskStation class exposes an interface to manipulate antivirus stations (PCs).

Note

It is advised to use server resource class AVDeskServer as a single entry point for every server resource manipulation instead of direct instantiation of AVDeskStation class.

Basic class usage example:

# Setting up server connection parameters.
av_server = pyavdesk.AVDeskServer('admin', 'password', 'http://192.168.1.70')

# Create a new station.
new_station = av_server.new_station()
new_station.save()

# Output generated station ID.
print new_station.id
class pyavdesk.pyavdesk.AVDeskStation(connector_resource, resource_id=None, predefined_handle=None)

AV-Desk station resource class is used to perform stations manipulations.

Parameters:
  • connector_resource – should be AVDeskServer instance.
  • resource_id – if set server call is performed to get information for resource with given ID.
  • predefined_handle – if set, resource data could be fetched from a resource at given handle.
Raises:

AVDeskError on failure

add_emails(emails_list)

Adds given emails to a list of e-mails defined for the resource.

Note

This method does not send data to server, for this to be done one needs to save resource object.

Parameters:emails_list – list of e-mails

Example:

resource_obj.add_emails(['person1@server.com', 'person2@server.com'])
add_to_groups(groups_list)

Add groups to resource association by group IDs or objects.

Parameters:groups_list – list of AVDeskGroup instances, or a list of strings representing groups IDs
Raises:AVDeskError on failure

Note

Resource to group association is not sent to server until object’s save() is not called.

Warning

Some AV-Desk server versions (namely 6.2) might handle only one group per administrator. In that case only the first group from the given list is linked with the administrator.

Example:

resource_obj.add_to_groups(['my_group_id', my_another_group_obj])
resource_obj.save()
create(auto_retrieve=True)

Performs a server call to create resource with properties defined in object.

Note

There is a convinience method save() to handle both create and update operations.

Parameters:auto_retrieve – boolean to specify whether an additional call to server is required after the create operation to retrieve full resource data. Default: True.
Returns:True on success
Raises:AVDeskError on failure

Warning

Setting auto_retrieve to False may increase operation performance, but also may leave the resource object data in a not up-to-date state. It is advised that auto_retrieve set to False is only used when the resource object won’t be used further after the operation.

Example:

created = resource_obj.create()
delete(**kwargs)

Performs server call in an attempt to delete the resource.

Returns:True on success
Raises:AVDeskError on failure

Example:

deleted = resource_obj.delete()
delete_emails(emails_list)

Removes given emails from a list of e-mails defined for the resource.

Note

This method does not send data to server, for this to be done one needs to save resource object.

Parameters:emails_list – list of e-mails

Example:

resource_obj.delete_emails(['person1@server.com', 'person2@server.com', 'person3@server.com'])
delete_from_groups(groups_list)

Removes groups to resource association by group IDs or objects.

Parameters:groups_list – list of AVDeskGroup instances, or a list of strings representing groups IDs
Raises:AVDeskError on failure

Note

Resource to group association is not sent to server until object’s save() is not called.

Example:

resource_obj.delete_from_groups(['my_group_id', my_another_group_obj])
resource_obj.save()
download_url

This property is used to get station’s download URL as string.

expires_time

This property is used to get and set station’s expires datetime (as unix timestamp).

get_av_bases()

Returns a list of antivirus bases used by station.

Returns:list of dictionaries with av bases data
Raises:AVDeskError on failure

Example:

av_bases = station.get_av_bases()

An extract from returned list:

[
    {
        'file_name': 'drw50001.vdb',
        'created_ts': 1320059155,
        'version': '500',
        'viruses': 24512
    },
    ...
]
get_av_components()

Performs a server call to retrieve a list of antivirus application components information for the resource.

Returns:list of dictionaries with components data
Raises:AVDeskError on failure

Example:

components = resource_obj.get_av_components()

An extract from returned list:

[
    {
        'status': 1,
        'code': 105,
        'parent_group_id': '2888b7ff-3625-465e-bcb8-957de17f6458',
        'code_text': 'Dr.Web Firewall',
        'status_text': 'Optional',
        ...
    },
    ...
]
get_av_components_installed()

Returns a list of antivirus application components installed at the station.

Returns:list of dictionaries with components data
Raises:AVDeskError on failure

Example:

installed = station.get_av_components_installed()

An extract from returned list:

[
    {
        'path': 'C:\Program Files\DrWeb AV-Desk',
        'code': 103,
        'code_text': 'Dr.Web Microsoft Outlook plugin',
        'server': 'tcp/94.251.81.210:2193',
        'installed_ts': 1320062616
    },
    ...
]
get_av_components_running()

Returns a list of antivirus application components running at the station.

Returns:list of dictionaries with components data
Raises:AVDeskError on failure

Example:

running = station.get_av_components_running()

An extract from returned list:

[
    {
        'code': 30,
        'code_text': 'Dr.Web AV-Desk Agent for Windows',
        'started_ts': 1320523510,
        'params': None,
        'user': None,
        'type': 8
    },
    ...
]
get_av_modules()

Returns a list of antivirus modules used by the station.

Returns:list of dictionaries with modules data
Raises:AVDeskError on failure

Example:

modules = station.get_av_modules()

An extract from returned list:

[
    {
        'hash': '78a61d78e110fbf27975df4a4dc70dfc',
        'name': 'Dr.Web(c) Scanner for Windows',
        'created_ts': 1320062617,
        'modified_ts': 1320062530,
        'file_name': 'DRWEB32W.EXE',
        'version': '6.00.11.7112',
        'file_size': 2299656
    },
    ...
]
get_av_packages()

Returns a list of antivirus agent download URLs for various platforms.

Returns:list of dictionaries with av packages data
Raises:AVDeskError on failure

Example:

av_packages = station.get_av_packages()

An extract from returned list:

[
    {
        'url': 'http://localhost/download/download.ds?id=some_id',
        'type': 1
    },
    ...
]
get_av_rights()

Performs a server call to retrieve a list of rights defined for the resource.

Returns:list of dictionaries with rigths data
Raises:AVDeskError on failure

Example:

rights = resource_obj.get_av_rights()

An extract from returned list:

[
    {
        'status': 1,
        'code': 53,
        'parent_group_id': '2888b7ff-3625-465e-bcb8-957de17f6458',
        'code_text': 'Uninstall Dr.Web Agent',
        'status_text': 'Enabled',
        ...
    },
    ...
]
get_block_time()

Returns a tuple with information about station blocking: begin and end unix timestamps.

Returns:list of dictionaries with modules data
Raises:AVDeskError on failure

Example:

start_at, finish_at = station.get_block_time()
get_emails()

Returns a list of e-mails defined for the resource.

Returns:list of e-mails

Example:

emails = resource_obj.get_emails()
get_groups(as_id=True)

Performs a server call and returns a list of groups associated with the resource.

Parameters:as_id – boolean. If True list of AVDeskGroup instances is returned, if False - list of strings representing groups IDs
Returns:list of objects which type is defined by as_id parameter
Raises:AVDeskError on failure

Note

Objects in the list returned have only basic information. To get full infomation use AVDeskGroup.retrieve_info().

Example:

groups = resource_obj.get_groups()
for group in groups:
    print 'Group ID - %s' % group.id
get_history(ts_from=0, ts_till=0, event_type_filter=None)

Performs a server call to retrieve station history information.

Parameters:
  • ts_from – timestamp of when history starts. If 0 - history starts at year 1970. Default 0.
  • ts_till – timestamp of when history ends. If 0 - history ends today. Default 0.
  • event_type_filter – event type identifier (see HISTORY_EVENT_TYPES) to filter history upon.
Returns:

list of dictionaries with events data

Raises:

AVDeskError on failure

Example:

history = station.get_history()

An extract from returned list:

[
    {
        'created_ts': 4294967295,
        'action_ts': 4294967295,
        'action_start_ts': 0,
        'action_finish_ts': 0,
        'tariff': None,
        'tariff_name': None,
        'event_type_id': 5
    },
    ...
]
get_key()

Performs a server call to retrieve a dictionary with key information for the resource.

Returns:dictionary with key information
Raises:AVDeskError on failure

Example:

key = resource_obj.get_key()

An example of returned dictionary:

{
    'inherited_group_id': '20e27d73-d21d-b211-a788-85419c46f0e6',
    'key': '=?ASCII?B?OyBEcldlYjMyIHY0LjE2?=' # This is a key in Base64 format.
}
get_parent(as_id=True)

Performs a server call to retrieve a parent resource for the current resource.

Parameters:as_id – boolean. If True resource object is returned, if False - resources’ ID
Returns:object or ID. See as_id parameter.
Raises:AVDeskError on failure

Example:

parent = resource_obj.get_parent()
print 'Parent ID - %s' % parent
get_place_data()

Performs a server call to retrieve station’s place information as dictionary.

Returns:dictionary
Raises:AVDeskError on failure

Example:

place = station.get_place_data()

An extract from dictionary returned:

{
    'province': 'Academgorodok',
    'city': 'Novosibirsk',
    'street': 'Some street',
    'room': None,
    'organization': 'Doctor Web, Ltd.',
    'latitude': 0,
    'longitude': 0,
    'country': 643,
    'floor': None,
    'department': None
}
get_resource_id()

Helper method to get resource identifier, which can be passed to such resource manipulation methods as get_info() and delete().

Returns:resource identifier as string
get_statistics(ts_from=0, ts_till=0, virus_limit=10)

Makes request to a server and returns a dictionary with station statistics.

Parameters:
  • ts_from – timestamp of when statistics starts. If 0 - statistics starts at year 1970. Default 0.
  • ts_till – timestamp of when staristics ends. If 0 - statistics ends today. Default 0.
  • virus_limit – virus statistics limiter, to return no more than a given number of viruses. Default 10.
Returns:

dictionary

Raises:

AVDeskError on failure

Example:

stats = station.get_statistics()

An extract from dictionary returned:

{
    'viruses': [
        {
            'name': 'Trojan.Spambot',
            'count': 3,
            'objects_list': [
                {
                    'originator': 57,
                     'originator_text': 'SpIDer Guard G3 for Workstations',
                     'owner': 'Unknown',
                      ...
                },
                ...
            ],
        },
    'scans': {
        'files': 128,
        'cured': 28,
         ...
    },
    'infections': {
        'ignored': 0,
        'errors': 0,
        'deleted': 28,
         ...
    },
    'stations_total': 1,
    'stations_state': {
        'unactivated': 0,
        'deinstalled': 0,
        'online': 1,
        ...
    }
}
get_tariff(as_id=True)

Performs a server call to retrieve a tariff resource for the station.

Parameters:as_id – boolean. If True AVDeskTariff object is returned, if False - tariff ID
Returns:object or ID. See as_id parameter.
Raises:AVDeskError on failure

Example:

tariff_id = resource_obj.get_tariff()
print 'Station tariff ID - %s' % tariff_id
grace_period

This property is used to get station’s grace period (in days) inherited from tariff group.

key

Performs a server call to retrieve a dictionary with key information for the resource.

Returns:dictionary with key information
Raises:AVDeskError on failure

Example:

key = resource_obj.get_key()

An example of returned dictionary:

{
    'inherited_group_id': '20e27d73-d21d-b211-a788-85419c46f0e6',
    'key': '=?ASCII?B?OyBEcldlYjMyIHY0LjE2?=' # This is a key in Base64 format.
}
last_seen_addr

This property is used to get station’s last seen network address as string.

last_seen_time

This property is used to get station’s last seen unix timestamp.

os

This property is used to get station’s OS as string.

parent

Performs a server call to retrieve a parent resource for the current resource.

Parameters:as_id – boolean. If True resource object is returned, if False - resources’ ID
Returns:object or ID. See as_id parameter.
Raises:AVDeskError on failure

Example:

parent = resource_obj.get_parent()
print 'Parent ID - %s' % parent
password

This property is used to get and station’s password.

place_data

Performs a server call to retrieve station’s place information as dictionary.

Returns:dictionary
Raises:AVDeskError on failure

Example:

place = station.get_place_data()

An extract from dictionary returned:

{
    'province': 'Academgorodok',
    'city': 'Novosibirsk',
    'street': 'Some street',
    'room': None,
    'organization': 'Doctor Web, Ltd.',
    'latitude': 0,
    'longitude': 0,
    'country': 643,
    'floor': None,
    'department': None
}
retrieve_info(resource_id=None)

Performs a server call to retrieve complete resource information by its ID and puts it into object’s properties.

Parameters:resource_id – specific ID of the resource. If None, ID is taken from the object itself.
Raises:AVDeskError on failure

Example:

# resource_obj contains no additional info.
assert resource_obj.name is None

# After the following request
resource_obj.retrieve_info('some_resource_id')

# resource_obj contains additional info.
assert resource_obj.name is not None
save(auto_retrieve=True)

A convinience method that automatically creates new resource on server if it doesn’t exists or updates it if it does.

Under the hood it switches between create() and update() methods.

Parameters:auto_retrieve – boolean to specify whether an additional call to server is required after the save operation to retrieve full resource data. Default: True.
Returns:True on success
Raises:AVDeskError on failure

Warning

Setting auto_retrieve to False may increase operation performance, but also may leave the resource object data in a not up-to-date state. It is advised that auto_retrieve set to False is only used when the resource object won’t be used further after the operation.

Example:

saved = resource_obj.save()
send_message(message_text, url='', url_text='', logo_abs_path='', logo_text='', logo_url='')

Sends a message to all group participants.

Parameters:
  • message_text – Message text which can contain {link} macros to place link given in link parameters to
  • url – URL to be placed in {link} macros
  • url_text – URL description text to be placed in {link} macros
  • logo_abs_path – Absolute path to a logo .bmp file to show in message
  • logo_text – Description text for a logo
  • logo_url – URL to go to on a logo click
Returns:

True on success

Raises:

AVDeskError on failure

Example:

group.send_message('Hello from pyavdesk!')
set_block_time(begin_at, finish_at)

Sets blocking information for the station.

Parameters:
  • begin_at – Block begin unix timestamp
  • finish_at – Block end unix timestamp
Returns:

True on success

Raises:

AVDeskError on failure

Example:

station.set_block_time(start_at, finish_at)
set_parent(id_or_obj)

Sets parent resource for the current resource.

Parameters:id_or_obj – Parent resource object or ID.
Raises:AVDeskError on failure

Example:

child_resource_obj.set_parent(parent_resource_obj)
# Is equivalent to:
child_resource_obj.set_parent('parent_resource_id')
set_place_data(country=None, latitude=None, longitude=None, province=None, city=None, street=None, organization=None, department=None, floor=None, room=None)

Sets information about station’s place.

Parameters:
  • country – ISO numeric country code integer - (see http://en.wikipedia.org/wiki/ISO_3166-1_numeric)
  • latitude – Latitude as integer
  • longitude – Latitude as integer
  • province – Province name string
  • city – City name string
  • street – Street name string
  • organization – Organization name string
  • department – Department name string
  • floor – Floor string
  • room – Room string

Example:

# Selectively set country and organization name for the station.
station.set_place_data(country=643, organization='Doctor Web, Ltd.')
set_tariff(id_or_obj)

Sets tariff for the current station.

Parameters:id_or_obj – Tariff resource object or ID.
Raises:AVDeskError on failure

Example:

station.set_tariff(tariff_resource_obj)
# Is equivalent to:
station.set_tariff('tariff_resource_id')
state

This property is used to get station’s current state as string (e.g. online).

statistics

Makes request to a server and returns a dictionary with station statistics.

Parameters:
  • ts_from – timestamp of when statistics starts. If 0 - statistics starts at year 1970. Default 0.
  • ts_till – timestamp of when staristics ends. If 0 - statistics ends today. Default 0.
  • virus_limit – virus statistics limiter, to return no more than a given number of viruses. Default 10.
Returns:

dictionary

Raises:

AVDeskError on failure

Example:

stats = station.get_statistics()

An extract from dictionary returned:

{
    'viruses': [
        {
            'name': 'Trojan.Spambot',
            'count': 3,
            'objects_list': [
                {
                    'originator': 57,
                     'originator_text': 'SpIDer Guard G3 for Workstations',
                     'owner': 'Unknown',
                      ...
                },
                ...
            ],
        },
    'scans': {
        'files': 128,
        'cured': 28,
         ...
    },
    'infections': {
        'ignored': 0,
        'errors': 0,
        'deleted': 28,
         ...
    },
    'stations_total': 1,
    'stations_state': {
        'unactivated': 0,
        'deinstalled': 0,
        'online': 1,
        ...
    }
}
tariff

Performs a server call to retrieve a tariff resource for the station.

Parameters:as_id – boolean. If True AVDeskTariff object is returned, if False - tariff ID
Returns:object or ID. See as_id parameter.
Raises:AVDeskError on failure

Example:

tariff_id = resource_obj.get_tariff()
print 'Station tariff ID - %s' % tariff_id
update(auto_retrieve=True)

Performs server call in attempt to update the resource with information from class properties.

Note

There is a convinience method save() to handle both create and update operations.

Parameters:auto_retrieve – boolean to specify whether an additional call to server is required after the update operation to retrieve full resource data. Default: True.
Returns:True on success
Raises:AVDeskError on failure

Warning

Setting auto_retrieve to False may increase operation performance, but also may leave the resource object data in a not up-to-date state. It is advised that auto_retrieve set to False is only used when the resource object won’t be used further after the operation.

Example:

updated = resource_obj.update()