Fetching latest commit…
Cannot retrieve the latest commit at this time
|Failed to load latest commit information.|
|doc||update man page copyright|
|ieee-oui.txt||mention xsltproc / docbook-xsl deps|
*omphalos* by nick black <email@example.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 =================================================================== GNU Autotools and the Autoconf Archive are used to build the configure script. They are not necessary when building from a release tarball. On Debian-based systems, install "automake" and "autoconf-archive". A C compiler is 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 TTY UI requires GNU Readline. The ncurses UI requires libncursesw (ncurses with wide character support), and libpanelw (distributed with SVR4 curses and ncurses). The X UI requires libX11 and friends. arp-scan's 'get-oui' program is used to build the IANA OUI file. wget is used to download the USB ID file. GnuPG is used to verify signed tarballs. Manpages and XHTML documentation require xsltproc and docbook-xsl. Your TERM and LOCALE/LANG environment variables need be correctly set to make full use of omphalos-ncurses. Ensure that a UTF-8 locale is being used, and that your terminal definition supports 256 colors. =================================================================== II. Building and installation =================================================================== If compiling from checked-out source, run "autoreconf -fi -Wall,error" to build the initial configure script (a configure script will be present in release tarballs). "./configure && make && sudo make postinstall" 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. To restore an omphalos directory to its pristine form, ensure a Makefile has been generated via ./configure, and run "make maintainer-clean". =================================================================== 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. Some fonts do not support the full range of Unicode glyphs used by omphalos, or render them in an unexpected way. Fonts known to cause problems include: - Terminus (vertical lines don't match up with rounded corners) - Computer Modern (lmodern) (numerous problems) - Cortoba (numerous problems) - Courier (spacing issues) - Electron (numerous problems) - FreeMono (spacing issues) - Nimbus (spacing issues) Fonts known to work include: - Arial - Bitstream Vera Sans - Comfortaa - Consolas - DejaVu Sans Mono - Droid Sans Mono - Inconsolata - Junicode - Liberation - PragmataPro - Sansation =================================================================== 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 <firstname.lastname@example.org>, patch [master f9fee3b] * Robert Edmonds <email@example.com>, for Autotools advice and assistance interpreting DNS packet captures.