INTRO
====
The Advanced Port Knocking Suite is a multi-purpose tool based on
 connection less TCP communications. It allows to launch commands, 
transmit data (with DES encryption support) as soon as a specific 
packet or a sequence of specific packets is received by the server. 
One of the advantages is that TCP ports involved in packet capture 
are closed... 

It includes two parts : a server (apks) which listens to packets on 
the wire and perform configured actions and an optional client (apkc) 
which helps building packets according to scenarii.

HOWTO
=====

0. Make sure the following PERL modules are available on your system
      - Net::RawIP
      - Getopt::Std (optional used for command line options)
      - Getopt::Long (optional for the same reason as above)
   You will also need libdes for encryption support. 

1. Edit the configuration file (defaults to ./apks.conf ./apkc.conf)
   - use # to comment out a line
   - each line is a rule. each received packet will be compared with 
     those rules. if parameters match an action will be taken.
   - a rule is divided in 18 space separated fields (see FIELDS section for details)
   - There are two types of rules
      o "Entry" rules are the first rules that make possible to start 
        a new scenario. A least one Entry rule is needed.
      o "Follow" rules which are part of a scenario.
   - Three actions can be taken
      o The daemon will execute a command in the background
      o The next step of the scenario is defined
      o The running scenario is reset
     
2. Run apks.pl / apkc.pl as root with apropriate options 

   apks options :
      --interface,-i listening interface, default eth0
      --logfile,-l   log file, default /var/log/apks.log
      --conf,-c      configuration file, default ./apks.conf
      --verbose,-v   more details
      --quiet,-q     run silently, default off
      --help,-h      this help
      --version,-V   display version and exit

   apkc options :
      --interface,-i writing interface, default eth0
      --conf,-c      configuration file, default ./apkc.conf
      --verbose,-v   more details
      --help,-h      this help
      --version,-V   display version and exit


FIELDS
======

NOTE : When specified * can be used as a wildcard to match any value.

TYPE => E:ENTRY F:FOLLOW
     The TYPE field is designed to sepcify which rules are entry point
     to the scenarii.
     E : The rule is an entry point
     F : The rule is one of the steps in a scenario

ID   => INTEGER > 0
     This is the field used to identify the rule. It must be unique 
     and not null.

TTL  => INTEGER | *
     A packet will match if its TTL is equal to the value.

SOURCE => IP ADDRESS | *
     A packet will match if its source IP address is equal to the value.

SPORT => INTEGER | *
    A packet will match if its source TCP port is equal to the value.

DPORT => INTEGER | *
    A packet will match if its destination TCP port is equal to the value.

SEQ => INTEGER | *
    A packet will match if its SYN sequence number is equal to the value.
    
SEQ_ACK => INTEGER | *
    A packet will match if its ACK sequence number is equal to the value.
    
URG ACK PSH RST SYN FIN => 0 | 1 | *
    A packet will match if the the corresponding TCP flag is set (1) or not set (0).

WIN => INTEGER | *
    A packet will match if the TCP window size is equal to the value.

DATA => quoted STRING | *
    This field is only used to transfer data. No match is performed on it. 
    Yes it is useless, but mandatory.

ACTION => NEXT(INTEGER | $ref) | CMD(STRING with $ref) | RST
    The action field tells the program what to do if the rule matches.
    - NEXT : The next rule to be matched in order to follow the scenario, 
             identified by its ID.
         o It may be an integer corresponding to the ID of the rule.
         o It may be the reference of another field (ex: %WIN refers to the 
           value of the TCP window size)   
    - CMD : The command to be launched.
         o It may be a plain text
         o It may refer to another field (%DATA)
         o It may be a mix (ex: ifconfig eth%FIN > /tmp/listdir)
    - RST : The running scenario is reset. 

KEY => STRING
    The key used to decrypt the DATA field.

RULES : EXEMPLES
================

E  1  *   *   1  5  *  *  *  *  *  *  1  *  *  *  CMD("/etc/init.d/sshd start") NULL
This rule is an Entry rule with ID 1. It means that if a packet with a source port 
of 1, a destination port of 5 and the SYN flag set to 1, tne program will launch SSH.

E  2  *   *   2  5  *  *  *  *  *  *  0  1  *  *  NEXT(3) NULL
F  3  *   *   *  9  *  *  *  *  *  1  *  0  *  *  CMD("/etc/init.d/sshd start") NULL
The first line (rule ID 2) is an entry rule. A packet with a source TCP port of 2, a 
destination port of 5, the SYN flag not set and the FIN flag set will load the rule 
with ID 3.
The second line (rule ID 3) is a rule that will be tested ONLY if it has been loaded 
by another rule (here with ID 2). Then if a packet with a destination port of 9, the 
RST flag set and the FIN flag not set is received the SSH server will be launched.

E  4  *  *  5  5  *  *  *  *  *  *  *  *  *  *  RST  NULL
If a packet with TCP source and desnation ports of 5 is received the scenario engine 
is reset. As an exemple if this packet is received after a packet matching the rule 
with ID 2 (see example above), the rule with ID 3 is unloaded. Then a packet matching 
the rule 3 will not be interpreted.

E  5  *  *  6  5  *  *  *  *  *  *  0  1  *  *  NEXT(%SPORT)         NULL
F  6  *  *  3  5  *  *  *  *  *  *  1  1  *  *  NEXT(%SEQ)           NULL 
F  7  *  *  1  5  *  *  *  *  *  *  1  *  *  *  CMD("ls -al 1>&2")   NULL
The Entry rule of this scenario is the rule with ID 5. If a packet matches then the 
rule with the ID correcponding to the TCP source port will be loaded (here it can only 
be the rule with ID 6). The rule 6 is a follow rule. If a packet matches this rule the 
next rule to be loaded will be the rule with the ID equals to the SYN sequence number 
in the packet. Let's say we had this value set to 7. Then the rule with 7 ID will be 
loaded, allowing list the running directory if a third packet matches the criteria of 
rule 7.

RULES : TIPS AND TRICKS
=======================

The pcap filter is optimized in order to reduce the number of packets to be 
analyzed. The filter is set on source IP as well as source and destination TCP 
ports. So if one of these fields is wilcarded in any rule, no filter will be set 
on this field and the number of packet captures -> analyzed will be greater.

The analyzing engine first try to match the next rule of a scenario. It the packet 
matches, the action is applied and that's it. If it doesn\'t match entry rules are 
tested in ... random order. If one matches the action is applied and we get out of 
the loop. So whatch out, one rule can hide another.

The -v option should be usefull as well as the logfile.

CLIENT
======

The client provides an interactive interface for crafting packets according to configuration 
file. In order to work properly it is necessary that the configuration used by the client and 
the server are similar.

A small help on commands is available. Just type ? ou h.

To list all loaded rule use the command r. It show the ID, type, action and encryption 
parameters for the rule. The full details can be viewed with the r+ command. The commands e 
and e+ provide the same kind of information for entry rule. 

The client keeps a state of a scenario running on the server. Then it is possible to get 
information about the next rule in scenario with the n and n+ commands.

To have a packet crafted according to a rule use the command x . Fields that have been 
set in the configuration file will be automaticaly filled. Other fields can be set to any 
acceptable value by the user.

TODO
====
1. Anti-replay
2. Comman-line mode for client

WHO
===
Renaud Bidou - renaud.bidou at iv2-technologies.com