Instance Scan 101
Getting Started with Instance Scan
Underused but Powerful Tool
"I think Instance Scan is probably one of the underused features of ServiceNow, and it's so powerful and useful.
If you've worked in 'Software dev teams' (E.g. Teams whom are building web apps in ReactJS, etc) then lint scans and security scans are the norm before deployments, however I see this less often in the ServiceNow space and this is where Instance scan can help you.
[...] in short, it lets use scan Scoped Apps, individual files, and Update Sets, amongst others.
This is a huge time saver, if you are constantly reviewing code before release and I would encourage you to spend 1 hour today looking at it, it's saved me weeks of effort."
Concrete Use Case
Instance Scan is highly relevant to the peer review process that every organization should have.
Instance Scan is a powerful tool for covering all our checks and checklists. In fact, it holds the potential to automate the peer review process entirely.
By integrating Instance Scan into your workflow—especially through the AEMC CI/CD pipeline—you unlock a level of efficiency and control that’s hard to achieve otherwise. It truly gives your process wings you never had before.
Read more here:
Why Instance Scan
As you develop code, the Instance Scan can help you to:
- Identify errant patterns and warning signs
- Codify best practices by writing checks
- Pursue and uphold quality standards
Additionally, instance scan can help us to enforce coding guidelines. Instead of manually using a coding guideline we can use instance scan to look into our code based on coding guidelines. Remember: the more capabilities you have on SN to customize/develop things, the more important is to have coding guidelines so that developers and implementors would have to consider these guidelines carefully when doing their implementations or customizations.
Basically, Instance Scan takes your instance to the Next Level!
Definition of Instance Scan
The instance scan is the little brother of health scan. The central entrypoint of the instance scan are:
- Checks
Refer below the definitions of the different check types. By default, SN ships a few hundred checks in your instance. But you can also create checks by yourself. Refer bellow to the Public GitHub Repo to see some example checks you can build by yourself.
Instance scan is comparable to ATF where tests are organised in suites. Simarlely, in instance scan checks are organised in suites as well, like files are organised in folders.
Remember:
- Automated Test Framework = Does it work
- Instance Scan = Is it done up to our standards
One of the interesting suite is the Instance Security Hardening Settings with a number of checks that all circle around the security configuration of your instance.
Instance Scan vs Health Scan
The underlying idea of both tools is to allow developers and implementers the possibility to get early warnings of what they are doing wrong. Essentially, both systems have the goal to uphold the developers and implementers to the quality standards you set out.
Even though the underlying workings are the same, these two tools are focusing on different topics:
- instance scan: focusses more on security system properties and possibility impact on the platform
- health scan: focusses more on finding vulnerabilities and scans against bad coding practices
Note: there’s a tool called Instance Troubleshooter that adds additional checks/defnitions to the instance scan checks. You can download it from the store.
Note2: by now the health scan checks should be incorporated in the instance scan.
Another Level of Quality Control
Instance Scan complements the Automated Testing Framework (ATF) to bring additional layers of quality enforcement to your testing and hardening process.
Instance Scan sits in-between developing and testing. Its purpose is twofold:
- To validate the code base that you have implemented
- To harden your application as you deploy it into your instance stacks
Example: you develop a custom app or a catalog item; use instance Scan to check for vulnerabilities and best practice violations; test what you developed with ATF.
Instance Scan Features
- Powerful Scan Engine
- Process Records / Data
- Upgradeability / Performance / Security / Manageability / User Experience
- 260+ Scan Checks
- Possible to Add Self Scan Checks
- Manual Scanning / Scheduled
- Check Suite / Applications / Update Sets / Point Checks
Instance Scan Components
Instance Scan is basically an engine in the platform.
Components (Suite & Check)
Instance Scan looks similar to ATF (test framework). You have the most granular object: a check; which in ATF is a test. Checks represent a definition of bad practice which runs against records in your instance. Additionally, you can build or group checks into suites. Suites can be hierarchical. You have the freedom to define what kind of checks you want to execute at a given moment in time. You can also automate these suites as part of your deployment process.
For example, once you can close an update set you can select when you execute a scan - if it should run on:
- The whole platform
- A scoped app
- The update set
Point Scan
Additionally, you can run a point scan on a bespoke object.
For example: you can execute a point scan on a script include to see if it’s coded on best practices.
Check Types
There are various check types. Choosing the right type of check for the job is key to success with Instance Scan.
There are four different check types that you can execute.
Table Check
The most fundamental one is the table check, which checks if a certain record exists on the specified table.
- Iterates all records on the specified table (i.e., incident, change, problem...) which match the filter conditions
- Unless a script is used, will generate a finding for every record matching the filter conditions
- Has an advanced option to allow scripting, but does not need a script
- Provides the engine.current object, which is a GlideRecord of the row currently being scanned
Best for:
- Enforcement based on a class of records, such as BRs or script includes
Not suitable for:
- Data spanning multiple unrelated tables in separate hierarchies
For example, you can scan for a property including a value.
Column Type Check
The column type check scans through three different column values of a specific data type, such as scriptm XML, or HTML. These are typically used in widgets, UI pages, service portal areas, or script.
- Finds all columns in the database which match the specified type, and iterates the values of those columns from every row
- Script must be used in order to generate findings
- Provides the engine.columnValue object, which is the string value of the column currently being scanned
Best for:
- Group Checks together that are performed at the same time
Not suitable for:
- Checks represent a definition of bad practice which is executed against records in your instance
For example, if you select column type check for JavaScript, the check will run on every script field that is in the platform. So, the scan will go through BRs, script includes, client scripts, etc. to run that particular check against all those existing scripts.
Script-only Check
The script-only check executes a standalone script irresptice of any particular data set. Benefit: a lot of flexibility. Caveat: you don’t know what you’re checking. It’s not like the point scan.
- Executes an independent script once, rather than iteratively over some underlying data set
- Scripting is required for this type of check
- Script-only checks cannot be run as part of targeted scans (such as scanning a scoped app or an update set) because their relevance cannot be determined
- Should be used as a last resort due to difficulty of use and lack of performance optimization
Best for:
- Enforcement based on singular calculations such as aggregate queries or API calls
Not suitable for:
- Policies based on data that lives anywhere in the database
Note: don't understestimate the power of script-only check though.
In this article you can find a few examples on how to use script-only checks.
Linter Check
The linter check executes a linter based check on your JS code. This is the most advanced check, which helps you to assess the code by for instance removing the unnecessary comments.
- Fundamentally the same as a Column Type Check, but only applies to script columns
- Provides an abstract syntax tree (AST) via the engine.rootNode object
- Currently challenging to use, and requires advanced knowledge of Mozilla Rhino AST structure
- Will be enhanced to provide a more user-friendly experience in a future release
Note: this article is based on Rome version.
Best for:
- Advanced JS parsing to identify function calls and construction of scriptable classes or script includes
Not suitable for:
- Anything else
For example, if you’re looking for a certain API call (i.e., js.log() statement, which you don’t want to have in production), the column type check will probably find it in the commented area, whereas the linter check fill find it in the code base itself. So, the latter is more advanced.
What They All Have in Common
Regardless of type, all checks share the following qualities:
For more info about instance scan have a look at this resource:
- https://www.servicenow.com/community/developer-blog/400-articles-blogs-videos-podcasts-share-projects-experiences/ba-p/2292127
How to use it
Instance scan is an app in the app navigator:
On the right, you can to drill down by different categories:
This is the management overview that you can get from the instance scan.
Checks
As mentioned above, the most important parts of the instance scan are the checks or definitions:
You can group by class to see the how many checks there are within different classes or definitions:
Examples of type of checks:
One interesting example of a table check is the Tables without ACLs:
If you create custom tables and don’t configure any ACLs on them then this is something that is considered as a security risk. Because you don’t control access to these tables. So, every table should be secured by ACLs.
Regarding a linter check example, the Cache flushed as part of scripts is a good one:
Linter checks are more complex than the table checks. But similarly important to run.
An example of column check is - Scripts should not contain gs.now():
.png)
This check runs against any scripts that matches the defined regular expression.
Suites
Scan Suites are Group Checks together that are performed at the same time:
When to you run an instance scan
You can of course do it ad-hoc or immediate, without previous planning. That’s one approach.
The more important one is when you want to deploy something after a sprint for example - as you’re going to a testing phase. That is when you want to test the package that you want to deploy. This is something you can do manually, i.e., click Test Check and get the results instantly. However, a better alternative is to build a flow and use the SN CICD spokes to trigger the instance scans. That’s a more secure and professional approach. Basically, it’s better to automate this step via a flow.
Another great time to run instance scans is during the clone or upgrade process. For example, when moving to an upgrade, you can paire instance scan just the same way as you would pair ATF. So, when you are about to gro through the upgrade process, take a fresh clone of the PROD instance to a sub-prod instance. Run your ATF and instance scans there to establish the baseline for where you are right now. Then perform that upgrade. And then run the same ATF and instance scans again to see how the upgrade may have positively or negatively affected either of those scans (ATF and instance scan). That is another good time and place to insert instance scan into your SN lifecycle processes.
Where to run checks
Assuming you have a classic three-tier landscape (Dev - Test - PROD), it is recommended to run the point scans (kinda like unit testing) on DEV. The deployment package is recommended to run on TEST env.
You have also the option to schedule a check suite. More specifically, you can schedule it against the full instance; against one or multiple scoped app(s); or against one or multiple update set(s):
Which types of checks to run in PROD
Instance scan doens’t modify any data. For certain scenarios it could definitely make sense to run them in PROD. For example, you want to check how many active records you have in a table or certain sytem property settings or credential settings for integrations, etc. But be cautious.
However, instance scan checks are not limited to security only. They also include things that may effect performance. Instance Troubleshooter is purposely build to run performance checks on PROD or at least PROD clone. So, performance and security types of items can totally be run in PROD.
Important note: it’s important to document the findings you’ve collected in order to have a better understanding of the impact they have on the system. And then remediate accordingly. Not all findings need to turn into a change!
So, what to do with a finding which is not valid, or that is false positive or just something went wrong?
- In that case you can mute it which means we marked that object. You’re not going to report it on the next you run the scan on the same instance.
- The other option you can do is to add a task to it. The task could be a story, INC, etc. The goal of the task is to have somebody else to fix that. You can also sync that task with other tools (i.e., Jira) you’re doing your development on or where you want to put it in the backlog.
Public GitHub Repo
For more example checks, check out this repo:
That repo is just a community hub to collect ideas on how to implement certain checks.
Note: it’s your responsibility to review any of those checks to see if they are good fit for your org and otherwise you can adjust them for your own practices.
Process for Handling Scan Findings
The process for handling scan findings is fairly straightforward.
Once you receive the scan results along with the associated findings, you can review each finding individually and create a scan task for it. These scan tasks allow you to manage findings in a structured way—similar to how you would handle incidents or problems using incident tasks or problem tasks.
Alternatively, if a finding is not relevant or should be excluded from future scans, you have the option to mute it. Muted findings will be excluded from subsequent scan runs, helping to reduce noise and focus on actionable issues.
Recommendation
Inspired by Mark Roethof’s tutorial on Instance Scan, I think it would be valuable to consider creating two separate Check Suites to validate both best practices and core instance features.
- One suite could be called Core Instance Check Suite, focusing on validating essential platform configurations and behaviors.
- The second could be the Best Practices Check Suite, aimed at enforcing development and configuration standards.
This separation would help us better organize our checks and make it easier to maintain and scale them over time.
Top takeaways
- Instance Scan can help ensuring the health of your instance
- Embed it into your way of work process
- Custom checks allow to check for almost anything
- Check ServiceNow Store and Community for ideas on what to check for
That’s a wrap!
For more practical stuff, check out my next article.
Source:
More resources to learn from:
- How to implement the instance scan process
- Enforcing Best Practices and Development Standards for your admins
- Unrevealing Instance Scan and sharing parts of the undocumented
- Ideas on embedding Instance Scan into your way of working
- [Video] de ServiceNow Instance Scan voor een gezonde goed presterende en veilige ServiceNow omgeving
Comments
Post a Comment