XCI scanner requests instruct the SNFMulti engine to read a message file, scan that file with the GBUdb enhanced pattern scanning engine, and return data about the scan. A scanner request will return the scan result code and optionally any X-headers or log data generated for the scan.

XCI scanner requests look something like this:

<snf>
  <xci>
    <scanner>
      <scan file='/tmp/msg0123456.tmp' xhdr='yes' log='yes' ip='12.34.56.78'/>
    </scanner>
  </xci>
</snf>  

In the fictitious example above, extra line breaks were added for readability. Normally the request would be transmitted as a single line of text. Also, in most cases, a much simpler request would be made. In this case, we've used all of the options so that we can describe them.

The file='/tmp/msg0123456.tmp' attribute indicates that the message file to be scanned is located by the path /tmp/msg0123456.tmp. It is important to always provide the full path to the message file.

Note: The message file presented to SNF does not need to be the entire message if the file is only a temporary file that won't be passed to other processes and message is larger than 64K bytes. Only the first 64K bytes need to be in the temporary file. This will minimize file I/O costs for larger messages and reduce any vulnerability to an attack that uses large message files.

The xhdr='yes' attribute is optional and indicates that the response should include X- header information. The default is xhdr='no'. If no xhdr attribute is defined then the default (no) is used. In order for X- header information to be generated the configuration file must not have them turned off ( mode= 'none' ).

Note: It is best practice for the calling application to collect X- headers from SNF through the XCI interface so that all X- headers can be injected at one time by the calling application. This saves rewriting the message file repeatedly -- once for each set of X- headers that might be injected by SNF and other processes. However, if the message file will be passed on to other processes through the file system then SNF can be configured to inject it's X- headers into the message file so that the calling application can simply pass the same file to the next process.

The log='yes' attribute is optional and indicates that the response should include log data for the scan. The default is log='no'. If no log attribute is defined then the default (no) is used. In order for log data to be generated the configuration file must not have XML logs turned off ( mode='none' ).

The ip='12.34.56.78' attribute is optional and indicates that the source IP for the message has already been determined as 12.34.56.78. If this option is used then GBUdb training directives may not function as expected. This option is best used when the calling application has already determined the correct source IP for the message and wishes to force the source IP value rather than have SNF+GBUdb discover it from Received headers in the message.

Note: It is often best to let SNF + GBUdb determine the source IP for a given message based on the Received headers. If the connecting IP is not already represented in the top Received header for the message then the calling application should create one in the top of the temporary file SNF is going to scan.

Please email support@armresearch.com with any questions.