*omphalos* by nick black <nickblack@linux.com>
==============================================

"Gaze into your omphalos." - James Joyce, Ulysses

Omphalos is an integrated tool for network enumeration and domination. It
is designed around Linux's rtnetlink(7) layer and PACKET_MMAP capabilities.
Whereas other tools are geared towards either reconnaissance or directed
attacks, omphalos is designed to "spray the area".

I. Requirements
II. Building and installation
III. Usage
IV. Hacking
V. FAQs
VI. Thanks

===================================================================
I. Requirements
===================================================================

autoconf, automake, and a C compiler are used at buildtime.

libsysfs, libnl3, libpcap, libpciaccess, libz, libiw and libcap are used at
both build and runtime.

Omphalos currently only builds or runs on a Linux kernel with PACKET_MMAP
sockets. Packet transmission requires at least a 2.6.29 kernel.

The ncurses UI requires libncursesw (ncurses with wide character support),
and libpanel (distributed with SVR4 curses and ncurses).

arp-scan's 'get-oui' program is currently used to build the IANA OUI file.

wget is used to download the USB ID file.

GnuPG is used to verify signed tarballs.

===================================================================
II. Building and installation
===================================================================

If compiling from checked-out source, run "autoreconf -fi" to build the
initial configure script (a configure script will be present in release
tarballs). "./configure && make && sudo make install" ought be
sufficient to build and install Omphalos. Run "./configure --help" to
see supported build parameters.

If filesystem-based capabilities are supported, it might be desirable to
bestow CAP_SETUID privileges (this is *not* equivalent to a setuid binary).
See "Usage" regarding switch to the "nobody" user when CAP_SETUID is
possessed: this can help defend users from malicious files, even if they're
not allowed to open packet sockets. If non-root users should be able to use
network capabilities, add CAP_NET_ADMIN and CAP_NET_RAW to the binary. This
can be accomplished by running "make sudobless" or running tools/addcaps.

If MADV_HUGEPAGE is available at compilation time, madvise() will be used
to advise hugepage backing for important, large data structures including
the ringbuffers. This could improve performance.

===================================================================
III. Usage
===================================================================

Several capabilities are required for omphalos's usage of packet and
netlink sockets. Omphalos *does not* need to run as root, and generally
should not be. See "Building and installation" for details on setting up
the omphalos binary's privileges.

If omphalos possesses the CAP_SETUID capability (as it always will if run
as root), it will by default attempt to become the "nobody" user. This can
be suppressed via an empty argument to the -u option (-u ""), but helps
defend against malicious input.

===================================================================
IV. Hacking
===================================================================

=======================================
IV.A Networking
=======================================

We cannot assume that we will see all control traffic, due to switched
networks, wireless topography, physical/network-layer encryption and drops.
Packets can be dropped (possibly silently) at the card, in the networking
stack (thus being neither copied nor processed), or due to a full
ringbuffer (thus being processed but not copied). It thus cannot be assumed
that all packets processed by the machine are able to be read, nor that all
packets seen on the wire even generate a statistic.

We cannot transmit with another station's hardware address; this will not
be generally allowed in a switched network.

We cannot assume that we have an IP address on a local network; this
requires configuration, and will never be the case for eg a bridge.

We cannot assume other hosts are not misconfigured, broken, or adversarial.

=======================================
IV.B UIs/clients
=======================================

Callback functions might be called by any number of different threads,
possibly concurrently. No relationship can be assumed between threads and
callbacks.

Callbacks are like interrupt handlers. There is a finite ringbuffer for
incoming packets. Packet handling must proceed at wire rate, or else the
ringbuffer will eventually be filled up. GUI events cannot generally
proceed at wire rate, so packet handlers must generally aggregate events
and dispatch work.

You can associate opaque state with an object passed to a callback by
returning a pointer to that opaque state. Returning NULL will disassociate
any attached opaque state. Don't keep a private store of things like
interface data or network sessions; use the general accessors.

It's fine to create threads in your UI, but do not do it until after
calling omphalos_setup(), since this drops permissions and sets up signal
masking necessary for cancellation to function properly. If there are
signals your UI threads must handle, mask them prior to calling
omphalos_setup(), unmask them in the handling thread, and remask them prior
to calling omphalos_init(). Masking them prior to calling omphalos_setup()
is not currently necessary, but will be should it ever spawn threads.

A diagnostic callback must be defined. omphalos_setup() will provide a
default fprintf(stderr,...) callback; you can change it prior to calling
omphalos_init(), but omphalos_init() will error out if it is set to NULL.
There is not yet any means to manage diagnostic output in omphalos_setup().

A packet callback will only reference an incoming interface for which the
device event callback has been successfully invoked, without an intervening
device removal callback invocation. A device removal callback can be invoked
with no corresponding device event callback. Host callbacks follow the same
rules as packet callbacks with regard to device callbacks.

=======================================
IV.C Porting
=======================================

Omphalos uses several advanced features of the Linux kernel directly, and
many use cases require other functionality. Porting will involve, at
minimum:

 - a means of reading packets from the wire (traditional packet(7) sockets,
    libpcap, etc)
 - a means of transmitting packets on the wire (traditional packet(7)
    sockets)
 - a means of acquiring link, address, route and neighbor information from
    the kernel (we use rtnetlink). this has traditionally been a messy set
    of ioctl()s on linux, which would have to be poll()ed.
 - a means of acquiring physical information from the kernel, especially
    for wireless devices (we use nl80211).
 - a means of dropping general privileges, but retaining those capabilities
    necessary for network activity (perhaps a client/server process pair'
    communicating over PF_UNIX sockets).

=======================================
V. FAQs
=======================================

1. omphalos-ncurses exits immediately after printing "Entering ncurses mode..."
1A. initscr() is probably calling exit() because it couldn't set up your
    terminal. Ensure the TERM environment variable is exported, and correctly
    set for your terminal type.

2. I see hosts with 0 packets sent or transmitted.
2A. Most likely they were present in your system's ARP cache.

3. I see a lot of "protocol 0800 is buggy, dev XXX" messages in dmesg.
3A. This is a diagnostic issued by the kernel's packet socket mechanism. It
    will show up if you run tcpdump, wireshark, or any other user of PF_PACKET
    sockets on the interface. It has nothing to do with omphalos or the packets
    it generates.

=======================================
VI. Thanks
=======================================

* Jeremy Stretch of PacketLife.net, for supplying PCAP-format unit tests.
* Peter Jensen <peter@diff.net>, patch [master f9fee3b]
* Robert Edmonds <edmonds@debian.org>, for Autotools advice and assistance
   interpreting DNS packet captures.