Configure a File Content Check Control (Windows)

Configure a File Content Check control to check the content of a Windows file. You'll tell us which file you want to evaluate and what you're looking for. We'll return all lines in the file that match. Note that only first 40kb of results are returned in the output file.

You can specify your file location using any of the path types: Registry Key, File Search, File Path

Good to Know

Please note the following for Windows File Content Check UDC:

- This control is only supported for Cloud Agents, which means that this control will only be evaluated using agent scan data.

- The Windows File Content Check UDC supports only text files. It does not support binary or other files.

- File path can only be absolute path.

- Multiline regex is supported for this control.

- Policy reports include file name from evidence as a part of actual values.  If scan results is empty, the file name is not shown in the report.

- The Windows File Content Check UDC is supported on Windows Agent 4.0 and later

General Information

The statement you provide is like the control name that describes what it is and how it should be implemented in the environment. You'll also need to decide which category the control belongs to. This is important because users can search and filter controls by category, they can also search by keywords in the statement.

Scan Parameters

The scan parameters are used to gather data needed for compliance evaluation at scan time. You can specify your file location using any of the path types: Registry Key, File Search, File Path. Choose a file location option and make settings.

Jump to a section to learn more about the following options:

Use Registry Key

Use File Search

Use File Path

Data Type: The actual value returned for this control is a String List, meaning we'll return a list of matches in the scan results.

Description: The control description will appear in compliance policies and reports. If you change the description at a later time, the description will be updated for all controls that use the same set of parameters.

Control Technologies

Your control may apply to many technologies. Select each technology you're interested in and provide a rationale statement and expected value.

Time Saving Tip: If you plan to enter the same settings for each technology you only need to do it once. Make your selections in the "Default Values for Control Technologies" section first and then select the check box for each technology you want. You'll see that the settings get copied automatically to each technology that you select.

Make these settings:

Rationale - Enter a rationale statement describing how the control should be implemented for each technology.

Cardinality - Select a cardinality for the control. Tell me about cardinality optionsTell me about cardinality options

Operator - (View only) The operator "regular expression" is used to compare the results to the default value, which is specified as a regular expression.

Default Value - Enter the expected value for each technology as a regular expression following PCRE standard. This regular expression is used to perform the pass/fail evaluation of the returned results. A list of strings returned in the scan results will be compared to the regular expression using the selected cardinality. Note that if you selected the "empty" or "not empty" cardinalities, the Default Value field is disabled and no value is entered.

Note: The Actual value includes the file name as part of the values to identify  which value comes from which file. The file name is not used for evaluation. 

References

Add up to 10 references for the control. These may be references to internal policies, documents and web sites. For each reference, enter a description, a URL or both. When providing a URL, you must start the URL with http://, https:// or ftp://.  For example, enter http://www.qualys.com to link to the Qualys web site. Once added users have the option to include references in policy reports.

Use Registry Key

This option checks the registry key value.

Registry Hive: This is the registry hive containing the registry key to be evaluated. Select a value from the list, such as HKLM, HKCU, HKCR, HKU.

Registry Key: This is the registry key to be evaluated (e.g. SOFTWARE\MICROSOFT\.NETFRAMEWORK).

Registry Name: This is a required field and this contains the name of the value to be evaluated (e.g. INSTALLROOT).

File Path: File Path is optional and can be an empty string. If set, it should be a path relative to the key value (e.g. qualys\a.txt).

Example: As shown in the example below, if Registry Key value is C:\Program Files\Qualys and filename is test\a.txt , then entire absolute path to retrieve the matching reg context in file would be C:\Program Files\Qualys\test\a.txt  

Registry Hive: HKLM
Registry Key: Qualys
Registry Name: PreExistingPath
File Path: test\a.txt

Regular Expression: This identifies the contents you want to look for in a file. The regular expression retrieves the data from the asset and returns the matching data in actual value in report (e.g. .* ,  ^.OriginalRegex.*?*$)

Use File Search

File Search

Tell us where to start our search (the base directory) and what you want to match. You can search for files and/or directories.

Base Directory: The search starts from the base directory. Be as specific as you can to reduce the search time (there is a time limit), such as C:\Windows, %windir%\qualys

Depth Levels: Limits the depth of the directory hierarchy below the base directory that should be included in the search. Any files and subdirectories located below the specified depth value will not be accessed. The default directory depth is 3. The depth of 1 means evaluating contents of the base directory only. The maximum directory depth is 10.

File/Directory Name

File/Directory Name: Use these fields to find files and directories based on the name. You'll notice that * is used by default for the File Name Include and Directory Name Include, meaning that all files will be a match. Note - When entering a file name, be sure to include only the file name, not the path to the file. When entering a directory name, only include the directory, not a file name.

Include Name filter: This expression is used to match any file or subdirectory names that should be included in the search result analysis. If the include filter is not defined, the default include name filter is "*" which matches names of any file or a subdirectory. Example: "*.txt" include name filter should only return names with the ".txt" extension.

Exclude Name filter: This expression is used to match any file or subdirectory names that should NOT be included in the search result analysis. If the exclude filter is not defined, the default exclude filter should be set to empty value (""). Empty exclude name filter should not be applied to any search results. Example: include filter ".log", exclude filter "*system*". This combination of filters can be used to search all files or subdirectories with the extension ".log" except for any files or directories that have "system" as the part of their name.

Include and Exclude filters support multiple expressions. One expression should be separated from another with a delimiter. The delimiter value should be a comma (,) character. Example: include filter "*.exe,*.dll,*.zip" should match all names with the ".exe", ".dll", or ".zip" extensions.

Search Limits

Set the max search time and the max number of results to return. We'll stop the search as soon as we hit one of these limits.

Time Limit: The time limit defines a period of time in seconds after which the search must stop. The default value of the search limit is 300 seconds (5 minutes). The minimum search time limit is 30 seconds. The maximum search time limit is 900 seconds (15 minutes). Unlimited search time is not allowed.

Match Limit: The search match limit defines the maximum number of matches that the search may find before it is stopped. The default search match limit is 50 file system objects. The minimum search match limit is 1 file system object. The maximum search match limit is 256 file system objects.

Regular Expression

Regular Expression: This identifies content you want to look for in the file. The regular expression value can include up to 4000 characters.

Windows uses CRLF (\r\n at end of line) to handle end of line characters on all Windows platforms. The regular expression must follow the Perl Compatible Regular Expressions (PCRE) format. Learn more.

Note: While forming regular expressions for Windows file content check, make sure you use the following to get accurate results:

- use ^# to return matching text starting with #  

- use ^#.* to return entire line starting with #

Use File Path

File Path

File Path: File path is the path to the file which will be evaluated on the host. This can only be absolute path to the file (e.g. C:\Windows\qualys.txt , %windir%\test.txt).

Regular Expression: This identifies content you want to look for in the Windows file (e.g. .*)

Regular Expressions - Use Case Examples

Windows uses CRLF ( \r\n at end of line) to handle end of line characters on all Windows platforms. The regular expression must follow the Perl Compatible Regular Expressions (PCRE) format. Learn more.

Sample 1: Match multiple highlighted rows starting with pattern

sample content:

<security mode="Transport">
<transport clientCredentialType="None" proxyCredentialType="None" realm=""/>
</security>
<security mode="Transport">
<transport clientCredentialType="None" />
<tagToIgnore/>

regex:

<transport clientCredentialType="None".*?>

Sample 2: Match multiple highlighted rows

sample content:

<optionItem>
<description>Passive mode base port <port>, 0 means let system choose port.</description>
<name>Ftp.PassiveBase</name>
<clusterNode>UNSPECIFIED</clusterNode>
<value>20444</value>
<readOnly>true</readOnly>
<isDisabled>false</isDisabled>
<isSpecified>true</isSpecified>
<encrypted>false</encrypted>
<exportRules>
<exportRule>
<configuration>filedrive.conf</configuration>
<exportKey>passive-base</exportKey>
<exportPath></exportPath>
</exportRule>
</exportRules>
<isComposite>false</isComposite>
</optionItem>

regex:

Below regex is compatible with CRLF to match multiple highlighted rows in above sample.

\s?\n\<name\>Ftp\.PassiveBase\</name\>\s?\n\<clusterNode\>UNSPECIFIED\</clusterNode\>\s*?\n\<value\>20444\</value>

Sample 3: Match entire line starting or ending with a pattern

The regex has to be crafted carefully to match the pattern. This regex will only match "The" starting at the beginning of the line.

regex: "^The"

To return all lines starting with "The" . regex should be updated as shown below.

regex: "^The.*"

Sample 4: Return all lines starting and ending with below pattern

sample content:

This is an example!

incorrect regex: "^This.\!$"

Above regex will not return any matching results. In this case, the regex specifically looks for lines starting with "This" and ending with "!". As the file is created on Windows, it would have CRLF ending. In this case, regex would work only if "\r" would be taken care of. Updating the regex as shown below would return expected results.

correct regex: "^This.\!\r$"

Sample 5: Match the end of line

If the regex ends with \s*$ (to indicate any amount of white space including new line characters before the EOL) expected results are returned.

sample content:

This is a file

regex: " ^This.*\file\s*$":

Sample 6: Return all lines starting with below pattern in xml file

sample content:

<IIsConfigObject Location="/LM/SmtpSvc/1/EventManager" />
<IIsConfigObject Location="/LM/SmtpSvc/1/EventManager/EventTypes" />
<IIsConfigObject Location="/LM/SmtpSvc/1/EventManager/EventTypes/{59175850-E533-11D1-AA67-00C04FA345F6}" />
<IIsConfigObject Location="/LM/SmtpSvc/1/EventManager/EventTypes/{59175850-E533-11D1-AA67-00C04FA345F6}/Bindings" />
<IIsConfigObject Location="/LM/SmtpSvc/1/EventManager/EventTypes/{59175850-E533-11D1-AA67-00C04FA345F6}/Bindings/{609B7E3A-C918-11D1-AA5E-00C04FA35B82}" />
- <IIsConfigObject Location="/LM/SmtpSvc/1/EventManager/EventTypes/{59175850-E533-11D1-AA67-00C04FA345F6}/Bindings/{609B7E3A-C918-11D1-AA5E-00C04FA35B82}/DisplayName">

regex:

While creating a regex in Windows to match all the lines starting with "<IisConfigObject Location=", please keep in mind that whitespace at the end, new line characters, tabs and carriage returns must be handled correctly. A slight difference (even an extra space) in content would not match the regex if not handled properly.

regex: "<IIsConfigObject\sLocation =.*?\n\s*>"

regex:  "<IIsConfigObject?\sLocation?\s=.*?\s*>"