Simplification of REST API baseline creation

Customizations
1

BigFix is considering simplifying the creation of baselines via the REST API by simplifying how baseline components are specified.

Currently, when creating a baseline via the REST API, each baseline component must include a lot of fields: action script, relevance, source id, action name, etc.

Using the Console, only a fixlet/task needs to be selected.

We want the REST API to behave more like the Console in this regard, and only require specifying the fixlet/task.

Here’s an example to show off what we’re thinking: The below XML will currently make a baseline via the REST API. Notice the many required fields.

<?xml version="1.0" encoding="UTF-8"?>
<BES xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="BES.xsd">
	<Baseline>
		<Title>baseline title</Title>
		<Description />
		<Relevance>true</Relevance>
		<BaselineComponentCollection>
			<BaselineComponentGroup>
				<BaselineComponent Name="Custom Fixlet_001" IncludeInRelevance="true" SourceSiteURL="http://dw001:52311/cgi-bin/bfgather.exe/actionsite" SourceID="36" ActionName="Action1">
					<ActionScript MIMEType="application/x-Fixlet-Windows-Shell">// Enter your action script here</ActionScript>
					<SuccessCriteria Option="OriginalRelevance"></SuccessCriteria>
					<Relevance>true</Relevance>
				</BaselineComponent>
			</BaselineComponentGroup>
		</BaselineComponentCollection>
	</Baseline>
</BES>

Below is a mock-up of how we’re currently thinking of simplifying it. Notice that only the REST API URL is required for the fixlet.

<?xml version="1.0" encoding="UTF-8"?>
<BES xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="BES.xsd">
	<Baseline>
		<Title>baseline title</Title>
		<Description />
		<Relevance>true</Relevance>
		<BaselineComponentCollection>
			<BaselineComponentGroup>
				<BaselineComponent Resource="https://dw001:52311/api/fixlet/master/36" />
			</BaselineComponentGroup>
		</BaselineComponentCollection>
	</Baseline>
</BES>

What do you all think?

@grlucche @jgstew @leewei @mschwarz: I believe that you four have experience with REST API baseline creation, so it would be great to get your feedback.

4 Likes
2

I prefer the sourcedfixlet action model, provide the source site and source fixlet and call it a day.

The resource url is a kind of weird thing to have to provide – ideally we’d just provide the source site and source fixlet.

Bill

2 Likes
3

Thank you for the feedback!

Could you please elaborate more on why providing a URL for a baseline component is weird?

4

As far as I can tell there is no other part of the the REST API that uses the resource url for anything (according to the BES.XSD Legacy Communities - IBM TechXchange Community )

The closest example is a sourced fixlet action which uses the sitename and FixletID

Though to be honest, asking for the resource URL is so many lightyears ahead of having us rip out every component of the fixlet that anything is better than how it is right now.

Can we get some mechanism to sync the baseline as well without having to re-grab all of the baseline components again?

3 Likes
5

I would second this.

The Resource URL seems to be specific to XML that is in the BESAPI.xsd schema, so mixing it into the BES.xsd schema seems like it would get a little ugly. Additionally the Resource URL has traditionally been a bit wonky, since sometimes the URL does not actually link to the location of the resource (for example with baselines), so I am not 100% comfortable with that until the URLs are a bit more consistent.

The Sourced Fixlet style seems like it would be a bit more consistent with the existing style of BES.xsd. Plus then you would be able to specify the default action as well. I have included a suggested format below, with a different baseline component tag to make it more clear that this is a different type of component. One problem with this style is that you could theoretically specify another baseline as a sourced fixlet, and I am not sure what would happen then.

<?xml version="1.0" encoding="UTF-8"?>
<BES xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="BES.xsd">
	<Baseline>
		<Title>baseline title</Title>
		<Description />
		<Relevance>true</Relevance>
		<BaselineComponentCollection>
			<BaselineComponentGroup>
				<SourcedBaselineComponent IncludeInRelevance="false">
				        <SourceFixlet>
				                <Sitename>My Site</Sitename>
				                <FixletID>1234</FixletID>
				                <Action>Action1</Action>
				        </SourceFixlet>
				</SourcedBaselineComponent>
			</BaselineComponentGroup>
		</BaselineComponentCollection>
	</Baseline>
</BES>

While we are at it, could we clean up the way we interact with Baselines through the REST API? As of 9.2.7 it has been pretty weird.

  • Make POST, GET, PUT, DELETE /api/baseline/... work for creating baselines instead of having to use /api/import/.. and /api/fixlet/...
  • Provide some single resource location to re-synchronize baselines, for example POST /api/baseline/custom/sitename/1234/resync
2 Likes
6

You guys are correct that resource URLs are not applicable to the BES.xsd schema, and we’re not proposing to mix the schemas. Damien’s example was a bit misleading in this regard, but the input to the baseline API would actually be from the BESAPI.xsd. The important distinction here is that BES.xsd must be natively importable by the Console as a .bes file (and via the Import function), but BESAPI schema only applies to the REST API. So this enhancement would be specific to REST API creation and not require core BES schema changes.

Maybe a better question is: do you generally do API-based baseline manipulation using session relevance to get the components or direct queries of REST API resources?

2 Likes
7

@steve I typically use both relevance queries and restapi queries to solve problems. When using the RESTAPI to do things like build baselines and invoke actions, I try to avoid using hard IDs or source URLs. This is because I have a test and production Bigfix environment, so I want to be able to write a script once and be able to target both environments using only fixlet and site names.

I do this by using my BES and BESAPI XML as a template and injecting values using a DSL. For example, here is what I do when I want to target a specific Computer Group on both test and production environments:

<Target>
  <CustomRelevance>exists true whose (if true then (member of group ${group("Important Windows Computers Group").id} of site "actionsite") else false))</CustomRelevance>
</Target>

I do a similar thing for building Baselines. Below is an example that looks up fixlets based on site and fixlet name using relevance, grabs the fixlet content using RESTAPI, formats it as a BaselineComponent and injects it into a baseline XML template:

<BaselineComponentGroup>
    ${toComponent(site("My Site").fixlet("My Fixlet 1"))}
    ${toComponent(site("My Site").fixlet("My Fixlet 2"))}
</BaselineComponentGroup>

And for resynchronizing baselines, I read the original baseline, extract the source URLs of the components, retrieve their content using RESTAPI and rebuild the relevance of the baseline by attempting to emulate the formatting of Bigfix, using relevance queries to look up Computer Group numbers etc:

1 Like
8

I’m posting the below on behalf of @mschwarz, who emailed the below to me but was unable to post it to the forum at this time.

1 Like
9

Thanks for the feedback everyone! @steve and I have been in discussion and we’re thrilled to see what we can do for you all.

Another Question for You All

Both the REST API URL and the two attributes {site, id} each uniquely identify the fixlet. However the REST API URL has the added benefit that it clearly indicates how to retrieve a representation of the fixlet, which can be quite useful for less experienced users.

So from that perspective, the URL has the advantage.

However, we’re wondering, is it significantly more difficult needing to provide the URL?

10

In my experience, the Resource URLs were often incorrect and were specified using HTTP instead of HTTPS when retrieving a resource. Then when you would try the URL as is, it wouldn’t work without rewriting the URL to use HTTPS instead. This may have been resolved in newer versions of BigFix, I haven’t checked recently.

Ideally you would be able to specify a Fixlet/Task for inclusion in a baseline using EITHER the URL or the site/fixlet in combination.

I also like the way the sourcedfixlet action works currently, and baselines could follow a similar method.

Also, Ideally, as many fields as possible would be optional with the defaults assumed. So the default action would be used if one exists, otherwise no action would be selected unless specified, same as in the console. (We create some fixlets and tasks without a default action on purpose to prevent them from being accidentally used in a baseline without extra effort)

I use a combination of Session Relevance, REST API resource queries, and other code to determine which things to add to a baseline, but the most common for me is probably session relevance. I have never worked with the resource URLs in session relevance, so I don’t know how easy they are to grab.

For me, the most common case is I just have a bunch of fixlets/tasks and I just want to shove them all into a baseline.

2 Likes
11

Good day! I’ve found this thread based on my desire to automate baseline creation.

When going to perform patch updates via BigFix’s provided fixlets, I baseline together all relevant fixlets from a particular site and then add them to a new baseline.

I have not done this yet programmatically. My question at this point is: Is the XML simplification still being considered, and if so, is there an estimate on it going into production at this time?

Also I would also add the URL seems less intuitive than a fixlet/site combination, but as @jgstew mentioned ideally both would be available.

12

I definitely already have a lot of stuff that automates baseline creation with the REST API. @jgo also has a program based upon some of my work.

See here: Automatic Baseline Creation and eventually AutoPatching

I currently have full auto patching solutions in place for specific applications, including Firefox, Skype, and iTunes, with more to come. I stepped back from OS patching because it was more complicated to handle as a first step and there was more benefit to gain from automating the software patches.

The way it works is the newest patches for each application are found using session relevance if and only if all of the current patches are not already contained within a baseline. The baseline XML is then generated with another session relevance statement with a check added to prevent the baseline from being run on a system where the application is opened. Another relevance statement is added to cause the baseline to be deployed progressively to endpoints so not all get the update at once. The previous baseline is stopped and the new baseline is started. The baseline waits for the target application to be closed on the targeted systems before running.

The automation is achieved entirely through a combination of session relevance and REST API calls, so there is no external logic, which means it can be automated through any language or function that can make REST API calls.

Related:

2 Likes
13

3 posts were split to a new topic: REST API for Baseline Creation