2.1.7 conflict merge

Author: Jim Olsen

BUILD/doc/source/conf.py

@@ -71,7 +71,7 @@
 master_doc = 'index'
 
 # General information about the project.
-copyright = u'2015, Tanium'
+copyright = u'2015, Tanium Inc.'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the

CHANGELOG.md

@@ -0,0 +1,95 @@
+#!/usr/bin/env python -i
+# -*- mode: Python; tab-width: 4; indent-tabs-mode: nil; -*-
+# ex: set tabstop=4
+# Please do not change the two lines above. See PEP 8, PEP 263.
+'''Provides an example workflow for how to deploy actions when require_action_approval == 1'''
+__author__ = 'Jim Olsen <[email protected]>'
+__version__ = '2.1.7'
+
+pytan_loc = '~/gh/pytan'
+
+import os
+import sys
+
+sys.dont_write_bytecode = True
+sys.path.append(os.path.join(os.path.expanduser(pytan_loc), 'lib'))
+
+my_file = os.path.abspath(sys.argv[0])
+my_name = os.path.splitext(os.path.basename(my_file))[0]
+my_dir = os.path.dirname(my_file)
+parent_dir = os.path.dirname(my_dir)
+lib_dir = os.path.join(parent_dir, 'lib')
+path_adds = [lib_dir]
+[sys.path.append(aa) for aa in path_adds if aa not in sys.path]
+
+import pytan
+import pytan.binsupport
+
+import time
+import logging
+
+
+@pytan.utils.func_timing
+def wait_for_new_action(saved_action_id):
+    while True:
+        # re-fetch the saved action in order to get the updated last_action attribute
+        saved_action = handler.get('saved_action', id=saved_action_id)[0]
+        # fetch the full object of the last action created by the saved action
+        full_action_object = handler.get('action', id=saved_action.last_action.id)[0]
+        if full_action_object.status != 'Pending':
+            print 'DEBUG: new action created by saved_action: {}'.format(full_action_object)
+            return full_action_object
+        print 'DEBUG: action is still in Pending status, new action not yet created: {} / {}'.format(full_action_object, full_action_object.status)
+        time.sleep(1)
+
+
+if __name__ == "__main__":
+    pytan.binsupport.version_check(reqver=__version__)
+
+    setupmethod = getattr(pytan.binsupport, 'setup_pytan_shell_argparser')
+    responsemethod = getattr(pytan.binsupport, 'process_pytan_shell_args')
+
+    parser = setupmethod(doc=__doc__)
+    args = parser.parse_args()
+
+    handler = pytan.binsupport.process_handler_args(parser=parser, args=args)
+    response = responsemethod(parser=parser, handler=handler, args=args)
+
+    # bump log level up to 2 so we can see poller timing logs
+    pytan.utils.set_log_levels(loglevel=2)
+
+    # enable timing logger for func_timing:
+    logging.getLogger('pytan.handler.timing').setLevel(getattr(logging, 'DEBUG'))
+
+    # establish a package name with params
+    pkg_name = "Custom Tagging - Add Tags{$1=\{test\}}"
+
+    # deploy the action with that package but set get_results to False so that it immediately returns and does not poll the action that is created by the saved action that will always be in Pending status
+    deployed_action = handler.deploy_action(package=pkg_name, run=True, get_results=False)
+
+    # get the action_object that was created by the platform on behalf of the saved_action, which should have a status of 'Pending' due to require_action_approval = 1
+    pending_action_obj = deployed_action['action_object']
+
+    # prove that the action created by the saved action before approval is "Pending"
+    print "DEBUG: action created by platform: {}, status: {}".format(pending_action_obj.id, pending_action_obj.status)
+
+    # get the saved_action_object that was created by the platform
+    unapproved_saved_action = deployed_action['saved_action_object']
+
+    # prove that the saved_action created by the platform is not yet approved
+    print "DEBUG: saved_action approved_flag before approval: {}".format(unapproved_saved_action.approved_flag)
+
+    # approve the saved action
+    saved_action_approval = handler.approve_saved_action(id=unapproved_saved_action.id)
+
+    # prove that the saved_action created by the platform is now approved
+    print "DEBUG: saved_action approved_flag after approval: {}".format(saved_action_approval.approved_flag)
+
+    # wait for the saved action to create a new action after approval
+    full_running_action_obj = wait_for_new_action(unapproved_saved_action.id)
+
+    # create an Action Poller for the new action
+    poller = pytan.pollers.ActionPoller(handler=handler, obj=full_running_action_obj)
+
+    # run the poller
+    poller.run()

EXAMPLES/POC/approved_action_workflow.py

@@ -0,0 +1,67 @@
+#!/usr/bin/env python
+# -*- mode: Python; tab-width: 4; indent-tabs-mode: nil; -*-
+# ex: set tabstop=4
+# Please do not change the two lines above. See PEP 8, PEP 263.
+'''Exports an action, its source package, and its temp package to json format for troubleshooting'''
+__author__ = 'Jim Olsen <[email protected]>'
+__version__ = '2.1.6'
+
+# change me to the location of PyTan!
+pytan_loc = '~/gh/pytan'
+
+import os
+import sys
+import traceback
+
+sys.dont_write_bytecode = True
+sys.path.append(os.path.join(os.path.expanduser(pytan_loc), 'lib'))
+
+my_file = os.path.abspath(sys.argv[0])
+my_name = os.path.splitext(os.path.basename(my_file))[0]
+my_dir = os.path.dirname(my_file)
+parent_dir = os.path.dirname(my_dir)
+lib_dir = os.path.join(parent_dir, 'lib')
+path_adds = [lib_dir]
+[sys.path.append(aa) for aa in path_adds if aa not in sys.path]
+
+import pytan
+import pytan.binsupport
+
+if __name__ == "__main__":
+    pytan.binsupport.version_check(reqver=__version__)
+
+    parser = pytan.binsupport.setup_parent_parser(doc=__doc__)
+    arggroup_name = 'Export Action Objects Options'
+    get_object_group = parser.add_argument_group(arggroup_name)
+    get_object_group.add_argument(
+        '--id',
+        required=True,
+        action='append',
+        default=[],
+        dest='id',
+        help='id of action to export objects for',
+    )
+
+    args = parser.parse_args()
+
+    handler = pytan.binsupport.process_handler_args(parser=parser, args=args)
+
+    try:
+        action = handler.get('action', id=args.id)[0]
+    except Exception as e:
+        traceback.print_exc()
+        print "\n\nError occurred: {}".format(e)
+        sys.exit(100)
+
+    e = handler.export_to_report_file(action, 'json')
+    print "Found action: {}, exported to: {}".format(action, e[0])
+
+    try:
+        action_pkg = handler.get('package', id=action.package_spec.id, include_hidden_flag=1)[0]
+    except Exception as e:
+        traceback.print_exc()
+        print "\n\nError occurred: {}".format(e)
+        sys.exit(100)
+
+    e = handler.export_to_report_file(action_pkg, 'json')
+    print "Found package for action: {}, exported to: {}".format(action_pkg, e[0])

EXAMPLES/POC/export_action_objects.py

@@ -0,0 +1,62 @@
+#!/usr/bin/env python
+# -*- mode: Python; tab-width: 4; indent-tabs-mode: nil; -*-
+# ex: set tabstop=4
+# Please do not change the two lines above. See PEP 8, PEP 263.
+'''Provides the ability to find all sensors that reference a given set of strings in their scripts, and all saved actions that reference those same sensors'''
+__author__ = 'Jim Olsen <[email protected]>'
+__version__ = '2.1.6'
+
+# change me to the location of PyTan!
+pytan_loc = '~/gh/pytan'
+
+# modify me for the list of string matches
+match_strings = [
+    "ldap://",
+]
+
+import os
+import sys
+
+sys.dont_write_bytecode = True
+sys.path.append(os.path.join(os.path.expanduser(pytan_loc), 'lib'))
+
+my_file = os.path.abspath(sys.argv[0])
+my_name = os.path.splitext(os.path.basename(my_file))[0]
+my_dir = os.path.dirname(my_file)
+parent_dir = os.path.dirname(my_dir)
+lib_dir = os.path.join(parent_dir, 'lib')
+path_adds = [lib_dir]
+[sys.path.append(aa) for aa in path_adds if aa not in sys.path]
+
+import pytan
+import pytan.binsupport
+
+if __name__ == "__main__":
+    pytan.binsupport.version_check(reqver=__version__)
+
+    setupmethod = getattr(pytan.binsupport, 'setup_pytan_shell_argparser')
+    responsemethod = getattr(pytan.binsupport, 'process_pytan_shell_args')
+
+    parser = setupmethod(doc=__doc__)
+    args = parser.parse_args()
+
+    handler = pytan.binsupport.process_handler_args(parser=parser, args=args)
+    response = responsemethod(parser=parser, handler=handler, args=args)
+
+    all_sensors = handler.get_all('sensor', include_hidden_flag=1)
+    matched_sensors = [
+        x
+        for x in all_sensors
+        for y in x.queries
+        for z in match_strings
+        if z.lower() in y.script.lower()
+    ]
+
+    m = "Found {} sensors that reference any of these strings: {}".format
+    print m(len(matched_sensors), ', '.join(match_strings))
+
+    for x in matched_sensors:
+        m = "Matched Sensor -- ID: {}, Name: {}".format
+        print m(x.id, x.name)
+
+    all_saved_actions = handler.get_all('saved_action', include_hidden_flag=1)

EXAMPLES/POC/find_content_matches.py

@@ -0,0 +1,75 @@
+#!/usr/bin/env python
+# -*- mode: Python; tab-width: 4; indent-tabs-mode: nil; -*-
+# ex: set tabstop=4
+# Please do not change the two lines above. See PEP 8, PEP 263.
+'''Gets clients using a filter that only returns clients that have registered within a certain time'''
+__author__ = 'Jim Olsen <[email protected]>'
+__version__ = '2.1.6'
+
+# change me to the location of PyTan!
+pytan_loc = '~/gh/pytan'
+
+import os
+import sys
+
+sys.dont_write_bytecode = True
+sys.path.append(os.path.join(os.path.expanduser(pytan_loc), 'lib'))
+
+my_file = os.path.abspath(sys.argv[0])
+my_name = os.path.splitext(os.path.basename(my_file))[0]
+my_dir = os.path.dirname(my_file)
+parent_dir = os.path.dirname(my_dir)
+lib_dir = os.path.join(parent_dir, 'lib')
+path_adds = [lib_dir]
+[sys.path.append(aa) for aa in path_adds if aa not in sys.path]
+
+import pytan
+import pytan.binsupport
+import taniumpy
+
+
+def get_clients_filter(handler, minutes=5):
+    kwargs = {}
+    if minutes:
+        cache_filter = taniumpy.CacheFilter()
+        cache_filter.field = 'last_registration'
+        cache_filter.type = 'Date'
+        cache_filter.operator = 'Greater'
+        cache_filter.not_flag = False
+        last_registration = -(minutes * 60)
+        cache_filter.value = pytan.utils.seconds_from_now(last_registration)
+
+        cache_filter_list = taniumpy.CacheFilterList()
+        cache_filter_list.append(cache_filter)
+        # cache_filter_list_body = cache_filter_list.toSOAPBody()
+        kwargs['cache_filters'] = cache_filter_list
+
+    search_spec = taniumpy.SystemStatusList()
+    clients = handler.session.find(search_spec, **kwargs)
+    return clients
+
+
+if __name__ == "__main__":
+    pytan.binsupport.version_check(reqver=__version__)
+
+    setupmethod = getattr(pytan.binsupport, 'setup_pytan_shell_argparser')
+    responsemethod = getattr(pytan.binsupport, 'process_pytan_shell_args')
+
+    parser = setupmethod(doc=__doc__)
+    parser.add_argument(
+        '-m',
+        '--minutes',
+        required=False,
+        action='store',
+        dest='minutes',
+        type=int,
+        default=5,
+        help='Only return clients that have registered in the last minutes',
+    )
+    args = parser.parse_args()
+
+    handler = pytan.binsupport.process_handler_args(parser=parser, args=args)
+    response = responsemethod(parser=parser, handler=handler, args=args)
+
+    clients = get_clients_filter(handler, minutes=args.minutes)
+    print clients

EXAMPLES/POC/get_client_filter.py

@@ -0,0 +1,64 @@
+#!/usr/bin/env python -i
+# -*- mode: Python; tab-width: 4; indent-tabs-mode: nil; -*-
+# ex: set tabstop=4
+# Please do not change the two lines above. See PEP 8, PEP 263.
+'''Provides an interactive console with pytan available as handler'''
+__author__ = 'Jim Olsen <[email protected]>'
+__version__ = '2.1.5'
+
+import os
+import sys
+sys.dont_write_bytecode = True
+
+# change me to the location of PyTan!
+pytan_loc = '~/gh/pytan'
+sys.path.append(os.path.join(os.path.expanduser(pytan_loc), 'lib'))
+
+my_file = os.path.abspath(sys.argv[0])
+my_name = os.path.splitext(os.path.basename(my_file))[0]
+my_dir = os.path.dirname(my_file)
+parent_dir = os.path.dirname(my_dir)
+lib_dir = os.path.join(parent_dir, 'lib')
+path_adds = [lib_dir]
+[sys.path.append(aa) for aa in path_adds if aa not in sys.path]
+
+import pytan
+import pytan.binsupport
+
+# List your sensors here that are exact name matches for sensors that should not be deleted
+KEEP_LIST = [
+    'Folder Exists',
+]
+
+# List your sensor categories that are exact matches for sensor categories that should not be deleted
+KEEP_CATEGORIES = [
+    'Reserved',
+]
+
+# Set this to True to actually delete, set to False to just report on what would be deleted
+ACTUALLY_DELETE = False
+
+if __name__ == "__main__":
+    pytan.binsupport.version_check(reqver=__version__)
+
+    setupmethod = getattr(pytan.binsupport, 'setup_pytan_shell_argparser')
+    parser = setupmethod(doc=__doc__)
+    args = parser.parse_args()
+
+    handler = pytan.binsupport.process_handler_args(parser=parser, args=args)
+
+    all_sensors = handler.get_all('sensor', include_hidden_flag=1)
+    print "-- {} sensors in total".format(len(all_sensors))
+
+    to_be_deleted = [
+        x for x in all_sensors
+        if x.name not in KEEP_LIST
+        and x.category not in KEEP_CATEGORIES
+    ]
+    print "-- {} sensors to be deleted".format(len(to_be_deleted))
+
+    for s in to_be_deleted:
+        print "!! Sensor ID {s.id!r}, name: {s.name!r} to be deleted!".format(s=s)
+        if ACTUALLY_DELETE:
+            handler.session.delete(s)
+            print "-- Sensor ID {s.id!r}, name: {s.name!r} deleted!".format(s=s)

EXAMPLES/POC/sensor_cleanup.py

@@ -0,0 +1,19 @@
+Copyright (c) 2015 [Tanium, Inc. 2015]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.