Passed
Pull Request — master (#267)
by Björn
01:33
created

gvm.protocols.gmpv7.gmpv7._check_event()   D

Complexity

Conditions 12

Size

Total Lines 73
Code Lines 54

Duplication

Lines 0
Ratio 0 %

Importance

Changes 0
Metric Value
cc 12
eloc 54
nop 3
dl 0
loc 73
rs 4.8
c 0
b 0
f 0

How to fix   Long Method    Complexity   

Long Method

Small methods make your code easier to understand, in particular if combined with a good name. Besides, if your method is small, finding a good name is usually much easier.

For example, if you find yourself adding comments to a method's body, this is usually a good sign to extract the commented part to a new method, and use the comment as a starting point when coming up with a good name for this new method.

Commonly applied refactorings include:

Complexity

Complex classes like gvm.protocols.gmpv7.gmpv7._check_event() often do a lot of different things. To break such a class down, we need to identify a cohesive component within that class. A common approach to find such a component is to look for fields/methods that share the same prefixes, or suffixes.

Once you have determined the fields that belong together, you can apply the Extract Class refactoring. If the component makes sense as a sub-class, Extract Subclass is also a candidate, and is often faster.

1
# -*- coding: utf-8 -*-
2
# Copyright (C) 2018 - 2019 Greenbone Networks GmbH
3
#
4
# SPDX-License-Identifier: GPL-3.0-or-later
5
#
6
# This program is free software: you can redistribute it and/or modify
7
# it under the terms of the GNU General Public License as published by
8
# the Free Software Foundation, either version 3 of the License, or
9
# (at your option) any later version.
10
#
11
# This program is distributed in the hope that it will be useful,
12
# but WITHOUT ANY WARRANTY; without even the implied warranty of
13
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14
# GNU General Public License for more details.
15
#
16
# You should have received a copy of the GNU General Public License
17
# along with this program.  If not, see <http://www.gnu.org/licenses/>.
18
19
# pylint: disable=too-many-lines,redefined-builtin
20
"""
21
Module for communication with gvmd in `Greenbone Management Protocol version 7`_
22
23
.. _Greenbone Management Protocol version 7:
24
    https://docs.greenbone.net/API/GMP/gmp-7.0.html
25
"""
26
import base64
27
import collections
28
import logging
29
import numbers
30
31
from typing import Any, List, Optional, Callable
32
33
from lxml import etree
34
35
from gvm.connections import GvmConnection
36
from gvm.errors import InvalidArgument, InvalidArgumentType, RequiredArgument
37
from gvm.utils import deprecation
38
39
from gvm.xml import create_parser, XmlCommand
40
41
from gvm.protocols.base import GvmProtocol
42
43
from . import types
44
from .types import *  # pylint: disable=unused-wildcard-import, wildcard-import
45
46
47
logger = logging.getLogger(__name__)
48
49
Severity = numbers.Real
50
51
52
def _check_command_status(xml: str) -> bool:
53
    """Check gmp response
54
55
    Look into the gmp response and check for the status in the root element
56
57
    Arguments:
58
        xml: XML-Source
59
60
    Returns:
61
        True if valid, otherwise False
62
    """
63
64
    if xml == 0 or xml is None:
65
        logger.error("XML Command is empty")
66
        return False
67
68
    try:
69
        root = etree.XML(xml, parser=create_parser())
70
        status = root.attrib["status"]
71
        return status is not None and status[0] == "2"
72
73
    except etree.Error as e:
74
        logger.error("etree.XML(xml): %s", e)
75
        return False
76
77
78
def _to_bool(value: bool) -> str:
79
    return "1" if value else "0"
80
81
82
def _to_base64(value: str) -> bytes:
83
    return base64.b64encode(value.encode("utf-8"))
84
85
86
def _to_comma_list(value: List) -> str:
87
    return ",".join(value)
88
89
90
def _add_filter(cmd, filter, filter_id):
91
    if filter:
92
        cmd.set_attribute("filter", filter)
93
94
    if filter_id:
95
        cmd.set_attribute("filt_id", filter_id)
96
97
98
def _is_list_like(value: Any) -> bool:
99
    return isinstance(value, (list, tuple))
100
101
102
def _check_event(
103
    event: AlertEvent, condition: AlertCondition, method: AlertMethod
104
):
105
    if event == AlertEvent.TASK_RUN_STATUS_CHANGED:
106
        if not condition:
107
            raise RequiredArgument(
108
                "condition is required for event {}".format(event.name),
109
            )
110
111
        if not method:
112
            raise RequiredArgument(
113
                "method is required for event {}".format(event.name),
114
            )
115
116
        if condition not in (
117
            AlertCondition.ALWAYS,
118
            AlertCondition.FILTER_COUNT_CHANGED,
119
            AlertCondition.FILTER_COUNT_AT_LEAST,
120
            AlertCondition.SEVERITY_AT_LEAST,
121
        ):
122
            raise InvalidArgument(
123
                "Invalid condition {} for event {}".format(
124
                    condition.name, event.name
125
                )
126
            )
127
        if method not in (
128
            AlertMethod.SCP,
129
            AlertMethod.SEND,
130
            AlertMethod.SMB,
131
            AlertMethod.SNMP,
132
            AlertMethod.SYSLOG,
133
            AlertMethod.EMAIL,
134
            AlertMethod.START_TASK,
135
            AlertMethod.HTTP_GET,
136
            AlertMethod.SOURCEFIRE_CONNECTOR,
137
            AlertMethod.VERINICE_CONNECTOR,
138
        ):
139
            raise InvalidArgument(
140
                "Invalid method {} for event {}".format(method.name, event.name)
141
            )
142
    elif event in (
143
        AlertEvent.NEW_SECINFO_ARRIVED,
144
        AlertEvent.UPDATED_SECINFO_ARRIVED,
145
    ):
146
        if not condition:
147
            raise RequiredArgument(
148
                "condition is required for event {}".format(event.name),
149
            )
150
151
        if not method:
152
            raise RequiredArgument(
153
                "method is required for event {}".format(event.name),
154
            )
155
156
        if condition not in (AlertCondition.ALWAYS,):
157
            raise InvalidArgument(
158
                "Invalid condition {} for event {}".format(
159
                    condition.name, event.name
160
                )
161
            )
162
        if method not in (
163
            AlertMethod.SCP,
164
            AlertMethod.SEND,
165
            AlertMethod.SMB,
166
            AlertMethod.SNMP,
167
            AlertMethod.SYSLOG,
168
            AlertMethod.EMAIL,
169
        ):
170
            raise InvalidArgument(
171
                "Invalid method {} for event {}".format(method.name, event.name)
172
            )
173
    elif event is not None:
174
        raise InvalidArgument('Invalid event "{}"'.format(event.name))
175
176
177
class GmpV7Mixin(GvmProtocol):
178
    """Python interface for Greenbone Management Protocol
179
180
    This class implements the `Greenbone Management Protocol version 7`_
181
182
    Arguments:
183
        connection: Connection to use to talk with the gvmd daemon. See
184
            :mod:`gvm.connections` for possible connection types.
185
        transform: Optional transform `callable`_ to convert response data.
186
            After each request the callable gets passed the plain response data
187
            which can be used to check the data and/or conversion into different
188
            representations like a xml dom.
189
190
            See :mod:`gvm.transforms` for existing transforms.
191
192
    .. _Greenbone Management Protocol version 7:
193
        https://docs.greenbone.net/API/GMP/gmp-7.0.html
194
    .. _callable:
195
        https://docs.python.org/3/library/functions.html#callable
196
    """
197
198
    types = types
0 ignored issues
show
Comprehensibility Best Practice introduced by
The variable types does not seem to be defined.
Loading history...
199
200
    def __init__(
201
        self,
202
        connection: GvmConnection,
203
        *,
204
        transform: Optional[Callable[[str], Any]] = None
205
    ):
206
        super().__init__(connection, transform=transform)
207
208
        # Is authenticated on gvmd
209
        self._authenticated = False
210
211
    def is_authenticated(self) -> bool:
212
        """Checks if the user is authenticated
213
214
        If the user is authenticated privileged GMP commands like get_tasks
215
        may be send to gvmd.
216
217
        Returns:
218
            bool: True if an authenticated connection to gvmd has been
219
            established.
220
        """
221
        return self._authenticated
222
223
    def authenticate(self, username: str, password: str) -> Any:
224
        """Authenticate to gvmd.
225
226
        The generated authenticate command will be send to server.
227
        Afterwards the response is read, transformed and returned.
228
229
        Arguments:
230
            username: Username
231
            password: Password
232
233
        Returns:
234
            Transformed response from server.
235
        """
236
        cmd = XmlCommand("authenticate")
237
238
        if not username:
239
            raise RequiredArgument(
240
                function=self.authenticate.__name__, argument='username'
241
            )
242
243
        if not password:
244
            raise RequiredArgument(
245
                function=self.authenticate.__name__, argument='password'
246
            )
247
248
        credentials = cmd.add_element("credentials")
249
        credentials.add_element("username", username)
250
        credentials.add_element("password", password)
251
252
        self._send(cmd.to_string())
253
        response = self._read()
254
255
        if _check_command_status(response):
256
            self._authenticated = True
257
258
        return self._transform(response)
259
260
    def create_agent(
261
        self,
262
        installer: str,
263
        signature: str,
264
        name: str,
265
        *,
266
        comment: Optional[str] = None,
267
        howto_install: Optional[str] = None,
268
        howto_use: Optional[str] = None
269
    ) -> Any:
270
        """Create a new agent
271
272
        Arguments:
273
            installer: A base64 encoded file that installs the agent on a
274
                target machine
275
            signature: A detached OpenPGP signature of the installer
276
            name: A name for the agent
277
            comment: A comment for the agent
278
            howto_install: A file that describes how to install the agent
279
            howto_use: A file that describes how to use the agent
280
281
        Returns:
282
            The response. See :py:meth:`send_command` for details.
283
        """
284
        if not name:
285
            raise RequiredArgument(
286
                function=self.create_agent.__name__, argument='name'
287
            )
288
289
        if not installer:
290
            raise RequiredArgument(
291
                function=self.create_agent.__name__, argument='installer'
292
            )
293
294
        if not signature:
295
            raise RequiredArgument(
296
                function=self.create_agent.__name__, argument='signature'
297
            )
298
299
        cmd = XmlCommand("create_agent")
300
        cmd.add_element("installer", installer)
301
        cmd.add_element("signature", signature)
302
        cmd.add_element("name", name)
303
304
        if comment:
305
            cmd.add_element("comment", comment)
306
307
        if howto_install:
308
            cmd.add_element("howto_install", howto_install)
309
310
        if howto_use:
311
            cmd.add_element("howto_use", howto_use)
312
313
        return self._send_xml_command(cmd)
314
315
    def clone_agent(self, agent_id: str) -> Any:
316
        """Clone an existing agent
317
318
        Arguments:
319
            agent_id: UUID of an existing agent to clone from
320
321
        Returns:
322
            The response. See :py:meth:`send_command` for details.
323
        """
324
        if not agent_id:
325
            raise RequiredArgument(
326
                function=self.clone_agent.__name__, argument='agent_id'
327
            )
328
329
        cmd = XmlCommand("create_agent")
330
        cmd.add_element("copy", agent_id)
331
        return self._send_xml_command(cmd)
332
333
    def create_alert(
334
        self,
335
        name: str,
336
        condition: AlertCondition,
337
        event: AlertEvent,
338
        method: AlertMethod,
339
        *,
340
        method_data: Optional[dict] = None,
341
        event_data: Optional[dict] = None,
342
        condition_data: Optional[dict] = None,
343
        filter_id: Optional[int] = None,
344
        comment: Optional[str] = None
345
    ) -> Any:
346
        """Create a new alert
347
348
        Arguments:
349
            name: Name of the new Alert
350
            condition: The condition that must be satisfied for the alert
351
                to occur; if the event is either 'Updated SecInfo arrived' or
352
                'New SecInfo arrived', condition must be 'Always'. Otherwise,
353
                condition can also be on of 'Severity at least', 'Filter count
354
                changed' or 'Filter count at least'.
355
            event: The event that must happen for the alert to occur, one
356
                of 'Task run status changed', 'Updated SecInfo arrived' or 'New
357
                SecInfo arrived'
358
            method: The method by which the user is alerted, one of 'SCP',
359
                'Send', 'SMB', 'SNMP', 'Syslog' or 'Email'; if the event is
360
                neither 'Updated SecInfo arrived' nor 'New SecInfo arrived',
361
                method can also be one of 'Start Task', 'HTTP Get', 'Sourcefire
362
                Connector' or 'verinice Connector'.
363
            condition_data: Data that defines the condition
364
            event_data: Data that defines the event
365
            method_data: Data that defines the method
366
            filter_id: Filter to apply when executing alert
367
            comment: Comment for the alert
368
369
        Returns:
370
            The response. See :py:meth:`send_command` for details.
371
        """
372
        if not name:
373
            raise RequiredArgument(
374
                function=self.create_alert.__name__, argument='name'
375
            )
376
377
        if not condition:
378
            raise RequiredArgument(
379
                function=self.create_alert.__name__, argument='condition'
380
            )
381
382
        if not event:
383
            raise RequiredArgument(
384
                function=self.create_alert.__name__, argument='event'
385
            )
386
387
        if not method:
388
            raise RequiredArgument(
389
                function=self.create_alert.__name__, argument='method'
390
            )
391
392
        if not isinstance(condition, AlertCondition):
393
            raise InvalidArgumentType(
394
                function=self.create_alert.__name__,
395
                argument='condition',
396
                arg_type=AlertCondition.__name__,
397
            )
398
399
        if not isinstance(event, AlertEvent):
400
            raise InvalidArgumentType(
401
                function=self.create_alert.__name__,
402
                argument='even',
403
                arg_type=AlertEvent.__name__,
404
            )
405
406
        if not isinstance(method, AlertMethod):
407
            raise InvalidArgumentType(
408
                function=self.create_alert.__name__,
409
                argument='method',
410
                arg_type=AlertMethod.__name__,
411
            )
412
413
        _check_event(event, condition, method)
414
415
        cmd = XmlCommand("create_alert")
416
        cmd.add_element("name", name)
417
418
        conditions = cmd.add_element("condition", condition.value)
419
420
        if condition_data is not None:
421
            for key, value in condition_data.items():
422
                _data = conditions.add_element("data", value)
423
                _data.add_element("name", key)
424
425
        events = cmd.add_element("event", event.value)
426
427
        if event_data is not None:
428
            for key, value in event_data.items():
429
                _data = events.add_element("data", value)
430
                _data.add_element("name", key)
431
432
        methods = cmd.add_element("method", method.value)
433
434
        if method_data is not None:
435
            for key, value in method_data.items():
436
                _data = methods.add_element("data", value)
437
                _data.add_element("name", key)
438
439
        if filter_id:
440
            cmd.add_element("filter", attrs={"id": filter_id})
441
442
        if comment:
443
            cmd.add_element("comment", comment)
444
445
        return self._send_xml_command(cmd)
446
447
    def clone_alert(self, alert_id: str) -> Any:
448
        """Clone an existing alert
449
450
        Arguments:
451
            alert_id: UUID of an existing alert to clone from
452
453
        Returns:
454
            The response. See :py:meth:`send_command` for details.
455
        """
456
        if not alert_id:
457
            raise RequiredArgument(
458
                function=self.clone_alert.__name__, argument='alert_id'
459
            )
460
461
        cmd = XmlCommand("create_alert")
462
        cmd.add_element("copy", alert_id)
463
        return self._send_xml_command(cmd)
464
465
    def create_config(self, config_id: str, name: str) -> Any:
466
        """Create a new scan config from an existing one
467
468
        Arguments:
469
            config_id: UUID of the existing scan config
470
            name: Name of the new scan config
471
472
        Returns:
473
            The response. See :py:meth:`send_command` for details.
474
        """
475
        if not name:
476
            raise RequiredArgument(
477
                function=self.create_config.__name__, argument='name'
478
            )
479
480
        if not config_id:
481
            raise RequiredArgument(
482
                function=self.create_config.__name__, argument='config_id'
483
            )
484
485
        cmd = XmlCommand("create_config")
486
        cmd.add_element("copy", config_id)
487
        cmd.add_element("name", name)
488
        return self._send_xml_command(cmd)
489
490
    def clone_config(self, config_id: str) -> Any:
491
        """Clone a scan config from an existing one
492
493
        Arguments:
494
            config_id: UUID of the existing scan config
495
496
        Returns:
497
            The response. See :py:meth:`send_command` for details.
498
        """
499
        if not config_id:
500
            raise RequiredArgument(
501
                function=self.clone_config.__name__, argument='config_id'
502
            )
503
504
        cmd = XmlCommand("create_config")
505
        cmd.add_element("copy", config_id)
506
        return self._send_xml_command(cmd)
507
508
    def import_config(self, config: str) -> Any:
509
        """Import a scan config from XML
510
511
        Arguments:
512
            config: Scan Config XML as string to import. This XML must
513
                contain a :code:`<get_configs_response>` root element.
514
515
        Returns:
516
            The response. See :py:meth:`send_command` for details.
517
        """
518
        if not config:
519
            raise RequiredArgument(
520
                function=self.import_config.__name__, argument='config'
521
            )
522
523
        cmd = XmlCommand("create_config")
524
525
        try:
526
            cmd.append_xml_str(config)
527
        except etree.XMLSyntaxError:
528
            raise InvalidArgument(
529
                function=self.import_config.__name__, argument='config'
530
            )
531
532
        return self._send_xml_command(cmd)
533
534
    def create_credential(
535
        self,
536
        name: str,
537
        credential_type: CredentialType,
538
        *,
539
        comment: Optional[str] = None,
540
        allow_insecure: Optional[bool] = None,
541
        certificate: Optional[str] = None,
542
        key_phrase: Optional[str] = None,
543
        private_key: Optional[str] = None,
544
        login: Optional[str] = None,
545
        password: Optional[str] = None,
546
        auth_algorithm: Optional[SnmpAuthAlgorithm] = None,
547
        community: Optional[str] = None,
548
        privacy_algorithm: Optional[SnmpPrivacyAlgorithm] = None,
549
        privacy_password: Optional[str] = None
550
    ) -> Any:
551
        """Create a new credential
552
553
        Create a new credential e.g. to be used in the method of an alert.
554
555
        Currently the following credential types are supported:
556
557
            - Username + Password
558
            - Username + private SSH-Key
559
            - Client Certificates
560
            - SNMPv1 or SNMPv2c protocol
561
562
        Arguments:
563
            name: Name of the new credential
564
            credential_type: The credential type.
565
            comment: Comment for the credential
566
            allow_insecure: Whether to allow insecure use of the credential
567
            certificate: Certificate for the credential.
568
                Required for cc credential type.
569
            key_phrase: Key passphrase for the private key.
570
                Used for the usk credential type.
571
            private_key: Private key to use for login. Required
572
                for usk credential type. Also used for the cc credential type.
573
                The supported key types (dsa, rsa, ecdsa, ...) and formats (PEM,
574
                PKC#12, OpenSSL, ...) depend on your installed GnuTLS version.
575
            login: Username for the credential. Required for
576
                up, usk and snmp credential type.
577
            password: Password for the credential. Used for
578
                up and snmp credential types.
579
            community: The SNMP community.
580
            auth_algorithm: The SNMP authentication algorithm.
581
                Required for snmp credential type.
582
            privacy_algorithm: The SNMP privacy algorithm.
583
            privacy_password: The SNMP privacy password
584
585
        Examples:
586
            Creating a Username + Password credential
587
588
            .. code-block:: python
589
590
                gmp.create_credential(
591
                    name='UP Credential',
592
                    credential_type=CredentialType.USENAME_PASSWORD,
593
                    login='foo',
594
                    password='bar',
595
                );
596
597
            Creating a Username + SSH Key credential
598
599
            .. code-block:: python
600
601
                with open('path/to/private-ssh-key') as f:
602
                    key = f.read()
603
604
                gmp.create_credential(
605
                    name='USK Credential',
606
                    credential_type=CredentialType.USERNAME_SSH_KEY,
607
                    login='foo',
608
                    key_phrase='foobar',
609
                    private_key=key,
610
                )
611
612
        Returns:
613
            The response. See :py:meth:`send_command` for details.
614
        """
615
        if not name:
616
            raise RequiredArgument(
617
                function=self.create_credential.__name__, argument='name'
618
            )
619
620
        if not isinstance(credential_type, CredentialType):
621
            raise InvalidArgumentType(
622
                function=self.create_credential.__name__,
623
                argument="credential_type",
624
                arg_type=CredentialType.__name__,
625
            )
626
627
        cmd = XmlCommand("create_credential")
628
        cmd.add_element("name", name)
629
630
        cmd.add_element("type", credential_type.value)
631
632
        if comment:
633
            cmd.add_element("comment", comment)
634
635
        if allow_insecure is not None:
636
            cmd.add_element("allow_insecure", _to_bool(allow_insecure))
637
638
        if credential_type == CredentialType.CLIENT_CERTIFICATE:
639
            if not certificate:
640
                raise RequiredArgument(
641
                    function=self.create_credential.__name__,
642
                    argument="certificate",
643
                )
644
645
            cmd.add_element("certificate", certificate)
646
647 View Code Duplication
        if (
0 ignored issues
show
Duplication introduced by
This code seems to be duplicated in your project.
Loading history...
648
            credential_type == CredentialType.USERNAME_PASSWORD
649
            or credential_type == CredentialType.USERNAME_SSH_KEY
650
            or credential_type == CredentialType.SNMP
651
        ):
652
            if not login:
653
                raise RequiredArgument(
654
                    function=self.create_credential.__name__, argument="login",
655
                )
656
657
            cmd.add_element("login", login)
658
659
        if (
660
            credential_type == CredentialType.USERNAME_PASSWORD
661
            or credential_type == CredentialType.SNMP
662
        ) and password:
663
            cmd.add_element("password", password)
664
665 View Code Duplication
        if credential_type == CredentialType.USERNAME_SSH_KEY:
0 ignored issues
show
Duplication introduced by
This code seems to be duplicated in your project.
Loading history...
666
            if not private_key:
667
                raise RequiredArgument(
668
                    function=self.create_credential.__name__,
669
                    argument="private_key",
670
                )
671
672
            _xmlkey = cmd.add_element("key")
673
            _xmlkey.add_element("private", private_key)
674
675
            if key_phrase:
676
                _xmlkey.add_element("phrase", key_phrase)
677
678
        if credential_type == CredentialType.CLIENT_CERTIFICATE and private_key:
679
            _xmlkey = cmd.add_element("key")
680
            _xmlkey.add_element("private", private_key)
681
682 View Code Duplication
        if credential_type == CredentialType.SNMP:
0 ignored issues
show
Duplication introduced by
This code seems to be duplicated in your project.
Loading history...
683
            if not isinstance(auth_algorithm, SnmpAuthAlgorithm):
684
                raise InvalidArgumentType(
685
                    function=self.create_credential.__name__,
686
                    argument="auth_algorithm",
687
                    arg_type=SnmpAuthAlgorithm.__name__,
688
                )
689
690
            cmd.add_element("auth_algorithm", auth_algorithm.value)
691
692
            if community:
693
                cmd.add_element("community", community)
694
695
            if privacy_algorithm is not None or privacy_password:
696
                _xmlprivacy = cmd.add_element("privacy")
697
698
                if privacy_algorithm is not None:
699
                    if not isinstance(privacy_algorithm, SnmpPrivacyAlgorithm):
700
                        raise InvalidArgumentType(
701
                            function=self.create_credential.__name__,
702
                            argument="privacy_algorithm",
703
                            arg_type=SnmpPrivacyAlgorithm.__name__,
704
                        )
705
706
                    _xmlprivacy.add_element(
707
                        "algorithm", privacy_algorithm.value
708
                    )
709
710
                if privacy_password:
711
                    _xmlprivacy.add_element("password", privacy_password)
712
713
        return self._send_xml_command(cmd)
714
715
    def clone_credential(self, credential_id: str) -> Any:
716
        """Clone an existing credential
717
718
        Arguments:
719
            credential_id: UUID of an existing credential to clone from
720
721
        Returns:
722
            The response. See :py:meth:`send_command` for details.
723
        """
724
        if not credential_id:
725
            raise RequiredArgument(
726
                function=self.clone_credential.__name__,
727
                argument='credential_id',
728
            )
729
730
        cmd = XmlCommand("create_credential")
731
        cmd.add_element("copy", credential_id)
732
        return self._send_xml_command(cmd)
733
734 View Code Duplication
    def create_filter(
0 ignored issues
show
Duplication introduced by
This code seems to be duplicated in your project.
Loading history...
735
        self,
736
        name: str,
737
        *,
738
        make_unique: Optional[bool] = None,
739
        filter_type: Optional[FilterType] = None,
740
        comment: Optional[str] = None,
741
        term: Optional[str] = None
742
    ) -> Any:
743
        """Create a new filter
744
745
        Arguments:
746
            name: Name of the new filter
747
            make_unique:
748
            filter_type: Filter for entity type
749
            comment: Comment for the filter
750
            term: Filter term e.g. 'name=foo'
751
752
        Returns:
753
            The response. See :py:meth:`send_command` for details.
754
        """
755
        if not name:
756
            raise RequiredArgument(
757
                function=self.create_filter.__name__, argument="name"
758
            )
759
760
        cmd = XmlCommand("create_filter")
761
        _xmlname = cmd.add_element("name", name)
762
763
        if comment:
764
            cmd.add_element("comment", comment)
765
766
        if term:
767
            cmd.add_element("term", term)
768
769
        if make_unique is not None:
770
            cmd.add_element("make_unique", _to_bool(make_unique))
771
772
        if filter_type:
773
            if not isinstance(filter_type, self.types.FilterType):
774
                raise InvalidArgumentType(
775
                    function=self.create_filter.__name__,
776
                    argument="filter_type",
777
                    arg_type=self.types.FilterType.__name__,
778
                )
779
780
            cmd.add_element("type", filter_type.value)
781
782
        return self._send_xml_command(cmd)
783
784
    def clone_filter(self, filter_id: str) -> Any:
785
        """Clone an existing filter
786
787
        Arguments:
788
            filter_id: UUID of an existing filter to clone from
789
790
        Returns:
791
            The response. See :py:meth:`send_command` for details.
792
        """
793
        if not filter_id:
794
            raise RequiredArgument(
795
                function=self.clone_filter.__name__, argument='filter_id'
796
            )
797
798
        cmd = XmlCommand("create_filter")
799
        cmd.add_element("copy", filter_id)
800
        return self._send_xml_command(cmd)
801
802
    def create_group(
803
        self,
804
        name: str,
805
        *,
806
        comment: Optional[str] = None,
807
        special: Optional[bool] = False,
808
        users: Optional[List[str]] = None
809
    ) -> Any:
810
        """Create a new group
811
812
        Arguments:
813
            name: Name of the new group
814
            comment: Comment for the group
815
            special: Create permission giving members full access to each
816
                other's entities
817
            users: List of user names to be in the group
818
819
        Returns:
820
            The response. See :py:meth:`send_command` for details.
821
        """
822
        if not name:
823
            raise RequiredArgument(
824
                function=self.create_group.__name__, argument='name'
825
            )
826
827
        cmd = XmlCommand("create_group")
828
        cmd.add_element("name", name)
829
830
        if comment:
831
            cmd.add_element("comment", comment)
832
833
        if special:
834
            _xmlspecial = cmd.add_element("specials")
835
            _xmlspecial.add_element("full")
836
837
        if users:
838
            cmd.add_element("users", _to_comma_list(users))
839
840
        return self._send_xml_command(cmd)
841
842
    def clone_group(self, group_id: str) -> Any:
843
        """Clone an existing group
844
845
        Arguments:
846
            group_id: UUID of an existing group to clone from
847
848
        Returns:
849
            The response. See :py:meth:`send_command` for details.
850
        """
851
        if not group_id:
852
            raise RequiredArgument(
853
                function=self.clone_group.__name__, argument='group_id'
854
            )
855
856
        cmd = XmlCommand("create_group")
857
        cmd.add_element("copy", group_id)
858
        return self._send_xml_command(cmd)
859
860
    def create_host(self, name: str, *, comment: Optional[str] = None) -> Any:
861
        """Create a new host asset
862
863
        Arguments:
864
            name: Name for the new host asset
865
            comment: Comment for the new host asset
866
867
        Returns:
868
            The response. See :py:meth:`send_command` for details.
869
        """
870
        if not name:
871
            raise RequiredArgument(
872
                function=self.create_host.__name__, argument='name'
873
            )
874
875
        cmd = XmlCommand("create_asset")
876
        asset = cmd.add_element("asset")
877
        asset.add_element("type", "host")  # ignored for gmp7, required for gmp8
878
        asset.add_element("name", name)
879
880
        if comment:
881
            asset.add_element("comment", comment)
882
883
        return self._send_xml_command(cmd)
884
885 View Code Duplication
    def create_note(
0 ignored issues
show
Duplication introduced by
This code seems to be duplicated in your project.
Loading history...
886
        self,
887
        text: str,
888
        nvt_oid: str,
889
        *,
890
        seconds_active: Optional[int] = None,
891
        hosts: Optional[List[str]] = None,
892
        port: Optional[int] = None,
893
        result_id: Optional[str] = None,
894
        severity: Optional[Severity] = None,
895
        task_id: Optional[str] = None,
896
        threat: Optional[SeverityLevel] = None
897
    ) -> Any:
898
        """Create a new note
899
900
        Arguments:
901
            text: Text of the new note
902
            nvt_id: OID of the nvt to which note applies
903
            seconds_active: Seconds note will be active. -1 on
904
                always, 0 off
905
            hosts: A list of hosts addresses
906
            port: Port to which the note applies
907
            result_id: UUID of a result to which note applies
908
            severity: Severity to which note applies
909
            task_id: UUID of task to which note applies
910
            threat: Severity level to which note applies. Will be converted to
911
                severity.
912
913
        Returns:
914
            The response. See :py:meth:`send_command` for details.
915
        """
916
        if not text:
917
            raise RequiredArgument(
918
                function=self.create_note.__name__, argument='text'
919
            )
920
921
        if not nvt_oid:
922
            raise RequiredArgument(
923
                function=self.create_note.__name__, argument='nvt_oid'
924
            )
925
926
        cmd = XmlCommand("create_note")
927
        cmd.add_element("text", text)
928
        cmd.add_element("nvt", attrs={"oid": nvt_oid})
929
930
        if seconds_active is not None:
931
            cmd.add_element("active", str(seconds_active))
932
933
        if hosts:
934
            cmd.add_element("hosts", _to_comma_list(hosts))
935
936
        if port:
937
            cmd.add_element("port", str(port))
938
939
        if result_id:
940
            cmd.add_element("result", attrs={"id": result_id})
941
942
        if severity:
943
            cmd.add_element("severity", str(severity))
944
945
        if task_id:
946
            cmd.add_element("task", attrs={"id": task_id})
947
948
        if threat is not None:
949
            if not isinstance(threat, SeverityLevel):
950
                raise InvalidArgumentType(
951
                    function="create_note",
952
                    argument="threat",
953
                    arg_type=SeverityLevel.__name__,
954
                )
955
956
            cmd.add_element("threat", threat.value)
957
958
        return self._send_xml_command(cmd)
959
960
    def clone_note(self, note_id: str) -> Any:
961
        """Clone an existing note
962
963
        Arguments:
964
            note_id: UUID of an existing note to clone from
965
966
        Returns:
967
            The response. See :py:meth:`send_command` for details.
968
        """
969
        if not note_id:
970
            raise RequiredArgument(
971
                function=self.clone_note.__name__, argument='note_id'
972
            )
973
974
        cmd = XmlCommand("create_note")
975
        cmd.add_element("copy", note_id)
976
        return self._send_xml_command(cmd)
977
978 View Code Duplication
    def create_override(
0 ignored issues
show
Duplication introduced by
This code seems to be duplicated in your project.
Loading history...
979
        self,
980
        text: str,
981
        nvt_oid: str,
982
        *,
983
        seconds_active: Optional[int] = None,
984
        hosts: Optional[List[str]] = None,
985
        port: Optional[int] = None,
986
        result_id: Optional[str] = None,
987
        severity: Optional[Severity] = None,
988
        new_severity: Optional[Severity] = None,
989
        task_id: Optional[str] = None,
990
        threat: Optional[SeverityLevel] = None,
991
        new_threat: Optional[SeverityLevel] = None
992
    ) -> Any:
993
        """Create a new override
994
995
        Arguments:
996
            text: Text of the new override
997
            nvt_id: OID of the nvt to which override applies
998
            seconds_active: Seconds override will be active. -1 on always, 0 off
999
            hosts: A list of host addresses
1000
            port: Port to which the override applies
1001
            result_id: UUID of a result to which override applies
1002
            severity: Severity to which override applies
1003
            new_severity: New severity for result
1004
            task_id: UUID of task to which override applies
1005
            threat: Severity level to which override applies. Will be converted
1006
                to severity.
1007
            new_threat: New severity level for results. Will be converted to
1008
                new_severity.
1009
1010
        Returns:
1011
            The response. See :py:meth:`send_command` for details.
1012
        """
1013
        if not text:
1014
            raise RequiredArgument(
1015
                function=self.create_override.__name__, argument='text'
1016
            )
1017
1018
        if not nvt_oid:
1019
            raise RequiredArgument(
1020
                function=self.create_override.__name__, argument='nvt_oid'
1021
            )
1022
1023
        cmd = XmlCommand("create_override")
1024
        cmd.add_element("text", text)
1025
        cmd.add_element("nvt", attrs={"oid": nvt_oid})
1026
1027
        if seconds_active is not None:
1028
            cmd.add_element("active", str(seconds_active))
1029
1030
        if hosts:
1031
            cmd.add_element("hosts", _to_comma_list(hosts))
1032
1033
        if port:
1034
            cmd.add_element("port", str(port))
1035
1036
        if result_id:
1037
            cmd.add_element("result", attrs={"id": result_id})
1038
1039
        if severity:
1040
            cmd.add_element("severity", str(severity))
1041
1042
        if new_severity:
1043
            cmd.add_element("new_severity", str(new_severity))
1044
1045
        if task_id:
1046
            cmd.add_element("task", attrs={"id": task_id})
1047
1048
        if threat is not None:
1049
            if not isinstance(threat, SeverityLevel):
1050
                raise InvalidArgumentType(
1051
                    function=self.create_override.__name__,
1052
                    argument="threat",
1053
                    arg_type=SeverityLevel.__name__,
1054
                )
1055
1056
            cmd.add_element("threat", threat.value)
1057
1058
        if new_threat is not None:
1059
            if not isinstance(new_threat, SeverityLevel):
1060
                raise InvalidArgumentType(
1061
                    function=self.create_override.__name__,
1062
                    argument="new_threat",
1063
                    arg_type=SeverityLevel.__name__,
1064
                )
1065
1066
            cmd.add_element("new_threat", new_threat.value)
1067
1068
        return self._send_xml_command(cmd)
1069
1070
    def clone_override(self, override_id: str) -> Any:
1071
        """Clone an existing override
1072
1073
        Arguments:
1074
            override_id: UUID of an existing override to clone from
1075
1076
        Returns:
1077
            The response. See :py:meth:`send_command` for details.
1078
        """
1079
        if not override_id:
1080
            raise RequiredArgument(
1081
                function=self.clone_override.__name__, argument='override_id'
1082
            )
1083
1084
        cmd = XmlCommand("create_override")
1085
        cmd.add_element("copy", override_id)
1086
        return self._send_xml_command(cmd)
1087
1088
    def create_permission(
1089
        self,
1090
        name: str,
1091
        subject_id: str,
1092
        subject_type: PermissionSubjectType,
1093
        *,
1094
        resource_id: Optional[str] = None,
1095
        resource_type: Optional[EntityType] = None,
1096
        comment: Optional[str] = None
1097
    ) -> Any:
1098
        """Create a new permission
1099
1100
        Arguments:
1101
            name: Name of the new permission
1102
            subject_id: UUID of subject to whom the permission is granted
1103
            subject_type: Type of the subject user, group or role
1104
            comment: Comment for the permission
1105
            resource_id: UUID of entity to which the permission applies
1106
            resource_type: Type of the resource. For Super permissions user,
1107
                group or role
1108
1109
        Returns:
1110
            The response. See :py:meth:`send_command` for details.
1111
        """
1112
        if not name:
1113
            raise RequiredArgument(
1114
                function=self.create_permission.__name__, argument='name'
1115
            )
1116
1117
        if not subject_id:
1118
            raise RequiredArgument(
1119
                function=self.create_permission.__name__, argument='subject_id'
1120
            )
1121
1122
        if not isinstance(subject_type, PermissionSubjectType):
1123
            raise InvalidArgumentType(
1124
                function=self.create_permission.__name__,
1125
                argument='subject_type',
1126
                arg_type=PermissionSubjectType.__name__,
1127
            )
1128
1129
        cmd = XmlCommand("create_permission")
1130
        cmd.add_element("name", name)
1131
1132
        _xmlsubject = cmd.add_element("subject", attrs={"id": subject_id})
1133
        _xmlsubject.add_element("type", subject_type.value)
1134
1135
        if comment:
1136
            cmd.add_element("comment", comment)
1137
1138 View Code Duplication
        if resource_id or resource_type:
0 ignored issues
show
Duplication introduced by
This code seems to be duplicated in your project.
Loading history...
1139
            if not resource_id:
1140
                raise RequiredArgument(
1141
                    function=self.create_permission.__name__,
1142
                    argument='resource_id',
1143
                )
1144
1145
            if not resource_type:
1146
                raise RequiredArgument(
1147
                    function=self.create_permission.__name__,
1148
                    argument='resource_type',
1149
                )
1150
1151
            if not isinstance(resource_type, self.types.EntityType):
1152
                raise InvalidArgumentType(
1153
                    function=self.create_permission.__name__,
1154
                    argument='resource_type',
1155
                    arg_type=self.types.EntityType.__name__,
1156
                )
1157
1158
            _xmlresource = cmd.add_element(
1159
                "resource", attrs={"id": resource_id}
1160
            )
1161
            _xmlresource.add_element("type", resource_type.value)
1162
1163
        return self._send_xml_command(cmd)
1164
1165
    def clone_permission(self, permission_id: str) -> Any:
1166
        """Clone an existing permission
1167
1168
        Arguments:
1169
            permission_id: UUID of an existing permission to clone from
1170
1171
        Returns:
1172
            The response. See :py:meth:`send_command` for details.
1173
        """
1174
        if not permission_id:
1175
            raise RequiredArgument(
1176
                function=self.clone_permission.__name__,
1177
                argument='permission_id',
1178
            )
1179
1180
        cmd = XmlCommand("create_permission")
1181
        cmd.add_element("copy", permission_id)
1182
        return self._send_xml_command(cmd)
1183
1184
    def create_port_list(
1185
        self, name: str, port_range: str, *, comment: Optional[str] = None
1186
    ) -> Any:
1187
        """Create a new port list
1188
1189
        Arguments:
1190
            name: Name of the new port list
1191
            port_range: Port list ranges e.g. `"T: 1-1234"` for tcp port
1192
                1 - 1234
1193
            comment: Comment for the port list
1194
1195
        Returns:
1196
            The response. See :py:meth:`send_command` for details.
1197
        """
1198
        if not name:
1199
            raise RequiredArgument(
1200
                function=self.create_port_list.__name__, argument='name'
1201
            )
1202
1203
        if not port_range:
1204
            raise RequiredArgument(
1205
                function=self.create_port_list.__name__, argument='port_range'
1206
            )
1207
1208
        cmd = XmlCommand("create_port_list")
1209
        cmd.add_element("name", name)
1210
        cmd.add_element("port_range", port_range)
1211
1212
        if comment:
1213
            cmd.add_element("comment", comment)
1214
1215
        return self._send_xml_command(cmd)
1216
1217
    def clone_port_list(self, port_list_id: str) -> Any:
1218
        """Clone an existing port list
1219
1220
        Arguments:
1221
            port_list_id: UUID of an existing port list to clone from
1222
1223
        Returns:
1224
            The response. See :py:meth:`send_command` for details.
1225
        """
1226
        if not port_list_id:
1227
            raise RequiredArgument(
1228
                function=self.clone_port_list.__name__, argument='port_list_id'
1229
            )
1230
1231
        cmd = XmlCommand("create_port_list")
1232
        cmd.add_element("copy", port_list_id)
1233
        return self._send_xml_command(cmd)
1234
1235
    def create_port_range(
1236
        self,
1237
        port_list_id: str,
1238
        start: int,
1239
        end: int,
1240
        port_range_type: PortRangeType,
1241
        *,
1242
        comment: Optional[str] = None
1243
    ) -> Any:
1244
        """Create new port range
1245
1246
        Arguments:
1247
            port_list_id: UUID of the port list to which to add the range
1248
            start: The first port in the range
1249
            end: The last port in the range
1250
            port_range_type: The type of the ports: TCP, UDP, ...
1251
            comment: Comment for the port range
1252
1253
        Returns:
1254
            The response. See :py:meth:`send_command` for details.
1255
        """
1256
        if not port_list_id:
1257
            raise RequiredArgument(
1258
                function=self.create_port_range.__name__,
1259
                argument='port_list_id',
1260
            )
1261
1262
        if not port_range_type:
1263
            raise RequiredArgument(
1264
                function=self.create_port_range.__name__,
1265
                argument='port_range_type',
1266
            )
1267
1268
        if not start:
1269
            raise RequiredArgument(
1270
                function=self.create_port_range.__name__, argument='start'
1271
            )
1272
1273
        if not end:
1274
            raise RequiredArgument(
1275
                function=self.create_port_range.__name__, argument='end'
1276
            )
1277
1278
        if not isinstance(port_range_type, PortRangeType):
1279
            raise InvalidArgumentType(
1280
                function=self.create_port_range.__name__,
1281
                argument='port_range_type',
1282
                arg_type=PortRangeType.__name__,
1283
            )
1284
1285
        cmd = XmlCommand("create_port_range")
1286
        cmd.add_element("port_list", attrs={"id": port_list_id})
1287
        cmd.add_element("start", str(start))
1288
        cmd.add_element("end", str(end))
1289
        cmd.add_element("type", port_range_type.value)
1290
1291
        if comment:
1292
            cmd.add_element("comment", comment)
1293
1294
        return self._send_xml_command(cmd)
1295
1296
    def import_report(
1297
        self,
1298
        report: str,
1299
        *,
1300
        task_id: Optional[str] = None,
1301
        task_name: Optional[str] = None,
1302
        task_comment: Optional[str] = None,
1303
        in_assets: Optional[bool] = None
1304
    ) -> Any:
1305
        """Import a Report from XML
1306
1307
        Arguments:
1308
            report: Report XML as string to import. This XML must contain
1309
                a :code:`<report>` root element.
1310
            task_id: UUID of task to import report to
1311
            task_name: Name of task to be created if task_id is not present.
1312
                Either task_id or task_name must be passed
1313
            task_comment: Comment for task to be created if task_id is not
1314
                present
1315
            in_asset: Whether to create or update assets using the report
1316
1317
        Returns:
1318
            The response. See :py:meth:`send_command` for details.
1319
        """
1320
        if not report:
1321
            raise RequiredArgument(
1322
                function=self.import_report.__name__, argument='report'
1323
            )
1324
1325
        cmd = XmlCommand("create_report")
1326
1327
        if task_id:
1328
            cmd.add_element("task", attrs={"id": task_id})
1329
        elif task_name:
1330
            _xmltask = cmd.add_element("task")
1331
            _xmltask.add_element("name", task_name)
1332
1333
            if task_comment:
1334
                _xmltask.add_element("comment", task_comment)
1335
        else:
1336
            raise RequiredArgument(
1337
                function=self.import_report.__name__,
1338
                argument='task_id or task_name',
1339
            )
1340
1341
        if in_assets is not None:
1342
            cmd.add_element("in_assets", _to_bool(in_assets))
1343
1344
        try:
1345
            cmd.append_xml_str(report)
1346
        except etree.XMLSyntaxError as e:
1347
            raise InvalidArgument(
1348
                "Invalid xml passed as report to import_report {}".format(e)
1349
            )
1350
1351
        return self._send_xml_command(cmd)
1352
1353
    def create_role(
1354
        self,
1355
        name: str,
1356
        *,
1357
        comment: Optional[str] = None,
1358
        users: Optional[List[str]] = None
1359
    ) -> Any:
1360
        """Create a new role
1361
1362
        Arguments:
1363
            name: Name of the role
1364
            comment: Comment for the role
1365
            users: List of user names to add to the role
1366
1367
        Returns:
1368
            The response. See :py:meth:`send_command` for details.
1369
        """
1370
1371
        if not name:
1372
            raise RequiredArgument(
1373
                function=self.create_role.__name__, argument='name'
1374
            )
1375
1376
        cmd = XmlCommand("create_role")
1377
        cmd.add_element("name", name)
1378
1379
        if comment:
1380
            cmd.add_element("comment", comment)
1381
1382
        if users:
1383
            cmd.add_element("users", _to_comma_list(users))
1384
1385
        return self._send_xml_command(cmd)
1386
1387
    def clone_role(self, role_id: str) -> Any:
1388
        """Clone an existing role
1389
1390
        Arguments:
1391
            role_id: UUID of an existing role to clone from
1392
1393
        Returns:
1394
            The response. See :py:meth:`send_command` for details.
1395
        """
1396
        if not role_id:
1397
            raise RequiredArgument(
1398
                function=self.clone_role.__name__, argument='role_id'
1399
            )
1400
1401
        cmd = XmlCommand("create_role")
1402
        cmd.add_element("copy", role_id)
1403
        return self._send_xml_command(cmd)
1404
1405
    def create_scanner(
1406
        self,
1407
        name: str,
1408
        host: str,
1409
        port: int,
1410
        scanner_type: ScannerType,
1411
        credential_id: str,
1412
        *,
1413
        ca_pub: Optional[str] = None,
1414
        comment: Optional[str] = None
1415
    ) -> Any:
1416
        """Create a new scanner
1417
1418
        Arguments:
1419
            name: Name of the scanner
1420
            host: The host of the scanner
1421
            port: The port of the scanner
1422
            scanner_type: Type of the scanner.
1423
            credential_id: UUID of client certificate credential for the
1424
                scanner
1425
            ca_pub: Certificate of CA to verify scanner certificate
1426
            comment: Comment for the scanner
1427
1428
        Returns:
1429
            The response. See :py:meth:`send_command` for details.
1430
        """
1431
        if not name:
1432
            raise RequiredArgument(
1433
                function=self.create_scanner.__name__, argument='name'
1434
            )
1435
1436
        if not host:
1437
            raise RequiredArgument(
1438
                function=self.create_scanner.__name__, argument='host'
1439
            )
1440
1441
        if not port:
1442
            raise RequiredArgument(
1443
                function=self.create_scanner.__name__, argument='port'
1444
            )
1445
1446
        if not scanner_type:
1447
            raise RequiredArgument(
1448
                function=self.create_scanner.__name__, argument='scanner_type'
1449
            )
1450
1451
        if not credential_id:
1452
            raise RequiredArgument(
1453
                function=self.create_scanner.__name__, argument='credential_id'
1454
            )
1455
1456
        if not isinstance(scanner_type, ScannerType):
1457
            raise InvalidArgumentType(
1458
                function=self.create_scanner.__name__,
1459
                argument='scanner_type',
1460
                arg_type=ScannerType.__name__,
1461
            )
1462
1463
        cmd = XmlCommand("create_scanner")
1464
        cmd.add_element("name", name)
1465
        cmd.add_element("host", host)
1466
        cmd.add_element("port", str(port))
1467
        cmd.add_element("type", scanner_type.value)
1468
1469
        if ca_pub:
1470
            cmd.add_element("ca_pub", ca_pub)
1471
1472
        cmd.add_element("credential", attrs={"id": str(credential_id)})
1473
1474
        if comment:
1475
            cmd.add_element("comment", comment)
1476
1477
        return self._send_xml_command(cmd)
1478
1479
    def clone_scanner(self, scanner_id: str) -> Any:
1480
        """Clone an existing scanner
1481
1482
        Arguments:
1483
            scanner_id: UUID of an existing scanner to clone from
1484
1485
        Returns:
1486
            The response. See :py:meth:`send_command` for details.
1487
        """
1488
        if not scanner_id:
1489
            raise RequiredArgument(
1490
                function=self.clone_scanner.__name__, argument='scanner_id'
1491
            )
1492
1493
        cmd = XmlCommand("create_scanner")
1494
        cmd.add_element("copy", scanner_id)
1495
        return self._send_xml_command(cmd)
1496
1497 View Code Duplication
    def create_schedule(
0 ignored issues
show
Duplication introduced by
This code seems to be duplicated in your project.
Loading history...
1498
        self,
1499
        name: str,
1500
        *,
1501
        comment: Optional[str] = None,
1502
        first_time_minute: Optional[int] = None,
1503
        first_time_hour: Optional[int] = None,
1504
        first_time_day_of_month: Optional[int] = None,
1505
        first_time_month: Optional[int] = None,
1506
        first_time_year: Optional[int] = None,
1507
        duration: Optional[int] = None,
1508
        duration_unit: Optional[TimeUnit] = None,
1509
        period: Optional[int] = None,
1510
        period_unit: Optional[TimeUnit] = None,
1511
        timezone: Optional[str] = None
1512
    ) -> Any:
1513
        """Create a new schedule
1514
1515
        Arguments:
1516
            name: Name of the schedule
1517
            comment: Comment for the schedule
1518
            first_time_minute: First time minute the schedule will run. Must be
1519
                an integer >= 0.
1520
            first_time_hour: First time hour the schedule will run. Must be an
1521
                integer >= 0.
1522
            first_time_day_of_month: First time day of month the schedule will
1523
                run. Must be an integer > 0 <= 31.
1524
            first_time_month: First time month the schedule will run. Must be an
1525
                integer >= 1 <= 12.
1526
            first_time_year: First time year the schedule will run. Must be an
1527
                integer >= 1970.
1528
            duration: How long the Manager will run the scheduled task for until
1529
                it gets paused if not finished yet. Must be an integer > 0.
1530
            duration_unit: Unit of the duration. One of second,
1531
                minute, hour, day, week, month, year, decade. Required if
1532
                duration is set.
1533
            period: How often the Manager will repeat the
1534
                scheduled task. Must be an integer > 0.
1535
            period_unit: Unit of the period. One of second,
1536
                minute, hour, day, week, month, year, decade. Required if
1537
                period is set.
1538
            timezone: The timezone the schedule will follow
1539
1540
        Returns:
1541
            The response. See :py:meth:`send_command` for details.
1542
        """
1543
        if not name:
1544
            raise RequiredArgument(
1545
                function=self.create_schedule.__name__, argument='name'
1546
            )
1547
1548
        cmd = XmlCommand("create_schedule")
1549
        cmd.add_element("name", name)
1550
1551
        if comment:
1552
            cmd.add_element("comment", comment)
1553
1554
        if (
1555
            first_time_minute is not None
1556
            or first_time_hour is not None
1557
            or first_time_day_of_month is not None
1558
            or first_time_month is not None
1559
            or first_time_year is not None
1560
        ):
1561
1562
            if first_time_minute is None:
1563
                raise RequiredArgument(
1564
                    function=self.create_schedule.__name__,
1565
                    argument='first_time_minute',
1566
                )
1567
            elif (
1568
                not isinstance(first_time_minute, numbers.Integral)
1569
                or first_time_minute < 0
1570
            ):
1571
                raise InvalidArgument(
1572
                    "first_time_minute argument of create_schedule needs to be "
1573
                    "an integer greater or equal 0"
1574
                )
1575
1576
            if first_time_hour is None:
1577
                raise RequiredArgument(
1578
                    function=self.create_schedule.__name__,
1579
                    argument='first_time_hour',
1580
                )
1581
            elif (
1582
                not isinstance(first_time_hour, numbers.Integral)
1583
                or first_time_hour < 0
1584
            ):
1585
                raise InvalidArgument(
1586
                    "first_time_hour argument of create_schedule needs to be "
1587
                    "an integer greater or equal 0"
1588
                )
1589
1590
            if first_time_day_of_month is None:
1591
                raise RequiredArgument(
1592
                    function=self.create_schedule.__name__,
1593
                    argument='first_time_day_of_month',
1594
                )
1595
            elif (
1596
                not isinstance(first_time_day_of_month, numbers.Integral)
1597
                or first_time_day_of_month < 1
1598
                or first_time_day_of_month > 31
1599
            ):
1600
                raise InvalidArgument(
1601
                    "first_time_day_of_month argument of create_schedule needs "
1602
                    "to be an integer between 1 and 31"
1603
                )
1604
1605
            if first_time_month is None:
1606
                raise RequiredArgument(
1607
                    function=self.create_schedule.__name__,
1608
                    argument='first_time_month',
1609
                )
1610
            elif (
1611
                not isinstance(first_time_month, numbers.Integral)
1612
                or first_time_month < 1
1613
                or first_time_month > 12
1614
            ):
1615
                raise InvalidArgument(
1616
                    "first_time_month argument of create_schedule needs "
1617
                    "to be an integer between 1 and 12"
1618
                )
1619
1620
            if first_time_year is None:
1621
                raise RequiredArgument(
1622
                    function=self.create_schedule.__name__,
1623
                    argument='first_time_year',
1624
                )
1625
            elif (
1626
                not isinstance(first_time_year, numbers.Integral)
1627
                or first_time_year < 1970
1628
            ):
1629
                raise InvalidArgument(
1630
                    "first_time_year argument of create_schedule needs "
1631
                    "to be an integer greater or equal 1970"
1632
                )
1633
1634
            _xmlftime = cmd.add_element("first_time")
1635
            _xmlftime.add_element("minute", str(first_time_minute))
1636
            _xmlftime.add_element("hour", str(first_time_hour))
1637
            _xmlftime.add_element("day_of_month", str(first_time_day_of_month))
1638
            _xmlftime.add_element("month", str(first_time_month))
1639
            _xmlftime.add_element("year", str(first_time_year))
1640
1641
        if duration is not None:
1642
            if not duration_unit:
1643
                raise RequiredArgument(
1644
                    function=self.create_schedule.__name__,
1645
                    argument='duration_unit',
1646
                )
1647
1648
            if not isinstance(duration_unit, TimeUnit):
1649
                raise InvalidArgumentType(
1650
                    function=self.create_schedule.__name__,
1651
                    argument='duration_unit',
1652
                    arg_type=TimeUnit.__name__,
1653
                )
1654
1655
            if not isinstance(duration, numbers.Integral) or duration < 1:
1656
                raise InvalidArgument(
1657
                    "duration argument must be an integer greater than 0"
1658
                )
1659
1660
            _xmlduration = cmd.add_element("duration", str(duration))
1661
            _xmlduration.add_element("unit", duration_unit.value)
1662
1663
        if period is not None:
1664
            if not period_unit:
1665
                raise RequiredArgument(
1666
                    function=self.create_schedule.__name__,
1667
                    argument='period_unit',
1668
                )
1669
1670
            if not isinstance(period_unit, TimeUnit):
1671
                raise InvalidArgumentType(
1672
                    function=self.create_schedule.__name__,
1673
                    argument='period_unit',
1674
                    arg_type=TimeUnit.__name__,
1675
                )
1676
1677
            if not isinstance(period, numbers.Integral) or period < 0:
1678
                raise InvalidArgument(
1679
                    "period argument must be a positive integer"
1680
                )
1681
1682
            _xmlperiod = cmd.add_element("period", str(period))
1683
            _xmlperiod.add_element("unit", period_unit.value)
1684
1685
        if timezone:
1686
            cmd.add_element("timezone", timezone)
1687
1688
        return self._send_xml_command(cmd)
1689
1690
    def clone_schedule(self, schedule_id: str) -> Any:
1691
        """Clone an existing schedule
1692
1693
        Arguments:
1694
            schedule_id: UUID of an existing schedule to clone from
1695
1696
        Returns:
1697
            The response. See :py:meth:`send_command` for details.
1698
        """
1699
        if not schedule_id:
1700
            raise RequiredArgument(
1701
                function=self.clone_schedule.__name__, argument='schedule_id'
1702
            )
1703
1704
        cmd = XmlCommand("create_schedule")
1705
        cmd.add_element("copy", schedule_id)
1706
        return self._send_xml_command(cmd)
1707
1708
    def create_tag(
1709
        self,
1710
        name: str,
1711
        resource_type: EntityType,
1712
        *,
1713
        resource_id: Optional[str] = None,
1714
        value: Optional[str] = None,
1715
        comment: Optional[str] = None,
1716
        active: Optional[bool] = None
1717
    ) -> Any:
1718
        """Create a new tag
1719
1720
        Arguments:
1721
            name: Name of the tag. A full tag name consisting of namespace
1722
                and predicate e.g. `foo:bar`.
1723
            resource_id: ID of the resource the tag is to be attached to.
1724
            resource_type: Entity type the tag is to be attached to
1725
            value: Value associated with the tag
1726
            comment: Comment for the tag
1727
            active: Whether the tag should be active
1728
1729
        Returns:
1730
            The response. See :py:meth:`send_command` for details.
1731
        """
1732
        if not name:
1733
            raise RequiredArgument(
1734
                function=self.create_tag.__name__, argument='name'
1735
            )
1736
1737
        if not resource_type:
1738
            raise RequiredArgument(
1739
                function=self.create_tag.__name__, argument='resource_type'
1740
            )
1741
1742
        if not isinstance(resource_type, self.types.EntityType):
1743
            raise InvalidArgumentType(
1744
                function=self.create_tag.__name__,
1745
                argument='resource_type',
1746
                arg_type=self.types.EntityType.__name__,
1747
            )
1748
1749
        cmd = XmlCommand("create_tag")
1750
        cmd.add_element("name", name)
1751
1752
        if not resource_id:
1753
            resource_id = ''
1754
1755
        _xmlresource = cmd.add_element(
1756
            "resource", attrs={"id": str(resource_id)}
1757
        )
1758
        _xmlresource.add_element("type", resource_type.value)
1759
1760
        if comment:
1761
            cmd.add_element("comment", comment)
1762
1763
        if value:
1764
            cmd.add_element("value", value)
1765
1766
        if active is not None:
1767
            if active:
1768
                cmd.add_element("active", "1")
1769
            else:
1770
                cmd.add_element("active", "0")
1771
1772
        return self._send_xml_command(cmd)
1773
1774
    def clone_tag(self, tag_id: str) -> Any:
1775
        """Clone an existing tag
1776
1777
        Arguments:
1778
            tag_id: UUID of an existing tag to clone from
1779
1780
        Returns:
1781
            The response. See :py:meth:`send_command` for details.
1782
        """
1783
        if not tag_id:
1784
            raise RequiredArgument(
1785
                function=self.clone_tag.__name__, argument='tag_id'
1786
            )
1787
1788
        cmd = XmlCommand("create_tag")
1789
        cmd.add_element("copy", tag_id)
1790
        return self._send_xml_command(cmd)
1791
1792
    def create_target(
1793
        self,
1794
        name: str,
1795
        *,
1796
        make_unique: Optional[bool] = None,
1797
        asset_hosts_filter: Optional[str] = None,
1798
        hosts: Optional[List[str]] = None,
1799
        comment: Optional[str] = None,
1800
        exclude_hosts: Optional[List[str]] = None,
1801
        ssh_credential_id: Optional[str] = None,
1802
        ssh_credential_port: Optional[int] = None,
1803
        smb_credential_id: Optional[str] = None,
1804
        esxi_credential_id: Optional[str] = None,
1805
        snmp_credential_id: Optional[str] = None,
1806
        alive_test: Optional[AliveTest] = None,
1807
        reverse_lookup_only: Optional[bool] = None,
1808
        reverse_lookup_unify: Optional[bool] = None,
1809
        port_range: Optional[str] = None,
1810
        port_list_id: Optional[str] = None
1811
    ) -> Any:
1812
        """Create a new target
1813
1814
        Arguments:
1815
            name: Name of the target
1816
            make_unique: Append a unique suffix if the name already exists
1817
            asset_hosts_filter: Filter to select target host from assets hosts
1818
            hosts: List of hosts addresses to scan
1819
            exclude_hosts: List of hosts addresses to exclude from scan
1820
            comment: Comment for the target
1821
            ssh_credential_id: UUID of a ssh credential to use on target
1822
            ssh_credential_port: The port to use for ssh credential
1823
            smb_credential_id: UUID of a smb credential to use on target
1824
            snmp_credential_id: UUID of a snmp credential to use on target
1825
            esxi_credential_id: UUID of a esxi credential to use on target
1826
            alive_test: Which alive test to use
1827
            reverse_lookup_only: Whether to scan only hosts that have names
1828
            reverse_lookup_unify: Whether to scan only one IP when multiple IPs
1829
                have the same name.
1830
            port_range: Port range for the target
1831
            port_list_id: UUID of the port list to use on target
1832
1833
        Returns:
1834
            The response. See :py:meth:`send_command` for details.
1835
        """
1836
        if not name:
1837
            raise RequiredArgument(
1838
                function=self.create_target.__name__, argument='name'
1839
            )
1840
1841
        cmd = XmlCommand("create_target")
1842
        _xmlname = cmd.add_element("name", name)
1843
1844
        if make_unique is not None:
1845
            _xmlname.add_element("make_unique", _to_bool(make_unique))
1846
1847
        if asset_hosts_filter:
1848
            cmd.add_element(
1849
                "asset_hosts", attrs={"filter": str(asset_hosts_filter)}
1850
            )
1851
        elif hosts:
1852
            cmd.add_element("hosts", _to_comma_list(hosts))
1853
        else:
1854
            raise RequiredArgument(
1855
                function=self.create_target.__name__,
1856
                argument='hosts or asset_hosts_filter',
1857
            )
1858
1859
        if comment:
1860
            cmd.add_element("comment", comment)
1861
1862
        if exclude_hosts:
1863
            cmd.add_element("exclude_hosts", _to_comma_list(exclude_hosts))
1864
1865
        if ssh_credential_id:
1866
            _xmlssh = cmd.add_element(
1867
                "ssh_credential", attrs={"id": ssh_credential_id}
1868
            )
1869
            if ssh_credential_port:
1870
                _xmlssh.add_element("port", str(ssh_credential_port))
1871
1872
        if smb_credential_id:
1873
            cmd.add_element("smb_credential", attrs={"id": smb_credential_id})
1874
1875
        if esxi_credential_id:
1876
            cmd.add_element("esxi_credential", attrs={"id": esxi_credential_id})
1877
1878
        if snmp_credential_id:
1879
            cmd.add_element("snmp_credential", attrs={"id": snmp_credential_id})
1880
1881
        if alive_test:
1882
            if not isinstance(alive_test, AliveTest):
1883
                raise InvalidArgumentType(
1884
                    function=self.create_target.__name__,
1885
                    argument='alive_test',
1886
                    arg_type=AliveTest.__name__,
1887
                )
1888
1889
            cmd.add_element("alive_tests", alive_test.value)
1890
1891
        if reverse_lookup_only is not None:
1892
            cmd.add_element(
1893
                "reverse_lookup_only", _to_bool(reverse_lookup_only)
1894
            )
1895
1896
        if reverse_lookup_unify is not None:
1897
            cmd.add_element(
1898
                "reverse_lookup_unify", _to_bool(reverse_lookup_unify)
1899
            )
1900
1901
        if port_range:
1902
            cmd.add_element("port_range", port_range)
1903
1904
        if port_list_id:
1905
            cmd.add_element("port_list", attrs={"id": port_list_id})
1906
1907
        return self._send_xml_command(cmd)
1908
1909
    def clone_target(self, target_id: str) -> Any:
1910
        """Clone an existing target
1911
1912
        Arguments:
1913
            target_id: UUID of an existing target to clone from
1914
1915
        Returns:
1916
            The response. See :py:meth:`send_command` for details.
1917
        """
1918
        if not target_id:
1919
            raise RequiredArgument(
1920
                function=self.clone_target.__name__, argument='target_id'
1921
            )
1922
1923
        cmd = XmlCommand("create_target")
1924
        cmd.add_element("copy", target_id)
1925
        return self._send_xml_command(cmd)
1926
1927 View Code Duplication
    def create_task(
0 ignored issues
show
Duplication introduced by
This code seems to be duplicated in your project.
Loading history...
1928
        self,
1929
        name: str,
1930
        config_id: str,
1931
        target_id: str,
1932
        scanner_id: str,
1933
        *,
1934
        alterable: Optional[bool] = None,
1935
        hosts_ordering: Optional[HostsOrdering] = None,
1936
        schedule_id: Optional[str] = None,
1937
        alert_ids: Optional[List[str]] = None,
1938
        comment: Optional[str] = None,
1939
        schedule_periods: Optional[int] = None,
1940
        observers: Optional[List[str]] = None,
1941
        preferences: Optional[dict] = None
1942
    ) -> Any:
1943
        """Create a new task
1944
1945
        Arguments:
1946
            name: Name of the task
1947
            config_id: UUID of scan config to use by the task
1948
            target_id: UUID of target to be scanned
1949
            scanner_id: UUID of scanner to use for scanning the target
1950
            comment: Comment for the task
1951
            alterable: Whether the task should be alterable
1952
            alert_ids: List of UUIDs for alerts to be applied to the task
1953
            hosts_ordering: The order hosts are scanned in
1954
            schedule_id: UUID of a schedule when the task should be run.
1955
            schedule_periods: A limit to the number of times the task will be
1956
                scheduled, or 0 for no limit
1957
            observers: List of names or ids of users which should be allowed to
1958
                observe this task
1959
            preferences: Name/Value pairs of scanner preferences.
1960
1961
        Returns:
1962
            The response. See :py:meth:`send_command` for details.
1963
        """
1964
        if not name:
1965
            raise RequiredArgument(
1966
                function=self.create_task.__name__, argument='name'
1967
            )
1968
1969
        if not config_id:
1970
            raise RequiredArgument(
1971
                function=self.create_task.__name__, argument='config_id'
1972
            )
1973
1974
        if not target_id:
1975
            raise RequiredArgument(
1976
                function=self.create_task.__name__, argument='target_id'
1977
            )
1978
1979
        if not scanner_id:
1980
            raise RequiredArgument(
1981
                function=self.create_task.__name__, argument='scanner_id'
1982
            )
1983
1984
        # don't allow to create a container task with create_task
1985
        if target_id == '0':
1986
            raise InvalidArgument(
1987
                'Invalid argument {} for target_id'.format(target_id)
1988
            )
1989
1990
        cmd = XmlCommand("create_task")
1991
        cmd.add_element("name", name)
1992
        cmd.add_element("config", attrs={"id": config_id})
1993
        cmd.add_element("target", attrs={"id": target_id})
1994
        cmd.add_element("scanner", attrs={"id": scanner_id})
1995
1996
        if comment:
1997
            cmd.add_element("comment", comment)
1998
1999
        if alterable is not None:
2000
            cmd.add_element("alterable", _to_bool(alterable))
2001
2002
        if hosts_ordering:
2003
            if not isinstance(hosts_ordering, HostsOrdering):
2004
                raise InvalidArgumentType(
2005
                    function=self.create_task.__name__,
2006
                    argument='hosts_ordering',
2007
                    arg_type=HostsOrdering.__name__,
2008
                )
2009
            cmd.add_element("hosts_ordering", hosts_ordering.value)
2010
2011
        if alert_ids:
2012
            if isinstance(alert_ids, str):
2013
                deprecation(
2014
                    "Please pass a list as alert_ids parameter to create_task. "
2015
                    "Passing a string is deprecated and will be removed in "
2016
                    "future."
2017
                )
2018
2019
                # if a single id is given as a string wrap it into a list
2020
                alert_ids = [alert_ids]
2021
            if _is_list_like(alert_ids):
2022
                # parse all given alert id's
2023
                for alert in alert_ids:
2024
                    cmd.add_element("alert", attrs={"id": str(alert)})
2025
2026
        if schedule_id:
2027
            cmd.add_element("schedule", attrs={"id": schedule_id})
2028
2029
            if schedule_periods is not None:
2030
                if (
2031
                    not isinstance(schedule_periods, numbers.Integral)
2032
                    or schedule_periods < 0
2033
                ):
2034
                    raise InvalidArgument(
2035
                        "schedule_periods must be an integer greater or equal "
2036
                        "than 0"
2037
                    )
2038
                cmd.add_element("schedule_periods", str(schedule_periods))
2039
2040
        if observers is not None:
2041
            if not _is_list_like(observers):
2042
                raise InvalidArgumentType(
2043
                    function=self.create_task.__name__,
2044
                    argument='observers',
2045
                    arg_type='list',
2046
                )
2047
2048
            # gvmd splits by comma and space
2049
            # gvmd tries to lookup each value as user name and afterwards as
2050
            # user id. So both user name and user id are possible
2051
            cmd.add_element("observers", _to_comma_list(observers))
2052
2053
        if preferences is not None:
2054
            if not isinstance(preferences, collections.abc.Mapping):
2055
                raise InvalidArgumentType(
2056
                    function=self.create_task.__name__,
2057
                    argument='preferences',
2058
                    arg_type=collections.abc.Mapping.__name__,
2059
                )
2060
2061
            _xmlprefs = cmd.add_element("preferences")
2062
            for pref_name, pref_value in preferences.items():
2063
                _xmlpref = _xmlprefs.add_element("preference")
2064
                _xmlpref.add_element("scanner_name", pref_name)
2065
                _xmlpref.add_element("value", str(pref_value))
2066
2067
        return self._send_xml_command(cmd)
2068
2069
    def create_container_task(
2070
        self, name: str, *, comment: Optional[str] = None
2071
    ) -> Any:
2072
        """Create a new container task
2073
2074
        A container task is a "meta" task to import and view reports from other
2075
        systems.
2076
2077
        Arguments:
2078
            name: Name of the task
2079
            comment: Comment for the task
2080
2081
        Returns:
2082
            The response. See :py:meth:`send_command` for details.
2083
        """
2084
        if not name:
2085
            raise RequiredArgument(
2086
                function=self.create_container_task.__name__, argument='name'
2087
            )
2088
2089
        cmd = XmlCommand("create_task")
2090
        cmd.add_element("name", name)
2091
        cmd.add_element("target", attrs={"id": "0"})
2092
2093
        if comment:
2094
            cmd.add_element("comment", comment)
2095
2096
        return self._send_xml_command(cmd)
2097
2098
    def clone_task(self, task_id: str) -> Any:
2099
        """Clone an existing task
2100
2101
        Arguments:
2102
            task_id: UUID of existing task to clone from
2103
2104
        Returns:
2105
            The response. See :py:meth:`send_command` for details.
2106
        """
2107
        if not task_id:
2108
            raise RequiredArgument(
2109
                function=self.clone_task.__name__, argument='task_id'
2110
            )
2111
2112
        cmd = XmlCommand("create_task")
2113
        cmd.add_element("copy", task_id)
2114
        return self._send_xml_command(cmd)
2115
2116
    def create_user(
2117
        self,
2118
        name: str,
2119
        *,
2120
        password: Optional[str] = None,
2121
        hosts: Optional[List[str]] = None,
2122
        hosts_allow: Optional[bool] = False,
2123
        ifaces: Optional[List[str]] = None,
2124
        ifaces_allow: Optional[bool] = False,
2125
        role_ids: Optional[List[str]] = None
2126
    ) -> Any:
2127
        """Create a new user
2128
2129
        Arguments:
2130
            name: Name of the user
2131
            password: Password of the user
2132
            hosts: A list of host addresses (IPs, DNS names)
2133
            hosts_allow: If True allow only access to passed hosts otherwise
2134
                deny access. Default is False for deny hosts.
2135
            ifaces: A list of interface names
2136
            ifaces_allow: If True allow only access to passed interfaces
2137
                otherwise deny access. Default is False for deny interfaces.
2138
            role_ids: A list of role UUIDs for the user
2139
2140
        Returns:
2141
            The response. See :py:meth:`send_command` for details.
2142
        """
2143
        if not name:
2144
            raise RequiredArgument(
2145
                function=self.create_user.__name__, argument='name'
2146
            )
2147
2148
        cmd = XmlCommand("create_user")
2149
        cmd.add_element("name", name)
2150
2151
        if password:
2152
            cmd.add_element("password", password)
2153
2154
        if hosts:
2155
            cmd.add_element(
2156
                "hosts",
2157
                _to_comma_list(hosts),
2158
                attrs={"allow": _to_bool(hosts_allow)},
2159
            )
2160
2161
        if ifaces:
2162
            cmd.add_element(
2163
                "ifaces",
2164
                _to_comma_list(ifaces),
2165
                attrs={"allow": _to_bool(ifaces_allow)},
2166
            )
2167
2168
        if role_ids:
2169
            for role in role_ids:
2170
                cmd.add_element("role", attrs={"id": role})
2171
2172
        return self._send_xml_command(cmd)
2173
2174
    def clone_user(self, user_id: str) -> Any:
2175
        """Clone an existing user
2176
2177
        Arguments:
2178
            user_id: UUID of existing user to clone from
2179
2180
        Returns:
2181
            The response. See :py:meth:`send_command` for details.
2182
        """
2183
        if not user_id:
2184
            raise RequiredArgument(
2185
                function=self.clone_user.__name__, argument='user_id'
2186
            )
2187
2188
        cmd = XmlCommand("create_user")
2189
        cmd.add_element("copy", user_id)
2190
        return self._send_xml_command(cmd)
2191
2192
    def delete_agent(
2193
        self, agent_id: str, *, ultimate: Optional[bool] = False
2194
    ) -> Any:
2195
        """Deletes an existing agent
2196
2197
        Arguments:
2198
            agent_id: UUID of the agent to be deleted.
2199
            ultimate: Whether to remove entirely, or to the trashcan.
2200
        """
2201
        if not agent_id:
2202
            raise RequiredArgument(
2203
                function=self.delete_agent.__name__, argument='agent_id'
2204
            )
2205
2206
        cmd = XmlCommand("delete_agent")
2207
        cmd.set_attribute("agent_id", agent_id)
2208
        cmd.set_attribute("ultimate", _to_bool(ultimate))
2209
2210
        return self._send_xml_command(cmd)
2211
2212
    def delete_alert(
2213
        self, alert_id: str, *, ultimate: Optional[bool] = False
2214
    ) -> Any:
2215
        """Deletes an existing alert
2216
2217
        Arguments:
2218
            alert_id: UUID of the alert to be deleted.
2219
            ultimate: Whether to remove entirely, or to the trashcan.
2220
        """
2221
        if not alert_id:
2222
            raise RequiredArgument(
2223
                function=self.delete_alert.__name__, argument='alert_id'
2224
            )
2225
2226
        cmd = XmlCommand("delete_alert")
2227
        cmd.set_attribute("alert_id", alert_id)
2228
        cmd.set_attribute("ultimate", _to_bool(ultimate))
2229
2230
        return self._send_xml_command(cmd)
2231
2232
    def delete_asset(
2233
        self, *, asset_id: Optional[str] = None, report_id: Optional[str] = None
2234
    ) -> Any:
2235
        """Deletes an existing asset
2236
2237
        Arguments:
2238
            asset_id: UUID of the single asset to delete.
2239
            report_id: UUID of report from which to get all
2240
                assets to delete.
2241
        """
2242
        if not asset_id and not report_id:
2243
            raise RequiredArgument(
2244
                function=self.delete_asset.__name__,
2245
                argument='asset_id or report_id',
2246
            )
2247
2248
        cmd = XmlCommand("delete_asset")
2249
        if asset_id:
2250
            cmd.set_attribute("asset_id", asset_id)
2251
        else:
2252
            cmd.set_attribute("report_id", report_id)
2253
2254
        return self._send_xml_command(cmd)
2255
2256
    def delete_config(
2257
        self, config_id: str, *, ultimate: Optional[bool] = False
2258
    ) -> Any:
2259
        """Deletes an existing config
2260
2261
        Arguments:
2262
            config_id: UUID of the config to be deleted.
2263
            ultimate: Whether to remove entirely, or to the trashcan.
2264
        """
2265
        if not config_id:
2266
            raise RequiredArgument(
2267
                function=self.delete_config.__name__, argument='config_id'
2268
            )
2269
2270
        cmd = XmlCommand("delete_config")
2271
        cmd.set_attribute("config_id", config_id)
2272
        cmd.set_attribute("ultimate", _to_bool(ultimate))
2273
2274
        return self._send_xml_command(cmd)
2275
2276
    def delete_credential(
2277
        self, credential_id: str, *, ultimate: Optional[bool] = False
2278
    ) -> Any:
2279
        """Deletes an existing credential
2280
2281
        Arguments:
2282
            credential_id: UUID of the credential to be deleted.
2283
            ultimate: Whether to remove entirely, or to the trashcan.
2284
        """
2285
        if not credential_id:
2286
            raise RequiredArgument(
2287
                function=self.delete_credential.__name__,
2288
                argument='credential_id',
2289
            )
2290
2291
        cmd = XmlCommand("delete_credential")
2292
        cmd.set_attribute("credential_id", credential_id)
2293
        cmd.set_attribute("ultimate", _to_bool(ultimate))
2294
2295
        return self._send_xml_command(cmd)
2296
2297
    def delete_filter(
2298
        self, filter_id: str, *, ultimate: Optional[bool] = False
2299
    ) -> Any:
2300
        """Deletes an existing filter
2301
2302
        Arguments:
2303
            filter_id: UUID of the filter to be deleted.
2304
            ultimate: Whether to remove entirely, or to the trashcan.
2305
        """
2306
        if not filter_id:
2307
            raise RequiredArgument(
2308
                function=self.delete_filter.__name__, argument='filter_id'
2309
            )
2310
2311
        cmd = XmlCommand("delete_filter")
2312
        cmd.set_attribute("filter_id", filter_id)
2313
        cmd.set_attribute("ultimate", _to_bool(ultimate))
2314
2315
        return self._send_xml_command(cmd)
2316
2317
    def delete_group(
2318
        self, group_id: str, *, ultimate: Optional[bool] = False
2319
    ) -> Any:
2320
        """Deletes an existing group
2321
2322
        Arguments:
2323
            group_id: UUID of the group to be deleted.
2324
            ultimate: Whether to remove entirely, or to the trashcan.
2325
        """
2326
        if not group_id:
2327
            raise RequiredArgument(
2328
                function=self.delete_group.__name__, argument='group_id'
2329
            )
2330
2331
        cmd = XmlCommand("delete_group")
2332
        cmd.set_attribute("group_id", group_id)
2333
        cmd.set_attribute("ultimate", _to_bool(ultimate))
2334
2335
        return self._send_xml_command(cmd)
2336
2337
    def delete_note(
2338
        self, note_id: str, *, ultimate: Optional[bool] = False
2339
    ) -> Any:
2340
        """Deletes an existing note
2341
2342
        Arguments:
2343
            note_id: UUID of the note to be deleted.
2344
            ultimate: Whether to remove entirely,or to the trashcan.
2345
        """
2346
        if not note_id:
2347
            raise RequiredArgument(
2348
                function=self.delete_note.__name__, argument='note_id'
2349
            )
2350
2351
        cmd = XmlCommand("delete_note")
2352
        cmd.set_attribute("note_id", note_id)
2353
        cmd.set_attribute("ultimate", _to_bool(ultimate))
2354
2355
        return self._send_xml_command(cmd)
2356
2357
    def delete_override(
2358
        self, override_id: str, *, ultimate: Optional[bool] = False
2359
    ) -> Any:
2360
        """Deletes an existing override
2361
2362
        Arguments:
2363
            override_id: UUID of the override to be deleted.
2364
            ultimate: Whether to remove entirely, or to the trashcan.
2365
        """
2366
        if not override_id:
2367
            raise RequiredArgument(
2368
                function=self.delete_override.__name__, argument='override_id'
2369
            )
2370
2371
        cmd = XmlCommand("delete_override")
2372
        cmd.set_attribute("override_id", override_id)
2373
        cmd.set_attribute("ultimate", _to_bool(ultimate))
2374
2375
        return self._send_xml_command(cmd)
2376
2377
    def delete_permission(
2378
        self, permission_id: str, *, ultimate: Optional[bool] = False
2379
    ) -> Any:
2380
        """Deletes an existing permission
2381
2382
        Arguments:
2383
            permission_id: UUID of the permission to be deleted.
2384
            ultimate: Whether to remove entirely, or to the trashcan.
2385
        """
2386
        if not permission_id:
2387
            raise RequiredArgument(
2388
                function=self.delete_permission.__name__,
2389
                argument='permission_id',
2390
            )
2391
2392
        cmd = XmlCommand("delete_permission")
2393
        cmd.set_attribute("permission_id", permission_id)
2394
        cmd.set_attribute("ultimate", _to_bool(ultimate))
2395
2396
        return self._send_xml_command(cmd)
2397
2398
    def delete_port_list(
2399
        self, port_list_id: str, *, ultimate: Optional[bool] = False
2400
    ) -> Any:
2401
        """Deletes an existing port list
2402
2403
        Arguments:
2404
            port_list_id: UUID of the port list to be deleted.
2405
            ultimate: Whether to remove entirely, or to the trashcan.
2406
        """
2407
        if not port_list_id:
2408
            raise RequiredArgument(
2409
                function=self.delete_port_list.__name__, argument='port_list_id'
2410
            )
2411
2412
        cmd = XmlCommand("delete_port_list")
2413
        cmd.set_attribute("port_list_id", port_list_id)
2414
        cmd.set_attribute("ultimate", _to_bool(ultimate))
2415
2416
        return self._send_xml_command(cmd)
2417
2418
    def delete_port_range(self, port_range_id: str) -> Any:
2419
        """Deletes an existing port range
2420
2421
        Arguments:
2422
            port_range_id: UUID of the port range to be deleted.
2423
        """
2424
        if not port_range_id:
2425
            raise RequiredArgument(
2426
                function=self.delete_port_range.__name__,
2427
                argument='port_range_id',
2428
            )
2429
2430
        cmd = XmlCommand("delete_port_range")
2431
        cmd.set_attribute("port_range_id", port_range_id)
2432
2433
        return self._send_xml_command(cmd)
2434
2435
    def delete_report(self, report_id: str) -> Any:
2436
        """Deletes an existing report
2437
2438
        Arguments:
2439
            report_id: UUID of the report to be deleted.
2440
        """
2441
        if not report_id:
2442
            raise RequiredArgument(
2443
                function=self.delete_report.__name__, argument='report_id'
2444
            )
2445
2446
        cmd = XmlCommand("delete_report")
2447
        cmd.set_attribute("report_id", report_id)
2448
2449
        return self._send_xml_command(cmd)
2450
2451
    def delete_report_format(
2452
        self, report_format_id: str, *, ultimate: Optional[bool] = False
2453
    ) -> Any:
2454
        """Deletes an existing report format
2455
2456
        Arguments:
2457
            report_format_id: UUID of the report format to be deleted.
2458
            ultimate: Whether to remove entirely, or to the trashcan.
2459
        """
2460
        if not report_format_id:
2461
            raise RequiredArgument(
2462
                function=self.delete_report_format.__name__,
2463
                argument='report_format_id',
2464
            )
2465
2466
        cmd = XmlCommand("delete_report_format")
2467
        cmd.set_attribute("report_format_id", report_format_id)
2468
        cmd.set_attribute("ultimate", _to_bool(ultimate))
2469
2470
        return self._send_xml_command(cmd)
2471
2472
    def delete_role(
2473
        self, role_id: str, *, ultimate: Optional[bool] = False
2474
    ) -> Any:
2475
        """Deletes an existing role
2476
2477
        Arguments:
2478
            role_id: UUID of the role to be deleted.
2479
            ultimate: Whether to remove entirely, or to the trashcan.
2480
        """
2481
        if not role_id:
2482
            raise RequiredArgument(
2483
                function=self.delete_role.__name__, argument='role_id'
2484
            )
2485
2486
        cmd = XmlCommand("delete_role")
2487
        cmd.set_attribute("role_id", role_id)
2488
        cmd.set_attribute("ultimate", _to_bool(ultimate))
2489
2490
        return self._send_xml_command(cmd)
2491
2492
    def delete_scanner(
2493
        self, scanner_id: str, *, ultimate: Optional[bool] = False
2494
    ) -> Any:
2495
        """Deletes an existing scanner
2496
2497
        Arguments:
2498
            scanner_id: UUID of the scanner to be deleted.
2499
            ultimate: Whether to remove entirely, or to the trashcan.
2500
        """
2501
        if not scanner_id:
2502
            raise RequiredArgument(
2503
                function=self.delete_scanner.__name__, argument='scanner_id'
2504
            )
2505
2506
        cmd = XmlCommand("delete_scanner")
2507
        cmd.set_attribute("scanner_id", scanner_id)
2508
        cmd.set_attribute("ultimate", _to_bool(ultimate))
2509
2510
        return self._send_xml_command(cmd)
2511
2512
    def delete_schedule(
2513
        self, schedule_id: str, *, ultimate: Optional[bool] = False
2514
    ) -> Any:
2515
        """Deletes an existing schedule
2516
2517
        Arguments:
2518
            schedule_id: UUID of the schedule to be deleted.
2519
            ultimate: Whether to remove entirely, or to the trashcan.
2520
        """
2521
        if not schedule_id:
2522
            raise RequiredArgument(
2523
                function=self.delete_schedule.__name__, argument='schedule_id'
2524
            )
2525
2526
        cmd = XmlCommand("delete_schedule")
2527
        cmd.set_attribute("schedule_id", schedule_id)
2528
        cmd.set_attribute("ultimate", _to_bool(ultimate))
2529
2530
        return self._send_xml_command(cmd)
2531
2532
    def delete_tag(
2533
        self, tag_id: str, *, ultimate: Optional[bool] = False
2534
    ) -> Any:
2535
        """Deletes an existing tag
2536
2537
        Arguments:
2538
            tag_id: UUID of the tag to be deleted.
2539
            ultimate: Whether to remove entirely, or to the trashcan.
2540
        """
2541
        if not tag_id:
2542
            raise RequiredArgument(
2543
                function=self.delete_tag.__name__, argument='tag_id'
2544
            )
2545
2546
        cmd = XmlCommand("delete_tag")
2547
        cmd.set_attribute("tag_id", tag_id)
2548
        cmd.set_attribute("ultimate", _to_bool(ultimate))
2549
2550
        return self._send_xml_command(cmd)
2551
2552
    def delete_target(
2553
        self, target_id: str, *, ultimate: Optional[bool] = False
2554
    ) -> Any:
2555
        """Deletes an existing target
2556
2557
        Arguments:
2558
            target_id: UUID of the target to be deleted.
2559
            ultimate: Whether to remove entirely, or to the trashcan.
2560
        """
2561
        if not target_id:
2562
            raise RequiredArgument(
2563
                function=self.delete_target.__name__, argument='target_id'
2564
            )
2565
2566
        cmd = XmlCommand("delete_target")
2567
        cmd.set_attribute("target_id", target_id)
2568
        cmd.set_attribute("ultimate", _to_bool(ultimate))
2569
2570
        return self._send_xml_command(cmd)
2571
2572
    def delete_task(
2573
        self, task_id: str, *, ultimate: Optional[bool] = False
2574
    ) -> Any:
2575
        """Deletes an existing task
2576
2577
        Arguments:
2578
            task_id: UUID of the task to be deleted.
2579
            ultimate: Whether to remove entirely, or to the trashcan.
2580
        """
2581
        if not task_id:
2582
            raise RequiredArgument(
2583
                function=self.delete_task.__name__, argument='task_id'
2584
            )
2585
2586
        cmd = XmlCommand("delete_task")
2587
        cmd.set_attribute("task_id", task_id)
2588
        cmd.set_attribute("ultimate", _to_bool(ultimate))
2589
2590
        return self._send_xml_command(cmd)
2591
2592
    def delete_user(
2593
        self,
2594
        user_id: str = None,
2595
        *,
2596
        name: Optional[str] = None,
2597
        inheritor_id: Optional[str] = None,
2598
        inheritor_name: Optional[str] = None
2599
    ) -> Any:
2600
        """Deletes an existing user
2601
2602
        Either user_id or name must be passed.
2603
2604
        Arguments:
2605
            user_id: UUID of the task to be deleted.
2606
            name: The name of the user to be deleted.
2607
            inheritor_id: The ID of the inheriting user or "self". Overrides
2608
                inheritor_name.
2609
            inheritor_name: The name of the inheriting user.
2610
2611
        """
2612
        if not user_id and not name:
2613
            raise RequiredArgument(
2614
                function=self.delete_user.__name__, argument='user_id or name'
2615
            )
2616
2617
        cmd = XmlCommand("delete_user")
2618
2619
        if user_id:
2620
            cmd.set_attribute("user_id", user_id)
2621
2622
        if name:
2623
            cmd.set_attribute("name", name)
2624
2625
        if inheritor_id:
2626
            cmd.set_attribute("inheritor_id", inheritor_id)
2627
2628
        if inheritor_name:
2629
            cmd.set_attribute("inheritor_name", inheritor_name)
2630
2631
        return self._send_xml_command(cmd)
2632
2633
    def describe_auth(self) -> Any:
2634
        """Describe authentication methods
2635
2636
        Returns a list of all used authentication methods if such a list is
2637
        available.
2638
2639
        Returns:
2640
            The response. See :py:meth:`send_command` for details.
2641
        """
2642
        return self._send_xml_command(XmlCommand("describe_auth"))
2643
2644
    def empty_trashcan(self) -> Any:
2645
        """Empty the trashcan
2646
2647
        Remove all entities from the trashcan. **Attention:** this command can
2648
        not be reverted
2649
2650
        Returns:
2651
            The response. See :py:meth:`send_command` for details.
2652
        """
2653
        return self._send_xml_command(XmlCommand("empty_trashcan"))
2654
2655
    def get_agents(
2656
        self,
2657
        *,
2658
        filter: Optional[str] = None,
2659
        filter_id: Optional[str] = None,
2660
        trash: Optional[bool] = None,
2661
        details: Optional[bool] = None,
2662
        format: Optional[str] = None
2663
    ) -> Any:
2664
        """Request a list of agents
2665
2666
        Arguments:
2667
            filter: Filter term to use for the query
2668
            filter_id: UUID of an existing filter to use for the query
2669
            trash: True to request the agents in the trashcan
2670
            details: Whether to include agents packageinformation when no format
2671
                was provided
2672
            format: One of "installer", "howto_install" or "howto_use"
2673
2674
        Returns:
2675
            The response. See :py:meth:`send_command` for details.
2676
        """
2677
        cmd = XmlCommand("get_agents")
2678
2679
        _add_filter(cmd, filter, filter_id)
2680
2681
        if trash is not None:
2682
            cmd.set_attribute("trash", _to_bool(trash))
2683
2684
        if details is not None:
2685
            cmd.set_attribute("details", _to_bool(details))
2686
2687
        if format:
2688
            if format not in ("installer", "howto_install", "howto_use"):
2689
                raise InvalidArgument(
2690
                    "installer argument needs to be one of installer, "
2691
                    "howto_install or howto_use"
2692
                )
2693
2694
            cmd.set_attribute("format", format)
2695
2696
        return self._send_xml_command(cmd)
2697
2698
    def get_agent(self, agent_id: str) -> Any:
2699
        """Request a single agent
2700
2701
        Arguments:
2702
            agent_id: UUID of an existing agent
2703
2704
        Returns:
2705
            The response. See :py:meth:`send_command` for details.
2706
        """
2707
        if not agent_id:
2708
            raise RequiredArgument(
2709
                function=self.get_agent.__name__, argument='agent_id'
2710
            )
2711
2712
        cmd = XmlCommand("get_agents")
2713
        cmd.set_attribute("agent_id", agent_id)
2714
2715
        # for single entity always request all details
2716
        cmd.set_attribute("details", "1")
2717
        return self._send_xml_command(cmd)
2718
2719
    def get_aggregates(self, resource_type: EntityType, **kwargs) -> Any:
2720
        """Request aggregated information on a resource type
2721
2722
        Additional arguments can be set via the kwargs parameter, but are not
2723
        yet validated.
2724
2725
        Arguments:
2726
           resource_type: The entity type to gather data from
2727
2728
        Returns:
2729
            The response. See :py:meth:`send_command` for details.
2730
        """
2731
        if not resource_type:
2732
            raise RequiredArgument(
2733
                function=self.get_aggregates.__name__, argument='resource_type'
2734
            )
2735
2736
        if not isinstance(resource_type, self.types.EntityType):
2737
            raise InvalidArgumentType(
2738
                function=self.get_aggregates.__name__,
2739
                argument='resource_type',
2740
                arg_type=self.types.EntityType.__name__,
2741
            )
2742
2743
        cmd = XmlCommand("get_aggregates")
2744
2745
        cmd.set_attribute("type", resource_type.value)
2746
2747
        cmd.set_attributes(kwargs)
2748
        return self._send_xml_command(cmd)
2749
2750
    def get_alerts(
2751
        self,
2752
        *,
2753
        filter: Optional[str] = None,
2754
        filter_id: Optional[str] = None,
2755
        trash: Optional[bool] = None,
2756
        tasks: Optional[bool] = None
2757
    ) -> Any:
2758
        """Request a list of alerts
2759
2760
        Arguments:
2761
            filter: Filter term to use for the query
2762
            filter_id: UUID of an existing filter to use for the query
2763
            trash: True to request the alerts in the trashcan
2764
            tasks: Whether to include the tasks using the alerts
2765
        Returns:
2766
            The response. See :py:meth:`send_command` for details.
2767
        """
2768
        cmd = XmlCommand("get_alerts")
2769
2770
        _add_filter(cmd, filter, filter_id)
2771
2772
        if trash is not None:
2773
            cmd.set_attribute("trash", _to_bool(trash))
2774
2775
        if tasks is not None:
2776
            cmd.set_attribute("tasks", _to_bool(tasks))
2777
2778
        return self._send_xml_command(cmd)
2779
2780
    def get_alert(self, alert_id: str) -> Any:
2781
        """Request a single alert
2782
2783
        Arguments:
2784
            alert_id: UUID of an existing alert
2785
2786
        Returns:
2787
            The response. See :py:meth:`send_command` for details.
2788
        """
2789
        if not alert_id:
2790
            raise RequiredArgument(
2791
                function=self.get_alert.__name__, argument='alert_id'
2792
            )
2793
2794
        cmd = XmlCommand("get_alerts")
2795
        cmd.set_attribute("alert_id", alert_id)
2796
        return self._send_xml_command(cmd)
2797
2798
    def get_assets(
2799
        self,
2800
        asset_type: AssetType,
2801
        *,
2802
        filter: Optional[str] = None,
2803
        filter_id: Optional[str] = None
2804
    ) -> Any:
2805
        """Request a list of assets
2806
2807
        Arguments:
2808
            asset_type: Either 'os' or 'host'
2809
            filter: Filter term to use for the query
2810
            filter_id: UUID of an existing filter to use for the query
2811
2812
        Returns:
2813
            The response. See :py:meth:`send_command` for details.
2814
        """
2815
        if not isinstance(asset_type, AssetType):
2816
            raise InvalidArgumentType(
2817
                function=self.get_assets.__name__,
2818
                argument='asset_type',
2819
                arg_type=AssetType.__name__,
2820
            )
2821
2822
        cmd = XmlCommand("get_assets")
2823
2824
        cmd.set_attribute("type", asset_type.value)
2825
2826
        _add_filter(cmd, filter, filter_id)
2827
2828
        return self._send_xml_command(cmd)
2829
2830
    def get_asset(self, asset_id: str, asset_type: AssetType) -> Any:
2831
        """Request a single asset
2832
2833
        Arguments:
2834
            asset_id: UUID of an existing asset
2835
            asset_type: Either 'os' or 'host'
2836
2837
        Returns:
2838
            The response. See :py:meth:`send_command` for details.
2839
        """
2840
        if not isinstance(asset_type, AssetType):
2841
            raise InvalidArgumentType(
2842
                function=self.get_asset.__name__,
2843
                argument='asset_type',
2844
                arg_type=AssetType.__name__,
2845
            )
2846
2847
        if not asset_id:
2848
            raise RequiredArgument(
2849
                function=self.get_asset.__name__, argument='asset_id'
2850
            )
2851
2852
        cmd = XmlCommand("get_assets")
2853
        cmd.set_attribute("asset_id", asset_id)
2854
        cmd.set_attribute("type", asset_type.value)
2855
2856
        return self._send_xml_command(cmd)
2857
2858 View Code Duplication
    def get_credentials(
0 ignored issues
show
Duplication introduced by
This code seems to be duplicated in your project.
Loading history...
2859
        self,
2860
        *,
2861
        filter: Optional[str] = None,
2862
        filter_id: Optional[str] = None,
2863
        scanners: Optional[bool] = None,
2864
        trash: Optional[bool] = None,
2865
        targets: Optional[bool] = None
2866
    ) -> Any:
2867
        """Request a list of credentials
2868
2869
        Arguments:
2870
            filter: Filter term to use for the query
2871
            filter_id: UUID of an existing filter to use for the query
2872
            scanners: Whether to include a list of scanners using the
2873
                credentials
2874
            trash: Whether to get the trashcan credentials instead
2875
            targets: Whether to include a list of targets using the credentials
2876
2877
        Returns:
2878
            The response. See :py:meth:`send_command` for details.
2879
        """
2880
        cmd = XmlCommand("get_credentials")
2881
2882
        _add_filter(cmd, filter, filter_id)
2883
2884
        if scanners is not None:
2885
            cmd.set_attribute("scanners", _to_bool(scanners))
2886
2887
        if trash is not None:
2888
            cmd.set_attribute("trash", _to_bool(trash))
2889
2890
        if targets is not None:
2891
            cmd.set_attribute("targets", _to_bool(targets))
2892
2893
        return self._send_xml_command(cmd)
2894
2895
    def get_credential(
2896
        self,
2897
        credential_id: str,
2898
        *,
2899
        credential_format: Optional[CredentialFormat] = None
2900
    ) -> Any:
2901
        """Request a single credential
2902
2903
        Arguments:
2904
            credential_id: UUID of an existing credential
2905
            credential_format: One of "key", "rpm", "deb", "exe" or "pem"
2906
2907
        Returns:
2908
            The response. See :py:meth:`send_command` for details.
2909
        """
2910
        if not credential_id:
2911
            raise RequiredArgument(
2912
                function=self.get_credential.__name__, argument='credential_id'
2913
            )
2914
2915
        cmd = XmlCommand("get_credentials")
2916
        cmd.set_attribute("credential_id", credential_id)
2917
2918
        if credential_format:
2919
            if not isinstance(credential_format, CredentialFormat):
2920
                raise InvalidArgumentType(
2921
                    function=self.get_credential.__name__,
2922
                    argument='credential_format',
2923
                    arg_type=CredentialFormat.__name__,
2924
                )
2925
2926
            cmd.set_attribute("format", credential_format.value)
2927
        return self._send_xml_command(cmd)
2928
2929 View Code Duplication
    def get_configs(
0 ignored issues
show
Duplication introduced by
This code seems to be duplicated in your project.
Loading history...
2930
        self,
2931
        *,
2932
        filter: Optional[str] = None,
2933
        filter_id: Optional[str] = None,
2934
        trash: Optional[bool] = None,
2935
        details: Optional[bool] = None,
2936
        families: Optional[bool] = None,
2937
        preferences: Optional[bool] = None,
2938
        tasks: Optional[bool] = None
2939
    ) -> Any:
2940
        """Request a list of scan configs
2941
2942
        Arguments:
2943
            filter: Filter term to use for the query
2944
            filter_id: UUID of an existing filter to use for the query
2945
            trash: Whether to get the trashcan scan configs instead
2946
            details: Whether to get config families, preferences, nvt selectors
2947
                and tasks.
2948
            families: Whether to include the families if no details are
2949
                requested
2950
            preferences: Whether to include the preferences if no details are
2951
                requested
2952
            tasks: Whether to get tasks using this config
2953
2954
        Returns:
2955
            The response. See :py:meth:`send_command` for details.
2956
        """
2957
        cmd = XmlCommand("get_configs")
2958
2959
        _add_filter(cmd, filter, filter_id)
2960
2961
        if trash is not None:
2962
            cmd.set_attribute("trash", _to_bool(trash))
2963
2964
        if details is not None:
2965
            cmd.set_attribute("details", _to_bool(details))
2966
2967
        if families is not None:
2968
            cmd.set_attribute("families", _to_bool(families))
2969
2970
        if preferences is not None:
2971
            cmd.set_attribute("preferences", _to_bool(preferences))
2972
2973
        if tasks is not None:
2974
            cmd.set_attribute("tasks", _to_bool(tasks))
2975
2976
        return self._send_xml_command(cmd)
2977
2978
    def get_config(self, config_id: str) -> Any:
2979
        """Request a single scan config
2980
2981
        Arguments:
2982
            config_id: UUID of an existing scan config
2983
2984
        Returns:
2985
            The response. See :py:meth:`send_command` for details.
2986
        """
2987
        if not config_id:
2988
            raise RequiredArgument(
2989
                function=self.get_config.__name__, argument='config_id'
2990
            )
2991
2992
        cmd = XmlCommand("get_configs")
2993
        cmd.set_attribute("config_id", config_id)
2994
2995
        # for single entity always request all details
2996
        cmd.set_attribute("details", "1")
2997
        return self._send_xml_command(cmd)
2998
2999
    def get_feeds(self) -> Any:
3000
        """Request the list of feeds
3001
3002
        Returns:
3003
            The response. See :py:meth:`send_command` for details.
3004
        """
3005
        return self._send_xml_command(XmlCommand("get_feeds"))
3006
3007
    def get_feed(self, feed_type: Optional[FeedType]) -> Any:
3008
        """Request a single feed
3009
3010
        Arguments:
3011
            feed_type: Type of single feed to get: NVT, CERT or SCAP
3012
3013
        Returns:
3014
            The response. See :py:meth:`send_command` for details.
3015
        """
3016
        if not feed_type:
3017
            raise RequiredArgument(
3018
                function=self.get_feed.__name__, argument='feed_type'
3019
            )
3020
3021
        if not isinstance(feed_type, FeedType):
3022
            raise InvalidArgumentType(
3023
                function=self.get_feed.__name__,
3024
                argument='feed_type',
3025
                arg_type=FeedType.__name__,
3026
            )
3027
3028
        cmd = XmlCommand("get_feeds")
3029
        cmd.set_attribute("type", feed_type.value)
3030
3031
        return self._send_xml_command(cmd)
3032
3033
    def get_filters(
3034
        self,
3035
        *,
3036
        filter: Optional[str] = None,
3037
        filter_id: Optional[str] = None,
3038
        trash: Optional[bool] = None,
3039
        alerts: Optional[bool] = None
3040
    ) -> Any:
3041
        """Request a list of filters
3042
3043
        Arguments:
3044
            filter: Filter term to use for the query
3045
            filter_id: UUID of an existing filter to use for the query
3046
            trash: Whether to get the trashcan filters instead
3047
            alerts: Whether to include list of alerts that use the filter.
3048
3049
        Returns:
3050
            The response. See :py:meth:`send_command` for details.
3051
        """
3052
        cmd = XmlCommand("get_filters")
3053
3054
        _add_filter(cmd, filter, filter_id)
3055
3056
        if trash is not None:
3057
            cmd.set_attribute("trash", _to_bool(trash))
3058
3059
        if alerts is not None:
3060
            cmd.set_attribute("alerts", _to_bool(alerts))
3061
3062
        return self._send_xml_command(cmd)
3063
3064
    def get_filter(self, filter_id: str) -> Any:
3065
        """Request a single filter
3066
3067
        Arguments:
3068
            filter_id: UUID of an existing filter
3069
3070
        Returns:
3071
            The response. See :py:meth:`send_command` for details.
3072
        """
3073
        if not filter_id:
3074
            raise RequiredArgument(
3075
                function=self.get_filter.__name__, argument='filter_id'
3076
            )
3077
3078
        cmd = XmlCommand("get_filters")
3079
        cmd.set_attribute("filter_id", filter_id)
3080
        return self._send_xml_command(cmd)
3081
3082 View Code Duplication
    def get_groups(
0 ignored issues
show
Duplication introduced by
This code seems to be duplicated in your project.
Loading history...
3083
        self,
3084
        *,
3085
        filter: Optional[str] = None,
3086
        filter_id: Optional[str] = None,
3087
        trash: Optional[bool] = None
3088
    ) -> Any:
3089
        """Request a list of groups
3090
3091
        Arguments:
3092
            filter: Filter term to use for the query
3093
            filter_id: UUID of an existing filter to use for the query
3094
            trash: Whether to get the trashcan groups instead
3095
3096
        Returns:
3097
            The response. See :py:meth:`send_command` for details.
3098
        """
3099
        cmd = XmlCommand("get_groups")
3100
3101
        _add_filter(cmd, filter, filter_id)
3102
3103
        if trash is not None:
3104
            cmd.set_attribute("trash", _to_bool(trash))
3105
3106
        return self._send_xml_command(cmd)
3107
3108
    def get_group(self, group_id: str) -> Any:
3109
        """Request a single group
3110
3111
        Arguments:
3112
            group_id: UUID of an existing group
3113
3114
        Returns:
3115
            The response. See :py:meth:`send_command` for details.
3116
        """
3117
        if not group_id:
3118
            raise RequiredArgument(
3119
                function=self.get_group.__name__, argument='group_id'
3120
            )
3121
3122
        cmd = XmlCommand("get_groups")
3123
        cmd.set_attribute("group_id", group_id)
3124
        return self._send_xml_command(cmd)
3125
3126
    def get_info_list(
3127
        self,
3128
        info_type: InfoType,
3129
        *,
3130
        filter: Optional[str] = None,
3131
        filter_id: Optional[str] = None,
3132
        name: Optional[str] = None,
3133
        details: Optional[bool] = None
3134
    ) -> Any:
3135
        """Request a list of security information
3136
3137
        Arguments:
3138
            info_type: Type must be either CERT_BUND_ADV, CPE, CVE,
3139
                DFN_CERT_ADV, OVALDEF, NVT or ALLINFO
3140
            filter: Filter term to use for the query
3141
            filter_id: UUID of an existing filter to use for the query
3142
            name: Name or identifier of the requested information
3143
            details: Whether to include information about references to this
3144
                information
3145
3146
        Returns:
3147
            The response. See :py:meth:`send_command` for details.
3148
        """
3149
        if not info_type:
3150
            raise RequiredArgument(
3151
                function=self.get_info_list.__name__, argument='info_type'
3152
            )
3153
3154
        if not isinstance(info_type, InfoType):
3155
            raise InvalidArgumentType(
3156
                function=self.get_info_list.__name__,
3157
                argument='info_type',
3158
                arg_type=InfoType.__name__,
3159
            )
3160
3161
        cmd = XmlCommand("get_info")
3162
3163
        cmd.set_attribute("type", info_type.value)
3164
3165
        _add_filter(cmd, filter, filter_id)
3166
3167
        if name:
3168
            cmd.set_attribute("name", name)
3169
3170
        if details is not None:
3171
            cmd.set_attribute("details", _to_bool(details))
3172
3173
        return self._send_xml_command(cmd)
3174
3175 View Code Duplication
    def get_info(self, info_id: str, info_type: InfoType) -> Any:
0 ignored issues
show
Duplication introduced by
This code seems to be duplicated in your project.
Loading history...
3176
        """Request a single secinfo
3177
3178
        Arguments:
3179
            info_id: UUID of an existing secinfo
3180
            info_type: Type must be either CERT_BUND_ADV, CPE, CVE,
3181
                DFN_CERT_ADV, OVALDEF, NVT or ALLINFO
3182
3183
        Returns:
3184
            The response. See :py:meth:`send_command` for details.
3185
        """
3186
        if not info_type:
3187
            raise RequiredArgument(
3188
                function=self.get_info.__name__, argument='info_type'
3189
            )
3190
3191
        if not isinstance(info_type, InfoType):
3192
            raise InvalidArgumentType(
3193
                function=self.get_info.__name__,
3194
                argument='info_type',
3195
                arg_type=InfoType.__name__,
3196
            )
3197
3198
        if not info_id:
3199
            raise RequiredArgument(
3200
                function=self.get_info.__name__, argument='info_id'
3201
            )
3202
3203
        cmd = XmlCommand("get_info")
3204
        cmd.set_attribute("info_id", info_id)
3205
3206
        cmd.set_attribute("type", info_type.value)
3207
3208
        # for single entity always request all details
3209
        cmd.set_attribute("details", "1")
3210
        return self._send_xml_command(cmd)
3211
3212 View Code Duplication
    def get_notes(
0 ignored issues
show
Duplication introduced by
This code seems to be duplicated in your project.
Loading history...
3213
        self,
3214
        *,
3215
        filter: Optional[str] = None,
3216
        filter_id: Optional[str] = None,
3217
        details: Optional[bool] = None,
3218
        result: Optional[bool] = None
3219
    ) -> Any:
3220
        """Request a list of notes
3221
3222
        Arguments:
3223
            filter: Filter term to use for the query
3224
            filter_id: UUID of an existing filter to use for the query
3225
            details: Add info about connected results and tasks
3226
            result: Return the details of possible connected results.
3227
3228
        Returns:
3229
            The response. See :py:meth:`send_command` for details.
3230
        """
3231
        cmd = XmlCommand("get_notes")
3232
3233
        _add_filter(cmd, filter, filter_id)
3234
3235
        if details is not None:
3236
            cmd.set_attribute("details", _to_bool(details))
3237
3238
        if result is not None:
3239
            cmd.set_attribute("result", _to_bool(result))
3240
3241
        return self._send_xml_command(cmd)
3242
3243
    def get_note(self, note_id: str) -> Any:
3244
        """Request a single note
3245
3246
        Arguments:
3247
            note_id: UUID of an existing note
3248
3249
        Returns:
3250
            The response. See :py:meth:`send_command` for details.
3251
        """
3252
        if not note_id:
3253
            raise RequiredArgument(
3254
                function=self.get_note.__name__, argument='note_id'
3255
            )
3256
3257
        cmd = XmlCommand("get_notes")
3258
        cmd.set_attribute("note_id", note_id)
3259
3260
        # for single entity always request all details
3261
        cmd.set_attribute("details", "1")
3262
        return self._send_xml_command(cmd)
3263
3264
    def get_nvts(
3265
        self,
3266
        *,
3267
        details: Optional[bool] = None,
3268
        preferences: Optional[bool] = None,
3269
        preference_count: Optional[bool] = None,
3270
        timeout: Optional[bool] = None,
3271
        config_id: Optional[str] = None,
3272
        preferences_config_id: Optional[str] = None,
3273
        family: Optional[str] = None,
3274
        sort_order: Optional[str] = None,
3275
        sort_field: Optional[str] = None
3276
    ):
3277
        """Request a list of nvts
3278
3279
        Arguments:
3280
            details: Whether to include full details
3281
            preferences: Whether to include nvt preferences
3282
            preference_count: Whether to include preference count
3283
            timeout: Whether to include the special timeout preference
3284
            config_id: UUID of scan config to which to limit the NVT listing
3285
            preferences_config_id: UUID of scan config to use for preference
3286
                values
3287
            family: Family to which to limit NVT listing
3288
            sort_order: Sort order
3289
            sort_field: Sort field
3290
3291
        Returns:
3292
            The response. See :py:meth:`send_command` for details.
3293
        """
3294
        cmd = XmlCommand("get_nvts")
3295
3296
        if details is not None:
3297
            cmd.set_attribute("details", _to_bool(details))
3298
3299
        if preferences is not None:
3300
            cmd.set_attribute("preferences", _to_bool(preferences))
3301
3302
        if preference_count is not None:
3303
            cmd.set_attribute("preference_count", _to_bool(preference_count))
3304
3305
        if timeout is not None:
3306
            cmd.set_attribute("timeout", _to_bool(timeout))
3307
3308
        if config_id:
3309
            cmd.set_attribute("config_id", config_id)
3310
3311
        if preferences_config_id:
3312
            cmd.set_attribute("preferences_config_id", preferences_config_id)
3313
3314
        if family:
3315
            cmd.set_attribute("family", family)
3316
3317
        if sort_order:
3318
            cmd.set_attribute("sort_order", sort_order)
3319
3320
        if sort_field:
3321
            cmd.set_attribute("sort_field", sort_field)
3322
3323
        return self._send_xml_command(cmd)
3324
3325
    def get_nvt(self, nvt_oid: str):
3326
        """Request a single nvt
3327
3328
        Arguments:
3329
            nvt_oid: OID of an existing nvt
3330
3331
        Returns:
3332
            The response. See :py:meth:`send_command` for details.
3333
        """
3334
        if not nvt_oid:
3335
            raise RequiredArgument(
3336
                function=self.get_nvt.__name__, argument='nvt_oid'
3337
            )
3338
3339
        cmd = XmlCommand("get_nvts")
3340
        cmd.set_attribute("nvt_oid", nvt_oid)
3341
3342
        # for single entity always request all details
3343
        cmd.set_attribute("details", "1")
3344
        return self._send_xml_command(cmd)
3345
3346
    def get_nvt_families(self, *, sort_order: Optional[str] = None):
3347
        """Request a list of nvt families
3348
3349
        Arguments:
3350
            sort_order: Sort order
3351
3352
        Returns:
3353
            The response. See :py:meth:`send_command` for details.
3354
        """
3355
        cmd = XmlCommand("get_nvt_families")
3356
3357
        if sort_order:
3358
            cmd.set_attribute("sort_order", sort_order)
3359
3360
        return self._send_xml_command(cmd)
3361
3362 View Code Duplication
    def get_overrides(
0 ignored issues
show
Duplication introduced by
This code seems to be duplicated in your project.
Loading history...
3363
        self,
3364
        *,
3365
        filter: Optional[str] = None,
3366
        filter_id: Optional[str] = None,
3367
        details: Optional[bool] = None,
3368
        result: Optional[bool] = None
3369
    ) -> Any:
3370
        """Request a list of overrides
3371
3372
        Arguments:
3373
            filter: Filter term to use for the query
3374
            filter_id: UUID of an existing filter to use for the query
3375
            details: Whether to include full details
3376
            result: Whether to include results using the override
3377
3378
        Returns:
3379
            The response. See :py:meth:`send_command` for details.
3380
        """
3381
        cmd = XmlCommand("get_overrides")
3382
3383
        _add_filter(cmd, filter, filter_id)
3384
3385
        if details is not None:
3386
            cmd.set_attribute("details", _to_bool(details))
3387
3388
        if result is not None:
3389
            cmd.set_attribute("result", _to_bool(result))
3390
3391
        return self._send_xml_command(cmd)
3392
3393
    def get_override(self, override_id: str) -> Any:
3394
        """Request a single override
3395
3396
        Arguments:
3397
            override_id: UUID of an existing override
3398
3399
        Returns:
3400
            The response. See :py:meth:`send_command` for details.
3401
        """
3402
        if not override_id:
3403
            raise RequiredArgument(
3404
                function=self.get_override.__name__, argument='override_id'
3405
            )
3406
3407
        cmd = XmlCommand("get_overrides")
3408
        cmd.set_attribute("override_id", override_id)
3409
3410
        # for single entity always request all details
3411
        cmd.set_attribute("details", "1")
3412
        return self._send_xml_command(cmd)
3413
3414 View Code Duplication
    def get_permissions(
0 ignored issues
show
Duplication introduced by
This code seems to be duplicated in your project.
Loading history...
3415
        self,
3416
        *,
3417
        filter: Optional[str] = None,
3418
        filter_id: Optional[str] = None,
3419
        trash: Optional[bool] = None
3420
    ) -> Any:
3421
        """Request a list of permissions
3422
3423
        Arguments:
3424
            filter: Filter term to use for the query
3425
            filter_id: UUID of an existing filter to use for the query
3426
            trash: Whether to get permissions in the trashcan instead
3427
3428
        Returns:
3429
            The response. See :py:meth:`send_command` for details.
3430
        """
3431
        cmd = XmlCommand("get_permissions")
3432
3433
        _add_filter(cmd, filter, filter_id)
3434
3435
        if trash is not None:
3436
            cmd.set_attribute("trash", _to_bool(trash))
3437
3438
        return self._send_xml_command(cmd)
3439
3440
    def get_permission(self, permission_id: str) -> Any:
3441
        """Request a single permission
3442
3443
        Arguments:
3444
            permission_id: UUID of an existing permission
3445
3446
        Returns:
3447
            The response. See :py:meth:`send_command` for details.
3448
        """
3449
        if not permission_id:
3450
            raise RequiredArgument(
3451
                function=self.get_permission.__name__, argument='permission_id'
3452
            )
3453
3454
        cmd = XmlCommand("get_permissions")
3455
        cmd.set_attribute("permission_id", permission_id)
3456
        return self._send_xml_command(cmd)
3457
3458 View Code Duplication
    def get_port_lists(
0 ignored issues
show
Duplication introduced by
This code seems to be duplicated in your project.
Loading history...
3459
        self,
3460
        *,
3461
        filter: Optional[str] = None,
3462
        filter_id: Optional[str] = None,
3463
        details: Optional[bool] = None,
3464
        targets: Optional[bool] = None,
3465
        trash: Optional[bool] = None
3466
    ) -> Any:
3467
        """Request a list of port lists
3468
3469
        Arguments:
3470
            filter: Filter term to use for the query
3471
            filter_id: UUID of an existing filter to use for the query
3472
            details: Whether to include full port list details
3473
            targets: Whether to include targets using this port list
3474
            trash: Whether to get port lists in the trashcan instead
3475
3476
        Returns:
3477
            The response. See :py:meth:`send_command` for details.
3478
        """
3479
        cmd = XmlCommand("get_port_lists")
3480
3481
        _add_filter(cmd, filter, filter_id)
3482
3483
        if details is not None:
3484
            cmd.set_attribute("details", _to_bool(details))
3485
3486
        if targets is not None:
3487
            cmd.set_attribute("targets", _to_bool(targets))
3488
3489
        if trash is not None:
3490
            cmd.set_attribute("trash", _to_bool(trash))
3491
3492
        return self._send_xml_command(cmd)
3493
3494
    def get_port_list(self, port_list_id: str):
3495
        """Request a single port list
3496
3497
        Arguments:
3498
            port_list_id: UUID of an existing port list
3499
3500
        Returns:
3501
            The response. See :py:meth:`send_command` for details.
3502
        """
3503
        if not port_list_id:
3504
            raise RequiredArgument(
3505
                function=self.get_port_list.__name__, argument='port_list_id'
3506
            )
3507
3508
        cmd = XmlCommand("get_port_lists")
3509
        cmd.set_attribute("port_list_id", port_list_id)
3510
3511
        # for single entity always request all details
3512
        cmd.set_attribute("details", "1")
3513
        return self._send_xml_command(cmd)
3514
3515
    def get_preferences(
3516
        self, *, nvt_oid: Optional[str] = None, config_id: Optional[str] = None
3517
    ) -> Any:
3518
        """Request a list of preferences
3519
3520
        When the command includes a config_id attribute, the preference element
3521
        includes the preference name, type and value, and the NVT to which the
3522
        preference applies. Otherwise, the preference element includes just the
3523
        name and value, with the NVT and type built into the name.
3524
3525
        Arguments:
3526
            nvt_oid: OID of nvt
3527
            config_id: UUID of scan config of which to show preference values
3528
3529
        Returns:
3530
            The response. See :py:meth:`send_command` for details.
3531
        """
3532
        cmd = XmlCommand("get_preferences")
3533
3534
        if nvt_oid:
3535
            cmd.set_attribute("nvt_oid", nvt_oid)
3536
3537
        if config_id:
3538
            cmd.set_attribute("config_id", config_id)
3539
3540
        return self._send_xml_command(cmd)
3541
3542
    def get_preference(self, name: str) -> Any:
3543
        """Request a nvt preference
3544
3545
3546
        Arguments:
3547
            name: name of a particular preference
3548
3549
        Returns:
3550
            The response. See :py:meth:`send_command` for details.
3551
        """
3552
        if not name:
3553
            raise RequiredArgument(
3554
                function=self.get_preference.__name__, argument='name'
3555
            )
3556
3557
        cmd = XmlCommand("get_preferences")
3558
3559
        cmd.set_attribute("preference", name)
3560
3561
        return self._send_xml_command(cmd)
3562
3563
    def get_reports(
3564
        self,
3565
        *,
3566
        filter: Optional[str] = None,
3567
        filter_id: Optional[str] = None,
3568
        note_details: Optional[bool] = None,
3569
        override_details: Optional[bool] = None,
3570
        no_details: Optional[bool] = None
3571
    ) -> Any:
3572
        """Request a list of reports
3573
3574
        Arguments:
3575
            filter: Filter term to use for the query
3576
            filter_id: UUID of an existing filter to use for the query
3577
            note_details: If notes are included, whether to include note details
3578
            override_details: If overrides are included, whether to include
3579
                override details
3580
            no_details: Whether to exclude results
3581
3582
        Returns:
3583
            The response. See :py:meth:`send_command` for details.
3584
        """
3585
        cmd = XmlCommand("get_reports")
3586
3587
        if filter:
3588
            cmd.set_attribute("report_filter", filter)
3589
3590
        if filter_id:
3591
            cmd.set_attribute("report_filt_id", filter_id)
3592
3593
        if note_details is not None:
3594
            cmd.set_attribute("note_details", _to_bool(note_details))
3595
3596
        if override_details is not None:
3597
            cmd.set_attribute("override_details", _to_bool(override_details))
3598
3599
        if no_details is not None:
3600
            cmd.set_attribute("details", _to_bool(not no_details))
3601
3602
        cmd.set_attribute("ignore_pagination", "1")
3603
3604
        return self._send_xml_command(cmd)
3605
3606
    def get_report(
3607
        self,
3608
        report_id: str,
3609
        *,
3610
        filter: Optional[str] = None,
3611
        filter_id: Optional[str] = None,
3612
        delta_report_id: Optional[str] = None,
3613
        report_format_id: Optional[str] = None,
3614
        ignore_pagination: Optional[bool] = None,
3615
        details: Optional[bool] = None
3616
    ) -> Any:
3617
        """Request a single report
3618
3619
        Arguments:
3620
            report_id: UUID of an existing report
3621
            filter: Filter term to use to filter results in the report
3622
            filter_id: UUID of filter to use to filter results in the report
3623
            delta_report_id: UUID of an existing report to compare report to.
3624
            report_format_id: UUID of report format to use
3625
            ignore_pagination: Whether to ignore the filter terms "first" and
3626
                "rows".
3627
            details: Request additional report information details
3628
3629
        Returns:
3630
            The response. See :py:meth:`send_command` for details.
3631
        """
3632
        if not report_id:
3633
            raise RequiredArgument(
3634
                function=self.get_report.__name__, argument='report_id'
3635
            )
3636
3637
        cmd = XmlCommand("get_reports")
3638
        cmd.set_attribute("report_id", report_id)
3639
3640
        _add_filter(cmd, filter, filter_id)
3641
3642
        if delta_report_id:
3643
            cmd.set_attribute("delta_report_id", delta_report_id)
3644
3645
        if report_format_id:
3646
            cmd.set_attribute("format_id", report_format_id)
3647
3648
        if ignore_pagination is not None:
3649
            cmd.set_attribute("ignore_pagination", _to_bool(ignore_pagination))
3650
3651
        if details is not None:
3652
            cmd.set_attribute("details", _to_bool(details))
3653
3654
        return self._send_xml_command(cmd)
3655
3656
    def get_report_formats(
3657
        self,
3658
        *,
3659
        filter: Optional[str] = None,
3660
        filter_id: Optional[str] = None,
3661
        trash: Optional[bool] = None,
3662
        alerts: Optional[bool] = None,
3663
        params: Optional[bool] = None,
3664
        details: Optional[bool] = None
3665
    ) -> Any:
3666
        """Request a list of report formats
3667
3668
        Arguments:
3669
            filter: Filter term to use for the query
3670
            filter_id: UUID of an existing filter to use for the query
3671
            trash: Whether to get the trashcan report formats instead
3672
            alerts: Whether to include alerts that use the report format
3673
            params: Whether to include report format parameters
3674
            details: Include report format file, signature and parameters
3675
3676
        Returns:
3677
            The response. See :py:meth:`send_command` for details.
3678
        """
3679
        cmd = XmlCommand("get_report_formats")
3680
3681
        _add_filter(cmd, filter, filter_id)
3682
3683
        if details is not None:
3684
            cmd.set_attribute("details", _to_bool(details))
3685
3686
        if alerts is not None:
3687
            cmd.set_attribute("alerts", _to_bool(alerts))
3688
3689
        if params is not None:
3690
            cmd.set_attribute("params", _to_bool(params))
3691
3692
        if trash is not None:
3693
            cmd.set_attribute("trash", _to_bool(trash))
3694
3695
        return self._send_xml_command(cmd)
3696
3697
    def get_report_format(self, report_format_id: str) -> Any:
3698
        """Request a single report format
3699
3700
        Arguments:
3701
            report_format_id: UUID of an existing report format
3702
3703
        Returns:
3704
            The response. See :py:meth:`send_command` for details.
3705
        """
3706
        if not report_format_id:
3707
            raise RequiredArgument(
3708
                function=self.get_report_format.__name__,
3709
                argument='report_format_id',
3710
            )
3711
3712
        cmd = XmlCommand("get_report_formats")
3713
        cmd.set_attribute("report_format_id", report_format_id)
3714
3715
        # for single entity always request all details
3716
        cmd.set_attribute("details", "1")
3717
        return self._send_xml_command(cmd)
3718
3719
    def get_results(
3720
        self,
3721
        *,
3722
        filter: Optional[str] = None,
3723
        filter_id: Optional[str] = None,
3724
        task_id: Optional[str] = None,
3725
        note_details: Optional[bool] = None,
3726
        override_details: Optional[bool] = None,
3727
        details: Optional[bool] = None
3728
    ) -> Any:
3729
        """Request a list of results
3730
3731
        Arguments:
3732
            filter: Filter term to use for the query
3733
            filter_id: UUID of an existing filter to use for the query
3734
            task_id: UUID of task for note and override handling
3735
            note_details: If notes are included, whether to include note details
3736
            override_details: If overrides are included, whether to include
3737
                override details
3738
            details: Whether to include additional details of the results
3739
3740
        Returns:
3741
            The response. See :py:meth:`send_command` for details.
3742
        """
3743
        cmd = XmlCommand("get_results")
3744
3745
        _add_filter(cmd, filter, filter_id)
3746
3747
        if task_id:
3748
            cmd.set_attribute("task_id", task_id)
3749
3750
        if details is not None:
3751
            cmd.set_attribute("details", _to_bool(details))
3752
3753
        if note_details is not None:
3754
            cmd.set_attribute("note_details", _to_bool(note_details))
3755
3756
        if override_details is not None:
3757
            cmd.set_attribute("override_details", _to_bool(override_details))
3758
3759
        return self._send_xml_command(cmd)
3760
3761
    def get_result(self, result_id: str) -> Any:
3762
        """Request a single result
3763
3764
        Arguments:
3765
            result_id: UUID of an existing result
3766
3767
        Returns:
3768
            The response. See :py:meth:`send_command` for details.
3769
        """
3770
        if not result_id:
3771
            raise RequiredArgument(
3772
                function=self.get_result.__name__, argument='result_id'
3773
            )
3774
3775
        cmd = XmlCommand("get_results")
3776
        cmd.set_attribute("result_id", result_id)
3777
3778
        # for single entity always request all details
3779
        cmd.set_attribute("details", "1")
3780
        return self._send_xml_command(cmd)
3781
3782 View Code Duplication
    def get_roles(
0 ignored issues
show
Duplication introduced by
This code seems to be duplicated in your project.
Loading history...
3783
        self,
3784
        *,
3785
        filter: Optional[str] = None,
3786
        filter_id: Optional[str] = None,
3787
        trash: Optional[bool] = None
3788
    ) -> Any:
3789
        """Request a list of roles
3790
3791
        Arguments:
3792
            filter: Filter term to use for the query
3793
            filter_id: UUID of an existing filter to use for the query
3794
            trash: Whether to get the trashcan roles instead
3795
3796
        Returns:
3797
            The response. See :py:meth:`send_command` for details.
3798
        """
3799
        cmd = XmlCommand("get_roles")
3800
3801
        _add_filter(cmd, filter, filter_id)
3802
3803
        if trash is not None:
3804
            cmd.set_attribute("trash", _to_bool(trash))
3805
3806
        return self._send_xml_command(cmd)
3807
3808
    def get_role(self, role_id: str) -> Any:
3809
        """Request a single role
3810
3811
        Arguments:
3812
            role_id: UUID of an existing role
3813
3814
        Returns:
3815
            The response. See :py:meth:`send_command` for details.
3816
        """
3817
        if not role_id:
3818
            raise RequiredArgument(
3819
                function=self.get_role.__name__, argument='role_id'
3820
            )
3821
3822
        cmd = XmlCommand("get_roles")
3823
        cmd.set_attribute("role_id", role_id)
3824
        return self._send_xml_command(cmd)
3825
3826 View Code Duplication
    def get_scanners(
0 ignored issues
show
Duplication introduced by
This code seems to be duplicated in your project.
Loading history...
3827
        self,
3828
        *,
3829
        filter: Optional[str] = None,
3830
        filter_id: Optional[str] = None,
3831
        trash: Optional[bool] = None,
3832
        details: Optional[bool] = None
3833
    ) -> Any:
3834
        """Request a list of scanners
3835
3836
        Arguments:
3837
            filter: Filter term to use for the query
3838
            filter_id: UUID of an existing filter to use for the query
3839
            trash: Whether to get the trashcan scanners instead
3840
            details:  Whether to include extra details like tasks using this
3841
                scanner
3842
3843
        Returns:
3844
            The response. See :py:meth:`send_command` for details.
3845
        """
3846
        cmd = XmlCommand("get_scanners")
3847
3848
        _add_filter(cmd, filter, filter_id)
3849
3850
        if trash is not None:
3851
            cmd.set_attribute("trash", _to_bool(trash))
3852
3853
        if details is not None:
3854
            cmd.set_attribute("details", _to_bool(details))
3855
3856
        return self._send_xml_command(cmd)
3857
3858
    def get_scanner(self, scanner_id: str) -> Any:
3859
        """Request a single scanner
3860
3861
        Arguments:
3862
            scanner_id: UUID of an existing scanner
3863
3864
        Returns:
3865
            The response. See :py:meth:`send_command` for details.
3866
        """
3867
        if not scanner_id:
3868
            raise RequiredArgument(
3869
                function=self.get_scanner.__name__, argument='scanner_id'
3870
            )
3871
3872
        cmd = XmlCommand("get_scanners")
3873
        cmd.set_attribute("scanner_id", scanner_id)
3874
3875
        # for single entity always request all details
3876
        cmd.set_attribute("details", "1")
3877
        return self._send_xml_command(cmd)
3878
3879
    def get_schedules(
3880
        self,
3881
        *,
3882
        filter: Optional[str] = None,
3883
        filter_id: Optional[str] = None,
3884
        trash: Optional[bool] = None,
3885
        tasks: Optional[bool] = None
3886
    ) -> Any:
3887
        """Request a list of schedules
3888
3889
        Arguments:
3890
            filter: Filter term to use for the query
3891
            filter_id: UUID of an existing filter to use for the query
3892
            trash: Whether to get the trashcan schedules instead
3893
            tasks: Whether to include tasks using the schedules
3894
3895
        Returns:
3896
            The response. See :py:meth:`send_command` for details.
3897
        """
3898
        cmd = XmlCommand("get_schedules")
3899
3900
        _add_filter(cmd, filter, filter_id)
3901
3902
        if trash is not None:
3903
            cmd.set_attribute("trash", _to_bool(trash))
3904
3905
        if tasks is not None:
3906
            cmd.set_attribute("tasks", _to_bool(tasks))
3907
3908
        return self._send_xml_command(cmd)
3909
3910
    def get_schedule(self, schedule_id: str) -> Any:
3911
        """Request a single schedule
3912
3913
        Arguments:
3914
            schedule_id: UUID of an existing schedule
3915
3916
        Returns:
3917
            The response. See :py:meth:`send_command` for details.
3918
        """
3919
        if not schedule_id:
3920
            raise RequiredArgument(
3921
                function=self.get_schedule.__name__, argument='schedule_id'
3922
            )
3923
3924
        cmd = XmlCommand("get_schedules")
3925
        cmd.set_attribute("schedule_id", schedule_id)
3926
        return self._send_xml_command(cmd)
3927
3928
    def get_settings(self, *, filter: Optional[str] = None) -> Any:
3929
        """Request a list of user settings
3930
3931
        Arguments:
3932
            filter: Filter term to use for the query
3933
3934
        Returns:
3935
            The response. See :py:meth:`send_command` for details.
3936
        """
3937
        cmd = XmlCommand("get_settings")
3938
3939
        if filter:
3940
            cmd.set_attribute("filter", filter)
3941
3942
        return self._send_xml_command(cmd)
3943
3944
    def get_setting(self, setting_id: str) -> Any:
3945
        """Request a single setting
3946
3947
        Arguments:
3948
            setting_id: UUID of an existing setting
3949
3950
        Returns:
3951
            The response. See :py:meth:`send_command` for details.
3952
        """
3953
        if not setting_id:
3954
            raise RequiredArgument(
3955
                function=self.get_setting.__name__, argument='setting_id'
3956
            )
3957
3958
        cmd = XmlCommand("get_settings")
3959
        cmd.set_attribute("setting_id", setting_id)
3960
        return self._send_xml_command(cmd)
3961
3962
    def get_system_reports(
3963
        self,
3964
        *,
3965
        name: Optional[str] = None,
3966
        duration: Optional[int] = None,
3967
        start_time: Optional[str] = None,
3968
        end_time: Optional[str] = None,
3969
        brief: Optional[bool] = None,
3970
        slave_id: Optional[str] = None
3971
    ) -> Any:
3972
        """Request a list of system reports
3973
3974
        Arguments:
3975
            name: A string describing the required system report
3976
            duration: The number of seconds into the past that the system report
3977
                should include
3978
            start_time: The start of the time interval the system report should
3979
                include in ISO time format
3980
            end_time: The end of the time interval the system report should
3981
                include in ISO time format
3982
            brief: Whether to include the actual system reports
3983
            slave_id: UUID of GMP scanner from which to get the system reports
3984
3985
        Returns:
3986
            The response. See :py:meth:`send_command` for details.
3987
        """
3988
        cmd = XmlCommand("get_system_reports")
3989
3990
        if name:
3991
            cmd.set_attribute("name", name)
3992
3993
        if duration is not None:
3994
            if not isinstance(duration, numbers.Integral):
3995
                raise InvalidArgument("duration needs to be an integer number")
3996
3997
            cmd.set_attribute("duration", str(duration))
3998
3999
        if start_time:
4000
            cmd.set_attribute("start_time", str(start_time))
4001
4002
        if end_time:
4003
            cmd.set_attribute("end_time", str(end_time))
4004
4005
        if brief is not None:
4006
            cmd.set_attribute("brief", _to_bool(brief))
4007
4008
        if slave_id:
4009
            cmd.set_attribute("slave_id", slave_id)
4010
4011
        return self._send_xml_command(cmd)
4012
4013
    def get_tags(
4014
        self,
4015
        *,
4016
        filter: Optional[str] = None,
4017
        filter_id: Optional[str] = None,
4018
        trash: Optional[bool] = None,
4019
        names_only: Optional[bool] = None
4020
    ) -> Any:
4021
        """Request a list of tags
4022
4023
        Arguments:
4024
            filter: Filter term to use for the query
4025
            filter_id: UUID of an existing filter to use for the query
4026
            trash: Whether to get tags from the trashcan instead
4027
            names_only: Whether to get only distinct tag names
4028
4029
        Returns:
4030
            The response. See :py:meth:`send_command` for details.
4031
        """
4032
        cmd = XmlCommand("get_tags")
4033
4034
        _add_filter(cmd, filter, filter_id)
4035
4036
        if trash is not None:
4037
            cmd.set_attribute("trash", _to_bool(trash))
4038
4039
        if names_only is not None:
4040
            cmd.set_attribute("names_only", _to_bool(names_only))
4041
4042
        return self._send_xml_command(cmd)
4043
4044
    def get_tag(self, tag_id: str) -> Any:
4045
        """Request a single tag
4046
4047
        Arguments:
4048
            tag_id: UUID of an existing tag
4049
4050
        Returns:
4051
            The response. See :py:meth:`send_command` for details.
4052
        """
4053
        if not tag_id:
4054
            raise RequiredArgument(
4055
                function=self.get_tag.__name__, argument='tag_id'
4056
            )
4057
4058
        cmd = XmlCommand("get_tags")
4059
        cmd.set_attribute("tag_id", tag_id)
4060
        return self._send_xml_command(cmd)
4061
4062
    def get_targets(
4063
        self,
4064
        *,
4065
        filter: Optional[str] = None,
4066
        filter_id: Optional[str] = None,
4067
        trash: Optional[bool] = None,
4068
        tasks: Optional[bool] = None
4069
    ) -> Any:
4070
        """Request a list of targets
4071
4072
        Arguments:
4073
            filter: Filter term to use for the query
4074
            filter_id: UUID of an existing filter to use for the query
4075
            trash: Whether to get the trashcan targets instead
4076
            tasks: Whether to include list of tasks that use the target
4077
4078
        Returns:
4079
            The response. See :py:meth:`send_command` for details.
4080
        """
4081
        cmd = XmlCommand("get_targets")
4082
4083
        _add_filter(cmd, filter, filter_id)
4084
4085
        if trash is not None:
4086
            cmd.set_attribute("trash", _to_bool(trash))
4087
4088
        if tasks is not None:
4089
            cmd.set_attribute("tasks", _to_bool(tasks))
4090
4091
        return self._send_xml_command(cmd)
4092
4093
    def get_target(self, target_id: str) -> Any:
4094
        """Request a single target
4095
4096
        Arguments:
4097
            target_id: UUID of an existing target
4098
4099
        Returns:
4100
            The response. See :py:meth:`send_command` for details.
4101
        """
4102
        if not target_id:
4103
            raise RequiredArgument(
4104
                function=self.get_target.__name__, argument='target_id'
4105
            )
4106
4107
        cmd = XmlCommand("get_targets")
4108
        cmd.set_attribute("target_id", target_id)
4109
        return self._send_xml_command(cmd)
4110
4111
    def get_tasks(
4112
        self,
4113
        *,
4114
        filter: Optional[str] = None,
4115
        filter_id: Optional[str] = None,
4116
        trash: Optional[bool] = None,
4117
        details: Optional[bool] = None,
4118
        schedules_only: Optional[bool] = None
4119
    ) -> Any:
4120
        """Request a list of tasks
4121
4122
        Arguments:
4123
            filter: Filter term to use for the query
4124
            filter_id: UUID of an existing filter to use for the query
4125
            trash: Whether to get the trashcan tasks instead
4126
            details: Whether to include full task details
4127
            schedules_only: Whether to only include id, name and schedule
4128
                details
4129
4130
        Returns:
4131
            The response. See :py:meth:`send_command` for details.
4132
        """
4133
        cmd = XmlCommand("get_tasks")
4134
4135
        _add_filter(cmd, filter, filter_id)
4136
4137
        if trash is not None:
4138
            cmd.set_attribute("trash", _to_bool(trash))
4139
4140
        if details is not None:
4141
            cmd.set_attribute("details", _to_bool(details))
4142
4143
        if schedules_only is not None:
4144
            cmd.set_attribute("schedules_only", _to_bool(schedules_only))
4145
4146
        return self._send_xml_command(cmd)
4147
4148
    def get_task(self, task_id: str) -> Any:
4149
        """Request a single task
4150
4151
        Arguments:
4152
            task_id: UUID of an existing task
4153
4154
        Returns:
4155
            The response. See :py:meth:`send_command` for details.
4156
        """
4157
        if not task_id:
4158
            raise RequiredArgument(
4159
                function=self.get_task.__name__, argument='task_id'
4160
            )
4161
4162
        cmd = XmlCommand("get_tasks")
4163
        cmd.set_attribute("task_id", task_id)
4164
4165
        # for single entity always request all details
4166
        cmd.set_attribute("details", "1")
4167
        return self._send_xml_command(cmd)
4168
4169
    def get_users(
4170
        self, *, filter: Optional[str] = None, filter_id: Optional[str] = None
4171
    ) -> Any:
4172
        """Request a list of users
4173
4174
        Arguments:
4175
            filter: Filter term to use for the query
4176
            filter_id: UUID of an existing filter to use for the query
4177
4178
        Returns:
4179
            The response. See :py:meth:`send_command` for details.
4180
        """
4181
        cmd = XmlCommand("get_users")
4182
4183
        _add_filter(cmd, filter, filter_id)
4184
4185
        return self._send_xml_command(cmd)
4186
4187
    def get_user(self, user_id: str) -> Any:
4188
        """Request a single user
4189
4190
        Arguments:
4191
            user_id: UUID of an existing user
4192
4193
        Returns:
4194
            The response. See :py:meth:`send_command` for details.
4195
        """
4196
        if not user_id:
4197
            raise RequiredArgument(
4198
                function=self.get_user.__name__, argument='user_id'
4199
            )
4200
4201
        cmd = XmlCommand("get_users")
4202
        cmd.set_attribute("user_id", user_id)
4203
        return self._send_xml_command(cmd)
4204
4205
    def get_version(self) -> Any:
4206
        """Get the Greenbone Manager Protocol version used by the remote gvmd
4207
4208
        Returns:
4209
            The response. See :py:meth:`send_command` for details.
4210
        """
4211
        return self._send_xml_command(XmlCommand("get_version"))
4212
4213
    def help(
4214
        self, *, format: Optional[str] = None, help_type: Optional[str] = ""
4215
    ) -> Any:
4216
        """Get the help text
4217
4218
        Arguments:
4219
            format: One of "html", "rnc", "text" or "xml
4220
            help_type: One of "brief" or "". Default ""
4221
4222
        Returns:
4223
            The response. See :py:meth:`send_command` for details.
4224
        """
4225
        cmd = XmlCommand("help")
4226
4227
        if help_type not in ("", "brief"):
4228
            raise InvalidArgument(
4229
                'help_type argument must be an empty string or "brief"'
4230
            )
4231
4232
        cmd.set_attribute("type", help_type)
4233
4234
        if format:
4235
            if not format.lower() in ("html", "rnc", "text", "xml"):
4236
                raise InvalidArgument(
4237
                    "help format Argument must be one of html, rnc, text or "
4238
                    "xml"
4239
                )
4240
4241
            cmd.set_attribute("format", format)
4242
4243
        return self._send_xml_command(cmd)
4244
4245
    def modify_agent(
4246
        self,
4247
        agent_id: str,
4248
        *,
4249
        name: Optional[str] = None,
4250
        comment: Optional[str] = None
4251
    ) -> Any:
4252
        """Modifies an existing agent
4253
4254
        Arguments:
4255
            agent_id: UUID of the agent to be modified.
4256
            name: Name of the new credential
4257
            comment: Comment for the credential
4258
4259
        Returns:
4260
            The response. See :py:meth:`send_command` for details.
4261
        """
4262
        if not agent_id:
4263
            raise RequiredArgument(
4264
                function=self.modify_agent.__name__, argument='agent_id'
4265
            )
4266
4267
        cmd = XmlCommand("modify_agent")
4268
        cmd.set_attribute("agent_id", str(agent_id))
4269
4270
        if name:
4271
            cmd.add_element("name", name)
4272
4273
        if comment:
4274
            cmd.add_element("comment", comment)
4275
4276
        return self._send_xml_command(cmd)
4277
4278
    def modify_alert(
4279
        self,
4280
        alert_id: str,
4281
        *,
4282
        name: Optional[str] = None,
4283
        comment: Optional[str] = None,
4284
        filter_id: Optional[str] = None,
4285
        event: Optional[AlertEvent] = None,
4286
        event_data: Optional[dict] = None,
4287
        condition: Optional[AlertCondition] = None,
4288
        condition_data: Optional[dict] = None,
4289
        method: Optional[AlertMethod] = None,
4290
        method_data: Optional[dict] = None
4291
    ) -> Any:
4292
        """Modifies an existing alert.
4293
4294
        Arguments:
4295
            alert_id: UUID of the alert to be modified.
4296
            name: Name of the Alert.
4297
            condition: The condition that must be satisfied for the alert to
4298
                occur. If the event is either 'Updated SecInfo
4299
                arrived' or 'New SecInfo arrived', condition must be 'Always'.
4300
                Otherwise, condition can also be on of 'Severity at least',
4301
                'Filter count changed' or 'Filter count at least'.
4302
            condition_data: Data that defines the condition
4303
            event: The event that must happen for the alert to occur, one of
4304
                'Task run status changed', 'Updated SecInfo arrived' or
4305
                'New SecInfo arrived'
4306
            event_data: Data that defines the event
4307
            method: The method by which the user is alerted, one of 'SCP',
4308
                'Send', 'SMB', 'SNMP', 'Syslog' or 'Email';
4309
                if the event is neither 'Updated SecInfo arrived' nor
4310
                'New SecInfo arrived', method can also be one of 'Start Task',
4311
                'HTTP Get', 'Sourcefire Connector' or 'verinice Connector'.
4312
            method_data: Data that defines the method
4313
            filter_id: Filter to apply when executing alert
4314
            comment: Comment for the alert
4315
4316
        Returns:
4317
            The response. See :py:meth:`send_command` for details.
4318
        """
4319
4320
        if not alert_id:
4321
            raise RequiredArgument(
4322
                function=self.modify_alert.__name__, argument='alert_id'
4323
            )
4324
4325
        cmd = XmlCommand("modify_alert")
4326
        cmd.set_attribute("alert_id", str(alert_id))
4327
4328
        if name:
4329
            cmd.add_element("name", name)
4330
4331
        if comment:
4332
            cmd.add_element("comment", comment)
4333
4334
        if filter_id:
4335
            cmd.add_element("filter", attrs={"id": filter_id})
4336
4337
        if condition:
4338
            if not isinstance(condition, AlertCondition):
4339
                raise InvalidArgumentType(
4340
                    function=self.modify_alert.__name__,
4341
                    argument='condition',
4342
                    arg_type=AlertCondition.__name__,
4343
                )
4344
4345
            conditions = cmd.add_element("condition", condition.value)
4346
4347
            if condition_data is not None:
4348
                for key, value in condition_data.items():
4349
                    _data = conditions.add_element("data", value)
4350
                    _data.add_element("name", key)
4351
4352
        if method:
4353
            if not isinstance(method, AlertMethod):
4354
                raise InvalidArgumentType(
4355
                    function=self.modify_alert.__name__,
4356
                    argument='method',
4357
                    arg_type=AlertMethod.__name__,
4358
                )
4359
4360
            methods = cmd.add_element("method", method.value)
4361
4362
            if method_data is not None:
4363
                for key, value in method_data.items():
4364
                    _data = methods.add_element("data", value)
4365
                    _data.add_element("name", key)
4366
4367
        if event:
4368
            if not isinstance(event, AlertEvent):
4369
                raise InvalidArgumentType(
4370
                    function=self.modify_alert.__name__,
4371
                    argument='event',
4372
                    arg_type=AlertEvent.__name__,
4373
                )
4374
4375
            _check_event(event, condition, method)
4376
4377
            events = cmd.add_element("event", event.value)
4378
4379
            if event_data is not None:
4380
                for key, value in event_data.items():
4381
                    _data = events.add_element("data", value)
4382
                    _data.add_element("name", key)
4383
4384
        return self._send_xml_command(cmd)
4385
4386
    def modify_asset(self, asset_id: str, comment: Optional[str] = "") -> Any:
4387
        """Modifies an existing asset.
4388
4389
        Arguments:
4390
            asset_id: UUID of the asset to be modified.
4391
            comment: Comment for the asset.
4392
4393
        Returns:
4394
            The response. See :py:meth:`send_command` for details.
4395
        """
4396
        if not asset_id:
4397
            raise RequiredArgument(
4398
                function=self.modify_asset.__name__, argument='asset_id'
4399
            )
4400
4401
        cmd = XmlCommand("modify_asset")
4402
        cmd.set_attribute("asset_id", asset_id)
4403
        cmd.add_element("comment", comment)
4404
4405
        return self._send_xml_command(cmd)
4406
4407
    def modify_auth(self, group_name: str, auth_conf_settings: dict) -> Any:
4408
        """Modifies an existing auth.
4409
4410
        Arguments:
4411
            group_name: Name of the group to be modified.
4412
            auth_conf_settings: The new auth config.
4413
4414
        Returns:
4415
            The response. See :py:meth:`send_command` for details.
4416
        """
4417
        if not group_name:
4418
            raise RequiredArgument(
4419
                function=self.modify_auth.__name__, argument='group_name'
4420
            )
4421
        if not auth_conf_settings:
4422
            raise RequiredArgument(
4423
                function=self.modify_auth.__name__,
4424
                argument='auth_conf_settings',
4425
            )
4426
        cmd = XmlCommand("modify_auth")
4427
        _xmlgroup = cmd.add_element("group", attrs={"name": str(group_name)})
4428
4429
        for key, value in auth_conf_settings.items():
4430
            _xmlauthconf = _xmlgroup.add_element("auth_conf_setting")
4431
            _xmlauthconf.add_element("key", key)
4432
            _xmlauthconf.add_element("value", value)
4433
4434
        return self._send_xml_command(cmd)
4435
4436
    def modify_config_set_nvt_preference(
4437
        self,
4438
        config_id: str,
4439
        name: str,
4440
        nvt_oid: str,
4441
        *,
4442
        value: Optional[str] = None
4443
    ) -> Any:
4444
        """Modifies the nvt preferences of an existing scan config.
4445
4446
        Arguments:
4447
            config_id: UUID of scan config to modify.
4448
            name: Name for preference to change.
4449
            nvt_oid: OID of the NVT associated with preference to modify
4450
            value: New value for the preference. None to delete the preference
4451
                and to use the default instead.
4452
        """
4453
        if not config_id:
4454
            raise RequiredArgument(
4455
                function=self.modify_config_set_nvt_preference.__name__,
4456
                argument='config_id',
4457
            )
4458
4459
        if not nvt_oid:
4460
            raise RequiredArgument(
4461
                function=self.modify_config_set_nvt_preference.__name__,
4462
                argument='nvt_oid',
4463
            )
4464
4465
        if not name:
4466
            raise RequiredArgument(
4467
                function=self.modify_config_set_nvt_preference.__name__,
4468
                argument='name',
4469
            )
4470
4471
        cmd = XmlCommand("modify_config")
4472
        cmd.set_attribute("config_id", str(config_id))
4473
4474
        _xmlpref = cmd.add_element("preference")
4475
4476
        _xmlpref.add_element("nvt", attrs={"oid": nvt_oid})
4477
        _xmlpref.add_element("name", name)
4478
4479
        if value:
4480
            _xmlpref.add_element("value", _to_base64(value))
4481
4482
        return self._send_xml_command(cmd)
4483
4484
    def modify_config_set_comment(
4485
        self, config_id: str, comment: Optional[str] = ""
4486
    ) -> Any:
4487
        """Modifies the comment of an existing scan config
4488
4489
        Arguments:
4490
            config_id: UUID of scan config to modify.
4491
            comment: Comment to set on a config. Default: ''
4492
        """
4493
        if not config_id:
4494
            raise RequiredArgument(
4495
                function=self.modify_config_set_comment.__name__,
4496
                argument='config_id argument',
4497
            )
4498
4499
        cmd = XmlCommand("modify_config")
4500
        cmd.set_attribute("config_id", str(config_id))
4501
4502
        cmd.add_element("comment", comment)
4503
4504
        return self._send_xml_command(cmd)
4505
4506
    def modify_config_set_scanner_preference(
4507
        self, config_id: str, name: str, *, value: Optional[str] = None
4508
    ) -> Any:
4509
        """Modifies the scanner preferences of an existing scan config
4510
4511
        Arguments:
4512
            config_id: UUID of scan config to modify.
4513
            name: Name of the scanner preference to change
4514
            value: New value for the preference. None to delete the preference
4515
                and to use the default instead.
4516
4517
        """
4518
        if not config_id:
4519
            raise RequiredArgument(
4520
                function=self.modify_config_set_scanner_preference.__name__,
4521
                argument='config_id',
4522
            )
4523
4524
        if not name:
4525
            raise RequiredArgument(
4526
                function=self.modify_config_set_scanner_preference.__name__,
4527
                argument='name argument',
4528
            )
4529
4530
        cmd = XmlCommand("modify_config")
4531
        cmd.set_attribute("config_id", str(config_id))
4532
4533
        _xmlpref = cmd.add_element("preference")
4534
4535
        _xmlpref.add_element("name", name)
4536
4537
        if value:
4538
            _xmlpref.add_element("value", _to_base64(value))
4539
4540
        return self._send_xml_command(cmd)
4541
4542
    def modify_config_set_nvt_selection(
4543
        self, config_id: str, family: str, nvt_oids: List[str]
4544
    ) -> Any:
4545
        """Modifies the selected nvts of an existing scan config
4546
4547
        The manager updates the given family in the config to include only the
4548
        given NVTs.
4549
4550
        Arguments:
4551
            config_id: UUID of scan config to modify.
4552
            family: Name of the NVT family to include NVTs from
4553
            nvt_oids: List of NVTs to select for the family.
4554
        """
4555
        if not config_id:
4556
            raise RequiredArgument(
4557
                function=self.modify_config_set_nvt_selection.__name__,
4558
                argument='config_id',
4559
            )
4560
4561
        if not family:
4562
            raise RequiredArgument(
4563
                function=self.modify_config_set_nvt_selection.__name__,
4564
                argument='family argument',
4565
            )
4566
4567
        if not _is_list_like(nvt_oids):
4568
            raise InvalidArgumentType(
4569
                function=self.modify_config_set_nvt_selection.__name__,
4570
                argument='nvt_oids',
4571
                arg_type='list',
4572
            )
4573
4574
        cmd = XmlCommand("modify_config")
4575
        cmd.set_attribute("config_id", str(config_id))
4576
4577
        _xmlnvtsel = cmd.add_element("nvt_selection")
4578
        _xmlnvtsel.add_element("family", family)
4579
4580
        for nvt in nvt_oids:
4581
            _xmlnvtsel.add_element("nvt", attrs={"oid": nvt})
4582
4583
        return self._send_xml_command(cmd)
4584
4585
    def modify_config_set_family_selection(
4586
        self,
4587
        config_id: str,
4588
        families: List[str],
4589
        *,
4590
        auto_add_new_families: Optional[bool] = True,
4591
        auto_add_new_nvts: Optional[bool] = True
4592
    ) -> Any:
4593
        """
4594
        Selected the NVTs of a scan config at a family level.
4595
4596
        Arguments:
4597
            config_id: UUID of scan config to modify.
4598
            families: List of NVT family names to select.
4599
            auto_add_new_families: Whether new families should be added to the
4600
                scan config automatically. Default: True.
4601
            auto_add_new_nvts: Whether new NVTs in the selected families should
4602
                be added to the scan config automatically. Default: True.
4603
        """
4604
        if not config_id:
4605
            raise RequiredArgument(
4606
                function=self.modify_config_set_family_selection.__name__,
4607
                argument='config_id',
4608
            )
4609
4610
        if not _is_list_like(families):
4611
            raise InvalidArgumentType(
4612
                function=self.modify_config_set_family_selection.__name__,
4613
                argument='families',
4614
                arg_type='list',
4615
            )
4616
4617
        cmd = XmlCommand("modify_config")
4618
        cmd.set_attribute("config_id", str(config_id))
4619
4620
        _xmlfamsel = cmd.add_element("family_selection")
4621
        _xmlfamsel.add_element("growing", _to_bool(auto_add_new_families))
4622
4623
        for family in families:
4624
            _xmlfamily = _xmlfamsel.add_element("family")
4625
            _xmlfamily.add_element("name", family)
4626
            _xmlfamily.add_element("all", "1")
4627
            _xmlfamily.add_element("growing", _to_bool(auto_add_new_nvts))
4628
4629
        return self._send_xml_command(cmd)
4630
4631
    def modify_config(
4632
        self, config_id: str, selection: Optional[str] = None, **kwargs
4633
    ) -> Any:
4634
        """Modifies an existing scan config.
4635
4636
        DEPRECATED. Please use *modify_config_set_* methods instead.
4637
4638
        modify_config has four modes to operate depending on the selection.
4639
4640
        Arguments:
4641
            config_id: UUID of scan config to modify.
4642
            selection: one of 'scan_pref', 'nvt_pref', 'nvt_selection' or
4643
                'family_selection'
4644
            name: New name for preference.
4645
            value: New value for preference.
4646
            nvt_oids: List of NVTs associated with preference to modify.
4647
            family: Name of family to modify.
4648
4649
        Returns:
4650
            The response. See :py:meth:`send_command` for details.
4651
        """
4652
        if not config_id:
4653
            raise RequiredArgument(
4654
                function=self.modify_config.__name__,
4655
                argument='config_id argument',
4656
            )
4657
4658
        if selection is None:
4659
            deprecation(
4660
                "Using modify_config to update the comment of a scan config is"
4661
                "deprecated. Please use modify_config_set_comment instead."
4662
            )
4663
            return self.modify_config_set_comment(
4664
                config_id, kwargs.get("comment")
4665
            )
4666
4667
        if selection not in (
4668
            "nvt_pref",
4669
            "scan_pref",
4670
            "family_selection",
4671
            "nvt_selection",
4672
        ):
4673
            raise InvalidArgument(
4674
                "selection must be one of nvt_pref, "
4675
                "scan_pref, family_selection or "
4676
                "nvt_selection"
4677
            )
4678
4679
        if selection == "nvt_pref":
4680
            deprecation(
4681
                "Using modify_config to update a nvt preference of a scan "
4682
                "config is deprecated. Please use "
4683
                "modify_config_set_nvt_preference instead."
4684
            )
4685
            return self.modify_config_set_nvt_preference(config_id, **kwargs)
4686
4687
        if selection == "scan_pref":
4688
            deprecation(
4689
                "Using modify_config to update a scanner preference of a "
4690
                "scan config is deprecated. Please use "
4691
                "modify_config_set_scanner_preference instead."
4692
            )
4693
            return self.modify_config_set_scanner_preference(
4694
                config_id, **kwargs
4695
            )
4696
4697
        if selection == "nvt_selection":
4698
            deprecation(
4699
                "Using modify_config to update a nvt selection of a "
4700
                "scan config is deprecated. Please use "
4701
                "modify_config_set_nvt_selection instead."
4702
            )
4703
            return self.modify_config_set_nvt_selection(config_id, **kwargs)
4704
4705
        deprecation(
4706
            "Using modify_config to update a family selection of a "
4707
            "scan config is deprecated. Please use "
4708
            "modify_config_set_family_selection instead."
4709
        )
4710
        return self.modify_config_set_family_selection(config_id, **kwargs)
4711
4712
    def modify_credential(
4713
        self,
4714
        credential_id: str,
4715
        *,
4716
        name: Optional[str] = None,
4717
        comment: Optional[str] = None,
4718
        allow_insecure: Optional[bool] = None,
4719
        certificate: Optional[str] = None,
4720
        key_phrase: Optional[str] = None,
4721
        private_key: Optional[str] = None,
4722
        login: Optional[str] = None,
4723
        password: Optional[str] = None,
4724
        auth_algorithm: Optional[SnmpAuthAlgorithm] = None,
4725
        community: Optional[str] = None,
4726
        privacy_algorithm: Optional[SnmpPrivacyAlgorithm] = None,
4727
        privacy_password: Optional[str] = None
4728
    ) -> Any:
4729
        """Modifies an existing credential.
4730
4731
        Arguments:
4732
            credential_id: UUID of the credential
4733
            name: Name of the credential
4734
            comment: Comment for the credential
4735
            allow_insecure: Whether to allow insecure use of the credential
4736
            certificate: Certificate for the credential
4737
            key_phrase: Key passphrase for the private key
4738
            private_key: Private key to use for login
4739
            login: Username for the credential
4740
            password: Password for the credential
4741
            auth_algorithm: The SNMP auth algorithm.
4742
            community: The SNMP community
4743
            privacy_algorithm: The SNMP privacy algorithm.
4744
            privacy_password: The SNMP privacy password
4745
4746
        Returns:
4747
            The response. See :py:meth:`send_command` for details.
4748
        """
4749
        if not credential_id:
4750
            raise RequiredArgument(
4751
                function=self.modify_credential.__name__,
4752
                argument='credential_id attribute',
4753
            )
4754
4755
        cmd = XmlCommand("modify_credential")
4756
        cmd.set_attribute("credential_id", credential_id)
4757
4758
        if comment:
4759
            cmd.add_element("comment", comment)
4760
4761
        if name:
4762
            cmd.add_element("name", name)
4763
4764
        if allow_insecure is not None:
4765
            cmd.add_element("allow_insecure", _to_bool(allow_insecure))
4766
4767
        if certificate:
4768
            cmd.add_element("certificate", certificate)
4769
4770
        if key_phrase is not None and not private_key:
4771
            raise RequiredArgument(
4772
                function=self.modify_credential.__name__, argument='private_key'
4773
            )
4774
4775
        if private_key:
4776
            _xmlkey = cmd.add_element("key")
4777
            _xmlkey.add_element("private", private_key)
4778
4779
            if key_phrase is not None:
4780
                _xmlkey.add_element("phrase", key_phrase)
4781
4782
        if login:
4783
            cmd.add_element("login", login)
4784
4785
        if password:
4786
            cmd.add_element("password", password)
4787
4788
        if auth_algorithm is not None:
4789
            if not isinstance(auth_algorithm, SnmpAuthAlgorithm):
4790
                raise InvalidArgumentType(
4791
                    function=self.modify_credential.__name__,
4792
                    argument='auth_algorithm',
4793
                    arg_type=SnmpAuthAlgorithm.__name__,
4794
                )
4795
            cmd.add_element("auth_algorithm", auth_algorithm.value)
4796
4797
        if community:
4798
            cmd.add_element("community", community)
4799
4800
        if privacy_algorithm is not None:
4801
            if not isinstance(privacy_algorithm, SnmpPrivacyAlgorithm):
4802
                raise InvalidArgumentType(
4803
                    function=self.modify_credential.__name__,
4804
                    argument='privacy_algorithm',
4805
                    arg_type=SnmpPrivacyAlgorithm.__name__,
4806
                )
4807
4808
            _xmlprivacy = cmd.add_element("privacy")
4809
            _xmlprivacy.add_element("algorithm", privacy_algorithm.value)
4810
4811
            if privacy_password is not None:
4812
                _xmlprivacy.add_element("password", privacy_password)
4813
4814
        return self._send_xml_command(cmd)
4815
4816 View Code Duplication
    def modify_filter(
0 ignored issues
show
Duplication introduced by
This code seems to be duplicated in your project.
Loading history...
4817
        self,
4818
        filter_id: str,
4819
        *,
4820
        comment: Optional[str] = None,
4821
        name: Optional[str] = None,
4822
        term: Optional[str] = None,
4823
        filter_type: Optional[FilterType] = None
4824
    ) -> Any:
4825
        """Modifies an existing filter.
4826
4827
        Arguments:
4828
            filter_id: UUID of the filter to be modified
4829
            comment: Comment on filter.
4830
            name: Name of filter.
4831
            term: Filter term.
4832
            filter_type: Filter type the filter applies to.
4833
4834
        Returns:
4835
            The response. See :py:meth:`send_command` for details.
4836
        """
4837
        if not filter_id:
4838
            raise RequiredArgument(
4839
                function=self.modify_filter.__name__, argument='filter_id'
4840
            )
4841
4842
        cmd = XmlCommand("modify_filter")
4843
        cmd.set_attribute("filter_id", filter_id)
4844
4845
        if comment:
4846
            cmd.add_element("comment", comment)
4847
4848
        if name:
4849
            cmd.add_element("name", name)
4850
4851
        if term:
4852
            cmd.add_element("term", term)
4853
4854
        if filter_type:
4855
            if not isinstance(filter_type, self.types.FilterType):
4856
                raise InvalidArgumentType(
4857
                    function=self.modify_filter.__name__,
4858
                    argument='filter_type',
4859
                    arg_type=self.types.FilterType.__name__,
4860
                )
4861
            cmd.add_element("type", filter_type.value)
4862
4863
        return self._send_xml_command(cmd)
4864
4865 View Code Duplication
    def modify_group(
0 ignored issues
show
Duplication introduced by
This code seems to be duplicated in your project.
Loading history...
4866
        self,
4867
        group_id: str,
4868
        *,
4869
        comment: Optional[str] = None,
4870
        name: Optional[str] = None,
4871
        users: Optional[List[str]] = None
4872
    ) -> Any:
4873
        """Modifies an existing group.
4874
4875
        Arguments:
4876
            group_id: UUID of group to modify.
4877
            comment: Comment on group.
4878
            name: Name of group.
4879
            users: List of user names to be in the group
4880
4881
        Returns:
4882
            The response. See :py:meth:`send_command` for details.
4883
        """
4884
        if not group_id:
4885
            raise RequiredArgument(
4886
                function=self.modify_group.__name__, argument='group_id'
4887
            )
4888
4889
        cmd = XmlCommand("modify_group")
4890
        cmd.set_attribute("group_id", group_id)
4891
4892
        if comment:
4893
            cmd.add_element("comment", comment)
4894
4895
        if name:
4896
            cmd.add_element("name", name)
4897
4898
        if users:
4899
            cmd.add_element("users", _to_comma_list(users))
4900
4901
        return self._send_xml_command(cmd)
4902
4903 View Code Duplication
    def modify_note(
0 ignored issues
show
Duplication introduced by
This code seems to be duplicated in your project.
Loading history...
4904
        self,
4905
        note_id: str,
4906
        text: str,
4907
        *,
4908
        seconds_active: Optional[int] = None,
4909
        hosts: Optional[List[str]] = None,
4910
        port: Optional[int] = None,
4911
        result_id: Optional[str] = None,
4912
        severity: Optional[Severity] = None,
4913
        task_id: Optional[str] = None,
4914
        threat: Optional[SeverityLevel] = None
4915
    ) -> Any:
4916
        """Modifies an existing note.
4917
4918
        Arguments:
4919
            note_id: UUID of note to modify.
4920
            text: The text of the note.
4921
            seconds_active: Seconds note will be active. -1 on always, 0 off.
4922
            hosts: A list of hosts addresses
4923
            port: Port to which note applies.
4924
            result_id: Result to which note applies.
4925
            severity: Severity to which note applies.
4926
            task_id: Task to which note applies.
4927
            threat: Threat level to which note applies. Will be converted to
4928
                severity.
4929
4930
        Returns:
4931
            The response. See :py:meth:`send_command` for details.
4932
        """
4933
        if not note_id:
4934
            raise RequiredArgument(
4935
                function=self.modify_note.__name__, argument='note_id'
4936
            )
4937
4938
        if not text:
4939
            raise RequiredArgument(
4940
                function=self.modify_note.__name__, argument='text'
4941
            )
4942
4943
        cmd = XmlCommand("modify_note")
4944
        cmd.set_attribute("note_id", note_id)
4945
        cmd.add_element("text", text)
4946
4947
        if seconds_active is not None:
4948
            cmd.add_element("active", str(seconds_active))
4949
4950
        if hosts:
4951
            cmd.add_element("hosts", _to_comma_list(hosts))
4952
4953
        if port:
4954
            cmd.add_element("port", str(port))
4955
4956
        if result_id:
4957
            cmd.add_element("result", attrs={"id": result_id})
4958
4959
        if severity:
4960
            cmd.add_element("severity", str(severity))
4961
4962
        if task_id:
4963
            cmd.add_element("task", attrs={"id": task_id})
4964
4965
        if threat is not None:
4966
4967
            if not isinstance(threat, SeverityLevel):
4968
                raise InvalidArgumentType(
4969
                    function=self.modify_note.__name__,
4970
                    argument='threat',
4971
                    arg_type=SeverityLevel.__name__,
4972
                )
4973
4974
            cmd.add_element("threat", threat.value)
4975
4976
        return self._send_xml_command(cmd)
4977
4978 View Code Duplication
    def modify_override(
0 ignored issues
show
Duplication introduced by
This code seems to be duplicated in your project.
Loading history...
4979
        self,
4980
        override_id: str,
4981
        text: str,
4982
        *,
4983
        seconds_active: Optional[int] = None,
4984
        hosts: Optional[List[str]] = None,
4985
        port: Optional[int] = None,
4986
        result_id: Optional[str] = None,
4987
        severity: Optional[Severity] = None,
4988
        new_severity: Optional[Severity] = None,
4989
        task_id: Optional[str] = None,
4990
        threat: Optional[SeverityLevel] = None,
4991
        new_threat: Optional[SeverityLevel] = None
4992
    ) -> Any:
4993
        """Modifies an existing override.
4994
4995
        Arguments:
4996
            override_id: UUID of override to modify.
4997
            text: The text of the override.
4998
            seconds_active: Seconds override will be active. -1 on always,
4999
                0 off.
5000
            hosts: A list of host addresses
5001
            port: Port to which override applies.
5002
            result_id: Result to which override applies.
5003
            severity: Severity to which override applies.
5004
            new_severity: New severity score for result.
5005
            task_id: Task to which override applies.
5006
            threat: Threat level to which override applies.
5007
                Will be converted to severity.
5008
            new_threat: New threat level for results. Will be converted to
5009
                new_severity.
5010
5011
        Returns:
5012
            The response. See :py:meth:`send_command` for details.
5013
        """
5014
        if not override_id:
5015
            raise RequiredArgument(
5016
                function=self.modify_override.__name__, argument='override_id'
5017
            )
5018
        if not text:
5019
            raise RequiredArgument(
5020
                function=self.modify_override.__name__, argument='text'
5021
            )
5022
5023
        cmd = XmlCommand("modify_override")
5024
        cmd.set_attribute("override_id", override_id)
5025
        cmd.add_element("text", text)
5026
5027
        if seconds_active is not None:
5028
            cmd.add_element("active", str(seconds_active))
5029
5030
        if hosts:
5031
            cmd.add_element("hosts", _to_comma_list(hosts))
5032
5033
        if port:
5034
            cmd.add_element("port", str(port))
5035
5036
        if result_id:
5037
            cmd.add_element("result", attrs={"id": result_id})
5038
5039
        if severity:
5040
            cmd.add_element("severity", str(severity))
5041
5042
        if new_severity:
5043
            cmd.add_element("new_severity", str(new_severity))
5044
5045
        if task_id:
5046
            cmd.add_element("task", attrs={"id": task_id})
5047
5048
        if threat is not None:
5049
            if not isinstance(threat, SeverityLevel):
5050
                raise InvalidArgumentType(
5051
                    function=self.modify_override.__name__,
5052
                    argument='threat',
5053
                    arg_type=SeverityLevel.__name__,
5054
                )
5055
            cmd.add_element("threat", threat.value)
5056
5057
        if new_threat is not None:
5058
            if not isinstance(new_threat, SeverityLevel):
5059
                raise InvalidArgumentType(
5060
                    function=self.modify_override.__name__,
5061
                    argument='new_threat',
5062
                    arg_type=SeverityLevel.__name__,
5063
                )
5064
5065
            cmd.add_element("new_threat", new_threat.value)
5066
5067
        return self._send_xml_command(cmd)
5068
5069
    def modify_permission(
5070
        self,
5071
        permission_id: str,
5072
        *,
5073
        comment: Optional[str] = None,
5074
        name: Optional[str] = None,
5075
        resource_id: Optional[str] = None,
5076
        resource_type: Optional[EntityType] = None,
5077
        subject_id: Optional[str] = None,
5078
        subject_type: Optional[PermissionSubjectType] = None
5079
    ) -> Any:
5080
        """Modifies an existing permission.
5081
5082
        Arguments:
5083
            permission_id: UUID of permission to be modified.
5084
            comment: The comment on the permission.
5085
            name: Permission name, currently the name of a command.
5086
            subject_id: UUID of subject to whom the permission is granted
5087
            subject_type: Type of the subject user, group or role
5088
            resource_id: UUID of entity to which the permission applies
5089
            resource_type: Type of the resource. For Super permissions user,
5090
                group or role
5091
5092
        Returns:
5093
            The response. See :py:meth:`send_command` for details.
5094
        """
5095
        if not permission_id:
5096
            raise RequiredArgument(
5097
                function=self.modify_permission.__name__,
5098
                argument='permission_id',
5099
            )
5100
5101
        cmd = XmlCommand("modify_permission")
5102
        cmd.set_attribute("permission_id", permission_id)
5103
5104
        if comment:
5105
            cmd.add_element("comment", comment)
5106
5107
        if name:
5108
            cmd.add_element("name", name)
5109
5110 View Code Duplication
        if resource_id or resource_type:
0 ignored issues
show
Duplication introduced by
This code seems to be duplicated in your project.
Loading history...
5111
            if not resource_id:
5112
                raise RequiredArgument(
5113
                    function=self.modify_permission.__name__,
5114
                    argument='resource_id',
5115
                )
5116
5117
            if not resource_type:
5118
                raise RequiredArgument(
5119
                    function=self.modify_permission.__name__,
5120
                    argument='resource_type',
5121
                )
5122
5123
            if not isinstance(resource_type, self.types.EntityType):
5124
                raise InvalidArgumentType(
5125
                    function=self.modify_permission.__name__,
5126
                    argument='resource_type',
5127
                    arg_type=self.types.EntityType.__name__,
5128
                )
5129
5130
            _xmlresource = cmd.add_element(
5131
                "resource", attrs={"id": resource_id}
5132
            )
5133
            _xmlresource.add_element("type", resource_type.value)
5134
5135
        if subject_id or subject_type:
5136
            if not subject_id:
5137
                raise RequiredArgument(
5138
                    function=self.modify_permission.__name__,
5139
                    argument='subject_id',
5140
                )
5141
5142
            if not isinstance(subject_type, PermissionSubjectType):
5143
                raise InvalidArgumentType(
5144
                    function=self.modify_permission.__name__,
5145
                    argument='subject_type',
5146
                    arg_type=PermissionSubjectType.__name__,
5147
                )
5148
5149
            _xmlsubject = cmd.add_element("subject", attrs={"id": subject_id})
5150
            _xmlsubject.add_element("type", subject_type.value)
5151
5152
        return self._send_xml_command(cmd)
5153
5154
    def modify_port_list(
5155
        self,
5156
        port_list_id: str,
5157
        *,
5158
        comment: Optional[str] = None,
5159
        name: Optional[str] = None
5160
    ) -> Any:
5161
        """Modifies an existing port list.
5162
5163
        Arguments:
5164
            port_list_id: UUID of port list to modify.
5165
            name: Name of port list.
5166
            comment: Comment on port list.
5167
5168
        Returns:
5169
            The response. See :py:meth:`send_command` for details.
5170
        """
5171
        if not port_list_id:
5172
            raise RequiredArgument(
5173
                function=self.modify_port_list.__name__, argument='port_list_id'
5174
            )
5175
        cmd = XmlCommand("modify_port_list")
5176
        cmd.set_attribute("port_list_id", port_list_id)
5177
5178
        if comment:
5179
            cmd.add_element("comment", comment)
5180
5181
        if name:
5182
            cmd.add_element("name", name)
5183
5184
        return self._send_xml_command(cmd)
5185
5186
    def modify_report_format(
5187
        self,
5188
        report_format_id: str,
5189
        *,
5190
        active: Optional[bool] = None,
5191
        name: Optional[str] = None,
5192
        summary: Optional[str] = None,
5193
        param_name: Optional[str] = None,
5194
        param_value: Optional[str] = None
5195
    ) -> Any:
5196
        """Modifies an existing report format.
5197
5198
        Arguments:
5199
            report_format_id: UUID of report format to modify.
5200
            active: Whether the report format is active.
5201
            name: The name of the report format.
5202
            summary: A summary of the report format.
5203
            param_name: The name of the param.
5204
            param_value: The value of the param.
5205
5206
        Returns:
5207
            The response. See :py:meth:`send_command` for details.
5208
        """
5209
        if not report_format_id:
5210
            raise RequiredArgument(
5211
                function=self.modify_report_format.__name__,
5212
                argument='report_format_id',
5213
            )
5214
5215
        cmd = XmlCommand("modify_report_format")
5216
        cmd.set_attribute("report_format_id", report_format_id)
5217
5218
        if active is not None:
5219
            cmd.add_element("active", _to_bool(active))
5220
5221
        if name:
5222
            cmd.add_element("name", name)
5223
5224
        if summary:
5225
            cmd.add_element("summary", summary)
5226
5227
        if param_name:
5228
            _xmlparam = cmd.add_element("param")
5229
            _xmlparam.add_element("name", param_name)
5230
5231
            if param_value is not None:
5232
                _xmlparam.add_element("value", param_value)
5233
5234
        return self._send_xml_command(cmd)
5235
5236 View Code Duplication
    def modify_role(
0 ignored issues
show
Duplication introduced by
This code seems to be duplicated in your project.
Loading history...
5237
        self,
5238
        role_id: str,
5239
        *,
5240
        comment: Optional[str] = None,
5241
        name: Optional[str] = None,
5242
        users: Optional[List[str]] = None
5243
    ) -> Any:
5244
        """Modifies an existing role.
5245
5246
        Arguments:
5247
            role_id: UUID of role to modify.
5248
            comment: Name of role.
5249
            name: Comment on role.
5250
            users: List of user names.
5251
5252
        Returns:
5253
            The response. See :py:meth:`send_command` for details.
5254
        """
5255
        if not role_id:
5256
            raise RequiredArgument(
5257
                function=self.modify_role.__name__, argument='role_id argument'
5258
            )
5259
5260
        cmd = XmlCommand("modify_role")
5261
        cmd.set_attribute("role_id", role_id)
5262
5263
        if comment:
5264
            cmd.add_element("comment", comment)
5265
5266
        if name:
5267
            cmd.add_element("name", name)
5268
5269
        if users:
5270
            cmd.add_element("users", _to_comma_list(users))
5271
5272
        return self._send_xml_command(cmd)
5273
5274
    def modify_scanner(
5275
        self,
5276
        scanner_id: str,
5277
        *,
5278
        scanner_type: Optional[ScannerType] = None,
5279
        host: Optional[str] = None,
5280
        port: Optional[int] = None,
5281
        comment: Optional[str] = None,
5282
        name: Optional[str] = None,
5283
        ca_pub: Optional[str] = None,
5284
        credential_id: Optional[str] = None
5285
    ) -> Any:
5286
        """Modifies an existing scanner.
5287
5288
        Arguments:
5289
            scanner_id: UUID of scanner to modify.
5290
            scanner_type: New type of the Scanner.
5291
            host: Host of the scanner.
5292
            port: Port of the scanner.
5293
            comment: Comment on scanner.
5294
            name: Name of scanner.
5295
            ca_pub: Certificate of CA to verify scanner's certificate.
5296
            credential_id: UUID of the client certificate credential for the
5297
                Scanner.
5298
5299
        Returns:
5300
            The response. See :py:meth:`send_command` for details.
5301
        """
5302
        if not scanner_id:
5303
            raise RequiredArgument(
5304
                function=self.modify_scanner.__name__,
5305
                argument='scanner_id argument',
5306
            )
5307
5308
        cmd = XmlCommand("modify_scanner")
5309
        cmd.set_attribute("scanner_id", scanner_id)
5310
5311
        if scanner_type is not None:
5312
            if not isinstance(scanner_type, ScannerType):
5313
                raise InvalidArgumentType(
5314
                    function=self.modify_scanner.__name__,
5315
                    argument='scanner_type',
5316
                    arg_type=ScannerType.__name__,
5317
                )
5318
5319
            cmd.add_element("type", scanner_type.value)
5320
5321
        if host:
5322
            cmd.add_element("host", host)
5323
5324
        if port:
5325
            cmd.add_element("port", str(port))
5326
5327
        if comment:
5328
            cmd.add_element("comment", comment)
5329
5330
        if name:
5331
            cmd.add_element("name", name)
5332
5333
        if ca_pub:
5334
            cmd.add_element("ca_pub", ca_pub)
5335
5336
        if credential_id:
5337
            cmd.add_element("credential", attrs={"id": str(credential_id)})
5338
5339
        return self._send_xml_command(cmd)
5340
5341 View Code Duplication
    def modify_schedule(
0 ignored issues
show
Duplication introduced by
This code seems to be duplicated in your project.
Loading history...
5342
        self,
5343
        schedule_id: str,
5344
        *,
5345
        comment: Optional[str] = None,
5346
        name: Optional[str] = None,
5347
        first_time_minute: Optional[int] = None,
5348
        first_time_hour: Optional[int] = None,
5349
        first_time_day_of_month: Optional[int] = None,
5350
        first_time_month: Optional[int] = None,
5351
        first_time_year: Optional[int] = None,
5352
        duration: Optional[int] = None,
5353
        duration_unit: Optional[TimeUnit] = None,
5354
        period: Optional[int] = None,
5355
        period_unit: Optional[TimeUnit] = None,
5356
        timezone: Optional[str] = None
5357
    ) -> Any:
5358
        """Modifies an existing schedule.
5359
5360
        Arguments:
5361
            schedule_id: UUID of schedule to modify.
5362
            name: Name of the schedule
5363
            comment: Comment for the schedule
5364
            first_time_minute: First time minute the schedule will run. Must be
5365
                an integer >= 0.
5366
            first_time_hour: First time hour the schedule will run. Must be an
5367
                integer >= 0.
5368
            first_time_day_of_month: First time day of month the schedule will
5369
                run. Must be an integer > 0 <= 31.
5370
            first_time_month: First time month the schedule will run. Must be an
5371
                integer >= 1 <= 12.
5372
            first_time_year: First time year the schedule will run
5373
            duration: How long the Manager will run the scheduled task for until
5374
                it gets paused if not finished yet.
5375
            duration_unit: Unit of the duration. One of second, minute, hour,
5376
                day, week, month, year, decade. Required if duration is set.
5377
            period: How often the Manager will repeat the scheduled task. Must
5378
                be an integer > 0.
5379
            period_unit: Unit of the period. One of second, minute, hour, day,
5380
                week, month, year, decade. Required if period is set.
5381
            timezone: The timezone the schedule will follow
5382
5383
        Returns:
5384
            The response. See :py:meth:`send_command` for details.
5385
        """
5386
        if not schedule_id:
5387
            raise RequiredArgument(
5388
                function=self.modify_schedule.__name__, argument='schedule_id'
5389
            )
5390
5391
        cmd = XmlCommand("modify_schedule")
5392
        cmd.set_attribute("schedule_id", schedule_id)
5393
5394
        if comment:
5395
            cmd.add_element("comment", comment)
5396
5397
        if name:
5398
            cmd.add_element("name", name)
5399
5400
        if (
5401
            first_time_minute is not None
5402
            or first_time_hour is not None
5403
            or first_time_day_of_month is not None
5404
            or first_time_month is not None
5405
            or first_time_year is not None
5406
        ):
5407
5408
            if first_time_minute is None:
5409
                raise RequiredArgument(
5410
                    function=self.modify_schedule.__name__,
5411
                    argument='first_time_minute',
5412
                )
5413
            elif (
5414
                not isinstance(first_time_minute, numbers.Integral)
5415
                or first_time_minute < 0
5416
            ):
5417
                raise InvalidArgument(
5418
                    "first_time_minute argument of modify_schedule needs to be "
5419
                    "an integer greater or equal 0"
5420
                )
5421
5422
            if first_time_hour is None:
5423
                raise RequiredArgument(
5424
                    function=self.modify_schedule.__name__,
5425
                    argument='first_time_hour',
5426
                )
5427
            elif (
5428
                not isinstance(first_time_hour, numbers.Integral)
5429
                or first_time_hour < 0
5430
            ):
5431
                raise InvalidArgument(
5432
                    "first_time_hour argument of modify_schedule needs to be "
5433
                    "an integer greater or equal 0"
5434
                )
5435
5436
            if first_time_day_of_month is None:
5437
                raise RequiredArgument(
5438
                    function=self.modify_schedule.__name__,
5439
                    argument='first_time_day_of_month',
5440
                )
5441
            elif (
5442
                not isinstance(first_time_day_of_month, numbers.Integral)
5443
                or first_time_day_of_month < 1
5444
                or first_time_day_of_month > 31
5445
            ):
5446
                raise InvalidArgument(
5447
                    "first_time_day_of_month argument of modify_schedule needs "
5448
                    "to be an integer between 1 and 31"
5449
                )
5450
5451
            if first_time_month is None:
5452
                raise RequiredArgument(
5453
                    function=self.modify_schedule.__name__,
5454
                    argument='first_time_month',
5455
                )
5456
            elif (
5457
                not isinstance(first_time_month, numbers.Integral)
5458
                or first_time_month < 1
5459
                or first_time_month > 12
5460
            ):
5461
                raise InvalidArgument(
5462
                    "first_time_month argument of modify_schedule needs "
5463
                    "to be an integer between 1 and 12"
5464
                )
5465
5466
            if first_time_year is None:
5467
                raise RequiredArgument(
5468
                    function=self.modify_schedule.__name__,
5469
                    argument='first_time_year',
5470
                )
5471
            elif (
5472
                not isinstance(first_time_year, numbers.Integral)
5473
                or first_time_year < 1970
5474
            ):
5475
                raise InvalidArgument(
5476
                    "first_time_year argument of create_schedule needs "
5477
                    "to be an integer greater or equal 1970"
5478
                )
5479
5480
            _xmlftime = cmd.add_element("first_time")
5481
            _xmlftime.add_element("minute", str(first_time_minute))
5482
            _xmlftime.add_element("hour", str(first_time_hour))
5483
            _xmlftime.add_element("day_of_month", str(first_time_day_of_month))
5484
            _xmlftime.add_element("month", str(first_time_month))
5485
            _xmlftime.add_element("year", str(first_time_year))
5486
5487
        if duration is not None:
5488
            if not duration_unit:
5489
                raise RequiredArgument(
5490
                    function=self.modify_schedule.__name__,
5491
                    argument='duration_unit',
5492
                )
5493
5494
            if not isinstance(duration_unit, TimeUnit):
5495
                raise InvalidArgumentType(
5496
                    function=self.modify_schedule.__name__,
5497
                    argument='duration_unit',
5498
                    arg_type=TimeUnit.__name__,
5499
                )
5500
5501
            if not isinstance(duration, numbers.Integral) or duration < 1:
5502
                raise InvalidArgument(
5503
                    "duration argument must be an integer greater than 0"
5504
                )
5505
5506
            _xmlduration = cmd.add_element("duration", str(duration))
5507
            _xmlduration.add_element("unit", duration_unit.value)
5508
5509
        if period is not None:
5510
            if not period_unit:
5511
                raise RequiredArgument(
5512
                    function=self.modify_schedule.__name__,
5513
                    argument='period_unit',
5514
                )
5515
5516
            if not isinstance(period_unit, TimeUnit):
5517
                raise InvalidArgumentType(
5518
                    function=self.modify_schedule.__name__,
5519
                    argument='period_unit',
5520
                    arg_type=TimeUnit.__name__,
5521
                )
5522
5523
            if not isinstance(period, numbers.Integral) or period < 1:
5524
                raise InvalidArgument(
5525
                    "period argument must be an integer greater than 0"
5526
                )
5527
5528
            _xmlperiod = cmd.add_element("period", str(period))
5529
            _xmlperiod.add_element("unit", period_unit.value)
5530
5531
        if timezone:
5532
            cmd.add_element("timezone", timezone)
5533
5534
        return self._send_xml_command(cmd)
5535
5536
    def modify_setting(
5537
        self,
5538
        setting_id: Optional[str] = None,
5539
        name: Optional[str] = None,
5540
        value: Optional[str] = None,
5541
    ) -> Any:
5542
        """Modifies an existing setting.
5543
5544
        Arguments:
5545
            setting_id: UUID of the setting to be changed.
5546
            name: The name of the setting. Either setting_id or name must be
5547
                passed.
5548
            value: The value of the setting.
5549
5550
        Returns:
5551
            The response. See :py:meth:`send_command` for details.
5552
        """
5553
        if not setting_id and not name:
5554
            raise RequiredArgument(
5555
                function=self.modify_setting.__name__,
5556
                argument='setting_id or name argument',
5557
            )
5558
5559
        if value is None:
5560
            raise RequiredArgument(
5561
                function=self.modify_setting.__name__, argument='value argument'
5562
            )
5563
5564
        cmd = XmlCommand("modify_setting")
5565
5566
        if setting_id:
5567
            cmd.set_attribute("setting_id", setting_id)
5568
        else:
5569
            cmd.add_element("name", name)
5570
5571
        cmd.add_element("value", _to_base64(value))
5572
5573
        return self._send_xml_command(cmd)
5574
5575
    def modify_tag(
5576
        self,
5577
        tag_id: str,
5578
        *,
5579
        comment: Optional[str] = None,
5580
        name: Optional[str] = None,
5581
        value: Optional[str] = None,
5582
        active: Optional[bool] = None,
5583
        resource_id: Optional[str] = None,
5584
        resource_type: Optional[EntityType] = None
5585
    ) -> Any:
5586
        """Modifies an existing tag.
5587
5588
        Arguments:
5589
            tag_id: UUID of the tag.
5590
            comment: Comment to add to the tag.
5591
            name: Name of the tag.
5592
            value: Value of the tag.
5593
            active: Whether the tag is active.
5594
            resource_id: ID of the resource to which to attach the tag.
5595
                Required if resource_type is set.
5596
            resource_type: Type of the resource to which to attach the tag.
5597
                Required if resource_id is set.
5598
5599
        Returns:
5600
            The response. See :py:meth:`send_command` for details.
5601
        """
5602
        if not tag_id:
5603
            raise RequiredArgument(
5604
                function=self.modify_tag.__name__, argument='tag_id'
5605
            )
5606
5607
        cmd = XmlCommand("modify_tag")
5608
        cmd.set_attribute("tag_id", str(tag_id))
5609
5610
        if comment:
5611
            cmd.add_element("comment", comment)
5612
5613
        if name:
5614
            cmd.add_element("name", name)
5615
5616
        if value:
5617
            cmd.add_element("value", value)
5618
5619
        if active is not None:
5620
            cmd.add_element("active", _to_bool(active))
5621
5622 View Code Duplication
        if resource_id or resource_type:
0 ignored issues
show
Duplication introduced by
This code seems to be duplicated in your project.
Loading history...
5623
            if not resource_id:
5624
                raise RequiredArgument(
5625
                    function=self.modify_tag.__name__, argument='resource_id'
5626
                )
5627
5628
            if not resource_type:
5629
                raise RequiredArgument(
5630
                    function=self.modify_tag.__name__, argument='resource_type'
5631
                )
5632
5633
            if not isinstance(resource_type, self.types.EntityType):
5634
                raise InvalidArgumentType(
5635
                    function=self.modify_tag.__name__,
5636
                    argument='resource_type',
5637
                    arg_type=self.types.EntityType.__name__,
5638
                )
5639
5640
            _xmlresource = cmd.add_element(
5641
                "resource", attrs={"id": resource_id}
5642
            )
5643
            _xmlresource.add_element("type", resource_type.value)
5644
5645
        return self._send_xml_command(cmd)
5646
5647
    def modify_target(
5648
        self,
5649
        target_id: str,
5650
        *,
5651
        name: Optional[str] = None,
5652
        comment: Optional[str] = None,
5653
        hosts: Optional[List[str]] = None,
5654
        exclude_hosts: Optional[List[str]] = None,
5655
        ssh_credential_id: Optional[str] = None,
5656
        ssh_credential_port: Optional[bool] = None,
5657
        smb_credential_id: Optional[str] = None,
5658
        esxi_credential_id: Optional[str] = None,
5659
        snmp_credential_id: Optional[str] = None,
5660
        alive_test: Optional[AliveTest] = None,
5661
        reverse_lookup_only: Optional[bool] = None,
5662
        reverse_lookup_unify: Optional[bool] = None,
5663
        port_list_id: Optional[str] = None
5664
    ) -> Any:
5665
        """Modifies an existing target.
5666
5667
        Arguments:
5668
            target_id: ID of target to modify.
5669
            comment: Comment on target.
5670
            name: Name of target.
5671
            hosts: List of target hosts.
5672
            exclude_hosts: A list of hosts to exclude.
5673
            ssh_credential_id: UUID of SSH credential to use on target.
5674
            ssh_credential_port: The port to use for ssh credential
5675
            smb_credential_id: UUID of SMB credential to use on target.
5676
            esxi_credential_id: UUID of ESXi credential to use on target.
5677
            snmp_credential_id: UUID of SNMP credential to use on target.
5678
            port_list_id: UUID of port list describing ports to scan.
5679
            alive_test: Which alive tests to use.
5680
            reverse_lookup_only: Whether to scan only hosts that have names.
5681
            reverse_lookup_unify: Whether to scan only one IP when multiple IPs
5682
                have the same name.
5683
5684
        Returns:
5685
            The response. See :py:meth:`send_command` for details.
5686
        """
5687
        if not target_id:
5688
            raise RequiredArgument(
5689
                function=self.modify_target.__name__, argument='target_id'
5690
            )
5691
5692
        cmd = XmlCommand("modify_target")
5693
        cmd.set_attribute("target_id", target_id)
5694
5695
        if comment:
5696
            cmd.add_element("comment", comment)
5697
5698
        if name:
5699
            cmd.add_element("name", name)
5700
5701
        if hosts:
5702
            cmd.add_element("hosts", _to_comma_list(hosts))
5703
            if exclude_hosts is None:
5704
                exclude_hosts = ['']
5705
5706
        if exclude_hosts:
5707
            cmd.add_element("exclude_hosts", _to_comma_list(exclude_hosts))
5708
5709
        if alive_test:
5710
            if not isinstance(alive_test, AliveTest):
5711
                raise InvalidArgumentType(
5712
                    function=self.modify_target.__name__,
5713
                    argument='alive_test',
5714
                    arg_type=AliveTest.__name__,
5715
                )
5716
            cmd.add_element("alive_tests", alive_test.value)
5717
5718
        if ssh_credential_id:
5719
            _xmlssh = cmd.add_element(
5720
                "ssh_credential", attrs={"id": ssh_credential_id}
5721
            )
5722
5723
            if ssh_credential_port:
5724
                _xmlssh.add_element("port", str(ssh_credential_port))
5725
5726
        if smb_credential_id:
5727
            cmd.add_element("smb_credential", attrs={"id": smb_credential_id})
5728
5729
        if esxi_credential_id:
5730
            cmd.add_element("esxi_credential", attrs={"id": esxi_credential_id})
5731
5732
        if snmp_credential_id:
5733
            cmd.add_element("snmp_credential", attrs={"id": snmp_credential_id})
5734
5735
        if reverse_lookup_only is not None:
5736
            cmd.add_element(
5737
                "reverse_lookup_only", _to_bool(reverse_lookup_only)
5738
            )
5739
5740
        if reverse_lookup_unify is not None:
5741
            cmd.add_element(
5742
                "reverse_lookup_unify", _to_bool(reverse_lookup_unify)
5743
            )
5744
5745
        if port_list_id:
5746
            cmd.add_element("port_list", attrs={"id": port_list_id})
5747
5748
        return self._send_xml_command(cmd)
5749
5750
    def modify_task(
5751
        self,
5752
        task_id: str,
5753
        *,
5754
        name: Optional[str] = None,
5755
        config_id: Optional[str] = None,
5756
        target_id: Optional[str] = None,
5757
        scanner_id: Optional[str] = None,
5758
        alterable: Optional[bool] = None,
5759
        hosts_ordering: Optional[HostsOrdering] = None,
5760
        schedule_id: Optional[str] = None,
5761
        schedule_periods: Optional[int] = None,
5762
        comment: Optional[str] = None,
5763
        alert_ids: Optional[List[str]] = None,
5764
        observers: Optional[List[str]] = None,
5765
        preferences: Optional[dict] = None
5766
    ) -> Any:
5767
        """Modifies an existing task.
5768
5769
        Arguments:
5770
            task_id: UUID of task to modify.
5771
            name: The name of the task.
5772
            config_id: UUID of scan config to use by the task
5773
            target_id: UUID of target to be scanned
5774
            scanner_id: UUID of scanner to use for scanning the target
5775
            comment: The comment on the task.
5776
            alert_ids: List of UUIDs for alerts to be applied to the task
5777
            hosts_ordering: The order hosts are scanned in
5778
            schedule_id: UUID of a schedule when the task should be run.
5779
            schedule_periods: A limit to the number of times the task will be
5780
                scheduled, or 0 for no limit.
5781
            observers: List of names or ids of users which should be allowed to
5782
                observe this task
5783
            preferences: Name/Value pairs of scanner preferences.
5784
5785
        Returns:
5786
            The response. See :py:meth:`send_command` for details.
5787
        """
5788
        if not task_id:
5789
            raise RequiredArgument(
5790
                function=self.modify_task.__name__, argument='task_id argument'
5791
            )
5792
5793
        cmd = XmlCommand("modify_task")
5794
        cmd.set_attribute("task_id", task_id)
5795
5796
        if name:
5797
            cmd.add_element("name", name)
5798
5799
        if comment:
5800
            cmd.add_element("comment", comment)
5801
5802
        if config_id:
5803
            cmd.add_element("config", attrs={"id": config_id})
5804
5805
        if target_id:
5806
            cmd.add_element("target", attrs={"id": target_id})
5807
5808
        if alterable is not None:
5809
            cmd.add_element("alterable", _to_bool(alterable))
5810
5811
        if hosts_ordering:
5812
            if not isinstance(hosts_ordering, HostsOrdering):
5813
                raise InvalidArgumentType(
5814
                    function=self.modify_task.__name__,
5815
                    argument='hosts_ordering',
5816
                    arg_type=HostsOrdering.__name__,
5817
                )
5818
            cmd.add_element("hosts_ordering", hosts_ordering.value)
5819
5820
        if scanner_id:
5821
            cmd.add_element("scanner", attrs={"id": scanner_id})
5822
5823
        if schedule_id:
5824
            cmd.add_element("schedule", attrs={"id": schedule_id})
5825
5826
        if schedule_periods is not None:
5827
            if (
5828
                not isinstance(schedule_periods, numbers.Integral)
5829
                or schedule_periods < 0
5830
            ):
5831
                raise InvalidArgument(
5832
                    "schedule_periods must be an integer greater or equal "
5833
                    "than 0"
5834
                )
5835
            cmd.add_element("schedule_periods", str(schedule_periods))
5836
5837
        if alert_ids is not None:
5838
            if not _is_list_like(alert_ids):
5839
                raise InvalidArgumentType(
5840
                    function=self.modify_task.__name__,
5841
                    argument='alert_ids',
5842
                    arg_type='list',
5843
                )
5844
5845
            for alert in alert_ids:
5846
                cmd.add_element("alert", attrs={"id": str(alert)})
5847
5848
        if observers is not None:
5849
            if not _is_list_like(observers):
5850
                raise InvalidArgumentType(
5851
                    function=self.modify_task.__name__,
5852
                    argument='observers',
5853
                    arg_type='list',
5854
                )
5855
5856
            cmd.add_element("observers", _to_comma_list(observers))
5857
5858
        if preferences is not None:
5859
            if not isinstance(preferences, collections.abc.Mapping):
5860
                raise InvalidArgumentType(
5861
                    function=self.modify_task.__name__,
5862
                    argument='preferences',
5863
                    arg_type=collections.abc.Mapping.__name__,
5864
                )
5865
5866
            _xmlprefs = cmd.add_element("preferences")
5867
            for pref_name, pref_value in preferences.items():
5868
                _xmlpref = _xmlprefs.add_element("preference")
5869
                _xmlpref.add_element("scanner_name", pref_name)
5870
                _xmlpref.add_element("value", str(pref_value))
5871
5872
        return self._send_xml_command(cmd)
5873
5874
    def modify_user(
5875
        self,
5876
        user_id: str = None,
5877
        name: str = None,
5878
        *,
5879
        new_name: Optional[str] = None,
5880
        password: Optional[str] = None,
5881
        role_ids: Optional[List[str]] = None,
5882
        hosts: Optional[List[str]] = None,
5883
        hosts_allow: Optional[bool] = False,
5884
        ifaces: Optional[List[str]] = None,
5885
        ifaces_allow: Optional[bool] = False
5886
    ) -> Any:
5887
        """Modifies an existing user.
5888
5889
        Arguments:
5890
            user_id: UUID of the user to be modified. Overrides name element
5891
                argument.
5892
            name: The name of the user to be modified. Either user_id or name
5893
                must be passed.
5894
            new_name: The new name for the user.
5895
            password: The password for the user.
5896
            roles_id: List of roles UUIDs for the user.
5897
            hosts: User access rules: List of hosts.
5898
            hosts_allow: If True, allow only listed, otherwise forbid listed.
5899
            ifaces: User access rules: List of ifaces.
5900
            ifaces_allow: If True, allow only listed, otherwise forbid listed.
5901
5902
        Returns:
5903
            The response. See :py:meth:`send_command` for details.
5904
        """
5905
        if not user_id and not name:
5906
            raise RequiredArgument(
5907
                function=self.modify_user.__name__, argument='user_id or name'
5908
            )
5909
5910
        cmd = XmlCommand("modify_user")
5911
5912
        if user_id:
5913
            cmd.set_attribute("user_id", user_id)
5914
        else:
5915
            cmd.add_element("name", name)
5916
5917
        if new_name:
5918
            cmd.add_element("new_name", new_name)
5919
5920
        if password:
5921
            cmd.add_element("password", password)
5922
5923
        if role_ids:
5924
            for role in role_ids:
5925
                cmd.add_element("role", attrs={"id": role})
5926
5927
        if hosts:
5928
            cmd.add_element(
5929
                "hosts",
5930
                _to_comma_list(hosts),
5931
                attrs={"allow": _to_bool(hosts_allow)},
5932
            )
5933
5934
        if ifaces:
5935
            cmd.add_element(
5936
                "ifaces",
5937
                _to_comma_list(ifaces),
5938
                attrs={"allow": _to_bool(ifaces_allow)},
5939
            )
5940
5941
        return self._send_xml_command(cmd)
5942
5943
    def move_task(self, task_id: str, *, slave_id: Optional[str] = None) -> Any:
5944
        """Move an existing task to another GMP slave scanner or the master
5945
5946
        Arguments:
5947
            task_id: UUID of the task to be moved
5948
            slave_id: UUID of slave to reassign the task to, empty for master.
5949
5950
        Returns:
5951
            The response. See :py:meth:`send_command` for details.
5952
        """
5953
        if not task_id:
5954
            raise RequiredArgument(
5955
                function=self.move_task.__name__, argument='task_id'
5956
            )
5957
5958
        cmd = XmlCommand("move_task")
5959
        cmd.set_attribute("task_id", task_id)
5960
5961
        if slave_id is not None:
5962
            cmd.set_attribute("slave_id", slave_id)
5963
5964
        return self._send_xml_command(cmd)
5965
5966
    def restore(self, entity_id: str) -> Any:
5967
        """Restore an entity from the trashcan
5968
5969
        Arguments:
5970
            entity_id: ID of the entity to be restored from the trashcan
5971
5972
        Returns:
5973
            The response. See :py:meth:`send_command` for details.
5974
        """
5975
        if not entity_id:
5976
            raise RequiredArgument(
5977
                function=self.restore.__name__, argument='entity_id'
5978
            )
5979
5980
        cmd = XmlCommand("restore")
5981
        cmd.set_attribute("id", entity_id)
5982
5983
        return self._send_xml_command(cmd)
5984
5985
    def resume_task(self, task_id: str) -> Any:
5986
        """Resume an existing stopped task
5987
5988
        Arguments:
5989
            task_id: UUID of the task to be resumed
5990
5991
        Returns:
5992
            The response. See :py:meth:`send_command` for details.
5993
        """
5994
        if not task_id:
5995
            raise RequiredArgument(
5996
                function=self.resume_task.__name__, argument='task_id'
5997
            )
5998
5999
        cmd = XmlCommand("resume_task")
6000
        cmd.set_attribute("task_id", task_id)
6001
6002
        return self._send_xml_command(cmd)
6003
6004
    def start_task(self, task_id: str) -> Any:
6005
        """Start an existing task
6006
6007
        Arguments:
6008
            task_id: UUID of the task to be started
6009
6010
        Returns:
6011
            The response. See :py:meth:`send_command` for details.
6012
        """
6013
        if not task_id:
6014
            raise RequiredArgument(
6015
                function=self.start_task.__name__, argument='task_id'
6016
            )
6017
6018
        cmd = XmlCommand("start_task")
6019
        cmd.set_attribute("task_id", task_id)
6020
6021
        return self._send_xml_command(cmd)
6022
6023
    def stop_task(self, task_id: str) -> Any:
6024
        """Stop an existing running task
6025
6026
        Arguments:
6027
            task_id: UUID of the task to be stopped
6028
6029
        Returns:
6030
            The response. See :py:meth:`send_command` for details.
6031
        """
6032
        if not task_id:
6033
            raise RequiredArgument(
6034
                function=self.stop_task.__name__, argument='task_id'
6035
            )
6036
6037
        cmd = XmlCommand("stop_task")
6038
        cmd.set_attribute("task_id", task_id)
6039
6040
        return self._send_xml_command(cmd)
6041
6042
    def sync_cert(self) -> Any:
6043
        """Request a synchronization with the CERT feed service
6044
6045
        Returns:
6046
            The response. See :py:meth:`send_command` for details.
6047
        """
6048
        return self._send_xml_command(XmlCommand("sync_cert"))
6049
6050
    def sync_config(self) -> Any:
6051
        """Request an OSP config synchronization with scanner
6052
6053
        Returns:
6054
            The response. See :py:meth:`send_command` for details.
6055
        """
6056
        return self._send_xml_command(XmlCommand("sync_config"))
6057
6058
    def sync_feed(self) -> Any:
6059
        """Request a synchronization with the NVT feed service
6060
6061
        Returns:
6062
            The response. See :py:meth:`send_command` for details.
6063
        """
6064
        return self._send_xml_command(XmlCommand("sync_feed"))
6065
6066
    def sync_scap(self) -> Any:
6067
        """Request a synchronization with the SCAP feed service
6068
6069
        Returns:
6070
            The response. See :py:meth:`send_command` for details.
6071
        """
6072
        return self._send_xml_command(XmlCommand("sync_scap"))
6073
6074
    def test_alert(self, alert_id: str) -> Any:
6075
        """Run an alert
6076
6077
        Invoke a test run of an alert
6078
6079
        Arguments:
6080
            alert_id: UUID of the alert to be tested
6081
6082
        Returns:
6083
            The response. See :py:meth:`send_command` for details.
6084
        """
6085
        if not alert_id:
6086
            raise InvalidArgument("test_alert requires an alert_id argument")
6087
6088
        cmd = XmlCommand("test_alert")
6089
        cmd.set_attribute("alert_id", alert_id)
6090
6091
        return self._send_xml_command(cmd)
6092
6093
    def trigger_alert(
6094
        self,
6095
        alert_id: str,
6096
        report_id: str,
6097
        *,
6098
        filter: Optional[str] = None,
6099
        filter_id: Optional[str] = None,
6100
        report_format_id: Optional[str] = None,
6101
        delta_report_id: Optional[str] = None
6102
    ) -> Any:
6103
        """Run an alert by ignoring its event and conditions
6104
6105
        The alert is triggered to run immediately with the provided filtered
6106
        report by ignoring the even and condition settings.
6107
6108
        Arguments:
6109
            alert_id: UUID of the alert to be run
6110
            report_id: UUID of the report to be provided to the alert
6111
            filter: Filter term to use to filter results in the report
6112
            filter_id: UUID of filter to use to filter results in the report
6113
            report_format_id: UUID of report format to use
6114
            delta_report_id: UUID of an existing report to compare report to.
6115
6116
        Returns:
6117
            The response. See :py:meth:`send_command` for details.
6118
        """
6119
        if not alert_id:
6120
            raise RequiredArgument(
6121
                function=self.trigger_alert.__name__,
6122
                argument='alert_id argument',
6123
            )
6124
6125
        if not report_id:
6126
            raise RequiredArgument(
6127
                function=self.trigger_alert.__name__,
6128
                argument='report_id argument',
6129
            )
6130
6131
        cmd = XmlCommand("get_reports")
6132
        cmd.set_attribute("report_id", report_id)
6133
        cmd.set_attribute("alert_id", alert_id)
6134
6135
        if filter:
6136
            cmd.set_attribute("filter", filter)
6137
6138
        if filter_id:
6139
            cmd.set_attribute("filt_id", filter_id)
6140
6141
        if report_format_id:
6142
            cmd.set_attribute("format_id", report_format_id)
6143
6144
        if delta_report_id:
6145
            cmd.set_attribute("delta_report_id", delta_report_id)
6146
6147
        return self._send_xml_command(cmd)
6148
6149
    def verify_agent(self, agent_id: str) -> Any:
6150
        """Verify an existing agent
6151
6152
        Verifies the trust level of an existing agent. It will be checked
6153
        whether signature of the agent currently matches the agent. This
6154
        includes the agent installer file. It is *not* verified if the agent
6155
        works as expected by the user.
6156
6157
        Arguments:
6158
            agent_id: UUID of the agent to be verified
6159
6160
        Returns:
6161
            The response. See :py:meth:`send_command` for details.
6162
        """
6163
        if not agent_id:
6164
            raise InvalidArgument("verify_agent requires an agent_id argument")
6165
6166
        cmd = XmlCommand("verify_agent")
6167
        cmd.set_attribute("agent_id", agent_id)
6168
6169
        return self._send_xml_command(cmd)
6170
6171
    def verify_report_format(self, report_format_id: str) -> Any:
6172
        """Verify an existing report format
6173
6174
        Verifies the trust level of an existing report format. It will be
6175
        checked whether the signature of the report format currently matches the
6176
        report format. This includes the script and files used to generate
6177
        reports of this format. It is *not* verified if the report format works
6178
        as expected by the user.
6179
6180
        Arguments:
6181
            report_format_id: UUID of the report format to be verified
6182
6183
        Returns:
6184
            The response. See :py:meth:`send_command` for details.
6185
        """
6186
        if not report_format_id:
6187
            raise RequiredArgument(
6188
                function=self.verify_report_format.__name__,
6189
                argument='report_format_id',
6190
            )
6191
6192
        cmd = XmlCommand("verify_report_format")
6193
        cmd.set_attribute("report_format_id", report_format_id)
6194
6195
        return self._send_xml_command(cmd)
6196
6197
    def verify_scanner(self, scanner_id: str) -> Any:
6198
        """Verify an existing scanner
6199
6200
        Verifies if it is possible to connect to an existing scanner. It is
6201
        *not* verified if the scanner works as expected by the user.
6202
6203
        Arguments:
6204
            scanner_id: UUID of the scanner to be verified
6205
6206
        Returns:
6207
            The response. See :py:meth:`send_command` for details.
6208
        """
6209
        if not scanner_id:
6210
            raise RequiredArgument(
6211
                function=self.verify_scanner.__name__, argument='scanner_id'
6212
            )
6213
6214
        cmd = XmlCommand("verify_scanner")
6215
        cmd.set_attribute("scanner_id", scanner_id)
6216
6217
        return self._send_xml_command(cmd)
6218