Skip to content

Scan Settings

Scan Configuration Overview

There are four configuration adjustments you can make to the Scanning Agents: Tag Name changes, Matching File handling, Scan Engine choice and decisions around which objects to scan (Scan list / Skip list). These Scan Behavior Settings modifications will apply to all agents currently running and new ones that spin up going forward no matter the region. Changes made here will not require a reboot for any agent, but could take 30 seconds to take affect. Such as, custom naming the tags we apply to each object as well as providing scan list and skip list functionality for the buckets.

Scan Settings

Note

These are global changes and therefore it is not currently possible to create different behavior by region or group.

Object Classification Tag Keys

Every file the s3 scanner touches has an AWS Tag applied to it. You can change the default key names if required or desired, but not the values.

Object Tagging

Key                             Description
classification-result Identifies whether a file is found to be nonmatching or having issues. Possible values: NonMatching, Matching, Unclassifiable, Error
  • NonMatching = no issues found with file
  • Matching = classified data found;
  • Unclassifiable = object is password protected or non-text
  • Error = access to object issues: KMS permissions, cross account permissions, bucket policy blocking, other
date-classified The date and time the object was scanned
Error Message A description of what has been identified in the file. Only populated for Error or Unclassifiable results.
classification-matches What classification rule(s) matched

Note

AWS allows an object to have only 10 tags applied to it. At most we will add 4 tags (for matching files) and only 2 tags for non-matching files. If you have a number of tags on your object already, we will trim the number of tags we add to ensure none of the existing tags are dropped. If only 1 tag is available for example, we will write only the classification-result tag onto the object.

Scan and Skip Lists

Buckets themselves are inherently skipped by the fact they are turned off to start. When you enable a bucket for scanning, you are explicitly marking it to be scanned. When you do this and nothing else, then all objects in the given bucket will be scanned no matter the path inside the bucket. This portion is all handled from the Bucket Protection page.

The Classify List and Classify Skip List located here inside the Agent Configuration page allows you to take this concept a step further by allowing you to apply it to paths (folders) within the buckets. Scan listing and skip listing are opposites of one another. Scan listing a path is explicitly marking that specific path(s) within that bucket to be scanned. All other paths within the bucket will be ignored. You can list as many paths within the bucket as you'd like. For example, you have 5 different paths within the bucket and you want to scan only 3 of them. Simply add the 3 you want scanned to the Scan List. There is no need to add the other 2 paths to the Skip List as they will automatically be skipped. Skip listing a path will stop that defined path(s) from being scanned, but leave all others to be scanned. Depending on how many you want to include versus exclude you can choose which list to leverage. From the previous example, you could have just Skip listed the 2 paths you didn't want to scan which leaves the other 3 to be scanned. With numbers that split you could go either way, but if you have a much larger number of paths, one may become more self-evident.

Special Scan / Skip List Capabilities

The root of the bucket is also a "path" that we define in the settings as an empty path. So, if you'd like to scan or skip list the root along with your paths you can do so.


You can use a wild card (*) in the path. This is useful in a repeated sub-path structure where you need to skip a certain folder amongst all those top level folders.

For example, you have a path structure that is Year/Month/scanMe and Year/Month/skipMe where the month reflects each month of the year creating 12 unique paths. Underneath that Month folder you have folders you want scanned or skipped. You can create a path one time to setup scanning in every Month folder like this: Year/*/scanMe. That path will scan the scanMe folder under every month in the bucket without you having to add 12 entries.

This could also be leveraged not just in the path, but down to the object name as well. If you only wanted to scan a certain file type in a given bucket/folder you could put a path with *.jpg.

Note

As you can see, but wasn't spelled out, the * does not mean everything at the level it is placed and below. If you wanted everything underneath Year you could place a path /Year/ and that would do absolutely everything below Year. The wildcard represents the level itself where it is placed only.


Similar to wild cards an often used with wild cards, you can specify a global entry or your Scan and Skip Lists. If you have a repeated path structure across all your buckets where being able to define a scan / skip entry that would apply to all, you can select the _GLOBAL_ option in place of a bucket to then define across all buckets.
Global Scan List example

Let's take a look at an example. The following is an S3 bucket with 4 paths (folders) in it. With the default settings, meaning no paths defined, the root and all 4 folders will be scanned. AWS S3 Bucket

First thing you need to do is enter the <bucket name> in the Scan List or Skip List field and click Add Scan list.
Scan list - Add Bucket
You'll get:
Scan list - Result
Next, you'll add the path you want to scan and click the Add Entry button. *This can be the full multi-depth path. Scan list - Add Path

That's it. You've now identified that the only thing you will scan in the css-protect-01 bucket will be the scan-me folder and nothing else. The steps above can be used for skip listing as well. Look below at the examples.

Scan list and Skip list Empty

Scan list

Skip list

Scan list and Skip list Rules

Note

You probably wouldn't have a scan list and a skip list entry for the same bucket as we see in this example, but it is possible and I'm sure a scenario could be found to support it.


Last update: May 20, 2022