##  ipguard

    ipguard v0.04
    Copyright (c) 2005 SeaD <sead@deep.perm.ru>

    See COPYRIGHT for copying info

##  what is ipguard

    ipguard - tool designed to protect LAN IP address space by ARP spoofing.

    ipguard listens network for ARP packets. All permitted MAC/IP pairs
    listed in 'ethers' file. If it recieves one with MAC/IP pair, which is
    not listed in 'ethers' file, it will send ARP reply with configured
    fake address. This will prevent not permitted host to work properly
    in this ethernet segment. Especially Windows(TM) hosts.


##  installation

    Download from: http://deep.perm.ru/files/ipguard/

    Note: you will need two libs for ipguard:
        libpcap (ftp://ftp.ee.lbl.gov/)
        libnet (http://www.packetfactory.net/libnet/dist/)

    % edit Makefile for your system

    % make
    % make install
    % ipguard fxp0


##  usage

    Parameters:

    ipguard [-felpmunbriodvh] <iface>

    -f | -e <ethers> - Ethers file. Format of `ethers' file described
        in ethers.sample. Default `/etc/ethers'.
    -l <log> - Log file. Default `/var/log/ipguard_<iface>.log'.
    -p <pid> - Pid file. Default `/var/run/ipguard_<iface>.pid'.
    -m <mac> - Fake MAC address. Will be sent in ARP reply as MAC
        of unlisted computer. Default `de:ad:xx:xx:xx:xx',
        `x' == random hex number.
    -u <sec> - Update ethers interval. Time between checks `ethers'
        file for changes and reread if any. 0 == no update.
    -n <num> - Fake replies number. Sended with interval 50ms.
    -b <num> - MAC buffer size. Number of last bad MAC/IP pairs
        stored in buffer. 0 == no buffer.
    -a - No address substitition. Like 0.0.0.0 or 00:00:00:00:00:00.
    -r - Read only. Do not send anything to net. Only listen.
    -x - Duplex mode. Send fake packets not only to intruder but
        to request for intruder address too.
    -i - Hidden mode. Do not block first ARP test by Windows(TM)
        when it enters net.
    -o - Promiscuous mode. Enable promiscuous mode. Usually useless.
    -d - Don't fork. Do not go into background and write all events
        to stderr.
    -v - Verbose. Little more messages.
    -h - Help. Short commandline parameters description.

    Signals:

    SIGHUP - Force reread of `ethers' and reopen log file.
    SIGUSR1 - Dumps current ethers table, bad ethers buffer
        and some statistics.
    SIGINT || SIGTERM - Shutdown ipguard.

    Some examples:

    Normal method, duplex, autoupdate /etc/ethers every 5 min and
    send 2 fake replies:

    # ipguard -x -u 300 -n 2 fxp0

    Read-only mode and remember last 100 not listed in `ethers' MACs.
    Useful for initial MAC/IP pairs collect:

    # ipguard -r -b 100 -f ./empty_file rl0

    Do not go to background and be more verbose, with test ethers file:

    # ipguard -dv -f /tmp/ethers my1


##  tips

    - You must have read permission on /dev/bpf* if you want to start
      ipguard in read-only mode and read/write permission for
      full functional if you're not root.
    - First MAC/IP pair in list always taken from listening interface,
      so you can't occasionally block yourself.


##  platforms

    ipguard was developed on:
    FreeBSD 4.10-RELEASE, gcc-2.95.4, libnet-1.0.2a, i386

    Compiled and works on:
    FreeBSD 5.4-RELEASE, gcc-3.3.3, libnet-1.0.2a, i386
    OpenBSD 3.6, gcc-2.95.3, libnet-1.0.2a, i386

    Any reports and patches for other platforms are welcome.


##  credits

    Authors of libpcap, libnet, arping, ip-sentinel
    citrin <citrin at citrin.ru> for testing assistance


##  bugs

    ipguard will not prevent changing MAC address along with IP by client.

    Linux send weird ARP packet when enters net. ipguard did'nt handle it.

    Signals like HUP, USR1 or TERM works only on new received arp packet.
    It's not a bug, it's a feature.


SeaD <sead@deep.perm.ru>
