Manual Chapter : Writing Custom Bot Signatures

Applies To:

Show Versions Show Versions


  • 17.1.1, 17.1.0, 17.0.0, 16.1.4, 16.1.3, 16.1.2, 16.1.1, 16.1.0, 16.0.1, 16.0.0, 15.1.9, 15.1.8, 15.1.7, 15.1.6, 15.1.5, 15.1.4, 15.1.3, 15.1.2, 15.1.1, 15.1.0, 15.0.1, 15.0.0, 14.1.5, 14.1.4, 14.1.3, 14.1.2, 14.1.0
Manual Chapter

Writing Custom Bot Signatures

About custom bot signatures

If your organization has additional needs for bot defense, you can write a
custom bot signature
to identify web robots by looking for specific patterns in the headers of incoming HTTP requests.
Bot signatures are similar to attack signatures; they are written using a limited subset of allowed keywords. You can design custom bot signatures to handle emergency situations, to support security policy enforcement unique to your networking environment, or to provide an analysis of specific activity on the network.
Being able to classify bots into different classes allows you to treat each class differently. You can report, block, or do nothing when a signature matches a malicious or trusted bot class. Further, malicious and trusted bots fall into more specific bot signature categories that can be handled as needed. You can create new categories if they are needed to classify custom bot signatures.

Bot signature syntax limitations

Bot signatures are developed using Snort syntax to search for bots in either the User-Agent field of the header or the URL, or both. The User-Agent field is examined to identify the browser and operating system. The URL is searched to locate bots that access specific peculiar URLs within a site, regardless of whether the site has such a URL (in most cases it does not).
The syntax of bot signatures is similar to that of attack signatures using the general format
keyword: "value"; modifier;
but bot signatures can include only the following attributes:
  • uricontent
    flag is not allowed)
  • headercontent
    flag is mandatory)
  • ipp
    (for regular expressions)
  • offset
  • depth
  • nocase
The following are not allowed in bot signatures:
  • negation
  • norm
    (normalization is predefined)
  • distance
  • within
Refer to the
Signature Options
Signature Syntax
, and examples for additional details on the syntax used in bot signatures.

Creating a custom bot signature

You can write custom bot signatures to increase bot protection for your web application.
  1. On the Main tab, click
    Bot Defense
    Bot Signatures
    Bot Signatures List
  2. Click
    The Bot Signature Properties screen opens.
  3. In the
    Bot Name
    field, type a unique name for the bot signature.
    If you attempt to create a custom bot signature with the same name as a system-supplied signature, you will receive an error and the signature will not be created.
  4. Select a bot category for the signature.
  5. In the
    setting, develop the bot signature.
    1. If the bot signature will search for patterns in the user-agent string or URL, use
      Simple Edit Mode
    2. If searching the user-agent string, for
      , select either
      match, and then type the pattern in the text box.
    3. If searching requests within the normalized URI path (excluding the Query String), for
      , select either
      match, and then type the pattern in the text box.
    If a bot signature requires multiple search strings, a conditional text match, or a search of both the URL and User-agent contexts, you cannot use the simple edit mode.
    To develop more complex bot signatures, use the
    Advanced Edit Mode
    to type expressions using Snort control. Refer to the
    Signature Options
    Signature Syntax
    sections for details. Refer to
    Bot signature syntax
    for special limitations when writing bot signatures.
    As an example, this signature searches the header for three terms: SODA, BAR, and for a specific hexadecimal value.
    headercontent:\"SODA\"; useragentonly; nocase; headercontent:\"BAR\"; useragentonly; nocase; headercontent:\"0x31303235343830303522\"; useragentonly; nocase;
    In this example, the bot signature searches both User-Agent and the URL:
    headercontent: "MaliciousBot/0.1"; useragentonly; uricontent: "/settings.php";
  6. In the
    field, type the name of one or more domains from which the bot can send its requests, and click
    This field is mandatory only for benign bots in the Search Engines category to validate their identity using reverse DNS lookup.
  7. For the
    setting, select a risk level.
    The risk level indicates the level of potential damage an attack containing this text may cause, if it were successful.
  8. Click
    to create the new bot signature.
The new bot signature is added to the bot signature list. The signature is now available for use in your Bot Defense Profiles. After associating your Bot Defense Profiles with a virtual server, the system examines traffic for bots (using the signature you developed plus others that are enabled) as one of the first checks.

Creating a new bot signature category

You can create customized bot signature categories if the default categories do not include the one you are looking for. You can create a new malicious or benign bot category.
  1. On the Main tab, click
    Bot Defense
    Bot Signatures
    Bot Signature Categories List
    The Bot Signature Categories List screen opens.
  2. Click
  3. Enter the new bot signature category name and select a bot class for the new category.
  4. Click
    to save the new bot signature category on the system.
The bot signature category is added to the appropriate list. If you create a customized bot signature, you can assign the category you created to that signature.