Impacket mssqlclient.py
Back to the Category Index / Back to the Command Index
Overview
Section titled “Overview”Connects to SQL Server over TCP or an SMB named pipe and starts an interactive shell or runs specified SQL queries. It supports SQL and Windows/Kerberos authentication.
| Item | Details |
|---|---|
| Implementation | examples/mssqlclient.py |
| Category | MSSQL / Exchange / MQTT |
| Size | 167 lines |
| Distribution | Installed as a script through scripts=examples/*.py in setup.py |
CLI and Inputs
Section titled “CLI and Inputs”Check python examples/mssqlclient.py -h for the current option definitions.
| Argument | Description |
|---|---|
target | [[domain/]username[:password]@]<targetName or address> |
-db | MSSQL database instance (default: None). |
-windows-auth | Use Windows authentication (default: false). |
-named-pipe | Connect through the specified SMB named pipe instead of TCP. |
-debug | Enable debug logging. |
-ts | Add timestamps to log output. |
-show | Display queries. |
-command | Commands to run in the SQL shell; multiple commands are accepted. |
-file | File containing commands to run in the SQL shell. |
--host-name | HostName property used when connecting to SQL Server. |
--app-name | AppName property used when connecting to SQL Server. |
--client-interface-name | CltIntName property used when connecting to SQL Server. |
-hashes | NTLM hashes in LMHASH:NTHASH format. |
-auth-smb | Credentials for the named pipe’s SMB connection, separate from SQL credentials, in [domain/]username[:password] format. |
-hashes-smb | NTLM hashes for the named pipe’s SMB connection in LMHASH:NTHASH format. |
-no-pass | Skip the password prompt (useful with -k). |
-k | Use Kerberos authentication. Read credentials from the ccache (KRB5CCNAME) based on the target; fall back to command-line credentials if none are valid. |
-aesKey | 128- or 256-bit AES key for Kerberos authentication. |
-dc-ip | Domain controller IP address. Defaults to the domain (FQDN) in target. |
-target-ip | Target machine IP address. Defaults to target; useful when the target is a NetBIOS name that cannot be resolved. |
-port | Target MSSQL port (default: 1433). |
Related technology: PRELOGIN, LOGIN7, and token streams in TDS / MQTT / Exchange.
Detailed Processing Flow
Section titled “Detailed Processing Flow”After parsing the target, the command connects through TCP or the SMB named pipe
specified by -named-pipe, then calls MSSQL.connect(), performs pre-login, and logs in.
-command / -file run batch queries; otherwise, MSSQLShell dispatches SQL and helper commands such as xp_cmdshell. Result rows and server messages are displayed from the TDS token parser.
How It Works
Section titled “How It Works”A TDS session normally proceeds through TCP connection, PRELOGIN, TLS if
needed, LOGIN7, and authentication token exchange. With -named-pipe,
an SMB connection carries the traffic through a pipe. SQL authentication
puts the username and password into LOGIN7 in TDS format; Windows
authentication exchanges NTLM/Kerberos tokens through the SSPI field.
-windows-auth switches the login mechanism, not just the username syntax.
When -windows-auth or -k is used with a named pipe, SQL Server sees
the Windows identity used for the SMB connection. With -auth-smb, these credentials may differ from those in the target argument.
After login, queries are sent as SQL Batch packets. The server returns
a token stream containing COLMETADATA, ROW, DONE, ERROR, INFO, and others.
MSSQL parses tokens in order and matches column schemas to row values.
-command and -file run batches; in interactive mode, MSSQLShell routes
local helpers and SQL text. The enum_tables helper queries sys.tables
in the current database and displays schema, table name, and type.
Database and context changes, along with transaction state, remain in the same session. Server-side procedures invoked by interactive helpers can change the target’s state, just like ordinary queries. A DONE token may follow an ERROR token, so do not confuse packet and token boundaries; display multiple result sets and NULL/type conversions correctly.
Key Implementation Elements
Section titled “Key Implementation Elements”| Symbol | Location | Entry Point for Tracing Behavior |
|---|---|---|
| module-level entry | 1 | Parses arguments and runs the operation at the top level |
Dependencies
Section titled “Dependencies”Internal Impacket Modules
Section titled “Internal Impacket Modules”| Module | Main Names Used |
|---|---|
impacket.examples | logger |
impacket.examples.mssqlshell | SQLSHELL |
impacket.examples.utils | parse_target |
impacket | tds, version |
Output, Side Effects, and Required Privileges
Section titled “Output, Side Effects, and Required Privileges”- Some operations change the target’s state. Confirm the target name, SID, and path before making changes.
Failure Paths and Cleanup
Section titled “Failure Paths and Cleanup”- Distinguish missing input files, damaged files, truncated reads, and unsupported formats.
When Changing the Implementation
Section titled “When Changing the Implementation”This command depends on impacket.tds.MSSQL, impacket.examples.mssqlshell, and Kerberos/NTLM helpers. The CLI bootstraps connections; changes to the TDS wire format belong in impacket/tds.py, while shell command changes belong in the shared shell.
Verification
Section titled “Verification”- Syntax:
python -m py_compile examples/mssqlclient.py - CLI:
python examples/mssqlclient.py -h - No test specific to this command was found. Choose shared-module tests and, if needed, a run in an isolated environment.