tanium / pytan

Python Wrapper for Tanium's SOAP API

Tanium is sunsetting PyTan and encouraging customers and partners to utilize the REST API for integrations. Work with your TAM to start using the REST API as soon as possible.

• PyTan
  • What is it?
  • Versions
  • Documentation Links
  • Quick Install Instructions
  • Release strategy
  • Package Info

PyTan

What is it?

This is a set of packages and scripts that provide a simple way for interfacing with the Tanium SOAP API using python or the command line.

Versions

• 2.3.0 (June 10 2019) Release Link

Documentation Links

Documentation is only generated for major releases!

• Online documentation for PyTan 2.1.6:
  • HTML: Main Index
  • HTML: PyTan API Examples
  • HTML: PyTan Command Line Usage
  • PDF: Standalone PDF version of HTML
• Offline documentation for PyTan 2.1.6:
  • Zipped HTML documentation for PyTan 2.1.6
  • PDF documentation for PyTan 2.1.6
• Other documentation:
  • Change Log for PyTan
  • To Do List for PyTan

Quick Install Instructions

• First, download PyTan using your browser by browsing to: https://github.com/tanium/pytan/releases/latest and choosing one of the Downloads (zip or tar.gz)
• Then refer to the OS specific instructions below to proceed.
• Additional information on installation can be found in the documentation

Mac OSX

• Create a new directory for storing PyTan:

mkdir ~/tanium

• Extract the PyTan ZIP file you downloaded to ~/tanium:

cd ~/tanium
unzip pytan-2.2.2.zip

• Verify that your OSX install has Python 2.7.x installed and that your PYTHONPATH points to 2.7.x:

python -V
python -c “import sys; print sys.path”

Linux

• Create a new directory for storing PyTan:

mkdir ~/tanium

• Extract the PyTan ZIP file you downloaded to ~/tanium:

cd ~/tanium
unzip pytan-2.2.2.zip

• Verify that your linux distribution has Python 2.7.x installed and that your PYTHONPATH points to 2.7.x:

python -V
python -c “import sys; print sys.path”

Windows

• Create a new directory for storing PyTan:

mkdir c:\tanium

• Extract the PyTan ZIP file you downloaded to C:\tanium
• Install Python 2.7.10:
  • Using your browser, download Python 2.7.10 from: https://www.python.org/downloads/release/python-2710/
  • Run the Python 2.7.10 installer
  • On the Customize Python section of the installer select, 'Add Python.exe to Path' to allow you to run Python from cmd shell without absolute path
  • Accept all other defaults for the installer

Release strategy

• The current stable version will always be maintained in the master branch.
• Unstable and development versions can be accessed via the develop branch.
• Full regression tests will be performed every major (x.0.0) or minor (0.x.0) release of PyTan
• All documentation and API examples will be rebuilt every major (x.0.0) or minor (0.x.0) release of PyTan
• Revision releases (0.0.x) will only be tested against the latest stable release of Tanium for each minor build (6.2.314.xxxx, 6.5.314.xxxx, etc.)

Package Info

• Author and Maintainer: Jim Olsen ([email protected])
• License: MIT
• Copyright: Tanium Inc. 2017

pytan's Issues

modify and add methods & scripts for RBAC

create_user needs full RBAC support
create_user needs full computer group support
create_user needs full content role set / content role set membership support

How do you specify the content set when calling create_package

Not sure if I need to put a new key in the json that's sent? I tried 'content_set': {content set name} and while the package was created, the content set was still default.

iteritems causing "dictionary changed size during iteration" runtime error

With python 2.7.10 on the windows platform, the following line within handler.py throws a "dictionary changed size during iteration" runtime error.

for k, v in locals().iteritems():

Changing iteritems() to items() seems to eliminate the issue.

for k, v in locals().items():

I only have access to the Windows platform within the environment in which I also have access to Tanium. So I can't test other platforms. I have had a peer on Mac state that they don't encounter the issue.

The switch to .items() also mirrors the recommendation found in pep 3106.

add computer_group native support to methods

ask_manual
deploy_action
?

change default of xml cleaner to false

Should no longer be needed. Move default into constants.py.

add secondary loop for if any data == current result unavail/etc

When [current result unavailable] or [results currently unavailable] found in output of resultset during question asker, add a secondary loop to keep fetching data for up to 10 minutes (or question expiry)

requests has issues with connecting to SSL servers that have more securely.

Need to update to latest requests with security extras.

change get logic to use cache_filters instead of objectlist for object selection

Getting object currently uses objectlist to define what should be fetched. Objectlist has limitations, one of which is that it will only return the first object if finds for name match.

run unit / functional tests

fix any errors!!

extract params doesn't allow for comma delimited param values

line 743 in utils.py needs the following entry to allow for escaped commas in values:

    if '\\,' in sp_value:
        sp_value = sp_value.replace('\\,', ',')

remove BUILD directory

can save on 34MB, not necessary in main distro

Some test systems already have WhiteListed URLs

This happens when my test system already has (or has had) white-listed URLs registered.

test_valid_get_object_18_get_whitelisted_url_by_id (__main__.ValidServerTests) ... 
+++ TESTING EXPECTED GET SUCCESS Handler.get() with kwargs {u'objtype': u'whitelisted_url', u'id': 1}
ERROR
****************************************************************************************************
2016-08-17T16:36:48: PyTan v'2.1.8' against Tanium v'6.6.314.5240' -- Valid Tests Finished

======================================================================
ERROR: test_valid_get_object_18_get_whitelisted_url_by_id (__main__.ValidServerTests)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/home/apena/work/soft/pytan/lib/ddt.py", line 163, in wrapper
    return func(self, *args, **kwargs)
  File "test/test_pytan_valid_server_tests.py", line 377, in test_valid_get_object
  File "/home/apena/work/soft/pytan/lib/pytan/handler.py", line 2265, in get
    raise pytan.exceptions.HandlerError(err(objtype, err_args))
HandlerError: No results found searching for whitelisted_url with {u'id': 1}!!

----------------------------------------------------------------------
Ran 87 tests in 131.560s

FAILED (errors=1)

get rid of 6.2/6.5 branching logic

No longer supporting 6.2
No longer NEED to rely on having the platform version, all code should work 6.5 and up.
Only going to validate and test against 7.2 from now on!!

Change get_server_version() to be more error proof

• don't get info.json anymore on init
• try to get current user info, and see if server version in that, if so use that.
• if not, just return unknown.

only admin's get server version returned in SOAP response?
only admin's get access to info.json?

Needs full testing.

Should also get rid of force server version? We're not relying on server version for anything anymore.

Submit pytan package to PyPI

Hi,
Any chance you will publish this package to pypl so it can be installed with pip install pytan?

Great package name BTW 👍

Thanks

Wrong quote characters

Super lame and minor issue, but thought I'd log anyways. In README.md, there are curved quotes for the python -c call that don't work. They actually need to be straight quotes.

Doesn't work:
python -c “import sys; print sys.path;”

Errors out:
File "", line 1
“import
^
SyntaxError: invalid syntax
-bash: print: command not found
-bash: ”: command not found

Should be:
python -c "import sys; print sys.path"

Deploy Action throws RBAC error

With the release of the new version (7.2), all action deployments throw RBAC errors when retrieving results. It is also no longer possible to deploy actions without specifying an action group.

When not specifying an action group, this error is displayed:
https://gist.github.com/Robiq/5a4b4efc325bdf4d00a839b49231b961

When specifying an action group, this error is displayed:
https://gist.github.com/Robiq/a975bd9ea8df42aea4997d6d00070090

Both of these are when logged in as an administrator with no restrictions.
If possible, a hotfix or temporary hack would be great, so that regular operations can be resumed.
Thank you!

lint all of pytan

using flake 8

add support for specifying timeout value for when to consider a question done

There already exists an argument called "--complete_pct" which tells Tanium at what percentage of clients have responded that it should consider the question complete, and return results.

In addition to % complete, it would be helpful to alternatively have the ability to specify a timeout value. That is, I could specify something like 180 seconds, and after 3 minutes, Tanium would consider a question complete, and return the results. Instead of waiting to reach a certain percentage threshold.

This is already a way to do this when using the Connect module. You can edit a connection, and under the Source > Saved Question > Advanced Settings, you can set "Answer Complete Percent" to 0, and set a "Timeout" value, and then Tanium will simply wait however many minutes are specified in the Timeout value before returning results.

In looking at the source code, there seems to be an argument called --override_timeout_secs, which looks like it may be intended to do this. However, when I pass this to ask_manual.py, for example, it complains with the error "ERROR:ask_manual:unrecognized arguments: --override_timeout_secs 120".

Here is the command I run:

C:\pytan-2.1.8\winbin>ask_manual.bat -u UNAME -p "PWD" --host SERVERNAME --port 443 --loglevel 4 --override_timeout_secs 120 -s "Computer Name" -s "Last Logged In User"

And here is the error I get

ERROR:ask_manual:unrecognized arguments: --override_timeout_secs 120

Thanks

default_behavior_for_saved_question_no_refresh_saved_data

we should modify default behavior to force refresh of data over no refresh, and create a more graceful error for questions without saved responses.

Parameters in Filter part of Manual Question

This is a valid question in the console:

Get Computer Name from all machines with Index Query File Exists[, , , b32189bdff6e577a92baa61ad49264e6, , , ] containing "Yes"

But when I try to run it as a manual question using PyTan, the parameters are stripped off the filter:

./ask_manual.py -s 'Computer Name' -f 'Index Query File Exists{fileName=b32189bdff6e577a92baa61ad49264e6}, that contains:Yes'
++ Asked Question 'Get Computer Name from all machines with Index Query File Exists containing "Yes"' ID: 2371224

I tried modifying get_filter_obj() in utils.py to add the parameters in the same way that build_selectlist_obj() does it, but that doesn't seem to work.

Below is the added_obj value just before the question is asked, as well as a diff of the code I tried to use to make it work. Since it's a valid question in the console, it seems like this should work. Is this a limitation with PyTan and I just haven't added the parameters correctly, or is it a limitation in the API?

added_obj JSON
{
"_type": "question",
"group": {
"_type": "group",
"filters": {
"_type": "filters",
"filter": [
{
"_type": "filter",
"not_flag": 0,
"operator": "RegexMatch",
"sensor": {
"_type": "sensor",
"id": 1295,
"parameters": {
"_type": "parameters",
"parameter": [
{
"_type": "parameter",
"key": "||fileName||",
"value": "b32189bdff6e577a92baa61ad49264e6"
}
]
},
"source_id": 1295
},
"value": ".Yes."
}
]
}
},
"selects": {
"_type": "selects",
"select": [
{
"_type": "select",
"filter": {
"_type": "filter",
"sensor": {
"_type": "sensor",
"hash": 3409330187
}
},
"sensor": {
"_type": "sensor",
"hash": 3409330187
}
}
]
}
}

diff --git a/lib/pytan/handler.py b/lib/pytan/handler.py
index 9b396c7..dddf302 100755
--- a/lib/pytan/handler.py
+++ b/lib/pytan/handler.py
@@ -3285,6 +3285,7 @@ class Handler(object):
'pytan_help',
'handler',
'sse',

•        'params',
   ]
   clean_kwargs = pytan.utils.clean_kwargs(kwargs=kwargs, keys=clean_keys)
  

@@ -3350,6 +3351,8 @@ class Handler(object):
# add our Question and get a Question ID back
h = "Issue an AddObject to add a Question object"
added_obj = self._add(obj=add_obj, pytan_help=h, **clean_kwargs)

•    print "added_obj JSON"
  

•    print added_obj.to_json(add_obj)
  
   m = "Question Added, ID: {}, query text: {!r}, expires: {}".format
   self.mylog.debug(m(added_obj.id, added_obj.query_text, added_obj.expiration))
  

  diff --git a/lib/pytan/utils.py b/lib/pytan/utils.py
  index 7cb521b..0b59a95 100644
  --- a/lib/pytan/utils.py
  +++ b/lib/pytan/utils.py
  @@ -604,6 +604,7 @@ def dehumanize_question_filters(question_filters):
  question_filter_defs = []
  for question_filter in question_filters:
  s, parsed_selector = extract_selector(question_filter)

•    s, parsed_params = extract_params(s)
   s, parsed_filter = extract_filter(s)
   if not parsed_filter:
       err = "Filter {!r} is not a valid filter!".format
  

  @@ -611,6 +612,7 @@ def dehumanize_question_filters(question_filters):

   question_filter_def = {}
   question_filter_def[parsed_selector] = s
  

•    question_filter_def['params'] = parsed_params
   question_filter_def['filter'] = parsed_filter
  
   dbg = (
  

  @@ -1235,6 +1237,7 @@ def build_group_obj(q_filter_defs, q_option_defs):
  for d in q_filter_defs:
  # validate/map question filter into a Filter()
  filter_obj = get_filter_obj(d)

•    print "filter_obj JSON:", filter_obj.to_json(filter_obj)
  
   # update filter_obj with any options
   filter_obj = apply_options_obj(q_option_defs, filter_obj, 'filter')
  

  @@ -1514,7 +1517,23 @@ def get_filter_obj(sensor_def):

  create our basic filter that is needed no matter what

  filter_obj = taniumpy.Filter()
  filter_obj.sensor = taniumpy.Sensor()

• filter_obj.sensor.hash = sensor_obj.hash

• user_params = sensor_def.get('params', {})
• param_objlist = build_param_objlist(

•    obj=filter_obj.sensor,
  

•    user_params=user_params,
  

•    delim='||',
  

•    derive_def=True,
  

•    empty_ok=True
  

• )
• print "PARAMS:", param_objlist.to_json(param_objlist)

• if param_objlist:

•    filter_obj.sensor.source_id = sensor_obj.id
  

•    filter_obj.sensor.parameters = param_objlist
  

•    filter_obj.sensor.id = sensor_obj.id
  

• else:

•    filter_obj.sensor.hash = sensor_obj.hash
  

  get the filter the user supplied

  filter_def = sensor_def.get('filter', {})

rework logging system for file logging support

• add log_level
• alias loglevel to log_level
• add log_con_ args
• add log_file_ args
• add log_show arg
• add concept of filters (using logger.con_enabled and logger.con_disabled)

reload(sys) drops stdio mappings

Discovered this issue when trying to use pytan with Project Jupyter. This is not really a bug, but in https://github.com/tanium/pytan/blob/master/lib/pytan/sessions.py
lines 39-41

import sys
reload(sys)
sys.setdefaultencoding('utf-8')

The reload(sys) kills off any stdio mappings that a user sets before the user loads pytan. It is a known issue
ipython/ipython#8354
http://stackoverflow.com/questions/3828723/why-we-need-sys-setdefaultencodingutf-8-in-a-py-script

There is a suggested fix of saving the stdio before reloading. Something like.

default_stdout = sys.stdout
default_stderr = sys.stderr
reload(sys)
sys.stdout = default_stdout
sys.stderr = default_stderr

Add support and test against 6.5 platform

sync up changes betwixt taniumpy local copy and repo

Taniumpy drift has gotten too large, fix it (also needed for full 6.5 support)

Client Status Filter Ability

When performing a request to gather system_status data using the following:

kwargs = {}
kwargs["objtype"] = u'client'
kwargs["status"] = u'Leader'

response = handler_object.get(**kwargs)

When dealing with this data I would like to be able to review only the data from the systems that have reported into the server in the last X number of registration periods (default is 4 minutes but I should be able to filter upon any set amount of time).

I found a way around this by doing the processing locally using the following but this is not optimal as it forces me to do post-processing of data:

day_ago = datetime.datetime.utcnow() - datetime.timedelta(days=1)
day_ago.isoformat()[:19]

client_list = []
for each in out['client_status']:
	client_time = datetime.datetime.strptime( each['last_registration'], "%Y-%m-%dT%H:%M:%S" )
	if day_ago < client_time:
		client_list.append(each['host_name'])

broken CR in folder name search regex match

Some CSV exports of content from folder name search with regex match produce incorrect CR's in Excel

add command line arguments to ask_manual and deploy_action

ask_manual:
override_estimated_total
override_passed_count
(add support to handler for this override_passed_count to be used interchangeably for force_passed_done_count like deploy_action)

deploy_action:
override_passed_count

update README.md before release

need new tag
ensure date/version/links all correct

add support for --options flags to bin

get_server_info errors out on pytan 2.0.3 against tanium 6.2

In pytan.sessions.py the function get_server_info it looks like self.http_post is returning a str instead of json:

d == digit; h == hex

dddd-ddddd-hhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhhh

This of course is problematic as you can't call get on a unicode string. The library technically continues functioning after the exception is thrown though...

Exception in thread Thread-2:
Traceback (most recent call last):
  File "/usr/local/Cellar/python/2.7.10/Frameworks/Python.framework/Versions/2.7/lib/python2.7/threading.py", line 810, in __bootstrap_inner
    self.run()
  File "/usr/local/Cellar/python/2.7.10/Frameworks/Python.framework/Versions/2.7/lib/python2.7/threading.py", line 763, in run
    self.__target(*self.__args, **self.__kwargs)
  File "../lib/pytan/handler.py", line 1609, in _derive_server_version
    self.server_version = self.session.get_server_version()
  File "../lib/pytan/sessions.py", line 421, in get_server_version
    self.server_info = self.get_server_info()
  File "../lib/pytan/sessions.py", line 409, in get_server_info
    body['diags_flat'] = self._flatten_server_info(body.get('Diagnostics', []))
AttributeError: 'unicode' object has no attribute 'get'Exception in thread Thread-2:
Traceback (most recent call last):
  File "/usr/local/Cellar/python/2.7.10/Frameworks/Python.framework/Versions/2.7/lib/python2.7/threading.py", line 810, in __bootstrap_inner
    self.run()
  File "/usr/local/Cellar/python/2.7.10/Frameworks/Python.framework/Versions/2.7/lib/python2.7/threading.py", line 763, in run
    self.__target(*self.__args, **self.__kwargs)
  File "../lib/pytan/handler.py", line 1609, in _derive_server_version
    self.server_version = self.session.get_server_version()
  File "../lib/pytan/sessions.py", line 421, in get_server_version
    self.server_info = self.get_server_info()
  File "../lib/pytan/sessions.py", line 409, in get_server_info
    body['diags_flat'] = self._flatten_server_info(body.get('Diagnostics', []))
AttributeError: 'unicode' object has no attribute 'get'

I don't really have access to the Tanium instance but I can try to work with the platform owner if this is unexpected. I did a simple get on /info.json and it looks like the second number increases every time and the last bit is random (I tried hex decoding it but it was gibberish).

pytan does not recognize/know about new object types in Tanium v7.2

. Need to rebuild taniumpy against 7.2 WSDL and update pytan mappings so that handler methods can use the new objects.

clean up open file handles

There are a number of file handles that are not properly being closed. Fix that

Some systems have require_action_aproval = 1

And PyTan tests fail.

test_valid_deploy_action_1_deploy_action_simple_against_windows_computers (__main__.ValidServerTests) ... 
+++ TESTING EXPECTED DEPLOY ACTION SUCCESS Handler.deploy_action() with kwargs {u'run': True, u'action_filters': u'Operating System, that contains:Windows', u'package': u'Distribute Tanium Standard Utilities'}
2016-08-17 16:25:40,842 INFO     pytan.pollers.QuestionPoller: ID 43133: Reached Threshold of 99% (1 of 1)
2016-08-17 16:25:40,867 WARNING  pytan.pollers.ActionPoller: ID 100: Action status is Pending, which is not one of: active, open
2016-08-17 16:25:40,887 WARNING  pytan.pollers.ActionPoller: ID 100: Action status is Pending, which is not one of: active, open
FAIL
****************************************************************************************************
2016-08-17T16:25:40: PyTan v'2.1.8' against Tanium v'6.6.314.5240' -- Valid Tests Finished

======================================================================
FAIL: test_valid_deploy_action_1_deploy_action_simple_against_windows_computers (__main__.ValidServerTests)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/home/apena/work/soft/pytan/lib/ddt.py", line 163, in wrapper
    return func(self, *args, **kwargs)
  File "test/test_pytan_valid_server_tests.py", line 197, in test_valid_deploy_action
AssertionError: 0 not greater than or equal to 1

----------------------------------------------------------------------
Ran 48 tests in 132.016s

FAILED (failures=1)

remove debug method locals methods/calls/loggers

Older testing stuff that is no longer necessary

Exports of questions with repeated column names returns incorrectly

Issue: Asking a compound question whose result sets contain fields with the same name causes the result from one to overwrite the other.

To reproduce: using pytan.Handler, ask "GET
Running Service Short Name containing "CryptSvc"
and
Running Service Short Name containing "Audiosrv"
FROM all machines" and export as CSV
Expected result: A CSV that looks like

Count,Running Service Short Name,Running Service Short Name,
4,CryptSvc,[no results]
7.CryptSvc,Audiosrv

Actual Result:

Count,Running Service Short Name,Running Service Short Name,
4,CryptSvc,CryptSvc
7.CryptSvc,CryptSvc

Action targets Computer Group instead of Action Group

Using PyTan version 2.2 at Accenture we ran into a scenario where the Actions created by Phantom were targeting the All Computers Computer Group instead of the Action Group of the same name. The The Computer Group had a lower ID in the groups table, so the Actions ended up being created with that group instead of the Action Group. This caused an issue with Action Approval where the Actions would not display for any user except the user that created the Action.

release

bump version
make 2.3.0 instead?
regen docs? (HUGE)

test_valid_question_18_ask_manual_question_complex_query2 assumes a google app is on the endpoint

This is invalid with most of the testing infrastructure out there (mostly windows based).