A node is used to represent virtually anything with an IP address or a single cloud entity. Nodes are scanned by our platform and configuration discovered, allowing for the tracking of changes, rich configuration differencing and for policies to be created which describe a nodes desired state.

Detected vs. Monitored

Monitored nodes are nodes that are actively being scanned, potentially with policies or benchmarks assigned to them. A list of currently monitored nodes can be seen by navigating to Discover > Monitored. These are the nodes you will have most contact with day to day and when referring to a node in most contexts we are referring to a monitored node.

Detected nodes are nodes that your UpGuard Core instance has become aware of via an integration sync (such as from AWS, Azure or GCP), a CSV upload, or from automated node discovery via scanning the network. Think of the detected nodes list as a sort of staging area or inbox for all the possible nodes you may or may not want to monitor. A list of detected nodes can be found by navigating to Discover > Detected. Nodes here can either be left in a staging or detected state, be promoted into being regularly monitored, or be deleted.

The important differences between detected and monitored nodes is shown below.

  Detected Monitored
Can be scanned No Yes, either on a schedule or by clicking the scan button.
Can have policies and benchmarks run on them. No Yes
Can be assigned an Environment No Is assigned to one environment - the Default environment by default.
Can be assigned to a Node Group No Can be assigned to one or many node groups.
  Can be promoted to being monitored. Cannot be moved back to a detected state.
Counts towards Node License Count No Yes

Discovery, Detected, Monitored Workflow

The Detected Nodes page is designed to be a buffer between all the possible nodes and devices you could be monitoring and the actual curated list of nodes that you are actually monitoring. If you have an auto-sync job scheduled to run against you AWS, Azure or GCP accounts, in particular, you’ll notice that the list of nodes you want to monitor can grow and shrink on a daily basis.

The best usage of the detected page is as follows:

  • Create integrations into your sources of nodes, like your AWS account for example.
  • Configure your assets in these sources to be sync’d and detected on a regular schedule.
    • Sync’d nodes that are already being monitored will remain so and be noted down as pre-existing nodes,
    • Sync’d nodes that are already on the detected page will remain so and be noted down as pre-existing nodes,
    • Sync’d nodes that are completely new will be added to the detected page and reported as new,
    • Any nodes identified as new, but failed to sync are also registered in the sync job,
    • Sync job results can be viewed by navigating to Control > Job History.
  • On a regular basis, review your list of Detected Nodes and action nodes like you would with an email inbox, by either deleting, leaving or promoting to being monitored.
  • When promoting nodes to being monitored, you will need to assign them to an Environment and optionally to an initial Node Group.

When promoting nodes from detected to monitored you may also need to add in a little extra information to allow them to be scanned. For example, we are able to detect your EC2 instances, but for obvious security reasons we cannot automatically detect how you would SSH or WinRM into these instances to scan them. Detected nodes that are missing information required to scan will have a notification icon next to them informing you of what information is missing before a scan can be attempted. Hovering your mouse pointer over the icon will list settings that are missing. Here we’ve detected an EC2 instance, which happens to be named Arch Linux, but we haven’t been able to reliably detect it’s inner operating system, nor do we know the username that is required to log in.


When promoting this node to being monitored, you will need to edit the node’s settings to fill in these details.

Monitored Node List

The node list provides an overview of your UpGuard environment, as well as serving as a launch pad for most of UpGuard’s functionality. The node list can be accessed via Discover > Monitored.

Status Summary Bar

The summary bar gives a quick count of the total number of nodes in a given node group, any failing nodes and a count of unmanaged nodes. Failing nodes are those that are failing to scan, as per the most recent attempt (as opposed to a node that is scanning, but potentially failing applied policies). An unmanaged node is a node that has no policies applied to it. Below we are viewing the node totals for the All Nodes node group which happens to contain all nodes currently being monitored.


Colored Bars

The colored bars on the far left-hand side indicate the status of the most recent scan: Red indicates an exception, black indicates a connectivity failure and no bar indicates success.


Hovering over the node name will give you more detailed status information. This is particularly useful for erroring and offline nodes.


To display a list of all failing nodes, type =scan_failure into the search bar at the top of the monitored nodes page and press enter. To view all offline nodes, type =offline into the search bar and press enter.

Multi-Select Functionality

Hovering over the node’s name will also reveal a checkbox that facilitates multi-select functionality. This can be used to difference the selected nodes, add the selected nodes to a node group or create a new node group from the selected nodes. You can also run an ad-hoc node scan on the selected nodes or bulk edit their common properties.


Compare Two Nodes

After selecting a node from the node list, you can compare that node to another by following these simple steps.

  1. Choose to select Another Node from the Compare to section on the left of the graph. compare-two-nodes-01

  2. Select the node from the list presented in the pop-out. compare-two-nodes-02

  3. You can also filter the list down to exactly what you are looking for. compare-two-nodes-03

  4. Then simply hit the compare button next to the node to go to the comparison view. compare-two-nodes-04

Here, blue configuration items represent items that only exist on the first node (or the original node selected), dark grey are items that only appear on the second node (the compared to node) and yellow items show configuration items that exist on both nodes, but have different attributes.

If you forget which node is which, refer to the key at the top of the graph.


You can also narrow down which type of differences you want to display and it is often useful to hide all Common items so you can focus only on the differences. To select which types of differences to display, locate the Display section on the left panel and toggle the types of differences you want to display or hide.


Comparing Historical Scans

You can use the current diff tools to compare a node scan from one node to a node scan from another node. To do so, select two nodes within a node group, then click the Diff 2 nodes button.


This will load up a difference between the most recent scans of the selected nodes. To compare historic scans of either node, locate the dropdowns in the left sidebar to select scans in the Compare to section. The diff view will change based on the scans selected via either the Scans for and Compare to dropdowns.


Using File Differencing

File differencing is only possible for files specifically listed in your Scan Options. i.e.: You must enter the full path to the file in the Scan Directories field of the Scan Options. eg:


This indicates to UpGuard that you want the full contents of the file scanned, not just a checksum of the contents. For more information on file scan options, please visit our guide on Files and Directories on the Scan Options page.

Now when a change is detected with the contents of the specified file you will get the option to see a side-by-side File Diff of the changes. You can also do side-by-side differencing against the same file on another machine.

Other Methods of File and Directory Differencing (Linux and Windows Only)

If you are particularly interested in differencing directories, files and file contents in a more focused way you can create a set of Linux Directory or Windows Directory nodes. When adding a Linux Directory node you specify the SSH details of the host that a particular directory or file exists on, and the Directory Path you would like to scan. For Windows Directory nodes you can either connect to a remote machine via WinRM, or install an agent on the machine hosting the directory itself.

Some file scan option examples of paths are:

Description Linux Example Windows Example
Scan a single file /etc/hosts %windir%\system.ini
Scan all text files in a specific directory /home/username/phd/*.txt C:\Users\admin\logs\*.txt
Scan all conf files in all directories under /etc /etc/**/*.conf -
Scan all ini files in all directories under C:\Windows\System32 - C:\Windows\System32\**\*.ini

Since a Directory node consists only of files and directories, differencing nodes of this type attempts to line up files for comparisons that have the same path and filename. Some common use cases and methods for differencing pairs of files are listed below.

Difference two identically named files on different devices

You can achieve this using a normal linux or windows scan, comparing the two nodes and then, if file content has been selected to be returned for each file, view the content difference between these nodes. However, you can also difference files in this situation using the Linux Directory and Windows Directory node types.

For example:

Compare /etc/hosts between prod01 and prod02

  • Add one Linux Directory node with the SSH details of prod01 and set the Directory Path to be /etc/hosts, then
  • Add another Linux Directory node with the SSH details of prod02 and set the Directory Path to be /etc/hosts.
  • Scan each node and compare the scans.

Differencing two files that exist on the same node

You may also want to difference two files that exist on the same node. Usually differencing nodes will not align files with different names for scan comparison as it treats them as separate configuration items. However, you can align these differently named files for comparison with the use of variables.

For example:

Compare /etc/one.conf with /etc/two.conf, both on prod01

  • Add a node called “one” with Directory Path /etc/{{ node_name }}.conf and SSH details of prod01, then
  • Add another node called “two” with Directory Path /etc/{{ node_name }}.conf and SSH details of prod01.

Here, {{ node_name }} is used as one of the built in variables that is substituted for the actual name of each corresponding node during a node scan. The results of these scans can be compared using a node difference view because the variables are only expanded when the scan takes place, not when results are being viewed. That is, /etc/{{ node_name }}.conf on the first node will align with /etc/{{ node_name }}.conf on the second node, even though during the node scan for each of these nodes, the resulting path will be slightly different when the node_name variable is expanded.

Note also, that you could have named each of these nodes /etc/one.conf and /etc/two.conf and just set the Directory Path to be {{ node_name }}.

Ad-hoc differencing of two files that exist on the same node

The example above shows how you can difference two files on the same node in a structured manner that allows proper change reporting and group differencing capabilities between 2 or more files. If, however, you want to quickly compare the content of two files collected as part of a single node scan you can access the difference view from the scan items page.

Given two files that have the View Raw File option available, to compare, click on the first file to bring up the file details in the right panel. Then right-click on the second file and select Compare With Selected. This will load the file content comparison view with the selected file contents compared with the second file’s contents.


Group Differencing

The ability to compare configuration items across multiple nodes in your environment is critical in uncovering and understanding inconsistencies. Classic scenarios where we see this functionality prove to be absolutely critical is in comparing nodes in a cluster (where an assumption exists that all nodes are like configured) or in comparing nodes that can be grouped by certain like characteristics or functionality such as by operating system or role.

Performing a Group Diff

To perform a group diff navigate to Discover > Monitored and select the nodes that you are interested in performing a group difference against. Once multiple nodes are selected, a Diff X Nodes button will appear which will allow you to perform a group diff.


The resulting node scan concensus output will be generated.




The presentation of this data has been inspired by using the Raft election metaphor. When comparing configuration that is the same across all nodes in a group diff, more consensus can be achieved about “what is the same”. This appears as a grey or lighter orange square. Similarly, if a given configuration item is different on each node (such as a package version) less consensus can be achieved and a brighter orange square appears.

What is then surfaced and highlighted are the configuration items that are inconsistent.


What Next?

For more information on organizing nodes into Environments and Node Groups, please view our guides on Environments and Node Groups, respectively.