README file for the Network Universal Frame Forge

README file for the Network Universal Frame Forge

README file for the Network Universal Frame Forge

  1. What is nuff?
  2. What makes nuff different?
  3. Why is there no ./configure script?
  4. What's with all these .scm and .nuff files?
  5. NUFFDIR Directory Structure
  6. Nuff documentation
  7. Shouts

What is nuff?

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:

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 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

What makes nuff different?

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:

Why is there no ./configure script?

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:

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


or on some systems


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.

What's with all these .scm and .nuff files?

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

A more interesting example is the trace script:

# nuff trace

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

NUFFDIR Directory Structure

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

Required NUFFDIR Subdirs

The directories that are required to exist in the NUFFDIR are:

  • ffun/ - core nuff scheme functions

  • docs/ - .nuffdoc files and other general documentation on nuff

  • code/ - .nuff files - the bundled nuff scripts

Optional NUFFDIR Contents

Other files and directories included with the nuff source distribution but not installed by make install:

  • GNUmakefile - the main build script for the nuff kernel

  • TODO - the nuff developer TODO-list

  • src/ - C source code files for the nuff kernel

NUFFDIR Search Order

The kernel needs a valid NUFFDIR to run. When it starts, it looks for a NUFFDIR in the following places (in order):

  • The NUFFDIR directory specified in the GNUmakefile when the nuff kernel was built.

  • A directory named in the environment variable NUFFDIR

  • The current working directory (.)

Nuff documentation

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:


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

All material is © Doug Hoyte and/or HCSW Labs unless otherwise noted or implied.