Instance Scan 101

 

Getting Started with Instance Scan

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.

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.

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

Instance Scan	Health Scan
The Checks/Definitions are mainly focussed around security of the instance. The Instance Scan is the driving force behind the Security Centre.	Has multiple hundred of checks. The Checks/Definitions are broader. They convey other critical components of the instance like performance, upgradibility, etc.
Sits on your Platform instance. It’s invocable whenever you need it at the granularity you need it	Runs outside of your environment and doing remote scanning of your platform based on your allowance
You can scan your instance as often as you want; as detailed as you want and run it on your leisure	It’s an external system that is run by SN. It connects to your instance and runs certain checks. And at the end you get a report from the SN company with all the goods and bads of your instance. Health Scan requires to have somebody from SN executing the scan
IMMIDIATE FEEDBACK	Need to wait for feedback from SN

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 elements

Instance Scan is basically an engine in the platform.

Elements (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 is 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. One of the entry points is the Dashboard which shows some stats of the last scan that you made:

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:

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():

This check runs against any scripts that matches the defined regular expression.

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.

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:

https://github.com/ServiceNowDevProgram/example-instancescan-checks 

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.

Top takeaways

1. Instance Scan can help ensuring the health of your instance
2. Custom checks allow to check for almost anything
3. 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:

• https://www.youtube.com/watch?v=gd5iGN3PWGw&ab_channel=ServiceNowCommunity
• https://www.youtube.com/watch?v=05z4XamuC3Y