pytbull 手册

- Official documentation for pytbull v2.1 -

Table of content

1. Description
2. Architecture
   1. Remote mode
   2. Local mode
3. Installation
   1. Standard installation (client)
   2. Server
   3. Backtrack 5
   4. Mac OS X
4. Configuration
   1. CLIENT section
   2. PATHS section
   3. ENV section
   4. FTP section
   5. TIMING section
   6. SERVER section
   7. TESTS section
   8. TESTS_PARAMS section
5. Usage
6. Errors
7. Syntax, write your own tests

Description

pytbull is an Intrusion Detection/Prevention System (IDS/IPS) Testing Framework for Snort, Suricata and any IDS/IPS that generates an alert file. It can be used to test the detection and blocking capabilities of an IDS/IPS, to compare IDS/IPS, to compare configuration modifications and to check/validate configurations.

The framework is shipped with about 300 tests grouped in 11 testing modules:

1. badTraffic: Non RFC compliant packets are sent to the server to test how packets are processed.
2. bruteForce: tests the ability of the server to track brute force attacks (e.g. FTP). Makes use of custom rules on Snort and Suricata.
3. clientSideAttacks: this module uses a reverse shell to provide the server with instructions to download remote malicious files. This module tests the ability of the IDS/IPS to protect against client-side attacks.
4. denialOfService: tests the ability of the IDS/IPS to protect against DoS attempts
5. evasionTechniques: various evasion techniques are used to check if the IDS/IPS can detect them.
6. fragmentedPackets: various fragmented payloads are sent to server to test its ability to recompose them and detect the attacks.
7. ipReputation: tests the ability of the server to detect traffic from/to low reputation servers.
8. normalUsage: Payloads that correspond to a normal usage.
9. pcapReplay: enables to replay pcap files
10. shellCodes: send various shellcodes to the server on port 21/tcp to test the ability of the server to detect/reject shellcodes.
11. testRules: basic rules testing. These attacks are supposed to be detected by the rules sets shipped with the IDS/IPS.

1. badTraffic：测试如何处理低质流量
2. bruteForce：测试暴力攻击
3. clientSideAttacks：测试客户端攻击
4. denialOfService：测试 DoS 攻击
5. evasionTechniques：测试各种闪避技术
6. fragmentedPackets：测试各种碎片攻击
7. ipReputation：测试服务器的 IP 信誉
8. normalUsage：测试一般用法
9. pcapReplay：启用 pcap 文件重放
10. shellCodes：测试 shell code
11. testRules：基本规则测试

It is easily configurable and could integrate new modules in the future.

There are basically 5 types of tests:

1. socket: open a socket on a given port and send the payloads to the remote target on that port.
2. command: send command to the remote target with the subprocess.call() python function.
3. scapy: send special crafted payloads based on the Scapy syntax
4. client side attacks: use a reverse shell on the remote target and send commands to it to make them processed by the server (typically wget commands).
5. pcap replay: enables to replay traffic based on pcap files

Architecture

Remote mode

In this mode, the IDS is plugged on the span port (or port mirroring) of the core switch and is configured in promiscuous mode. The IDS analyzes all traffic that goes through the core switch. Malicious files can be downloaded either by pytbull or by the server. This mode is called "remote".

 

Local mode

In this mode, files are downloaded on the client pytbull is started from.

IDS mode with attacked server in DMZ

In this configuration, a firewall splits the network into 3 parts (lan, wan, dmz). The IDS is plugged in a span port (or port mirroring) of the switch with its interface configured in promiscuous mode. It will analyze every traffic that is sent to the LAN interface of the firewall.

 

IPS mode

In this configuration, a firewall splits the network into 3 parts (lan, wan, dmz). The IDS is plugged between pytbull and the firewall. To give the IDS a chance to detect the malicious files, pytbull has to download the infected files itself.

 

IPS mode with attacked server in DMZ

In this configuration, a firewall splits the network into 3 parts (lan, wan, dmz). The IDS is plugged between pytbull and the firewall. Malicious files have to be downloaded by pytbull directly to give the IDS a chance to detect them.

 

Installation

Standard installation (client)

Prerequisites

Ensure Python (2.6.5) and following dependencies are installed. On a Debian based Linux distribution, just issue:

$ sudo apt-get install python python-scapy python-feedparser python-cherrypy3

Also install necessary tools (nmap, hping3, nikto, ab, ...). Either install them from sources or from the repositories. From the packages, this can be simply done by issuing:

$ sudo apt-get install nmap hping3 nikto tcpreplay apache2-utils

At last, you will need ncrack to test the bruteForce module:

$ sudo aptitude install build-essential checkinstall libssl-dev libssh-dev
$ wget https://nmap.org/ncrack/dist/ncrack-0.5.tar.gz
$ tar -xzf ncrack-0.5.tar.gz
$ cd ncrack-0.5
$ ./configure
$ make
$ sudo make install

Pytbull

From tar.bz2 (stable release)

Download and uncompress pytbull:

$ cd /usr/local/src/
$ wget https://downloads.sourceforge.net/project/pytbull/pytbull-2.0.tar.bz2
$ bzip2 -cd pytbull-2.0.tar.bz2 | tar xf -
$ sudo mv pytbull/ /opt/
$ cd /opt/python/

There is nothing to install, but some configuration to do. Please refer to the next section.

From Mercurial (development release)

If you wish to obtain the latest development release, install pytbull from Mercurial. As a prerequisite, install Mercurial:

$ sudo apt-get install mercurial

Then get pytbull as follows:

$ cd /opt/
$ sudo hg clone http://pytbull.hg.sourceforge.net:8000/hgroot/pytbull/pytbull

Server

Prerequisites

Install Python (2.6.5). On a Debian based Linux box, just issue:

$ sudo apt-get install python

You will also need to install a FTP server (port 21/tcp), apache2 (port 80/tcp) and SSH (port 22/tcp):

$ sudo apt-get install vsftpd apache2 openssh-server

The configuration file for vsftpd is located in /etc/vsftpd.conf. It is advised to have at least these 2 parameters:

# Allow anonymous FTP? (Disabled by default)
anonymous_enable=NO
# Uncomment this to allow local users to log in.
local_enable=YES

pytbull (server)

You can copy the reverse shell from the server/ directory into the server that hosts the IDS/IPS.

Installation on Backtrack 5

pytbull is already shipped with BackTrack. Just use the dedicated configuration file:

$ sudo ./pytbull -c conf/config.bt5.cfg -t 192.168.1.16

Installation on Mac OS X

Mac OS X is not officially supported. However, I've developed pytbull on my Mac ;-)

• Install Macports
• Install python and its necessary bindings:

$ sudo port install python26
$ sudo port select --set python python26
$ sudo port install py26-scapy
$ sudo port install py26-iniparse
$ sudo port install py26-feedparser

• Install tools:

$ sudo port install nmap
$ sudo port install hping3
$ sudo port install tcpreplay

Configuration file

CLIENT section

CLIENT section
ipaddr	The IP address of the client where pytbull is installed.
iface	Interface used by pytbull to send the payloads.
useproxy	0 or 1. Only used by the client to connect to googlecode to check if a newer version of Pytbull is available.
proxyhost	IP address of the proxy, e.g. 192.168.100.1
proxyport	Integer. Proxy port, e.g. 8080
proxyuser	Proxy username (used for proxies that require an authentication).
proxypass	Proxy password (used for proxies that require an authentication).

PATHS section

PATHS section
urlpdf	URL to your third party server (where malicious PDF files are hosted).  Don't put a trailing slash at the end of the URL
pdfdir	Relative path to the place where malicious pdf files will be saved. Default to pdf/malicious Don't put a trailing slah at the end of the path.
pcapdir	Relative path to the place where pcap files are stored. Default: pcap Don't put a trailing slah at the end of the path.
tempfile	Temporary file used by pytbull. Default value: /tmp/pytbull.tmp
alertsfile	Path to your remote alerts file (Snort, Suricata, other). Default to /var/log/snort/alert (for Snort)

ENV section

ENV section
sudo	Path to the sudo command. Default to /usr/bin/sudo
nmap	Path to your nmap. Default to /usr/bin/nmap
nikto	Path to your nikto. Default to /pentest/scanners/nikto-2.1.4/nikto.pl
niktoconf	Path to your nikto configuration file. Default to /pentest/scanners/nikto-2.1.4/nikto.conf
hping3	Path to your hping3. Default to /usr/sbin/hping3
tcpreplay	Path to your tcpreplay. Default to /usr/bin/tcpreplay
localhost	Environment variable used in some tests. Default to 127.0.0.1

FTP section

FTP section
ftpproto	Method used to grab the alerts file. Possible values: ftp, ftps, sftp. Default: ftp
ftpport	Port (TCP) used to grab the alerts file. Default: 21
ftpuser	Login to connect to the remote FTP service (Snort/Suricata)
ftppasswd	Password to 1connect to the remote FTP service (Snort/Suricata)

TIMING section

TIMING section
sleepbeforegetalerts	Integer. Time elapsed (in seconds) before getting the alerts, just after the payload has been sent to the server. Default: 2
sleepbeforenexttest	Integer. Time elapsed (in seconds) between 2 tests. Default: 2
sleepbeforetwoftp	Integer. Apply to multipleFailedLogins module. Time elapsed (in seconds) between 2 bad login attempts. Default to 2
urltimeout	Integer. Apply to all internet connections. Time (in seconds) before considering the resource as inaccessible. Default to 10

SERVER section

SERVER section
reverseshellport	Defines the tcp port to use for the reverse shell (used by the clientSideAttacks module). Default value: 12345

TESTS section

TESTS section
clientSideAttacks	Client side attacks module. Will check that the reverse shell is running on the remote server (Snort/Suricata). Refer to the clientSideAttacks.py to change the payloads.  Value=0|1
testRules	Test Rules module. Will test alerts based on signature files. Refer to the testRules.py source to change the payloads.  Value=0|1
badTraffic	Bad Traffic module. Will send non RFC compliant packets to the remote target. Refer to the badTraffic.py source to change the payloads.  Value=0|1
fragmentedPackets	Fragmented Packets module. Will fragment attacks on multiple small packets. Refer to the fragmentedPackets.py source to change the payloads.  Value=0|1
multipleFailedLogins	Multiple Failed Logins module. Will basically do a brute force attempt against the remote FTP service. Refer to the multipleFailedLogins.py source to change the payloads.  Value=0|1
evasionTechniques	Evasion Techniques module. Will send obfuscated attacks to the remote target. Refer to the evastionTechniques.py to change the payloads.  Value=0|1
shellCodes	ShellCodes module. Will send malicious hex-encoded payloads to the remote target. Refer to the shellCodes.py source to change the payloads.  Value=0|1
denialOfService	Denial of Service module. Will attempt to flood the server with special packets. Refer to the denialOfService.py source to change the payloads.  Value=0|1
pcapReplay	Pcap replay module. Enables to replay actions from a pcap file.  Value=0|1

TESTS_PARAMS section

TESTS_PARAMS section
ipreputationnbtests	Number of probed IPs for the ipReputation module.  integer

Usage

If you have selected the clientSideAttacks module (see configuration file section for more information), you will need to start the reverse shell on the server. Following command uses port 34567/tcp:

$ ./pytbull-server.py -p 34567

Since the files are downloaded in the current directory, you can create a pdf/ directory and start pytbull from the parent location:

$ mkdir pdf/
$ cd pdf/
$ ../pytbull-server.py -p 34567

Then start pytbull (on the client side). An example to start pytbull tests against 192.168.100.48, running Snort:

$ sudo ./pytbull -t 192.168.100.48

Notice that you will need to adapt (config.cfg) the port used by the reverse shell if you use the optional parameter -p on remote side.

Errors

SetGen is not defined

While running pytbull, if you have following error:

Traceback (most recent call last):
  File "./pytbull.py", line 507, in <module>
    oPytbull.doAllTests()
  File "./pytbull.py", line 333, in doAllTests
    self.doTest( eval( ('%s.%s'+'(self._target).getPayloads()') % (module[1],
    module[1][:1].upper()+module[1][1:]) ) )
  File "./pytbull.py", line 197, in doTest
    eval(payload[2])
  File "<string>", line 1, in <module>
  File "/usr/lib/pymodules/python2.6/scapy/sendrecv.py", line 235, in send
    __gen_send(conf.L3socket(*args, **kargs), x, inter=inter, loop=loop,
    count=count,verbose=verbose)
  File "/usr/lib/pymodules/python2.6/scapy/sendrecv.py", line 207, in __gen_send
    x = SetGen(x)
NameError: global name 'SetGen' is not defined

Just add following line at the beginning of this file: /usr/lib/pymodules/python2.6/scapy/sendrecv.py as follows: (http://trac.secdev.org/scapy/ticket/324)

from base_classes import SetGen

Nmap illegal argument

If you get this error:

Illegal Argument to -P, use -PN, -PO, -PI, -PB, -PE, -PM, -PP, -PA, -PU, -PT,
or -PT80 (or whatever number you want for the TCP probe destination port)
QUITTING!

Replace "-Pn" with "-PN" in the Nmap tests. Nmap has changed the syntax in recent releases.

FTP Error, 550 Failed to open file

If you have this error while all tests passed (BASIC CHECKS):

***ERROR: FTP Error, 550 Failed to open file.
Check your configuration (section FTP in config.cfg).
Also check privileges on remote host. 

It means that pytbull is unable to gather the alerts file with the credentials specified in the configuration file.

Check that the alerts file path is correct ([PATHS] section, param "alertsfile") and check that the user (section [FTP], param "ftpuser") is allowed to access the alerts file.

I recommend to manually perform these tests using Filezilla.

Syntax - Write your own tests

Well, want to contribute or just write your own tests? Just that easy...

Using configuration variables

Some commands (sudo, nmap, hping, ...) are specified in the configuration file (config.cfg). You can consider them as environment variables. If you write your own tests, you can call them as follows:

%{VAR}

Where:

• {VAR} represents the name of the environment variable as defined in the configuration file.

Example:

%sudo% %nmap% -sX -p 80 %target%

Notice that the old syntax still works:

self.config.get('{SECTION}', '{VAR}')

Where:

• {SECTION} represents the section name in the configuration file (e.g. 'PATHS')
• {VAR} is the name of the variable

Based on sockets

Syntax:

self.payloads.append([
  '{TEST_NAME}',
  'socket',
  {PORT},
  '{PAYLOAD}',
  '{PATTERN}'
])

Where:

• TEST_NAME: String corresponding to the test name. Example: "Simple LFI test"
• PORT: Integer. TCP port to connect to. Example: 22 (SSH)
• PAYLOAD: Payload to send. For example: "GET /index.php?page=../../../etc/passwd HTTP/1.1 Host: 127.0.0.1 User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.7.5) Gecko/20041202 Firefox/1.0 "
• PATTERN: Pattern for string matching

Example:

self.payloads.append([
  "Javascript Obfuscation",
  "socket",
  80,
  """GET /index.php?page=%sCscript%3Ealert%28%29%3C%2Fscript%3E HTTP/1.1
Host: 127.0.0.1

""",
  ""
])

Based on a command

Syntax:

self.payloads.append([
  '{TEST_NAME}',
  'command',
  {COMMAND_ARGS_ARRAY},
  '{PATTERN}'
])

Where:

• TEST_NAME: String corresponding to the test name.
• COMMAND_ARGS_ARRAY: Array of the command and arguments.
• PATTERN: Pattern for string matching

Example

self.payloads.append([
  "Full SYN Scan",
  "command",
  [self.config.get('PATHS','sudo'), self.config.get('PATHS','nmap'),
   '-sS', '-p-', self._target],
  "122:1:1"
])

Based on Scapy

Syntax

self.payloads.append([
  '{TEST_NAME}',
  'scapy',
  '{SCAPY_PAYLOAD}',
  '{PATTERN}'
])

Where

• TEST_NAME: String identifying the test
• SCAPY_PAYLOAD: String representing the Scapy payload. Example: """sr1(IP(dst="%s")/TCP(dport=1433)/"0"*1000)""" % self._target
• PATTERN: Pattern for string matching

Example

self.payloads.append([
  "Ping of death",
  "scapy",
  """send(fragment(IP(dst="%s")/ICMP()/("X"*60000)), verbose=0)""" % self._target,
  "123:"
])

Based on pcap

Syntax

self.payloads.append([
  '{TEST_NAME}',
  'pcap',
  '{PCAP_PATH}',
  '{PATTERN}'
])

Where

• TEST_NAME: String identifying the test
• PCAP_PATH: Path to pcap to be replayed
• PATTERN: Pattern for string matching

Example:

self.payloads.append([
  "test",
  "pcap",
  "pcap/test.pcap",
  "129:15:1"
])