Pike

Pike is a (nearly) pure-Python framework for writing SMB2/3 protocol correctness tests.

• Pike
  • Prerequisites
  • Install
  • Build instructions
  • Running tests
  • Kerberos Hints
  • Decoding BufferOverrun
    • With Pike
    • With Wireshark
  • License
  • Other

Prerequisites

Required for basic functionality:

• Python 2.7, 3.6+
• PyCryptodomex

Required for building kerberos library:

• Python development headers
• MIT gssapi_krb5 (plus development headers)
  • Ubuntu: krb5-user, libkrb5-dev

Optional: epydoc for doc generation

Install

$ python -m pip install pike-smb2

Build instructions

Ubuntu 14.04 / 16.04

apt-get install -y --no-install-recommends krb5-user libkrb5-dev python-dev build-essential python2.7 python-pip
pip install setuptools pycryptodomex
python setup.py install

Running tests

The tests in the test subdirectory are ordinary Python unittest tests and can be run as usual. The following environment variables are used by the tests:

PIKE_SERVER=<host name or address>
PIKE_SHARE=<share name>
PIKE_CREDS=DOMAIN\User%Passwd
PIKE_LOGLEVEL=info|warning|error|critical|debug
PIKE_SIGN=yes|no
PIKE_ENCRYPT=yes|no
PIKE_MAX_DIALECT=DIALECT_SMBX_Y_Z
PIKE_MIN_DIALECT=DIALECT_SMBX_Y_Z
PIKE_TRACE=yes|no

If PIKE_TRACE is set to yes then incoming/outgoing packets will be logged at the debug level.

$ python -m unittest discover -s pike/test -p *.py

Alternatively, to build and run all tests

$ python setup.py test

To run an individual test file

$ python -m unittest discover -s pike/test -p echo.py

To run an individual test case

$ python -m unittest pike.test.echo.EchoTest.test_echo

Kerberos Hints

Setting up MIT Kerberos as provided by many Linux distributions to interoperate with an existing Active Directory and Pike is relatively simple.

If PIKE_CREDS is not specified and the kerberos module was built while installing pike then your current Kerberos credentials will be used to authenticate.

Use a minimal /etc/krb5.conf on the client such as the following

[libdefaults]
    default_realm = AD.EXAMPLE.COM

Retrieve a ticket for the desired user

$ kinit user_1

(Optional) in leiu of DNS, add host entries for the server name + domain

$ echo "10.1.1.150    smb-server.ad.example.com" >> /etc/hosts

Run pike tests

$ PIKE_SERVER="smb-server.ad.example.com" PIKE_SHARE="C$" python -m unittest discover -s pike/test -p tree.py

Note that you will probably need to specify the server by fully-qualified hostname in order for Kerberos to figure out which ticket to use. If you get errors during session setup when using an IP address, this is probably the reason.

Decoding BufferOverrun

When pike encounters a buffer or boundary problem, BufferOverrun is raised with the full packet bytes. This can be used in two ways.

With Pike

For some problems, it may be necessary to run pike with a debugger while decoding the packet bytes to reproduce runtime parsing or decoding issues.

from binascii import unhexlify
import array
import pike.netbios

buf = array.array("B", unhexlify(b'00000114fe534d4240000000000000000000040001000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000041000100110302008a8c2a17f5f24e5eb278dd8aaa90d42e1e0000000000010000001000000010006c52c4c7e53dd60166157c68c63dd60180005500d8000000605306062b0601050502a0493047a019301706092a864886f712010202060a2b06010401823702020aa32a3028a0261b246e6f745f646566696e65645f696e5f5246433431373840706c656173655f69676e6f72650000000100260000000000010020000100c93dfb463f3e99ed9030a66d28548c330a4ae9a65856237d00e61f68c14eb09f0000020004000000000001000200'))
nb = pike.netbios.Netbios()
nb.parse(buf)

With Wireshark

Other decoding problems may be easier to understand by looking at the packet with a pcap analysis tool.

$ echo '00000114fe534d4240000000000000000000040001000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000041000100110302008a8c2a17f5f24e5eb278dd8aaa90d42e1e00000000000100000010000000100050cff0c2e43dd60166157c68c63dd60180005500d8000000605306062b0601050502a0493047a019301706092a864886f712010202060a2b06010401823702020aa32a3028a0261b246e6f745f646566696e65645f696e5f5246433431373840706c656173655f69676e6f7265000000010026000000000001002000010017af98eb38fdcd3db91bdca1303e9c72ef37b7e572abf897e47bd779aaa641d90000020004000000000001000200' \
  | xxd -r -p - \
  | od -Ax -tx1 -v \
  | text2pcap -i46 -T 445,445 - - \
  | tshark -P -V -r -

• xxd decodes the ascii hex bytestream output from the BufferOverrun exception into binary
• od dumps the output to a format wireshark can read
• text2pcap (wireshark) appends fake ethernet and IP headers to the SMB packet and writes a pcap file to stdout
• tshark (wireshark) decodes the SMB packet and displays full packet details

License

This project, pike and pike-smb2, is released under a Simplified BSD License granted by Dell Inc.'s Open Source Project program, except code under pykerb/ which is released under an Apache 2.0 License granted by Apple Inc.
All project contributions are entirely reflective of the respective author(s) and not of Dell Inc. or Apple Inc.

See file LICENSE for licensing information.

Other

There is older API documentation from epydoc.

Pike, with the exception of pykerb and certain build scripts (see below), is licensed under Simplified BSD License as follows:

Copyright © 2013-2020, Dell Inc. or its subsidiaries. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

pykerb is licensed under the terms of the Apache 2.0 license as follows:

Copyright © 2006-2009 Apple Inc. All rights reserved.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Certain build scripts such as configure and the mk directory are from the MakeKit build system (http://mkbuild.sf.net). None of these files are incorporated into the final build output. The license (3-clause BSD) is viewable at the following URL:

https://github.com/bkoropoff/makekit/blob/master/COPYING