Company News Products Data Tools Support Documentation Q & A Contact Us

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

SNFClient

Command Line

The command line functions of SNFClient allow you to:

Viewing Help Mode

For help with using the different functions of SNFClient, you can run SNFClient.exe with no parameters. The result is something like this:

>SNFClient.exe

Help: 
 To scan a message file use:
     SNFClient.exe [-xhdr] [-source=<IP4Address>] <FileNameToScan>
 or: SNFClient.exe <Authenticationxx> <FileNameToScan>

 To test an IP with GBUdb use:
     SNFClient.exe -test <IP4Address>
	 
 To update GBUdb records use:
     SNFClient.exe -set <IP4Address> <good|bad|ignore|ugly|-> <badcount|-> <goodcount|->
 or: SNFClient.exe -drop <IP4Address>
 or: SNFClient.exe -good <IP4Address>
 or: SNFClient.exe -bad <IP4Address>

 To check SNFServer status use:
     SNFClient.exe -status.second
 or: SNFClient.exe -status.minute
 or: SNFClient.exe -status.hour

 To shut down the SNFServer use:
     SNFClient.exe -shutdown
	 
 For more information see www.armresearch.com
 C) 2007-2008 Arm Research Labs, LLC.

Back to Top

Perform SMTP Message Scan:

SNFClient.exe <FileNameToScan>

This is the normal message scan mode. <FileNameToScan> should be replaced with the full path to an SMTP message file.

SNFClient.exe <authenticationxx> <FileNameToScan>

This is the version 2 backwards compatible message scan mode. <authenticationxx> should be replaced with the 16 character authentication string (in fact, any string of letters and numbers will work). <FileNameToScan> should be replaced with the full path to an SMTP message file.

This mode offers backward compatibility to SNF version 2.x by accepting and ignoring an authentication string. When in compatibility mode it is ok to rename the SNFClient.exe program to match the SNF license id as was required for versions prior to 3.0. Note that although the 3.x SNFClient can be called like the 2.x versions of SNF, it cannot load the rulebase file and scan the message like version 2.x could. The SNFServer engine must be running in order for SNFClient to scan messages. If SNFClient cannot connect to SNFServer it will continue to try for a while and then will return a 0 (fail-safe) result.

SNFClient.exe -xhdr <FileNameToScan>

This mode will scan an SMTP message and return the X-Headers that SNF would (or did) add to the message. The result may look somehting like this:

>SNFClient.exe -xhdr \SNF\test\junkmsg.txt
X-Sniffy-Version:
        SNFMulti Engine Version 2.9rc25 Build: May  1 2008 14:19:06
        SNF Server Version 2-9b2 Build: May  1 2008 14:19:17
X-Sniffy-License: prescale
X-Sniffy-RulebaseUTC: 20070516185328
X-Sniffy-Identifier: \SNF\test\junkmsg.txt
X-Sniffy-GBUdb-Result: 0, 69.251.204.89, Ugly c=0.214287 p=1 Source Truncate
X-Sniffy-Scan-Result: 20
X-Sniffy-Rules:
        20-0-0--1-f
X-Sniffy-Spam: Yes
X-Sniffy-SNF-Group: Truncated

The X- headers that are reported are identical to what would be (or has been) injected into the message.

If the SNF engine is configured to provide the X- headers to the API then the X- headers will be created but will not be added to the message. In this mode a system can use the -xhdr option to collect the headers that SNF would like to add to the message so that they can be interpreted and perhaps added later along with any other headers the system might want to inject (thus rewriting the message only once).

If the SNF engine is configured to inject the X- headers into the message then the X- headers are provided through the API AND the message file will be re-written to include the X- headers.

The X- headers that are produced are highly customizable and depend upon the settings provided in the SNF configuration file (usually snf_engine.xml, or snfmdplugin.xml).

SNFClient.exe -source=<IP4Address> <FileNameToScan>

This mode will scan an SMTP message and use the provided IP address as the source IP for the message disregarding what is found in the Received: headers. This is useful when the calling system knows the source IP and that IP is not present in the Received: headers.

SNFClient.exe -xhdr -source=<IP4Address> <FileNameToScan>

This mode combines the X-Header and IP Source modes (see above).

Back to Top

Perform IP Testing

SNFClient.exe -test <IP4Address>

This mode retrieves GBUdb data about the IP address provided. <IP4Address> should be replaced with the IP you wish to test.

The result code returned indicates the GBUdb Range that best represents the IP's statistics. In general, a zero result code indicates that the IP is not associated with spam and a non-zero result code indicates that the IP is a spam source.

Important: Only the -test mode returns a GBUdb related result code. The other GBUdb functions in SNFClient will return a zero.

In addition to producing a numeric result code, this mode also produces a report (stdout) that describes the complete GBUdb record (if any) for the IP being tested. That report will look something like this:

>SNFClient.exe -test 12.34.56.78
GBUdb Record for 12.34.56.78
  Type Flag: ugly
  Bad Count: 9
 Good Count: 0
Probability: 1
 Confidence: 0.226425
      Range: truncate
       Code: 20

All GBUdb manipulation functions report the complete GBUdb record that resulted from the transaction.

Note that the above IP test returned result code 20 which is the default code associated with IPs that fall in the Truncate GBUdb range.

>echo %errorlevel%
20

The IP 12.34.56.78 was used in simulation for testing purposes only ;-)

Back to Top

Update GBUdb Records

SNFClient.exe -set <IP4Address> ( good | bad | ugly | ignore ) <bad> <good>

This mode creates or updates the GBUdb record for the given IP.

GBUdb records consist of a flag that determines the mode of the record, a count of known bad encounters, and a count of known good encounters. If you wish to leave part of the GBUdb record with it's default (or current) value then use the dash ( - ) character in place of the corresponding command line parameter.

For example, to set the bad count to zero for a particular IP without changing any other parts of the GBUdb record you might do the following:

>SNFClient.exe -set 12.34.56.78 - 0 -
GBUdb Record for 12.34.56.78
  Type Flag: ugly
  Bad Count: 0
 Good Count: 0
Probability: 0
 Confidence: 0
      Range: new
       Code: 0

In the above example, the flag ( good | bad | ugly | ignore ) and good event count <good>command line parameters were left in their original state, but the bad count <bad> was changed to zero. The original state of the record can be seen above (see Perform IP Testing). By changing the bad count to zero the IP has moved out of the truncate range and now looks like a "new" record (both counts zero, default "ugly" flag).

There are 4 possible flags:

Good - The IP is administratively white-listed.

Bad - The IP is administratively black-listed.

Ignore - The IP is to be ignored (infrastructure, transparent).

Ugly - The IP is to be judged on it's behavior / statistics.

In this example, we will black-list the IP by setting it's flag to Bad:

>SNFClient.exe -set 12.34.56.78 bad - -
GBUdb Record for 12.34.56.78
  Type Flag: bad
  Bad Count: 0
 Good Count: 0
Probability: 0
 Confidence: 0
      Range: truncate
       Code: 20

Note that with the bad flag set the IP record will now return the truncate result code when tested without regard for the good and bad event counts.

In this example, we set the record for this IP back to it's original state. The important parts are that the flag was ugly, the bad count was 9, and the good count was 0: 

>SNFClient.exe -set 12.34.56.78 ugly 9 0
GBUdb Record for 12.34.56.78
  Type Flag: ugly
  Bad Count: 9
 Good Count: 0
Probability: 1
 Confidence: 0.226425
      Range: truncate
       Code: 20

Note that the Probability and Confidence figures are now calculated to the same values as before and that the Range and associated result code are also correct (compare with the -test example for this IP above).

In this next example, we will change the good event counter so that the IP is no longer found in the truncate range:

>SNFClient.exe -set 12.34.56.78 - - 1
GBUdb Record for 12.34.56.78
  Type Flag: ugly
  Bad Count: 9
 Good Count: 1
Probability: 0.8
 Confidence: 0.237282
      Range: black
       Code: 63

Note that we only changed the good count. The other parts of the GBUdb record were left unchanged.

Note that with only 10 total encounters, only 1 out of 10 needs to be good in order to keep the IP out of the default truncate range. The IP doesn't get off the black-list completely however. Now with 9 out of 10 encounters counted as bad the IP is in the black range.

SNFClient.exe -good <IP4Address>

This mode adds a "good" encounter to a GBUdb record. This mode can be used to provide additional training data.

In this example, we will add a good encounter to the 12.34.56.78 IP:

>SNFClient.exe -good 12.34.56.78
GBUdb Record for 12.34.56.78
  Type Flag: ugly
  Bad Count: 9
 Good Count: 2
Probability: 0.636364
 Confidence: 0.247104
      Range: caution
       Code: 40

Note that with the additional good encounter the IP now has moved into the caution range.

SNFClient.exe -bad <IP4Address>

This mode adds a "bad" encounter to a GBUdb record. This mode can be used to provide additional training data. 

>SNFClient.exe -bad 12.34.56.78
GBUdb Record for 12.34.56.78
  Type Flag: ugly
  Bad Count: 10
 Good Count: 2
Probability: 0.666667
 Confidence: 0.25607
      Range: caution
       Code: 40

SNFClient.exe -drop <IP4Address>

This mode drops the given IP from the GBUdb if it exists. The result is that all statistics and flags are erased. If a -test were issued for the same IP immediately after a -drop then the result would be that of a new (unknown) IP. The GBUdb record data returned after this command indicates what would happen if that -test were run:

>SNFClient.exe -drop 12.34.56.78
GBUdb Record for 12.34.56.78
  Type Flag: ugly
  Bad Count: 0
 Good Count: 0
Probability: 0
 Confidence: 0
      Range: new
       Code: 0

Note that the flag is set to the default "ugly" and that both good and bad event counters are set to zero. The resulting calculations place the IP in the "new" range and the result of a -test for this IP would return zero.

Hint: A quick way to safely clear a GBUdb false positives is to use the -drop command causing GBUdb to forget what it knows about the IP and to start learning from scratch.

Back to Top

Get Realtime Status Information

SNFClient.exe -status.second
SNFClient.exe -status.minute
SNFClient-exe -status.hour

This mode reports the current status of the SNF engine on the local system.

If the command is successful then the result code will be zero and the requested status report (second, minute, or hour) will be displayed (stdout).

If the command is not successful then a non-zero result code (usually 99) will be returned and no status report will be displayed (stdout).

Usually SNFClient returns a zero (fail-safe) result code when an error occurs. THIS IS NOT TRUE of the -status.xxxx mode. This allows systems to use the -status.xxxx mode to check the health of the SNF Engine. If a nonzero result is returned then there is a problem with the SNF Engine.

Here is an example of using -status.second to check the health of the SNF Engine. In this case, the SNFServer has been shut down so there is not SNF Engine to respond to the request. SNFClient waits a few seconds while it tries to connect to the SNF Engine via it's XCI interface. When that fails it returns a non-zero value and does not produce a status report:

>SNFClient.exe -status.second

>echo %errorlevel%
99

Here is an example of using -status.minute to check the health of the SNF Engine and examine current message rates and other interesting data. The status report that is returned is in XML format:

>SNFClient.exe -status.minute

<!-- Status Report -->
<stats nodeid='xxxxxxxx' basetime='20080507203350' elapsed='60610' class='minute'>
  <version>
    <engine>SNFMulti Engine Version 2.9rc20 Build: Apr 10 2008 22:26:09</engine>
    <platform>SNF Server Version 2-9b2 Build: Apr 10 2008 17:40:38</platform>
  </version>
  <timers>
    <run started='20080411023442' elapsed='2311209'/>
    <sync latest='20080507203429' elapsed='22'/>
    <save latest='20080507203140' elapsed='191'/>
    <condense latest='20080507131332' elapsed='26479'/>
  </timers>
  <gbudb>
    <size bytes='142606336'/>
    <records count='678177'/>
    <utilization percent='98.5258'/>
  </gbudb>
  <counters>
    <m c='3668'/>
    <s c='3653'/>
    <h c='15'/>
    <t c='862'/>
    <b c='1'/>
  </counters>
  <rates>
    <m s='62.1796' m='3640.13' h='219589' d='4.21389e+006'/>
    <s s='61.6835' m='3623.93' h='218738' d='4.17159e+006'/>
    <h s='0.496114' m='16.2023' h='851.386' d='42302.5'/>
    <w s='0' m='0' h='0' d='0'/>
    <c s='0' m='0' h='1.77003' d='2295.28'/>
    <b s='0' m='0.900131' h='27.4355' d='2184.11'/>
    <t s='16.5371' m='865.926' h='47632.5' d='995030'/>
    <a s='0' m='0' h='0' d='0'/>
    <r s='0' m='0' h='0' d='0'/>
  </rates>
  <results>
    <histogram hits='3668'>
      <g k='0' c='15'/>
      <g k='5' c='73'/>
      <g k='20' c='862'/>
      <g k='47' c='1'/>
      <g k='50' c='16'/>
      <g k='52' c='2196'/>
      <g k='53' c='8'/>
      <g k='54' c='107'/>
      <g k='57' c='6'/>
      <g k='58' c='8'/>
      <g k='59' c='1'/>
      <g k='60' c='374'/>
      <g k='63' c='1'/>
    </histogram>
  </results>
  <rules>
    <rulebase utc='20080507202625'/>
    <active utc='20080507202625'/>
    <update ready='no' utc='20080507202429'/>
    <latest rule='1879554'/>
    <histogram hits='2790'>
      <g k='18291' c='611'/>
      <g k='32625' c='2'/>

      ... many additional entries omitted ...
	
      <g k='1879153' c='2'/>
      <g k='1879158' c='4'/>
      <g k='1879172' c='2'/>
      <g k='1879370' c='2'/>
    </histogram>
  </rules>
  <panics>
  </panics>
</stats>

For detailed information about the data contained in a status report please read the section on Status Logs.

Back to Top

Server Controls

SNFClient.exe -shutdown

This mode sends the shutdown command to the SNFServer on the local system. This is the preferred (clean) way to stop the SNFServer.

Example:

>SNFClient.exe -shutdown
 [Server Says: shutdown in progress]

Back to Top

 

Please email support@armresearch.com with any questions.

Copyright © 2007 - 2010 ARM Research Labs, LLC