Hacking the hacked shell

General

All the sources of the Packet Shell are in the src/ distribution directory, which contains the core of the shell with all the planned extensions to the tcsh.

They are divided into 3 separate groups of files:

• support files
• admin files
• rendering files

with the obvious meaning their name and class suggests.

The support files are the common development framework, while the admin and rendering files use to implement their own functionalities. Admin commands act on the network interfaces (open/enable/close/swap) while the rendering commands act on the hosts hash tables for the purpose of well printing on character based terminals.

Here's what the core files do:

• support files
  • args.c => How to handle dynamic arrays of strings
  • cache.c => Routines to handle the internal hosts cache
  • datalinks.c => Network interfaces protocol decoders
  • decoders.c => Decoders/counters for the most common protocols
  • ettercap.c => passive OS fingerprints resolver
  • ettercap.h => Automatically generated file to keep the table of OS fingerprints names
  • ettercap2c.c => An utility to convert the etter.finger.os passive OS fingerprints file to a C variable
  • etter.finger.os => The list of OS fingerprints maintained by ettercap project
  • fmemdmp.c => Routine to dump memory area
  • glob.c => The glob.c and glob.h from glibc-2.3.1 by GNU
  • hash.h => Simple hash table implementation by Michael W. Shaffer <mwshaffer@yahoo.com>
  • hash.c => Simple hash table implementation by Michael W. Shaffer <mwshaffer@yahoo.com>
  • init.c => All that serves to initialze the Packet Shell
  • interface.c => How to handle the table of network interface(s)
  • interval.c => How to handle time and time intervals
  • list.h => Simple doubly-linked list implementation by Michael W. Shaffer <mwshaffer@yahoo.com>
  • list.c => Simple doubly-linked list implementation by Michael W. Shaffer <mwshaffer@yahoo.com>
  • nic.h => Automatically generated file to keep the table of NIC vendor names
  • oui.txt => The list of NIC vendor names maintained by IEEE
  • oui2c.c => An utility to convert the IEEE oui.txt NIC vendor file to a C variable
  • pksh.h => Definitions for the Packet Shell
  • prompt.c => How to manage the Packet Shell prompt
  • render.c => Printing routines to have a well formatted output for bytes, packets, hosts and protocols
  • sort.c => How to sort the hosts cache
  • stupid.c => The simplest Packet Shell built-in extension to be used as a template
  • vendor.c => NIC vendor names resolver
  • wrapper.c => Wrapper around original pksh_xxx() for use with tcsh

• admin files
  • pkclose.c => Close network interface(s)
  • pkdev.c => List all network interfaces suitable for being used with the Packet Shell
  • pkenable.c => Enable packets capture on network interface(s)
  • pkfilter.c => Display/Apply the BPF filter associated to a network interface
  • pkhelp.c => Provide short help messages for all the built-ins extensions implemented by the Packet Shell
  • pkopen.c => Open network interface(s) to look at packets on the network
  • pkstatus.c => Display detailed about the current status of network interface(s)
  • pkswap.c => Manage the stack of referenced network interfaces
  • pkuptime.c => Tell how long the shell has been running

• rendering files
  • bytes.c => Tell the hosts cache and display detailed information in terms of bytes
  • packets.c => Tell the hosts cache and display detailed information in terms of packets
  • pkarp.c => Tell and display the ARP cache like the arp command does
  • pkfinger.c => Tell the hosts cache and display detailed information for hosts like the 'finger' command does for users
  • pkhosts.c => Tell and display the hosts cache to show the table of hosts viewed on network interface(s)
  • pklast.c => Tell and display the hosts cache like the 'last' command does for users
  • pkwho.c => Tell and display the hosts cache like the 'who' and 'rwho' commands do for users
  • throughput.c => Tell and display the hosts cache to show detailed information about the throughput viewed on network interface(s)
  • protocols.c => Tell and display the hosts cache to show detailed information about the protocols usage on network interface(s)

Writing Extensions

This section explains how to add a new built-in to the Packet Shell. As I said in the documentation, the Packet Shell is easily extendible. At the time of writing, I had already implemented about 18 new built-ins.

The simplest possible extension to the Packet Shell can be found in src/stupid.c in the source distribution, which can be used both as template and also as an valuable tutorial for the beginners.

Suppose now you want to add a new function to the already available extensions for the Packet Shell. Here are the istructions to proceed.

• Copy the source file src/stupid.c in src/foo.c and edit the copy to meet your requirements.
  Choose the name you want to assign to the new built-in extension and assign the name to the function
  e.g.
  int foo (int argc, char * argv []) { ... }


• Edit the src/Makefile to add foo.c to the list of known sources to be compiled.
  
  In fact this Makefile can be used only with development goals in mind, just to allow on-place compilation and before the extension has to be definitely inserted into the pksh shell.


• Edit configure at the top level
  • add the source file foo.c to the shell variable $CMDADMIN or $CMDVIEWS depending on its class
  • lookup in the source tcsh file sh.init.c for the right place in the struct biltins bfunc[] array where to insert the command
    
    Warning: Please note that alphabetic order in this table is vital.
    You will miss the extension if you insert the entry in a wrong place!
    This is currently tcsh limitation for unknown reasons.
    
    You have be warned!!!
  
  
  • Add a branch [case] needed to patch sh.init.c in subroutine linenumber() near the begin of the file.
    
    Example: if the name you have assigned to the new extension is foo then it must be placed before the already exiting command foreach which is alphabetically following, and therefore you have to add a line in the switch section of the linenumeber() subroutine of configure which looks like this:
    
    foo) before=foreach ;;