Agent Policy

Introduction to Level 2 Rules

Policy File Editing

Customize the .NET agent's behavior by adding your own rules to the customerPolicy.xml file, which is located in C:\ProgramData\Contrast\dotnet\customerPolicy.xml. You can also override rules in the agent's built-in policy by adding a rule with the same method signature to the customerPolicy.xml file. This file won't be overwritten during agent updates.

NOTE Policy file editing is not currently supported on the agent deployed to Azure App Service.

File-Based Rules

The .NET agent detects vulnerabilities in your application configuration files as well as in JavaScript and ASPX files. You can disable rules that you no longer want the agent to detect.

The file-based rules are configured by changing the file-based-rules xml element. See the following sections for explanations of these rules.

  <file-based-rules>
    <client-side-technology-detection enabled="true" />
    <web-config-checks enabled="true">
      <authorization-settings enabled="true" />
      <custom-errors enabled="true" />
      <debug-compilation enabled="true" />
      <event-validation enabled="true" />
      <forms-auth-protected enabled="true" />
      <forms-auth-redirect enabled="true" />
      <forms-auth-ssl enabled="true" />
      <httponly-cookies enabled="true" />
      <http-runtime-version-header enabled="true" />
      <http-runtime-header-checking enabled="true" />
      <http-runtime-max-request-length enabled="true" />
      <http-runtime-cache-control enabled="true" />
      <membership-password-settings enabled="true" />
      <plain-text-connection-strings enabled="true" />
      <request-validation enabled="true" />
      <role-cookie-protected enabled="true" />
      <role-cookie-ssl enabled="true" />
      <session-rewriting enabled="true" />
      <session-timeout enabled="true" />
      <session-regen enabled="true" />
      <trace enabled="true" />
      <viewstate-validation enabled="true" />
      <viewstate-encryption enabled="true" />
      <wcf-replay-detection enabled="true" />
      <wcf-metadata enabled="true" />
      <wcf-exception-detail enabled="true" />
    </web-config-checks>
    <aspx-config-checks enabled="true">
      <debug-compilation enabled="true" />
      <event-validation enabled="true" />
      <request-validation enabled="true" />
      <request-validation-controls enabled="true" />
      <viewstate-encryption enabled="true" />
      <viewstate-encryption-mac enabled="true" />
      <trace enabled="true" />
    </aspx-config-checks>
  </file-based-rules>

Client-side technology detection

The .NET agent scans the CSS, JavaScript and ASPX files in your application to detect client-side technologies and JavaScript libraries such as JQuery, Flash and Silverlight. Set client-side-technology-detection to enabled="false" to remove these checks.

ASPX file security checks

Setting Explanation
debug-compilation Ensure page debug is not set to true"
event-validation Ensure postback event validation isn't disabled for the page
request-validation Ensure request validation isn't disabled for the page
request-validation-controls Ensure request validation isn't disabled for individual controls
viewstate-encryption Ensure viewstate encryption isn't disabled for the page
viewstate-encryption-mac Ensure viewstate mac isn't disabled for the page
trace Ensure tracing is turned off for the page

Config file security checks

The .NET agent scans your application's web.config or app.config files for various security issues. Set web-config-checks enabled to false to disable all checks. You can also disable specific rules by changing one or more of the options below.

Setting Description
authorization-deny If ASP.NET file-based authorization is used, ensure rules are not missing a deny-all rule, and don't allow all before a deny rule is present
custom-errors Check that a custom error page is defined
debug-compilation Ensure that the application isn't running in debug mode
event-validation Ensure that ASP.NET postbacks are validated
forms-auth-protected Ensure forms authentication cookies are validated and encrypted
forms-auth-redirect Ensure authenticated users cannot be redirected to other applications
forms-auth-ssl Ensure that forms authentication cookies use SSL
httponly-cookies Ensure cookies are HttpOnly
http-runtime-version-header Ensure ASP.NET does not send its version number to the client
http-runtime-header-checking Ensures that end-of-line characters in HTTP response are encoded to prevent header injection attacks
http-runtime-max-request-length Ensure HTTP Request size isn't too large (greater than 4096 bytes)
http-runtime-cache-control Ensure that Cache-Control:private header is sent on HTTP response
membership-password-settings Ensure that ASP.NET membership provider's password policy is secure
plain-text-connection-strings Ensure that database connection strings aren't stored unencrypted/in plain text
request-validation Ensure HTTP requests are validated
role-cookie-protected Ensure that role cookies are validated and encrypted
role-cookie-ssl Ensure that role cookies use SSL
session-rewriting Ensure session can't be rewritten
session-timeout Ensure session timeout isn't too long (> 30 minutes)
session-regen Ensure client can't regenerate expired sessions
trace Ensure ASP.NET tracing is disabled
viewstate-validation Ensure ASP.NET Viewstate validation is enabled
viewstate-encryption Ensure ASP.NET Viewstate is encrypted
wcf-replay-detection Ensure WCF replays are detected
wcf-metadata Ensure WCF service metadata can't be sent to the client
wcf-exception-detail Ensure WCF faults don't send detailed exception stack traces to the client

Response-Based Rules

The .NET agent will scan the response stream of your application for various security issues. You can disable some or all of these checks. Disabling all response-based checks will result in a small performance improvement for analyzed web applications.

  <response-based-rules>
    <full-content-analysis enabled="true">
      <clickjacking-controls enabled="true" />
      <form-autocomplete enabled="true" />
      <form-parameter-pollution enabled="true" />
    </full-content-analysis>
    <header-analysis enabled="true">
      <cache-controls enabled="true" />
      <http-insecure-auth-protocol enabled="true" />
      <httponly-cookies enabled="true" />
      <session-rewriting enabled="true" />
    </header-analysis>
  </response-based-rules>


Setting Description
clickjacking-controls Ensure that frame-breaking scripts or headers are present
cache-controls Ensure page caching is disabled with header or meta tags
form-autocomplete Ensure form controls have autocomplete disabled
form-parameter-pollution Ensure form tags prevent parameter pollution by including an action attribute
http-insecure-auth-protocol Ensure that insecure auth protocols (Basic or Digest) are not used
httponly-cookies Ensure cookies are HttpOnly
session-rewriting Ensure session cannot be rewritten because of cookie-less sessions

Source Rules

The .NET agent instruments your application code and follows user-provided data to detect potential security issues by marking all user-provided data - such as FORMS posts, web service calls or HTTP headers - as tainted. A potential security issue exists if tainted data isn't escaped safely before it gets to an output sink, such as HTML pages, databases or system commands.

  • Sources: Set methods whose return data should be tagged.
  • Tag-lists: Set methods that add tags to data as it flows through them. For example, you can tag data as "escaped" so it doesn't trigger a security finding.
  • Propagators: Instrument methods with more advanced syntax to control how data should be propagated through them. Unlike tag-lists, new tags aren't attached to this data.
  • Rules: Set output methods that check incoming data. Tags present on the data determine if a security finding is generated.

Source Rule Syntax

  <sources>
      ...
    <!-- HttpRequest Sources -->
    <method name="HTTP Request QueryString" signature="System.Collections.Specialized.NameValueCollection System.Web.HttpRequest.get_QueryString()" tags="cross-site" sourceType="parameter" />
    <method name="HTTP Request Form" signature="System.Collections.Specialized.NameValueCollection System.Web.HttpRequest.get_Form()" tags="cross-site" sourceType="parameter" target="R" />
    <method name="HTTP Request Method" signature="System.String System.Web.HttpRequest.get_RequestType()" tags="limited-chars" sourceType="uri" />
  </sources>

Method

method name="Name" signature="SIGNATURE" tags="TAGS" [enabled="ENABLED"] [sourceType="SOURCETYPE"]
  • SIGNATURE: Signature of the method to instrument.
    (Required)

  • TAGS: All data that is the return of a method specified here is tagged as "tainted". All tainted data triggers a warning if it makes it to a rule method, unless it has other tags added to it by a taglist method, which invalidate a rule. Besides the "tainted" tag, you can list additional tags in the tags attribute to automatically attach them to the data.
    (Required)

  • TARGET: Specify which part of the signature returns untrusted data. By default, this is R for "return object". You can also say O for "this object", and P0, P1, or P2 for first, second, or third parameter argument and so on.
    (Optional)

  • NAME: Unique name for this source (Optional)

  • SOURCETYPE: For better display in Contrast, list the origin of the untrusted data. The default is "other".
    (Optional)

    Possible values are:

    • parameter
    • header
    • cookie
    • querystring
    • uri
    • body
  • ENABLED: Add the enabled attribute and set it to "false" to disable the rule. The default is "true".
    (Optional)

Tag Rules

Tag Rule Syntax

<tags>
    ...
    <tag-list id="escapeForHTML" tags="html-encoded">
      ...    
      <!-- First parameter (P0) is the source and return object is the target to tag -->
      <method target="R" signature="System.String Custom.Web.EncodingUtility.HtmlEncode(System.String)" />
      <!-- Third parameter (P2) is the source and the return object (R) is target to tag -->
      <method target="R" source="P2" signature="System.String Custom.Web.EncodingUtility.HtmlEncode(System.Int32,System.Int32,System.String)" />
      <!-- First parameter (P0) is the source and second parameter (P1) is the target to tag -->
      <method target="P1" signature="void Custom.Web.EncodingUtility.HtmlEncodeToArray(System.String,ref System.Char[])" />
      <!-- First parameter (P0) is the source and is also tagged temporarily during the method -->
      <method target="P0" signature="void Custom.Web.EncodingUtility.HtmlEncode(System.String,System.IO.TextWriter)" scope="method" />
    </tag-list>
    ...
</tags>

Tag methods are organized in tag-lists under a single tag specified in tag-list's tags attribute. This tag should be used on the disallowed tags on Trigger method.

Method

On the method node, specify the data source and target.

 method target="TARGET" [source="SOURCE"] signature="SIGNATURE" [scope="TAG_SCOPE"] [enabled="ENABLED"]
  • SIGNATURE: Signature of the method to instrument.
    (Required)

  • TARGET: (Required) Use one of the following

    • R: Return object
    • P[Number]: Parameter reference (0-based). You can use P0for first parameter, P1 for second parameter, etc.
  • SOURCE: (Optional)

    • P[Number]: Parameter reference (0-based)
    • The default is P0. You can use P0for first parameter, P1 for second parameter, etc.
  • ENABLED: Add the enabled attribute and set it to "false" to disable the rule. The default is "true". (Optional)

  • TAG_SCOPE: (Optional)

    • lifetime: The target object is tagged for its lifetime. This is the default.
    • method: The target is only tagged during the tagger method, and reverts to its original state after the method exits.

Propagator Rules

Propagators are an advanced feature integral to correcting agent operation. Contrast highly discourages overriding any of the default propagators. You may need to add new propagators, although this scenario isn't fully supported. The syntax isn't very user-friendly because propagation is complex and propagator rule syntax is subject to change in future versions.

You can disable individual propagator rules in the customerPolicy.xml file. Add an override rule with the same signature, and set its enabled attribute as false.

Example:

   <propagators>
     <method signature="void System.Text.StringBuilder..ctor(System.String)" enabled="false" />
       ...
   </propagators>

Trigger Rules

Trigger rules specify methods whose incoming data should be checked for security issues. Any tainted data that doesn't have a proper escape tag allowed by the rule raises a finding that's sent to Contrast.

Trigger Rule Syntax

<rules>
  ...
  <rule id="reflected-xss">
      <pattern>
        <event>
          <method signature="void Acme.MyObject.Write(System.Web.TextWriter)" />
            <object tracked="true" required-tags="cross-site" disallowed-tags="html-encoded,url-encoded,js-encoded,custom-encoded,limited-chars" />
        </event>
        <event performPreMatchSubstring="true">
          <method signature="void System.Web.HttpWriter.WriteString(System.String)" />
          <params>
            <param index="1" tracked="true" required-tags="cross-site" disallowed-tags="html-encoded,url-encoded,js-encoded,custom-encoded,limited-chars" good-value-regex="^(ESCAPED.*)" startsWithTaint="true" />
          </params>
        </event>
      </pattern>
        <stack-blacklist>
          <entry>System.Diagnostics.Tracing.EventSource..ctor()</entry>
          <entry>System.Web.Security.Cryptography.SP800_108.DeriveKeyImpl()</entry>
        </stack-blacklist>
    </rule>
    ...
</rules>

Rule(s)

  • Pattern
    • Event(s)
      • Method
      • This Object
      • Return Object
      • Param(s)
  • Stack Blacklist
    • Entry(ies)

Rule: Rule id="ID" [enabled=ENABLED]

  • ID
    (Required)

  • ENABLED: Add the enabled attribute and set it to "false" to disable all rules with this ID. The default is "true".
    (Optional)

Pattern

Event

Each event element must have a Method sub-element and at least one of the following sub elements: This Object, Params, or Return Object.

  • event [className=CLASS_NAME] [enterOnly=ENTER_ONLY] [performPreMatchSubstring=PERFORM_PRE_MATCH_SUBSTRING]

    • CLASS_NAME
      (Optional)

    • ENTER_ONLY:

      • true: Evaluate trigger before the method code. Return value is unavailable.
      • false: Evaluate trigger after method code. This is the default.

      (Optional)

    • PERFORM_PRE_MATCH_SUBSTRING:

      If "true", the trigger is evaluated on a subset of first parameter where the second parameter is starting index and third parameter is subset length. Method source must be param with index=1. The default is "false".

      (Optional)

Method

  • method signature="SIGNATURE" [enabled=ENABLED]

    • SIGNATURE: Signature of the method to instrument
    • ENABLED: Add the enabled attribute and set it to "false" to disable the rule for this signature. The default is "true".

    (Optional)

This Object:

  • object [required-tags=REQUIRED_TAGS] [disallowed-tags=DISALLOWED_TAGS] [tracked=TRACKED] [startsWithTaint=STARTS_WITH_TAINT] [good-value-regex=GOOD_VALUE_REGEX]

    • REQUIRED_TAGS: Trigger finding if all of these tags are present.
    • DISALLOWED_TAGS: Don't trigger finding if any of these tags are present.
    • TRACKED: Object must be already tracked to trigger finding. The default is "false".
    • STARTS_WITH_TAINT: If true, the source must start with tainted data. The default is "false".
    • GOOD_VALUE_REGEX: If the source matches the following regex, the finding isn't triggered.

    (Optional)

Return Object

  • return [required-tags=REQUIRED_TAGS] [disallowed-tags=DISALLOWED_TAGS] [tracked=TRACKED] [startsWithTaint=STARTS_WITH_TAINT] [good-value-regex=GOOD_VALUE_REGEX]

    • REQUIRED_TAGS, DISALLOWED_TAGS, TRACKED, STARTS_WITH_TAINT, GOOD_VALUE_REGEX: same as in "This Object" (see above)

    (Optional)

Params

  • params [connector=CONNECTOR]

    • param index="INDEX" [required-tags=REQUIRED_TAGS] [disallowed-tags=DISALLOWED_TAGS] [tracked=TRACKED] [startsWithTaint=STARTS_WITH_TAINT] [good-value-regex=GOOD_VALUE_REGEX]

      • CONNECTOR:

        • and: Trigger finding only if all parameters are satisfied
        • or: Trigger finding if any parameter is satisfied. This is the default.
          (Optional)
      • INDEX:

        • 1-based index of the parameter
        • REQUIRED_TAGS, DISALLOWED_TAGS, TRACKED, STARTS_WITH_TAINT, GOOD_VALUE_REGEX: same as in This object, see above
          (Required)

Stack Blacklist

If the trigger method contains one of these methods in its stack trace, the finding will not be satisfied.

  • stack-blacklist

    • entry SIGNATURE

      • SIGNATURE: Signature of the of method to instrument for stack blacklist.
        (Required)