NAME

FProt::Client - Client interface to the fpscand(1) virus scanning daemon

SYNOPSIS

    use FProt::Client;

    # Spawn an object configured to use the default 127.0.0.1:10200 host/port
    my $fpc = FProt::Client->new;

    # A host and/or port can optionally be supplied to override the default
    my $fpc = FProt::Client->new(
        host => '10.0.0.1', # Scanning box
        port => 10200,      # Default port
    );

    # Check if we could connect to the daemon
    warn "Connected" if $fpc->ping;

    # Scan a single file
    my ($status, $msg) = $fpc->scan_file('/etc/crontab');
    if ($status & 0x03) {
        print "/etc/crontab is clean\n";
    }

    # Scan with options (see SCANNING OPTIONS in fpscand(8))
    my %opt = (scanlevel => 3, archive => 99);
    my ($status, $msg) = $fpc->scan_file(\%opt, '/etc/crontab');
    if ($status & 0x03) {
        print "/etc/crontab is clean\n";
    }

    my ($status, $msg, $file, $archive_item) = $fpc->scan_file('/etc/crontab');

    # Scan a stream (also accepts an optional hashref as the first argument)
    use File::stat;
    my $file = 'README';
    open $fh, '<', $file or die $!;
    my ($status, $msg, $file, $archive_item) = $fpc->scan_stream($file, $fh, stat($file_txt)->size);

    # Close the connection with the daemon, called automatically by
    # DESTROY
    $fpc->quit;

DESCRIPTION

Provides an interface to the fpscand(1) virus scanning daemon. The daemon is capable of scanning both files on its local machine and files that are sent to it over the socket (currently limited by the daemon to 10MB).

METHODS

new

Constructor, only configures the object with the host and port it should connect and does not initiate a connection (see "ping" for testing the connection). A connection is lazily initiated when one of the methods that require it below are called.

Optional arguments:

host

The host or IP address to connect to, defaults to 127.0.0.1 which is the interface fpscand binds to by default.

port

The TCP port to connect to, defaults to 10200 which is the default fpscpand port.

ping

Checks if a connection can be established with the daemon.

scan_file

Scan a given absolute path to a file. A hashref of scanning option key-values can be optionally given as the first argument to pass options to fpscand (see SCANNING OPTIONS in fpscand(8)).

A list of values is returned:

An infection code

An integer indicating the clean status of the file, see return codes for an explanation of the return values.

A status message

A human-readable message indicating the status of the file.

The file name

The file name as fpscand returns it, this will be the full path to the file.

Archive item

When scanning archives (.zip, .tar etc.) this will be the name of a suspicious file in the archive. There is no fourth field for normal files.

scan_stream

Like "scan_file" but scans a stream. Takes three additional arguments instead of a filename, example:

    use File::stat;
    open $fh, '<', $file or die $!;
    my @ret = $fpc->scan_stream($file, $fh, stat($file)->size);

queue_file

TODO: implement

info

Return various information that's given by the HELP command. Returns a key-value list with the following keys and their values after being lower-cased:

fpscand

The version of fpscand.

engine

The version of the F-Prot engine fpscand is using.

protocol

The protocol this libary is speaking to fpscand.

signatures

The ID of the antivirus signature loaded into fpscand. This is in the format:

   YYYYMMDDHHMM[MD5]

Where MD5 is a 32-bit MD5 sum of the signature file (the square brackets are not present in the string).

uptime

The uptime of the fpscand.

quit

Inform the daemon that we are going away and close the connection to it, this will be automatically called (via DESTROY) when the object goes out of scope.

INTERNAL METHODS

These methods should not be used by normal users of this class but they might be overridden if the module was sub-classed,

command

Send a command on the current socket and return a chomp-ed response.

socket

Get a IO::Socket::INET TCP socket to host/port given to "new". Takes care of opening one if there isn't one already or if the previous socket has been closed for some reason.

Return codes

These are the return codes the scanning fuctions return, the code is a bitfield.

Infection codes (bits 1-2)

1. At least one virus-infected object was found (and remains)

2. At least one suspicious (heuristic match) object was found (and remains)

3. Both 1 and 2.

Testing for infections could thus be done with <$exitcode & 0x03>.

Error/unsure code (bits 3-6)

These may be combined with infection codes.

4

Interrupted by user. (SIGINT, SIGBREAK)

8

Scan restriction caused scan to skip files (maxdepth directories, maxdepth archives, exclusion list, etc)

16

Platform error (out of memory, real I/O errors, insufficient file permission etc.)

32

Internal engine error (whatever the engine fails at).

16+4(20)

Initilization error, i.e. every failure that occurs before any scanning starts.

32+16(48)

Crashed (handle_gpf).

Clean codes (bits 7-8)

64

Clean as far as we know, although at least one object was not scanned (encrypted file, unsupported/unknown compression method, corrupted or invalid file).

128

At least one object was disinfected (clean now).

192

same as 64 + 128, i.e. something skipped, something disinfected. Overall: Clean

AUTHOR

Ævar Arnfjörð Bjarmason <avar@f-prot.com>

LICENSE

Copyright 2007-2008 Ævar Arnfjörð Bjarmason.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm FProt::Client

perl -MCPAN -e shell
install FProt::Client