If you would like to skip directly to the technical details, click here<\/a>. You can also jump right into the companion script<\/a> on github if that is more your speed.<\/p>\n\n\n\n Limitations to the pace of administrative activities are simply a fact of life once an enterprise has reached a certain level of maturity. These limitations are not necessarily arbitrary as each enterprise has unique constraints. One must respect these limits as an aspiring developer of automation or you may find yourself in hot water. Tanium moves quickly by design. Automation through Tanium moves at an even greater pace. Mistakes delivered via automation move even quicker still. It is your responsibility to develop solutions with these simple truths in mind. Tell me if you’ve heard this one; your team has been asked to deploy a BIOS update to endpoints. You do not know for sure how many will be online in the evening. The Support team says that this activity creates high call volume and wants a maximum audience of 1 (Suspend disbelief here; we are labbing this). InfoSec wants this effort completed by the end of the week due to a vulnerability in old BIOS versions. You need to hit the maximum number of endpoints each night to get this done by the end of the week.<\/p>\n\n\n\n The scenario is likely familiar for anyone in Ops. To address this problem, we need to do the following:<\/p>\n\n\n\n All 4 of these tasks are technically possible with the API but creating a deployment with Deploy via TanREST is sufficiently complex to require its own article. For the sake of simplicity, we will assume you did that manually during the day and just want the automation to dynamically handle adding endpoints to the targeting logic in the evening.<\/p>\n\n\n\n We want use Tanium Interact to ensure that our targeting logic is precise before we go any further. I used the following investigative question for that purpose:<\/p>\n\n\n\n No change in an enterprise environment propagates more quickly than a mistake so I am consciously using this opportunity to validate the BIOS Versions<\/strong> as well as the Computer Names <\/strong>of the endpoints that would be captured by the filtering logic. Doing so actually helped me identify an initial problem in my targeting logic; there was an Or<\/strong> clause rather than an And<\/strong> clause which resulted in some unintended assets showing up. <\/p>\n\n\n\n I tend to rely heavily on the PowerShell PSCustomObject<\/a> when I am doing this type of work; it is a versatile data type that is easy to work with. We are establishing a PSCustomObject with the $biosObject<\/strong> variable and giving it some basic structural properties that we will be calling on later. <\/p>\n\n\n With that out of the way, we pass the $biosObject.question<\/strong> property to the New-TaniumCoreParseQuestion<\/strong> function and capture the output of that activity in $biosObject.parsed<\/strong>.<\/p>\n\n\n If the parser finds only 1 possible interpretation of the submitted question, we will have a canonical value of 1 which will satisfy our if statement. The $biosObject.parsed<\/strong> property that we put data into previously is now called upon and passed to the New-TaniumCoreQuestion<\/strong> function which formally puts the Tanium platform to the task of gathering that information.<\/p>\n\n\n The results of the question have been collected at this point and the script moves on to gather those results into the $biosObject.results<\/strong> property by way of the Get-TaniumCoreQuestionResult <\/strong>function. <\/p>\n\n\n This next part is interesting. We collected the results for this section below where we determine if the number of online assets meeting our criteria breaches the $biosMax value that we set at the beginning of the script.<\/p>\n\n\n If the number of online assets exceeds our maximum allowable value for BIOS upgrades, we use some basic math to determine what percentage of the online assets must be targeted in order to maximize the night’s deployment opportunity.<\/p>\n\n\n The block below uses New-TaniumActionObject<\/strong> to create an action object. The syntax here is highly sensitive so move carefully to modify it. The comparison operators are listed below the script block. I use the Custom Tagging – Add Tags<\/strong> package with a date-specific tag and deliver it to a percentage of the online assets determined by our little algebra problem from earlier. The Windows OS Type,<\/strong> Is Virtual<\/strong>, BIOS Version<\/strong>, and Online Random Sample <\/strong>sensors are used to accomplish this.<\/p>\n\n\n Supported operators:<\/p>\n\n\n The Action <\/strong>object has been established and validated at this point so it is then passed to the New-TaniumAction<\/strong> function and the output of that activity is passed into $biosObject.action<\/strong>. The script then pauses for 5 minutes and then gathers the results into the $biosObject.actionResult<\/strong> property.<\/p>\n\n\n The else portion of this is identical save for the absence of the Online Random Sample<\/strong> sensor. <\/p>\n\n\n\n Disclaimer: <\/strong>Any code made available on this site is free to use at your own discretion but it is provided without any explicit or implied guarantees of support, reliability, or functionality. I accept no responsibility in the event that the code, in its original form or any derivative versions thereafter, malfunctions or causes problems . Anything from this site that you decide to work with should be tested thoroughly in development environments in collaboration with your Technical Account Manager (TAM) until such time that you, the responsible party, decides that you are satisfied with its outcomes.<\/p>\n","protected":false},"excerpt":{"rendered":" This post is the third entry of a multi-part series that will teach users how to dynamically target endpoints for administrative activity by leveraging questions and actions issued via the Tanium API. The plan for the series is as follows: Starting the Conversation \u2013 Asking basic questions via the Tanium API Taking Action \u2013 Issuing […]<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[9,6],"tags":[14,12,10,7],"class_list":["post-592","post","type-post","status-publish","format-standard","hentry","category-powershell","category-tanium","tag-automation","tag-operations","tag-powershell","tag-tanium"],"_links":{"self":[{"href":"https:\/\/buildbreakautomate.com\/index.php\/wp-json\/wp\/v2\/posts\/592","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/buildbreakautomate.com\/index.php\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/buildbreakautomate.com\/index.php\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/buildbreakautomate.com\/index.php\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/buildbreakautomate.com\/index.php\/wp-json\/wp\/v2\/comments?post=592"}],"version-history":[{"count":14,"href":"https:\/\/buildbreakautomate.com\/index.php\/wp-json\/wp\/v2\/posts\/592\/revisions"}],"predecessor-version":[{"id":621,"href":"https:\/\/buildbreakautomate.com\/index.php\/wp-json\/wp\/v2\/posts\/592\/revisions\/621"}],"wp:attachment":[{"href":"https:\/\/buildbreakautomate.com\/index.php\/wp-json\/wp\/v2\/media?parent=592"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/buildbreakautomate.com\/index.php\/wp-json\/wp\/v2\/categories?post=592"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/buildbreakautomate.com\/index.php\/wp-json\/wp\/v2\/tags?post=592"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}A Rock | Ops | A Hard Place<\/h2>\n\n\n\n
Unfortunately, Ops teams must perpetually seek to balance risks. Moving too quickly with a given activity may imperil the stability of the environment. Moving too slowly may invite the condemnation of your InfoSec team. To that end, deployment rings with well-defined sizes or audiences are a common compromise. Let’s explore how we can respect such compromises with TanREST while making the most of a dynamic, online audience.<\/p>\n\n\n\nOpportunistic Deployments with TanREST<\/h2>\n\n\n\n
Familiar Territory<\/h3>\n\n\n\n
Unfamiliar Approach<\/h3>\n\n\n\n
Validate Your Targeting<\/h5>\n\n\n\n
![\"\"](\"https:\/\/buildbreakautomate.com\/wp-content\/uploads\/2022\/04\/apiSeries3-01-targetingValidation.png\")
![\"\"](\"https:\/\/buildbreakautomate.com\/wp-content\/uploads\/2022\/04\/apiSeries3-02-customTagsBeforeInvocation.png\")
The Companion Snippets<\/h5>\n\n\n\n
\n$biosObject = [PSCustomObject]@{\n\tquestion = "Get Online from all machines with ( ( Windows OS Type contains windows workstation and Is Virtual equals yes ) and BIOS Version < 090009 )"\n\tparsed = $null\n\tmax = $biosMax\n\tid = $null\n\tresults = $null\n\tresultCount = $null\n\tactionObject = $null\n\taction = $null\n\tactionResult = $null\n}\n<\/pre><\/div>\n\n\n\n## Pass question property of $biosObject to parser and retain results in parsed property of $biosObject\n\n$biosObject.parsed = New-TaniumCoreParseQuestion -Data @{text=$biosObject.question}\n<\/pre><\/div>\n\n\n\n## Submit Tanium questions upon validating that canonical value of 1\n\nif($biosObject.parsed.from_canonical_text -eq 1) {\n\tWrite-Output 'Gathering number of online assets meeting BIOS targeting logic...'\n\t\n\t$biosObject.id = @{ query_text = $biosObject.parsed[0].question_text } | New-TaniumCoreQuestion | Select-Object -ExpandProperty id\n}\n\nWrite-Output \"Sleeping 60 seconds to allow response to BIOS targeting question...\"\n\nStart-Sleep -Seconds 60\n<\/pre><\/div>\n\n\n\n## Collect question results into the results property of $biosObject\n\n$biosObject.results = Get-TaniumCoreQuestionResult -ID $biosObject.id | Format-TaniumCoreQuestionResults\n\n$biosObject.resultCount = $biosObject.results | Where-Object {$_.Online -eq 'True'} | Select-Object -ExpandProperty Count\n\nWrite-Output \"The number of online respondents to BIOS targeting logic is $($biosObject.resultCount).\"\n<\/pre><\/div>\n\n\n\nif ([int]$($biosObject.resultCount) -gt $biosObject.max -and $null -ne $biosObject.resultCount) \n<\/pre><\/div>\n\n\n
\n## Determine the maximum percentage of online assets that can be targeted within your defined maximum\n\n\t[int]$biosSamplePercentage = ($biosObject.max \/ $biosObject.resultCount * 100)\n<\/pre><\/div>\n\n\n
\n$biosObject.actionObject = New-TaniumActionObject -Name \"Dynamic Deployment Targeting - BIOS Example - $($(Get-Date).ToString(\"yyyyMMdd\"))\" `\n\t\t-Package 'Custom Tagging - Add Tags' `\n\t\t-Parameters @{key='$1';value=$(-join ($(Get-Date).ToString(\"yyyyMMdd\"),'-IPUTarget'))} `\n\t\t-Filter @(`\n\t\t@{sensor='Windows OS Type';operator='contains';value='workstation'},`\n\t\t@{sensor='Is Virtual';operator='contains';value='yes'},`\n\t\t@{sensor='BIOS Version';operator='lt';value='090009'}, `\n\t\t@{sensor='Online Random Sample';operator='contains';value='True';params=@(\"$biosSamplePercentage\")}) `\n\t\t-ActionGroup 'All Windows Workstations' `\n\t\t-Expiration 600\n<\/pre><\/div>\n\n\n\n contains = Return contains the supplied value\n notcontains = Return does not contain the supplied value\n startswith = Return starts with the supplied value\n notstartswith = Return does not start with the supplied value\n endswith = Return ends with the supplied value\n notendswith = Return does not end with the supplied value\n regex = Return matches the supplied regular expression\n notregex = Return does not match the supplied regular expression\n lt = Return is less than the supplied value\n notlt = Return is not less than the supplied value\n le = Return is less than or equal to the supplied value\n nle = Return is not less than or equal to the supplied value\n gt = Return is greater than the supplied value\n ngt = Return is not greater than the supplied value\n ge = Return is greater than or equal to the supplied value\n nge = Return is not greater than or equal to the supplied value\n eq = Return is equal to the supplied value\n neq = Return is not equal to the supplied value\n<\/pre><\/div>\n\n\n
\n## Pass the assembled Action object to the API to deploy the Custom Tagging - Add Tags package\n\n\t$biosObject.action = New-TaniumAction -Data $biosObject.actionObject\n\n\t## Sleep while package is deployed\n\n\tStart-Sleep -Seconds 300\n\n\t## Collect the results of the deployed Action\n\n $biosObject.actionResult = (Get-TaniumCoreActionResult -WebSession $Session -ID $($biosObject.action.id))\n<\/pre><\/div>\n\n\n
![\"\"](\"https:\/\/buildbreakautomate.com\/wp-content\/uploads\/2022\/04\/apiSeries3-03-actionDeployment.png\")
![\"\"](\"https:\/\/buildbreakautomate.com\/wp-content\/uploads\/2022\/04\/apiSeries3-04-actionDeploymentStatus.png\")
![\"\"](\"https:\/\/buildbreakautomate.com\/wp-content\/uploads\/2022\/04\/apiSeries3-05-customTagsAfterInvocation.png\")