Manual Chapter : Writing Custom Attack Signatures

Applies To:

Show Versions Show Versions

BIG-IP ASM

  • 12.1.6, 12.1.5, 12.1.4, 12.1.3, 12.1.2, 12.1.1, 12.1.0
Manual Chapter

Writing Custom Attack Signatures

About custom attack signatures

Custom attack signatures are those that your organization creates and adds to the attack signature pool. Custom attack signatures must adhere to a specific rule syntax. They are never updated by F5 Networks. All user-defined signatures are carried forward as-is when the system is updated to a new software version.

You can develop custom attack signatures, if needed, for specific purposes in your environment. The signatures that you define are stored in the attack signatures pool along with the system-supplied signatures. You can also export and import custom signatures to and from other Application Security Manager™ systems.

Note: Developing custom attack signatures is an advanced feature only needed in specific cases.

Creating a custom attack signature

Custom attack signatures can handle security policy enforcement unique to your networking environment, emergency situations, or analysis of specific activity on the network. If your organization has a need for a custom attack signature, you can create one using the F5 attack signature syntax.
  1. On the Main tab, click Security > Options > Application Security > Attack Signatures .
    The Attack Signature screen opens.
  2. Click Create.
    The Create New Attack Signature screen opens.
  3. In the Name field, type a unique name for the attack signature.
    Note: If you attempt to create a customized attack signature with the same name as a system-supplied attack signature, you will receive an error and the attack signature will not be created.
  4. In the Description field, type an optional description of the signature.
  5. For the Signature Type setting, select Request or Response to determine whether the new signature applies to client requests or server responses.
  6. For the Systems setting, select from the Available Systems list any systems to which the new signature applies, and move them to the Assigned Systems list.
  7. For the Attack Type setting, select the type of threat that the new signature protects against.
  8. For the Rule setting, type a rule according to the syntax guidelines to specify the content of the signature.
    The rule is the heart of the attack signature. Refer to the Signature Options and Signature Syntax sections for details. Refer to Bot signature syntax for special limitations when writing bot signatures.
  9. For the Accuracy setting, select an accuracy level.
    The accuracy level indicates the ability of the attack signature to identify the attack, including susceptibility to false-positive alarms.
  10. For the Risk setting, select a risk level.
    The risk level indicates the level of potential damage this attack may cause, if it were successful.
  11. Click Create to create the new attack signature.
The new attack signature is placed into the attack signature pool and is added to the signature sets for the systems you specified. The custom signature is put in staging for all policies that have this signature in their assigned signature sets. It is a good idea to make sure that the new signature was added to the appropriate security policies.

Attack signature example: Protecting the management interface

This example describes an attack signature that blocks attempts to access the management interface, which is located at http://example.com/manage/. The web server is IIS, and the signature ignores URL case, treating manage the same as MaNAGE.

The following example attack signature examines the URL part (without the query string) and is not case-sensitive. The signature does not need to use a regular expression, because it needs to match only one pattern (manage):
   uricontent:"/manage/"; nocase; objonly;
This signature can detect URLs that contain /manage/ (the nocase modifier causes it to be not case-sensitive so that it also catches /mAnage/, for example). The signature catches, for example: http://example.com/portal/manage/panel/index.php.

This signature also catches a request that contains:

   http://example.com/manage/admin.php
It does not catch:
   http://example.com/admin.php?a=%2Fmanage%2F 
In the example, %2f is URL-encoded in place of / because the query string part cannot include an explicit forward slash.

Attack signature example: Protecting against cross-site scripting

This example describes an attack signature that blocks a cross-site scripting attempt that use HTML events such as onmousemove, onmousedown, onmouseup and other similar events within a parameter.

HTML is not case-sensitive, so the signature should not distinguish between upper- and lower-case. That way, the browser treats the onMousemOve event the same as onmousemove.

This example signature is not case-sensitive and looks inside a parameter. The signature also uses a regular expression for these reasons:

  • To support several events in a single signature
  • To ignore special characters such as the space (the browser normalizes several spaces into a single space)
  • To match a certain pattern: "[event_name] =" (for example, to reduce false positives, so the single word onmousemove or blablaonmousemove does not match the signature)

The signature has two parts:

  • The constant keyword that matches the word onmouse (not case-sensitive)
  • A regular expression that matches several events (separated by a vertical bar |), ignores non-word characters (\W*), and matches a certain pattern (\b for word boundary and = for [event_name] = pattern)
   valuecontent:"onmouse"; nocase; norm;  
   re2:"/\bonmouse(?:move|down|up|out|over|enter|leave|wheel) \\W*=/Vsi"; norm; 
The example signature would catch:
   http://example.com/index.php?a=onmousedown%3D%22alert(document.cookie)%22
After parameter a is URL-decoded, you can see onmousedown="alert(document.cookie)". The same signature would also catch requests where this expression is located in the request body, for instance:
   POST /index.php HTTP/1.1 Host: example.com 
   a=onmousedown%3D%22alert(document.cookie)%22
The example signature would not catch:
   http://example.com/onmousedown%3d/
since it is located in the URI part of the request, and not in the query string part.

Exporting custom attack signatures

You can export all custom attack signatures from one Application Security Manager™ system for use on another system. Both systems must be running the same software version. This is useful if you need to use the same user-defined attack signatures on multiple systems, or if you want to use a custom signature to develop another one on a different system.
  1. On the Main tab, click Security > Options > Application Security > Attack Signatures .
    The Attack Signature screen opens.
  2. Click Export.
    The web browser opens a file download screen.
  3. Save the file in a convenient location.
    Application Security Manager uses a file name with this format:

    sigfile_<date>_<time>.xml

The system exports all custom attack signatures to the XML file.

Importing custom attack signatures

Before you can import custom signatures to an Application Security Manager™ (ASM) system, they must first have been exported from a different system in XML file format.
You can import custom attack signatures that you want to use from other ASM™ systems. Both systems must be running the same software version.
  1. On the Main tab, click Security > Options > Application Security > Attack Signatures .
    The Attack Signature screen opens.
  2. Click Import.
    The Import Attack Signatures screen opens.
  3. In the Choose File field, specify the path to the XML file that contains the exported custom attack signature.
  4. Click Import.
The system imports the custom signature, and issues either a success message or a failure message. If the import was not successful, make any required changes to the XML file, and then try to import the file again. Successfully imported signatures are placed into the attack signature pool, and added to the signature sets for the systems you specified.

After the import, the system puts updated signatures into staging for the Enforcement Readiness Period (specified in Policy properties). Custom signatures are put into staging for all policies that have this signature in their assigned signature sets. It is a good idea to make sure that the new signature was added to the appropriate security policies.

About attack signatures in XML format

The XML file format is the only accepted import format for attack signatures. Following is an example of the XML format used when saving user-defined attack signatures for import onto another system.

<?xml version="1.0" encoding="utf-8"?>
<signatures export_version="11.X.X">
  <sig id="300000000">
    <rev num="1">
      <sig_name>Unique signature name</sig_name>
      <rule>msg:"Signature Name"; content:"soda";</rule>
      <last_update>2011-04-15 13:37:17</last_update>
      <apply_to>Request</apply_to>
      <risk>3</risk>
      <accuracy>2</accuracy>
      <doc>Any additional descriptive text</doc>f
      <attack_type>Cross Site Scripting (XSS)</attack_type>
      <systems>
        <system_name>IIS</system_name>
        <system_name>Microsoft Windows</system_name>
      </systems>
    </rev>
  </sig>
</signatures>
Warning: The sig_name attribute uniquely identifies a user-defined attack signature. Therefore, when you import an attack signature XML file, if there are any signatures in the XML file whose sig_name attribute matches that of any existing user-defined signatures, the system overwrites the existing definition with the imported definition.