Session Relevance SMBIOS vendor & serial_number

OriPall · July 20, 2023, 1:55pm

I’ve been looking around for information and testing various things but am stumped. I started working with BigFix just over a month ago so still learning things.

Using session relevance or REST API (which I’ll be using), how can I get all computers that do not have a setting, value or set date for two different custom settings and return the following information for them?

Name of it (computer name, this is simple)
value of vendor of structure “bios_information” of smbios
value of serial_number of structure “bios_information” of smbios

Getting the vendor and serial_number information in WebReports is easy to do but I can’t figure out how to put together the correct session relevance. At the same time, I can work with and figure out client relevance fairly well by now but session relevance is being more difficult for me.

I get an error that bios and smbios are not defined and cannot find out how to proceed here.

The following is something I used to get computers with a specific active directory path and returning a few properties, I’m not sure who created the original version of this which I copied and was able to modify to my needs, maybe JasonWalker, but credit goes to them.

I’ve modified the computer filter section to something that may work as a client relevance, but it may need fixing too.
The first two set of properties in the end need to be modified to get the vendor and serial_number, but as mentioned, I’m stumped on how.

(name of item 0 of it|"missing Name", 
(if (size of item 1 of it = 1) then ((if it = "" then "False" else it) of concatenation ";" of values of results (item 0 of it, elements of item 1 of it)) else ("False")),
(if (size of item 2 of it = 1) then ((if it = "" then "False" else it) of concatenation ";" of values of results (item 0 of it, elements of item 2 of it)) else ("False")) 
of (elements of item 0 of it, item 1 of it, item 2 of it) 
of (set of BES computers whose (
((not exists setting "Property1" of it) OR ((not exists effective date of it) OR (not exists value of it) as string) of it) 
OR 
((not exists setting "Property2" of it) OR ((not exists effective date of it) OR (not exists value of it) as string) of it)
), 
set of bes properties whose (name of it as lowercase = ("Property1") as lowercase), 
set of bes properties whose (name of it as lowercase = ("Property2") as lowercase))

Assistance with this would be much appreciated.

Thanks,
Pall

trn · July 20, 2023, 3:15pm

You are mixing up both client & sesion relevance and properties & settings

You can query client properties directly from session relevance (although it doesn’t feel particularly snappy it does get the results)

A simple sample:

	(
		name of it | 
		(
			"ID: " & id of it as string 
		)
		| "No Name" , operating system of it | "No OS" , 
		(
			value of it as string | "Default" 
		)
		of client setting 
		whose
		(
			name of it = "_BESClient_Comm_CommandPollIntervalSeconds" 
		)
		of it 
	)
	of bes computers 
	whose
	(
		exists client setting 
		whose
		(
			name of it = "_BESClient_Comm_CommandPollEnable" 
		and
			value of it = "1" 
		)
		of it 
	)

JasonWalker · July 20, 2023, 5:13pm

First off, welcome to BigFix, and I’ve gotta say that I’m impressed you’re already digging in to Session Relevance. This is usually something new BigFixers manage to avoid for at least the first few years of using the product, and I hope some of this helps you get started.

There are several concepts to work through here. I started writing a much longer response, but I can see now I need to turn that into a blog post a training session instead. I’ll give a couple of basics here about how to discover what’s possible in Session Relevance, and then I’ll jump straight into your specific ask.

First, if you aren’t using the Console Presentation Debugger while you’re working through this, I highly recommend it. See Open the BigFix Console Presentation Debugger for how to add the Debug menu to the Console and use the Console Presentation Debugger to test out Session Relevance.

Session Relevance runs in the Server/Web Reports, not on the endpoints themselves. It can only retrieve the things that clients have previously reported. So, you can’t do things like “read a registry value”; what you can do is to create an Analysis that the clients process to read the registry value, which gets reported as a ‘bes property result’ and then this result can be queried in Session Relevance.

There are basically two ways to figure out “what can I query”. The first is to read through the references at developer.bigfix.com . There we can use the Relevance → Inspector Search function to search for ‘bes computer’, and find the reference at https://developer.bigfix.com/relevance/reference/bes-computer.html showing everything that can be retrieved from a bes computer. The other is to use Introspection - relevance constructs that ask questions about the relevance language itself. Some common instrospection queries are things like

properties

properties of type "bes computer"

types

properties whose (it as string contains "setting")

A couple of screenshot examples:

We can see in that last one that a ‘bes client setting’ in Session Relevance is not quite the same thing as a client setting in Client Relevance. For one thing, there’s no ‘effective date’ property of a bes client setting, so you just can’t query that part at all, unless you were to create a Custom Property that reports the effective date from the client.

I don’t know if you actually have a client setting that’s being set based on the Serial Number. I don’t. And we don’t have a single default property that returns that (we have separate Analyses for Windows, Mac, UNIX, etc. that retrieve serial numbers, but it’s complicated that those are separate Properties/Analyses based on OS type)

(name of it, name of source analysis of it | "Global", name of site of source analysis of it | "Global") of bes properties whose (name of it as lowercase contains "serial")

Serial Number - VMWare Workstation, VMWare Workstation Information (Windows), BES Inventory and License
Serial Number - Mac OS X, Hardware Information (Mac OS X), BES Inventory and License
OSD Serial, Bare Metal Target Information, OS Deployment and Bare Metal Imaging
profile serial info, PowerVM LPAR Overview, Server Automation
serial adapters Refactored, PowerVM VIOS Overview, Server Automation
profile serial info, PowerVM VIOS Overview, Server Automation
Serial Number, Device Attributes Analysis, BESUEM

Likewise we don’t have a single ‘Vendor’ property either.
So what I would do is to create a new Analysis to retrieve these from the client. Again, checking the introspectors on the client side, I’ve retooled your Client Relevance pieces a bit. ‘serial_number’ doesn’t come from ‘bios_information’, it comes from ‘system_information’ of smbios. I’ve also added a default of “None” if the machine does not have an smbios or the smbios is missing those structures. Some of my virtual machines are running under ProxMox, a KVM-based virtualization platform, and don’t provide some of the SMBIOS properties so this is something I can actually test -

q: value "vendor" of structure "bios_information" of smbios as string | "None"
A: LENOVO
T: 2.019 ms
I: singular string

q: value "serial_number" of structure "system_information" of smbios as string | "None"
A: PF1PAL4Z
T: 1.816 ms
I: singular string

Next I create an Analysis to retrieve these:

It’s fairly easy now to retrieve the results of one of the properties. Filter to the ‘analysis name’ and ‘property name’ to ensure I’m not duplicating any of the other ‘smbios’ properties I happen to have created already (I have several in my deployment) -

(name of computer of it, values of it) of results of bes properties whose (name of source analysis of it = "smbios information" and name of it as lowercase ="smbios vendor")

rhel8-sv1.domain.home, SeaBIOS
WEBUI, EFI Development Kit II / OVMF
OSD, EFI Development Kit II / OVMF
BES-ROOT, EFI Development Kit II / OVMF
BFC, EFI Development Kit II / OVMF
WIN11, EFI Development Kit II / OVMF
BFI, EFI Development Kit II / OVMF
WIN2022-TEST1, EFI Development Kit II / OVMF

(name of computer of it, values of it) of results of bes properties whose (name of source analysis of it = "smbios information" and name of it as lowercase ="smbios serial number")

rhel8-sv1.domain.home, None
WEBUI, None
OSD, None
BES-ROOT, None
TESTMACHINE01, None
BFC, None
WIN11, None
DC, None
BFI, None
WIN2022-TEST1, None

Notice in my small lab, the first query returned 8 results and the second returned 10 (though all of them are the default ‘None’, because all of these were ProxMox VMs that don’t have serial numbers in SMBIOS). The problem there is that between running the first query and the second, two more computers reported in.
This highlights one problem - if a computer has not reported a result, it gets dropped when looping ‘bes property results’. There’s not an indication that the computer is skipped

So, instead of using the ‘results of bes property’ to create the results, we need to find a different creation class. One that loops through every computer and can tell us whether one is missing. That’s were we look instead at results (bes computer, bes property) as a creation class, because we can tell whether or not it exists. But now that my computers have reported in, I don’t have that case anymore so I’ll artificially change the relevance on this analysis to ‘windows of operating system’, just so my Linux machines will get dropped out of the results and I can demonstrate that for the next few queries.

This time I’ll loop through all of the ‘bes computers’ and just retrieve whether it is reporting a result for the new ‘smbios serial number’ property:

(name of item 0 of it, exists results (item 0 of it, item 1 of it)) of (bes computers, bes properties whose (name of source analysis of it = "smbios information" and name of it as lowercase ="smbios serial number"))

rhel8-sv1.domain.home, False
WEBUI, False
WEBUI, True
OSD, True
BES-ROOT, True
TESTMACHINE01, True
BFC, True
WIN11, True
DC, True
BFI, True
WIN2022-TEST1, True

We can loop through that and check both properties

( 
    name of item 0 of it
  , exists results (item 0 of it, item 1 of it)
  , exists results (item 0 of it, item 2 of it)
) of (
    bes computers
  , bes properties whose (name of source analysis of it = "smbios information" and name of it as lowercase ="smbios serial number")
  , bes properties whose (name of source analysis of it = "smbios information" and name of it as lowercase ="smbios vendor")
)

rhel8-sv1.domain.home, False, False
WEBUI, False, False
WEBUI, True, True
OSD, True, True
BES-ROOT, True, True
TESTMACHINE01, True, True
BFC, True, True
WIN11, True, True
DC, True, True
BFI, True, True
WIN2022-TEST1, True, True

Here, my rhel8-sv1 is not reporting (because it’s not relevant to the analysis), and one instance of my two computers named ‘WEBUI’ is not reporting (because it is offline). But that gives us good test cases for ‘computer has not reported the property’.

We can now retrieve the value if it has been reported, and a ‘Not Reported’ if it has not:

( 
    name of item 0 of it
  , (if exists results (item 0 of it, item 1 of it) then values of results (item 0 of it, item 1 of it) else "Not Reported") of it
  , (if exists results (item 0 of it, item 2 of it) then values of results (item 0 of it, item 2 of it) else "Not Reported") of it
    ) of 
(
    bes computers
  , bes properties whose (name of source analysis of it = "smbios information" and name of it as lowercase ="smbios serial number")
  , bes properties whose (name of source analysis of it = "smbios information" and name of it as lowercase ="smbios vendor")
)

rhel8-sv1.domain.home, Not Reported, Not Reported
WEBUI, Not Reported, Not Reported
WEBUI, None, EFI Development Kit II / OVMF
OSD, None, EFI Development Kit II / OVMF
BES-ROOT, None, EFI Development Kit II / OVMF
TESTMACHINE01, None, EFI Development Kit II / OVMF
BFC, None, EFI Development Kit II / OVMF
WIN11, None, EFI Development Kit II / OVMF
DC, None, EFI Development Kit II / OVMF
BFI, None, EFI Development Kit II / OVMF
WIN2022-TEST1, None, EFI Development Kit II / OVMF

Now, I see in your original query you were trying to use ‘set of bes properties’. That’s a really good thing, and I’ll try to explain it here but brolly33’s post at Efficient Session Relevance Query for Computer Properties may do a better job of explaining it.

When we build a query like

(
        bes computers
      , bes properties whose (name of source analysis of it = "smbios information" and name of it as lowercase ="smbios serial number")
      , bes properties whose (name of source analysis of it = "smbios information" and name of it as lowercase ="smbios vendor")
    )

what happens internally is what we call a ‘cross product’. Basically, this behaves like a nested loop that matches every item 0 against every item 1 and every item 2. Think of it as

for each bes computer
   for each bes property
       if bes property does not match "smbios serial number"
            next
       for each bes property
            if bes property does not match "smbios vendor"
                 next
            return bes computer, bes property 1, bes property 2

For every bes computer, we loop through the list of every bes property and see whether it matches the first property we’re looking up (smbios serial number). If this isn’t the correct bes property, we drop the result and try the next computer. For the second bes computer, we repeat that lookup of every bes property. Eventually we find the right property to match item 1, and then we start looping through every bes property again to find the one that matches item 2.

On a small scale this is pretty fast. But the slowest part of the query is looking up the right bes properties, and that lookup is repeated for every computer, so this query gets slower the more computers we add.

By introducing the use of ‘set’, what we can do is run each of those slow lookups only once. This is because a ‘set of bes computers’ is treated as a single item; the lookup for ‘item 1’ then, only executes one time to retrieve the ‘smbios serial number’ property. We return that property as a ‘set of bes properties’ again, and because a ‘set’ is still just one instance, our second lookup for ‘item 2’ to retrieve the ‘smbios vendor’ property only executes one time.

(
           set of bes computers
          , set of bes properties whose (name of source analysis of it = "smbios information" and name of it as lowercase ="smbios serial number")
          , set of bes properties whose (name of source analysis of it = "smbios information" and name of it as lowercase ="smbios vendor")
        )

( since we expect there’s only one ‘smbios serial number’ property and one ‘smbios vendor’ property, we could have skipped using ‘set of bes properties’ for each of those. But retrieving also the properties as a ‘set’ allows for better error handling later - if the ‘item 1’ set has a size of zero, we could say the property doesn’t exist; if the ‘item 1’ set has a size greater than one, we could say that there are duplicate properties with the same name, etc.)

Just to get some comparison timings on this, counting the number of results:

number of
    (
        bes computers
      , bes properties whose (name of source analysis of it = "smbios information" and name of it as lowercase ="smbios serial number")
    )

takes 435 milliseconds to run on my small deployment. Adding the second property adds more time -

number of
(
    bes computers
  , bes properties whose (name of source analysis of it = "smbios information" and name of it as lowercase ="smbios serial number")
  , bes properties whose (name of source analysis of it = "smbios information" and name of it as lowercase ="smbios vendor")
)

takes 835 milliseconds on my small deployment. That’s doubled - and will continue to double every time we add another property to the lookup.

By contrast, retrieving each item as a ‘set’, and then unwinding the values of each set, is much faster. This query runs in 78 milliseconds - more than 10x faster, and the difference would get larger as more computers and more property lookups are added.

number of
(
 elements of item 0 of it
 , elements of item 1 of it
 , elements of item 2 of it
) of
(
    set of bes computers
  , set of bes properties whose (name of source analysis of it = "smbios information" and name of it as lowercase ="smbios serial number")
  , set of bes properties whose (name of source analysis of it = "smbios information" and name of it as lowercase ="smbios vendor")
)

Retrieving the results, or noting the results have not been reported, then all wraps up into this much more efficient query that finishes in 85 milliconds on my small deployment:

(
 id of item 0 of it
 , name of item 0 of it | "ComputerName Not Reported"
 , (if exists results (item 0 of it, item 1 of it) then values of results (item 0 of it, item 1 of it) else "Not Reported") of it
 , (if exists results (item 0 of it, item 2 of it) then values of results (item 0 of it, item 2 of it) else "Not Reported") of it 
) of 
    (
     elements of item 0 of it
     , elements of item 1 of it
     , elements of item 2 of it
    ) of
    (
        set of bes computers
      , set of bes properties whose (name of source analysis of it = "smbios information" and name of it as lowercase ="smbios serial number")
      , set of bes properties whose (name of source analysis of it = "smbios information" and name of it as lowercase ="smbios vendor")
    )

9024435, rhel8-sv1.domain.home, Not Reported, Not Reported
10369450, WEBUI, Not Reported, Not Reported
10545704, WEBUI, None, EFI Development Kit II / OVMF
11635830, OSD, None, EFI Development Kit II / OVMF
539193122, BES-ROOT, None, EFI Development Kit II / OVMF
550537096, TESTMACHINE01, None, EFI Development Kit II / OVMF
551784780, BFC, None, EFI Development Kit II / OVMF
1080793101, WIN11, None, EFI Development Kit II / OVMF
1085519785, DC, None, EFI Development Kit II / OVMF
1612964630, BFI, None, EFI Development Kit II / OVMF
1618041656, WIN2022-TEST1, None, EFI Development Kit II / OVMF

I know that’s a lot to take in, and there’s a lot more that I could write on this, but I think you should take some time on this and then let me know where you have some difficulties. I’m planning to write at more length later in either a blog or training material so your feedback helps, don’t hold back!

JasonWalker · July 21, 2023, 1:53pm

This video may be helpful too…it has only basic Session Relevance itself, but gives a great overview of getting started, and describes several different tools for using Session Relevance, like the Excel Connector, Session Relevance Tester, and the Web Reports QNA page

OriPall · August 23, 2023, 1:05pm

Sorry I’m late to reply.

@trn, thank you for assisting me towards the right track and for your example which I’ve noted down as a quick template to use and modify when I need

@JasonWalker, thank you for providing such extensive information. I was able to use the information that you provided, which, again, is extensive, to learn and understand how this works better and solve the problem I was having.