surprising behaviour of tio.agents.list(filter)

[nikothome]

Describe the bug
Hi,
I brought myself in a bad situation the other day and, while this behaviour is not the sole source of that, it surely contributed a little bit. I'm also not ruling out that I'm misunderstanding how that function should work.

When calling tio.agents.list() with an incorrect filter - the function returns ALL agents instead of either raising an exception or returning no agent iterator objects at all. That's especially bad if you plan to unlink only a certain subset of agents and not all agents linked to your container.

To Reproduce
Steps to reproduce the behavior:

my_filter=("name", "match", "CBLT")
 
for agents in tio_prod.agents.list(filters=my_filter):
       print(agents["name"])

output:

my_other_agent__1
my_other_agent__2
my_other_agent__3
my_other_agent__4
my_other_CBLT_agent__1
my_other_CBLT_agent__2
my_other_CBLT_agent__3

when I'm directly supplying the tuple it works are expected:

for agents in tio_prod.agents.list(("name", "match", "CBLT")):
        print(agents["name"])

output:

my_other_CBLT_agent__1
my_other_CBLT_agent__2
my_other_CBLT_agent__3

As a side note: the documentation states, that one can pass multiple filters without stating exactly how. My first assumption was to either pass a tuple of tuples or a list of tuples. Neither of which works. Apparently you should just supply one tuple with all filters concatenated?

Expected behavior
if a filter syntactically wrong or of the wrong type an exception should be raised.

System Information (please complete the following information):

• OS: Windows 11
• Architecture: 64 bits
• Version: pyTenable 1.7.3 with python 3.12
• Memory: 32G

[SteveMcGrath]

As the filters attribute is an arbitrary argument list, there are a couple of approaches:

1. Define them directly by simply comma-delimitating these:

my_filter1=("name", "match", "CBLT")
my_filter2=("name", "match", "something")
 
for agents in tio_prod.agents.list(my_filter1, my_filter2):
       print(agents["name"])

2. Define them as a list or tuple and then pass them in, declaring them as an argument list:

my_filters=[("name", "match", "CBLT"), ("name", "match", "something")]
 
for agents in tio_prod.agents.list(*my_filters):
       print(agents["name"])

[nikothome]

hi @SteveMcGrath,
thanks for the quick update.
The fact that I'm getting ALL agents back if the filter is wrongfully specified is really considered "as-designed"? I asked a little bit around here and not a single person would have expected that.
If that's the case, then I would at least suggest an update to the documentation.

[SteveMcGrath]

its a result of the approach that was taken to construct the payload to send to the API. it means that if you pass something is doesn't necessarily understand, it wont be registered. Its a throwback from when the APIs were changing a lot and we had to support all the way down to Python 2.6, which precluded us from using anything modern. You can see WHY it's behaving that way here, however as more than 2/3rds of the TVM/TIO package is written that way, you can imagine the scope of the project to modernize a lot of this.

There has been some debate on if we build a net-new branch, attempting to support backwards compat where we can, or to just replace the bits in-place.

All new code has had to adhere to modern techniques of type hints, pydantic models, and leveraging more of Python 3.10+. So this is simply an issue of that legacy code that needs to be refactored out.

[SteveMcGrath]

As for the documentation, it IS correct, its specifying the filters argument as an arbitrary list, as denoted by the single *. I think what can be done for the next version is to add an example with multiple filters