BADTOUCH(1)

NAME
badtouch - scriptable network authentication cracker

SYNOPSIS
badtouch [-nVh] command

DESCRIPTION
badtouch is a scriptable network authentication cracker. While the space for common service bruteforce is already very well saturated, you may still end up writing your own python scripts when testing credentials for web applications. The scope of badtouch is specifically cracking custom services. This is done by writing scripts that are loaded into a lua runtime. Those scripts represent a single service and provide a `verify(user, password)` function that returns either true or false. Concurrency, progress indication and reporting is magically provided by the badtouch runtime.

OPTIONS

-n, --workers <workers>
    The number of concurrent workers to run.

-o, --output <output>
    Write results to this file.

-v, --verbose
    Enable verbose output.

-h, --help
    Prints help information.

-V, --version
    Prints version information.

SUBCOMMANDS
Pick one of the following subcommands.

  Dictionary attack

Try each password for each user with every script.
    badtouch dict <users> <passwords> [scripts]...

  Credential confirmation

Load a list of credentials with the format user:password and verify them with every script.
    badtouch creds <credentials> [scripts]...

  Username enumeration

Takes a list of username and verifies they exist on the system. This is still executing the verify function with two arguments, but the password is set to nil. You may write a script that can do both by checking the password for nil to detect in which mode the script is executed.
    badtouch enum <users> [scripts]...

  Oneshot

Test a single username-password combination using a specific script. This command is also useful when developing a new script. If the password argument is omitted, the script is executed in enumerate mode. If you want to use this command in scripts, set -x so the exitcode is set to 2 if the credentials are invalid.
    badtouch oneshot [-x] <script> <user> [password]

RUNTIME REFERENCE
The badtouch runtime provides a number of functions that can be used to test target systems.

  base64_decode

Decode a base64 string.
    base64_decode("ww==")

  base64_encode

Encode a binary array with base64.
    base64_encode("\x00\xff")

  clear_err

Clear all recorded errors to prevent a requeue.
    if last_err() then
        clear_err()
        return false
    else
        return true
    end

  execve

Execute an external program. Returns the exit code.
    execve("myprog", {"arg1", "arg2", "--arg", "3"})

  hex

Hex encode a list of bytes.
    hex({0x6F, 0x68, 0x61, 0x69, 0x0A, 0x00})

  hmac_md5

Calculate an hmac with md5. Returns a binary array.
    hmac_md5("secret", "my authenticated message")

  hmac_sha1

Calculate an hmac with sha1. Returns a binary array.
    hmac_sha1("secret", "my authenticated message")

  hmac_sha2_256

Calculate an hmac with sha2_256. Returns a binary array.
    hmac_sha2_256("secret", "my authenticated message")

  hmac_sha2_512

Calculate an hmac with sha2_512. Returns a binary array.
    hmac_sha2_512("secret", "my authenticated message")

  hmac_sha3_256

Calculate an hmac with sha3_256. Returns a binary array.
    hmac_sha3_256("secret", "my authenticated message")

  hmac_sha3_512

Calculate an hmac with sha3_512. Returns a binary array.
    hmac_sha3_512("secret", "my authenticated message")

  html_select

Parses an html document and returns the first element that matches the css selector. The return value is a table with text being the inner text and attrs being a table of the elements attributes.
    csrf = html_select(html, 'input[name="csrf"]')
    token = csrf["attrs"]["value"]

  html_select_list

Same as html_select but returns all matches instead of the first one.
    html_select_list(html, 'input[name="csrf"]')

  http_basic_auth

Sends a GET request with basic auth. Returns true if no WWW-Authenticate header is set and the status code is not 401.
    http_basic_auth("https://httpbin.org/basic-auth/foo/buzz", user, password)

  http_mksession

Create a session object. This is similar to requests.Session in python-requests and keeps track of cookies.
    session = http_mksession()

  http_request

Prepares an http request. The first argument is the session reference and cookies from that session are copied into the request. After the request has been sent, the cookies from the response are copied back into the session. The next arguments are the method, the url and additional options. Please note that you still need to specify an empty table {} even if no options are set. The following options are available:
- query - a map of query parameters that should be set on the url
- headers - a map of headers that should be set
- basic_auth - configure the basic auth header with {"user, "password"}
- user_agent - overwrite the default user agent with a string
- json - the request body that should be json encoded
- form - the request body that should be form encoded
- body - the raw request body as string
    req = http_request(session, 'POST', 'https://httpbin.org/post', {
        json={
            user=user,
            password=password,
        }
    })
    resp = http_send(req)
    if last_err() then return end
    if resp["status"] ~= 200 then return "invalid status code" end

  http_send

Send the request that has been built with http_request. Returns a table with the following keys:
- status - the http status code
- headers - a table of headers
- text - the response body as string
    req = http_request(session, 'POST', 'https://httpbin.org/post', {
        json={
            user=user,
            password=password,
        }
    })
    resp = http_send(req)
    if last_err() then return end
    if resp["status"] ~= 200 then return "invalid status code" end

  json_decode

Decode a lua value from a json string.
    json_decode("{\"data\":{\"password\":\"fizz\",\"user\":\"bar\"},\"list\":[1,3,3,7]}")

  json_encode

Encode a lua value to a json string. Note that empty tables are encoded to an empty object {} instead of an empty list [].
    x = json_encode({
        hello="world",
        almost_one=0.9999,
        list={1,3,3,7},
        data={
            user=user,
            password=password,
            empty=nil
        }
    })

  last_err

Returns nil if no error has been recorded, returns a string otherwise.
    if last_err() then return end

  ldap_bind

Connect to an ldap server and try to authenticate with the given user
    ldap_bind("ldaps://ldap.example.com/",
        "cn=\"" .. ldap_escape(user) .. "\",ou=users,dc=example,dc=com", password)

  ldap_escape

Escape an attribute value in a relative distinguished name.
    ldap_escape(user)

  ldap_search_bind

Connect to an ldap server, log into a search user, search for the target user and then try to authenticate with the first DN that was returned by the search.
    ldap_search_bind("ldaps://ldap.example.com/",
        -- the user we use to find the correct DN
        "cn=search_user,ou=users,dc=example,dc=com", "searchpw",
        -- base DN we search in
        "dc=example,dc=com",
        -- the user we test
        user, password)

  md5

Hash a byte array with md5 and return the results as bytes.
    hex(md5("\x00\xff"))

  mysql_connect

Connect to a mysql database and try to authenticate with the provided credentials. Returns a mysql connection on success.
    sock = mysql_connect("127.0.0.1", 3306, user, password)

  mysql_query

Run a query on a mysql connection. The 3rd parameter is for prepared statements.
    rows = mysql_query(sock, 'SELECT VERSION(), :foo as foo', {
        foo='magic'
    })

  print

Prints the value of a variable. Please note that this bypasses the regular writer and may interfer with the progress bar. Only use this for debugging.
    print({
        data={
            user=user,
            password=password
        }
    })

  rand

Returns a random u32 with a minimum and maximum constraint. The return value can be greater or equal to the minimum boundary, and always lower than the maximum boundary. This function has not been reviewed for cryptographic security.
    rand(0, 256)

  randombytes

Generate the specified number of random bytes.
    randombytes(16)

  sha1

Hash a byte array with sha1 and return the results as bytes.
    hex(sha1("\x00\xff"))

  sha2_256

Hash a byte array with sha2_256 and return the results as bytes.
    hex(sha2_256("\x00\xff"))

  sha2_512

Hash a byte array with sha2_512 and return the results as bytes.
    hex(sha2_512("\x00\xff"))

  sha3_256

Hash a byte array with sha3_256 and return the results as bytes.
    hex(sha3_256("\x00\xff"))

  sha3_512

Hash a byte array with sha3_512 and return the results as bytes.
    hex(sha3_512("\x00\xff"))

  sleep

Pauses the thread for the specified number of seconds. This is mostly used to debug concurrency.
    sleep(3)

  sock_connect

Create a tcp connection.
    sock = sock_connect("127.0.0.1", 1337)

  sock_send

Send data to the socket.
    sock_send(sock, "hello world")

  sock_recv

Receive up to 4096 bytes from the socket.
    x = sock_recv(sock)

  sock_sendline

Send a string to the socket. A newline is automatically appended to the string.
    sock_sendline(sock, line)

  sock_recvline

Receive a line from the socket. The line includes the newline.
    x = sock_recvline(sock)

  sock_recvall

Receive all data from the socket until EOF.
    x = sock_recvall(sock)

  sock_recvline_contains

Receive lines from the server until a line contains the needle, then return this line.
    x = sock_recvline_contains(sock, needle)

  sock_recvline_regex

Receive lines from the server until a line matches the regex, then return this line.
    x = sock_recvline_regex(sock, "^250 ")

  sock_recvn

Receive exactly n bytes from the socket.
    x = sock_recvn(sock, 4)

  sock_recvuntil

Receive until the needle is found, then return all data including the needle.
    x = sock_recvuntil(sock, needle)

  sock_sendafter

Receive until the needle is found, then write data to the socket.
    sock_sendafter(sock, needle, data)

  sock_newline

Overwrite the default `\n` newline.
    sock_newline(sock, "\r\n")

SECURITY
To report a security issue please contact kpcyrd on ircs://irc.hackint.org.

SEE ALSO
The documentation at lua.org.

AUTHORS
This program was originally written and is currently maintained by kpcyrd. Bugs and patches are welcome on github:

    https://github.com/kpcyrd/badtouch