Documentation Home
Help! Errors
Help! False Positives
Help! Spam Leakage
Installation Guides
Features
Procedures
SNF Community
Software
Technology
Tools
Direct Support
Glossary
Q&A

SNFServer

XML Client Interface

snf/xci/gbudb

The GBUdb part of the XCI interface supports one request/response per connection. The <gbudb> element in the request indicates that this request is for the GBUdb engine. In the XCI protocol for GBUdb, the <gbudb> element will contain exactly one element. The inner most element determines whether the XCI message is a result or one of several types of request.

XCI GBUdb result format

XCI requests for the GBUdb engine generally take the form of a single line of text terminated with a new line character. The response from an XCI GBUdb request is also generally a single line of text ending with a new line. The fictitious example below is split into separate lines to show its struture and to avoid wrapping. The XCI response to a GBUdb request will always take the same format:

<snf>
  <xci>
    <gbudb>
      <result 
        ip='12.34.56.78' type='ugly' 
        p='1.0' c='0.071429' b='2' g='0' 
        range='caution' code='40'/>
    </gbudb>
  </xci>
</snf> 

The response provides the full detail of the GBUdb record after the request is completed. If the request is a test and the record did not yet exist then the result will show the default new entry data -- all counts zero and the type flag set to ugly.

The above example indicates the following:

The ip='12.34.56.78' attribute indicates that the IP for this record is 12.34.56.78.

The type='ugly' attribute indicates that the flag for this IP is ugly.

The p='1.0' attribute indicates that the probability figure for this IP is 1.0.

The c='0.071429' attribute indicates that the confidence figure for this IP is 0.071429.

The b='2' attribute indicates that the bad count for this IP is 2 (two bad events on record).

The g='0' attribute indicates that the good count for this IP is 0 (zero good events on record).

The range='caution' attribute indicates that the statistics for this IP place it in the caution range.

The code='40' attribute indicates that the result code associated with this range is 40.

XCI GBUdb test format

Test requests are used to retrieve data on a IP without making any changes. If the IP is not in the GBUdb dataset then the result will show zero for both bad and good counts and the default flag of "ugly".

<snf><xci><gbudb><test ip='12.34.56.78'/></gbudb></xci></snf>

The <test/> element indicates that this is an IP test request.

The ip='12.34.56.78' indicates that the IP to test is 12.34.56.78.

XCI GBUdb set format

Set requests are used to change one or more fields of a GBUdb record, or establish a new record if it does not yet exist. There are three fields in a GBUdb record (aside from the IP itself) and they are the type flag (good, bad, ugly, ignore), the good event count, and bad event count. Each of these are represented by an attribute in the <set/> element. At least one of these should be present in a set request for a given IP. Missing attributes in the request will not be changed. The first four examples below show this by changing only the type flag. The final example changes all three fields:

<snf><xci><gbudb><set ip='12.34.56.78' type='good'/></gbudb></xci></snf>
<snf><xci><gbudb><set ip='12.34.56.78' type='bad'/></gbudb></xci></snf>
<snf><xci><gbudb><set ip='12.34.56.78' type='ugly'/></gbudb></xci></snf>
<snf><xci><gbudb><set ip='12.34.56.78' type='ignore'/></gbudb></xci></snf>
<snf><xci><gbudb><set ip='12.34.56.78' type='ugly' b='1' g='0'/></gbudb></xci></snf>

In the final example:

The ip='12.34.56.78' attribute indicates we are setting data values for the IP 12.34.56.78.

The type='ugly' attribute indicates we are setting the type flag to ugly.

The b='1' attribute indicates we are setting the bad event counter to 1.

The g='0' attribute indicates we are setting the good event counter to 0.

XCI GBUdb good event format

A good event request records a non-spam event in GBUdb for a specific IP. If the IP record does not yet exist then the record is created before the good event is recorded. This mechanism allows systems to train the GBUdb about IP sources when messages from that source might not be scanned in the normal way -- such as when they are white-listed by another filtering component.

<snf><xci><gbudb><good ip='12.34.56.78'/></gbudb></xci></snf>

The <good/> element indicates that this is a good event request.

The ip='12.34.56.78' indicates that the event should be recorded for the IP 12.34.56.78.

XCI GBUdb bad event format

A bad event request records a spam event in GBUdb for a specific IP. If the IP record does not yet exist then the record is created before the bad event is recorded. This mechanism allows systems to train the GBUdb about IP sources when messages from that source might not be scanned in the normal way -- such as when they are black-listed by another filtering component.

<snf><xci><gbudb><bad ip='12.34.56.78'/></gbudb></xci></snf>

The <bad/> element indicates that this is a bad event request.

The ip='12.34.56.78' indicates that the event should be recorded for the IP 12.34.56.78.

XCI GBUdb drop format

A drop request causes GBUdb to forget about an IP. If there is a record for the IP then the record is removed. The effect is that GBUdb will report the IP as unknown if queried again -- the flag will be ugly (the default) and both event counters will be zero.

<snf><xci><gbudb><drop ip='12.34.56.78'/></gbudb></xci></snf>

The <drop/> element indicates that data for this IP should be forgotten (drop the record).

The ip='12.34.56.78' indicates the IP to forget is 12.34.56.78.

Please email support@armresearch.com with any questions.