README version -- 0.2.1 Calea-lite is a re-implementation of the opencalea program, desgined with simplicity and ease of use in mind, while maintaining a roboust framework with many useful tools. To use calea-lite, you must first set up a controller. The controller is a central server that can control an unlimited (within reason) number of taps. Each tap "belongs" to a controller. Each instance of the tap program can only "belong" to one controller, but is capable of running many taps. The same physical tap device may run multiple instances of the tap program, if they wish to be controlled by more than one control server, although care should be taken not to overwhelm the tap machine, as the two tap processes will have no knowledge of each other. Finally, a listener must also be set up. Every tap may have its own listener. A sample usage is shown below: (for details on configuration - please see the "Getting Started" section below) FIRST: A controller is set up on a machine at 10.0.0.1 controller@10.0.0.1: ./controller SECOND: A tap machine is placed on the network. Once this machine has been placed, the tap process must be started (and possibly authenticated), and then no direct access to this machine is ever needed again. tapmachine@10.0.0.2: (sudo?) ./tap <-- Register itself with a controller (configured in 'tap.ini') THIRD: A listening machine (at say 10.0.0.3) is set up to listen for an incoming tap. Generally, this machine will be set up with some information about authentification. Optionally, the listener can register itself with the controller as well; this allows for new authentification data to be sent to both the tap and the listener at the same time, although it is not required. listener@10.0.0.3: ./listener <-- OPT: Configure controller in listener.ini FOURTH: The controller initiates a tap on the tap device. There are a large number of options here, including setting up taps on multiple devices, setting up authentification between the tap(s) and listener, and other options. You may read in further depth in the CONTROLLER section. For now, the simplest example is presented (assuming you have already run ./control above): controller@10.0.0.1: opencalea-lite> list All known clients: [DEVID] [DEV] [LOC] [STATUS] 4 tap purpleparrot@127.0.0.1 idle 5 kerb bluebarracuda@10.0.0.10 idle opencalea-lite> start 4 -t pcap Successfully started tap session 1 -- ./tap -t pcap -f "ip" opencalea-lite> start purpleparrot -t cmc -c asdf Successfully started tap session 2 -- ./tap -t cmc -c asdf -f "ip" opencalea-lite> start bluebarracuda ppannuto opencalea-lite> list All known clients: [DEVID] [DEV] [LOC] [STATUS] 4 tap purpleparrot@127.0.0.1 2 active: TAP_ID: 1, ./tap -t pcap -f "ip" TAP_ID: 2, ./tap -t cmc -c asdf -f "ip" 5 kerb bluebarracuda@10.0.0.10 1 active: Principal Name: ppannuto, Sending to 1 listeners opencalea-lite> stop 4 2 Please be patient, this may take several seconds. Tap session 2 stopped successfully opencalea-lite> shutdown purpleparrot This will end the olc process on the remote machine. You will not be able to run any more taps without accessing the machine and manually restarting the ocl process. Are you SURE you wish to continue (y/N)? y ** Message: There is 1 running tap session on 4 ** Message: Stopping tap ID 1 on 4 Please be patient, this may take several seconds. Tap session 1 stopped successfully ** Message: All running taps stopped ** Message: Connection to 4 terminated. ** Message: Device 4 shutdown successfully opencalea-lite> quit opencalea-lite> ** Message: opencalea-lite controller shutting down... ** Message: quit issued to server... ** Message: opencalea-lite server recieved quit ** Message: server shutdown complete. ** Message: cleaning up... ** Message: opencalea-lite quit complete. controller@10.0.0.1~: // Notice that in this example, the kerbTap on bluebarrcuda will still be tapping 'ppannuto', even though the controller has shut down. // You must explicitly stop the tap session on kerbTap for it to end. Getting Started: vi tap.ini [vi listener.ini , vi controller.ini] The first order of business is configuring opencalea-lite (ocl). Each program has a *.ini file associated to it. In all likelyhood, the only fields you will need to modify are the ip addresses pointing to the controller / listener in tap.ini and to the controller in listener.ini (although this does not do anything as of v0.1.x). In addition, the tap.ini file has various other configuration options that you may be interested in. The file is well commented - if you need any further assistance you will need to contact a developer. All configuration is done via the *.ini files. As a consequence, none of the ocl programs take any arguments (with the except of a tap setup to run in "standalone" mode, explained in the TAP section). ** NEW - v.0.1.5: All of the ocl programs have a built-in configuaration utility, (eg ./tap --configure) which will interactively prompt you for various configuration options. It separates configuration into two blocks, basic and advanced. You will always be prompted for the basic options and then asked if you wish to configure the advanced options. (sudo?) ./tap Once this is done, you will need to start tap programs on remote machines. You may start as many taps as you wish, and the controller does not need to be active to start a tap. Note that the tap process must be run as root or as a user who has been given explicit permission to access network devices - it will output a warning if it does not believe it has enough privlidges to function correctly (beta). ./listener On whatever machine you have configured to be the listening machine, you must run the listener processs. This process can be left alone once started, and only needs enough permissions to bind to the port given in listener.ini (default: 3001) and write files in the directory in which it is being run. Logging the output of the listener process (./listener &> listener.log &) may be useful, as it will give you a trail of all taps that it has collected - and their filenames, in case you forgot... ;) ./controller On whatever machine you have configured to be the controller, you must run the controller process. Running taps will automatically connect to the controller in the background - no notification is given in the interest of not interrupting you if you are typing a command. Type the 'list' command to see all connected devices. It is worth noting the 'connect_timeout' fields in tap/listener.ini - these are the frequency at which the remote processes will attempt to automatically connect to the controller. It defaults to 60 seconds, which means it may take up to 60 seconds (or more, depending on configuration) for all of the devices to connect to the controller. The controller features an interactive help system. Simply type 'help' at the ocl prompt to get help; 'help COMMAND' is also supported for detailed help for most commands. CONTROLLER I promise, I'll write this section soon. For now, just use the interactive help. It's really pretty good. TAP Again, the interactive help is pretty good for most situations. Please use that. --standalone (-a) This is designed for the situation where you may want to just run one tap, without bothering with setting up / using a controller. The address of the listener in tap.ini must still be valid, and the listener process must already be running. The construct is the same as if you were running it from the controller, think of these as being equal: "opencalea-lite> start 4 ..." == "./tap --standalone ..." ... is any subsequent arguments that you wish to pass to the tap. LISTENER TODO (sorry) - If you really need help, please contact the developers Email Notifications / Configuring Sendmail: The OCL tap processes will attempt to send email notifications of all started and stopped taps by default. This functionality is currently very primitive. Simple emails are sent to an email via sendmail, which is assumed to be configured and running. By default, emails are sent to admin@hostname. To configure where email notifications are sent, simply edit tap.ini, or use the built-in configuration utility. KERBEROS TAPS: There is a second type of tap program, a Kerberos watching tap. This can be run by executing sudo ./kerbTap Kerberos taps will watch the network for kerberos messages indicating logons and ticket grants. This can be used to watch for a specific username logging into a machine somewhere on the network using kerberos authentication. The Keberos Tap will connect to the controller specified in the kerb_tap.ini file. The controller can tell the tap to begin watching for a username by the command: start DEVICE-ID USERNAME [LISTENER-IP LISTENER-PORT] The listener IP and listener port are optional if the default listener (specified in kerb_tap.ini) is to be used. This command will cause the tap specified by the device ID to begin watching for the specified username and send the collected data to the specified listener. To stop watching a username: stop DEVICE-ID USERNAME When the tap sees a kerberos message that is for a user specified to be watched it collects the username, the IP of the machine the user is using, and the Kerberos message type (Currently only AS_REP (type 11) and TGS_REP (type 13) messages are watched for). This data is sent on to the listener in the following format: Byte 0 - The kerbTap message type. This is KT_GENMSG for tap data. Byte 1 - The kerberos message type (Either 11 for AS_REP or 13 for TGS_REP) Bytes 2-5 - The IP (Version 4) of the user. This is an integer which can be converted to a string using inet_ntop() Byte 6 - The length of the following username string Bytes 7-rest - The username