Automating Instance Scan (API's, Spokes)

Hi there,

Another article on automating Instance Scan?! Yes 🙂 In previous articles I already explored how to automate Instance Scan within the same Instance, and a way of automating triggering an Update Set scan on another Instance. Though there's more! While watching the weekly "Creator Toolbox" series with Chuck Tomasi and Andrew Barnes, they shared a Docs page which amongst others listed API's for "Healthscan". Wait, what, Healthscan? Shouldn't this be Instance Scan? While searching myself, I found some interesting documentation that is hardly mentioned anywhere.

API's

While I should have looked at the Docs first 🙂 I jumped right into an Instance and opened the REST API Explorer. There's a Namespace available for "sn_cicd". When selected, I noticed an API Name that starts with Instance Scan: "CICD Instance Scan Execution", interesting! The methods available:

Most of the methods are pretty straightforward to get going. Just a target_table, a target_sys_id, things like that. All work like a charm, no Docs needed for this! These methods would open possibilities to start executing Update Set scans, Application scans, Point scans, etcetera.

Execute scan with suite on scoped apps (POST) / Execute scan with suite on update sets (POST)

Two methods though, need a bit more explanation to get going: "Execute scan with suite on scoped apps" and "Execute scan with suite on update sets". When simply providing the suite_sys_id and executing you will encounter on both a "500 Internal Server Error" message a Response Body:

{
    "result": {
        "status": "3",
        "status_label": "Failed",
        "status_message": "Invalid Request Body",
        "status_detail": "",
        "error": ""
    }
}

Now we do have to look at documentation 🙂 The Docs does mention providing "app_scope_sys_ids" as Request body parameter for "Execute scan with suite on scoped apps". With the Builder Request Body within REST API Explorer, it's not possible to get this working unfortunately. This is because "app_scope_sys_ids" should be provided in JSON format. Using the Raw Response Body though… just copying the example from the Docs page won't work, the { } are missing, so here you go:

{
    "app_scope_sys_ids": ["134450a0b3781300787162ac16a8dc1e", "1ee91295db352010cc6a85184b9619e4"]
}

For "Execute scan with suite on update sets" the usage is similar. Instead of "app_scope_sys_ids" it's just "update_sets_sys_ids". So for example:

{
    "update_sets_sys_ids": ["fac9de55db352010cc6a85184b961944", "e5af801c2ffb6010cd5dd99df699b6cd", "cdeda2cb0b203200cbf38ee337673a2d"]
}

Spokes

So now we can use the API's in Business Rules, Script Includes, etcetera. Though what about Flow Designer? Are we going to create Actions for this? Or can we create a Spoke? Or might there even already be Spokes available? While exploring the Actions list within Flow Designer I noticed Application "Continuous Integration and Continuous Delivery (CICD) Spoke"! Three Instance Scan related Spokes are already out-of-the-box available:

This looks promising, just drag and droppable Spokes which you can use within Flows and Subflows, easily configurable. I just accidentally came across these, while these are actually documented mentioned on the Docs, they only made it hard to find.

When using for example the "Instance Scan Execute Point Scan" Spoke, the only thing to configure is:

Missing spokes

Looking at the out-of-the-box REST API Methods available, it does look like some Spokes are missing:
- Instance Scan Execute Scan with Combo;
- Instance Scan Execute Scan with Suite on Scoped Apps;
- Instance Scan Execute Scan with Suite on Update Sets.

Who knows, maybe these will be added with Rome, or San Diego? Because I can't wait, I will build these myself and share these in the next two or three weeks.

Recap

And that's it! Just sharing documentation, API's and Spokes which are buried, and adding some knowledge gained about gaps in the documentation. Knowing these API's and Spokes are available, automating Instance Scan shouldn't be a tough job to realize!

---

And that's it, hope you like it.

Kind regards,
Mark
2020-2021 ServiceNow Community MVP
2020-2021 ServiceNow Developer MVP

---

LinkedIn