README file for the Network Universal Frame Forge

Nuff, the Network Universal Frame Forge, is a security software distribution tightly coupled with 2 excellent networking libraries available on almost all flavours of unix:

• Dug Song's libdnet "low-level networking library". Tested with 1.11.

• Lawrence Berkeley National Laboratory's libpcap "packet capture library". Any pcap with pcap_get_selectable_fd(). Tested with 0.9.4.

If you are looking at this distribution and thinking things look a little different than your average security software distribution, you're right, they are. Nuff is actually a scheme interpreter with a collection of scheme functions and macros for encoding and decoding network data packets seamlessly across a diverse range of network protocols.

Although nuff is completely scheme based, the extreme flexibility of the language allows nuff to mostly impersonate an ordinary unix citizen obeying the letter of the law: C.

Nuff was originally written by Doug Hoyte and HCSW Labs in 2006/2007. Nuff, and all its accompanying and associated files, are (C) Doug Hoyte and HCSW Labs unless otherwise noted or implied. Your rights to distribute and modify this software are protected under the terms and conditions of the GNU General Public License available at www.gnu.org. The .nuffdoc files in the docs/ directory ARE NOT covered under the GNU GPL. Although you are granted an unlimited, irrevocable right to distribute the .nuffdocs with nuff, all other rights to these files are reserved.

Nuff was started as a hobby project with a primary purpose of marrying my 2 favourite hacking activities: low-level network packet mischief and symbolic computation. It was designed to target the OpenBSD and Linux operating systems but should be mostly portable to other systems that support libdnet and libpcap. Since I designed nuff with nobody in mind except myself, you might find you disagree with some of my unconventional design decisions. That said, I sincerely hope you find nuff useful and interesting.

-Doug Hoyte, Hardcore Software

Nuff was designed to make certain things easy. First and foremost, nuff is designed to be a flexible, convenient, safe environment for experimenting with network protocols. I want to be the first to say that many of nuff's ideas are not new and have been implemented to various extents in other programs. The design of nuff was influenced heavily by the following excellent tools: nmap, netcat, tcpdump, dsniff, thc-rut/amap/etc, hping2/3, scapy, yersinia, pcapy/impacket, paketto keiretsu, and others.

But I wrote nuff for a reason. In my opinion, nuff makes numerous improvements to the traditional techniques for programming low-level network applications. When creating nuff it was my goal to make some tasks that were difficult or error-prone in the past easy. Nuff was designed to be an efficient, highly-flexible packet sniffer/dissector/creator/injector.

Although the learning curve is fairly steep, especially if you don't know lisp, it goes very high. Nuff takes some good ideas present in the above mentioned tools and invents others for itself that, when taken together, provide a more powerful low-level security programming environment than any other I have experienced to date.

These are some of the ways nuff is different than your average unix security software tool:

• Nuff was designed around the concept of asynchronicity. This means that all nuff primitives are designed to work in a concurrent scheme continuation-based environment (see "nuff doc language"). Nuff makes it easy to simultaneously handle multiple diverse sources of input/output. From sockets to pcap descriptors to signals to user commands on standard input, nuff handles I/O uniformly and concurrently. Unlike most other programming environments, which require a good deal of programmer effort to create sophisticated asynchronous network programs, nuff was specifically tailored for exactly this task. In nuff, things work in parallel "by default".

• Nuff abstracts away the traditional network programming concept of sockets. When programming nuff, you can't directly access the OS-provided sockets at all. Instead, you use an opaque, more generic, data type called a "Packet Transport Descriptor". PTDs are discussed further in "nuff doc language" and there are signifigant differences between them and sockets. For instance, multiple continuations (kind of like threads) can listen on the same PTD and all receive a complete copy of the data (except that the data actually shares memory - see "nuff doc language"). Also, you can't manually close PTDs: they are closed by the garbage collector when determined to be no longer needed.

• Nuff does not use the DNS resolver code provided by your operating system (note for SunOS porters - this means you don't need to link in -lnsl). Nuff implements its own DNS parsing/resolution system which allows us multiple efficiency optimisations. For instance, when your script is read in, the nuff compiler will try to look for obvious DNS resolutions your program might make given the code and the supplied user arguments and then starts them up "in parallel" and "in the background" so they are ready sooner when/if your program actually needs them.

• Nuff comes bundled with a comprehensive online documentation system. There are the nuffdoc files we will see shortly and a powerful describe feature similar to unix's manpage system and common lisp's describe. See "nuff doc language" for details.

• Nuff was designed from the ground-up with security in mind. The nuff compiler takes many pro-active security measures to protect you - the users and programmers of nuff scripts. See "nuff doc security" for details.

• Nuff does not use the unix getopt(3) function to parse command line arguments so the behaviour is slightly different. See "nuff doc language" for details.

• Nuff was designed to support as many different processor architectures as possible. Nuff has been tested on big/little endian, 32/64 bit, aligned/unaligned architectures. Nuff requires at least a 32 bit processor.

• Nuff has a reasonably small footprint and doesn't require any 3rd party run-time environments. This is because we feel there may be many fruitful embedded/mobile-code uses for nuff in the future. We bundle a small, relativley unsophisticated scheme system with the nuff kernel (tinyscheme - derivative of minischeme). The kernel only needs to link with libc, libm, libdnet, and libpcap. There are no dependencies on other applications or libraries.

  When designing nuff we actually chose a slow and simple scheme interpreter on purpose - it provides an impetus for writing efficient macro expansions. If we can make a useful real-time packet processing tool perform acceptably well with simple interpreted scheme, imagine the production performance we can get when/if nuff is complemented with a decent scheme compiler.

• Nuff does not support microsoft windows. While nuff isn't actively tested on operating systems other than OpenBSD and Linux, we have high hopes that it will be portable to most flavours of unix with libdnet and libpcap. We are happy to accept unix portability patches.

  Although a windows port is probably possible (nuff's dependencies are a subset of nmap's dependencies and nmap runs fine on windows) the nuff development team possesses neither the resources nor the inclination to maintain a windows port. We may be willing to consider non-intrusive windows portability patches, but feel that since nuff's raison-d'etre is to leverage the most advanced unix networking features, windows, and the headaches it brings, would probably be a net negative for the codebase.

Nuff assumes that the user is a competent unix hacker. If you aren't, well, this will be even more difficult.

Make sure you have GNU Make installed on your system. You need to edit the file "GNUmakefile" in the main nuff directory. Specify at least:

• A NUFFDIR "install directory"

• Your build type. Will depend on your Operating System

• Link/Include paths for the 2 libraries described above: libdnet and libpcap

Once you've made the necessary modifications, you can run:

make

or on some systems

gmake

Which will run a single gcc command to compile the "nuff kernel".

An optional step is to now run the command:

make install

Which will copy files to the NUFFDIR directory you specified in the GNUmakefile. For the breakdown on the files installed see the "NUFFDIR Directory Structure" section.

Note that make install doesn't copy the nuff kernel into your path which you might also want to do:

cp nuff /wherever/sbin/

Do NOT install nuff setuid.

Nuff also assumes that the user is at least familiar with scheme or lisp. If you aren't, but you've made it this far, well, you just might be in for a treat.

Although nuff does just about everything in scheme, basic unix experience is generally all that's required to use nuff.

Let's run nuff:

$ nuff
nuff - the Network Universal Frame Forge - by Doug Hoyte
  [nuff kernel v1.2] [nuffdir /usr/local/nuffcode]

*

The * is a scheme read-eval-print-loop (REPL for short). If you're familiar with scheme or lisp you know the power behind a humble REPL. We have a full R5RS scheme system along with many convenience macros including a CL format. If you read "nuff doc language" you will see that we often suggest trying things in the REPL. That means you type it here, at the star prompt.

But it's possible you didn't want to do this at all. Hit control-c to return to your unix shell and forget all about scheme if you like. We can use nuff like a normal unix command. One useful option that unix commands often provide is "help". Nuff provides this too:

$ nuff -help

gives help on the help command itself. It tells you that you can also read the help information on more specific commands. A simple, generic nuff test script is the ping command. You can read its help info like so:

$ nuff -help ping

and use ping itself like so:

# nuff ping google.com

A more interesting example is the trace script:

# nuff trace google.com

Nuff has a small but growing collection of scripts included with the default install. To read their manual pages, see "nuff doc code".

Nuff requires access to a directory called the NUFFDIR. An unpacked nuff source distribution is a valid NUFFDIR. So is the directory installed with a make install command.

1. Required NUFFDIR Subdirs
2. Optional NUFFDIR Contents
3. NUFFDIR Search Order

Nuff comes bundled with its own documentation system, parser, and formatter. This may sound redundant and a waste of effort, especially when there are many existing systems like TeX, docbook, and HTML, but nuff actually benefits a lot from the close integration of documentation and code. The fact that we use the scheme language means that our code is uniform - easy to parse and process. So for large portions of the most change-prone code, we are saved from writing/maintaining any text at all. The code is, literally, self documenting.

Nuff's documentation system is called nuffdoc and you are reading a nuffdoc right now. You might be reading this from the website or in formatted ascii with a nuff installation or the raw nuffdoc file or elsewhere. Nuffdocs can always be read in formatted ascii by running the command "nuff doc <topic>". For instance:

$ nuff doc readme

You might also want to pipe this output to your pager of choice:

$ nuff doc readme | less

What you read from here depends on your interest in nuff. Here are some pointers:

• The manual pages for nuff's bundled utilities and scripts

  nuff doc code
  

• Information on using nuff safely and details on nuff's security features

  nuff doc security
  

• Reference and tutorial for creating nuff scripts

  nuff doc language
  

• Reference documentation on nuff operating system/packet library interfaces

  nuff doc interfaces
  

• Reference documentation on network protocol layers supported by nuff

  nuff doc layers
  

This one is for the h4x0rs. The ones that run 'tings. Big ups:

syke, madness, cyb0rg/asm, theclone, fyodor, d00tz, duff, blackheart, rt, magma, nummish