authoscope 0.8.1

.TH AUTHOSCOPE "1" "August 2018" "authoscope 0.6.1" "User Commands"
.SH NAME
authoscope \- scriptable network authentication cracker

.SH SYNOPSIS
.B authoscope
[\fB\-nVh\fR] command

.SH DESCRIPTION
authoscope 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 authoscope 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 authoscope runtime.

.SH OPTIONS
.TP
\fB\-n\fR, \fB\-\-workers\fR <workers>
The number of concurrent workers to run.
.TP
\fB\-o\fR, \fB\-\-output\fR <output>
Write results to this file.
.TP
\fB\-v\fR, \fB\-\-verbose\fR
Enable verbose output.
.TP
\fB\-h\fR, \fB\-\-help\fR
Prints help information.
.TP
\fB\-V\fR, \fB\-\-version\fR
Prints version information.

.SH SUBCOMMANDS
Pick one of the following subcommands.

.SS Dictionary attack
.LP
Try each password for each user with every script.
.RS
\fBauthoscope dict\fR
<\fBusers\fR>
<\fBpasswords\fR>
[\fBscripts\fR]...
.RE

.SS Credential confirmation
.LP
Load a list of credentials with the format \fBuser:password\fR and verify them
with every script.
.RS
\fBauthoscope creds\fR
<\fBcredentials\fR>
[\fBscripts\fR]...
.RE

.SS Username enumeration
.LP
Takes a list of username and verifies they exist on the system. This is still
executing the \fBverify\fR function with two arguments, but the password is set
to \fBnil\fR. You may write a script that can do both by checking the password
for nil to detect in which mode the script is executed.
.RS
\fBauthoscope enum\fR
<\fBusers\fR>
[\fBscripts\fR]...
.RE

.SS Oneshot
.LP
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.
.RS
\fBauthoscope oneshot\fR
[\fB\-x\fR]
<\fBscript\fR>
<\fBuser\fR>
[\fBpassword\fR]

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

.SS base64_decode
.LP
Decode a base64 string.
.RS
.nf
\fBbase64_decode("ww==")\fP
.fi
.RE

.SS base64_encode
.LP
Encode a binary array with base64.
.RS
.nf
\fBbase64_encode("\\x00\\xff")\fP
.fi
.RE

.SS clear_err
.LP
Clear all recorded errors to prevent a requeue.
.RS
.nf
\fBif last_err() then
    clear_err()
    return false
else
    return true
end\fP
.fi
.RE

.SS execve
.LP
Execute an external program. Returns the exit code.
.RS
.nf
\fBexecve("myprog", {"arg1", "arg2", "--arg", "3"})\fP
.fi
.RE

.SS hex
.LP
Hex encode a list of bytes.
.RS
.nf
\fBhex({0x6F, 0x68, 0x61, 0x69, 0x0A, 0x00})\fR
.fi
.RE

.SS hmac_md5
.LP
Calculate an hmac with md5. Returns a binary array.
.RS
.nf
\fBhmac_md5("secret", "my authenticated message")\fR
.fi
.RE

.SS hmac_sha1
.LP
Calculate an hmac with sha1. Returns a binary array.
.RS
.nf
\fBhmac_sha1("secret", "my authenticated message")\fR
.fi
.RE

.SS hmac_sha2_256
.LP
Calculate an hmac with sha2_256. Returns a binary array.
.RS
.nf
\fBhmac_sha2_256("secret", "my authenticated message")\fR
.fi
.RE

.SS hmac_sha2_512
.LP
Calculate an hmac with sha2_512. Returns a binary array.
.RS
.nf
\fBhmac_sha2_512("secret", "my authenticated message")\fR
.fi
.RE

.SS hmac_sha3_256
.LP
Calculate an hmac with sha3_256. Returns a binary array.
.RS
.nf
\fBhmac_sha3_256("secret", "my authenticated message")\fR
.fi
.RE

.SS hmac_sha3_512
.LP
Calculate an hmac with sha3_512. Returns a binary array.
.RS
.nf
\fBhmac_sha3_512("secret", "my authenticated message")\fR
.fi
.RE

.SS html_select
.LP
Parses an html document and returns the first element that matches the css
selector. The return value is a table with \fBtext\fR being the inner text and
\fBattrs\fR being a table of the elements attributes.
.RS
.nf
\fBcsrf = html_select(html, 'input[name="csrf"]')
token = csrf["attrs"]["value"]\fP
.fi
.RE

.SS html_select_list
.LP
Same as \fBhtml_select\fP but returns all matches instead of the first one.
.RS
.nf
\fBhtml_select_list(html, 'input[name="csrf"]')\fP
.fi
.RE

.SS http_basic_auth
.LP
Sends a \fBGET\fR request with basic auth. Returns \fBtrue\fR if no
\fBWWW-Authenticate\fR header is set and the status code is not \fB401\fR.
.RS
.nf
\fBhttp_basic_auth("https://httpbin.org/basic-auth/foo/buzz", user, password)\fP
.fi
.RE

.SS http_mksession
.LP
Create a session object. This is similar to \fBrequests.Session\fR in
python-requests and keeps track of cookies.
.RS
.nf
\fBsession = http_mksession()\fP
.fi
.RE

.SS http_request
.LP
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 \fBmethod\fR, the \fBurl\fR and additional options. Please
note that you still need to specify an empty table \fB{}\fR even if no options are
set. The following options are available:

.nf
- \fBquery\fR - a map of query parameters that should be set on the url
- \fBheaders\fR - a map of headers that should be set
- \fBbasic_auth\fR - configure the basic auth header with \fB{"user, "password"}\fR
- \fBuser_agent\fR - overwrite the default user agent with a string
- \fBjson\fR - the request body that should be json encoded
- \fBform\fR - the request body that should be form encoded
- \fBbody\fR - the raw request body as string
.fi
.RS
.nf
\fBreq = 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\fP
.fi
.RE

.SS http_send
.LP
Send the request that has been built with \fBhttp_request\fR.
Returns a table with the following keys:

.nf
- \fBstatus\fR - the http status code
- \fBheaders\fR - a table of headers
- \fBtext\fR - the response body as string
.fi
.RS
.nf
\fBreq = 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\fP
.fi
.RE

.SS json_decode
.LP
Decode a lua value from a json string.
.RS
.nf
\fBjson_decode("{\\"data\\":{\\"password\\":\\"fizz\\",\\"user\\":\\"bar\\"},\\"list\\":[1,3,3,7]}")\fP
.fi
.RE

.SS json_encode
.LP
Encode a lua value to a json string. Note that empty tables are encoded to an
empty object \fB{}\fR instead of an empty list \fB[]\fR.
.RS
.nf
\fBx = json_encode({
    hello="world",
    almost_one=0.9999,
    list={1,3,3,7},
    data={
        user=user,
        password=password,
        empty=nil
    }
})\fP
.fi
.RE

.SS last_err
.LP
Returns \fBnil\fR if no error has been recorded, returns a string otherwise.
.RS
.nf
\fBif last_err() then return end\fP
.fi
.RE

.SS ldap_bind
.LP
Connect to an ldap server and try to authenticate with the given user
.RS
.nf
\fBldap_bind("ldaps://ldap.example.com/",
    "cn=\\"" .. ldap_escape(user) .. "\\",ou=users,dc=example,dc=com", password)\fP
.fi
.RE

.SS ldap_escape
.LP
Escape an attribute value in a relative distinguished name.
.RS
.nf
\fBldap_escape(user)\fP
.fi
.RE

.SS ldap_search_bind
.LP
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.
.RS
.nf
\fBldap_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)\fP
.fi
.RE

.SS md5
.LP
Hash a byte array with md5 and return the results as bytes.
.RS
.nf
\fBhex(md5("\\x00\\xff"))\fP
.fi
.RE

.SS mysql_connect
.LP
Connect to a mysql database and try to authenticate with the provided
credentials. Returns a mysql connection on success.
.RS
.nf
\fBsock = mysql_connect("127.0.0.1", 3306, user, password)\fP
.fi
.RE

.SS mysql_query
.LP
Run a query on a mysql connection. The 3rd parameter is for prepared
statements.
.RS
.nf
\fBrows = mysql_query(sock, 'SELECT VERSION(), :foo as foo', {
    foo='magic'
})\fP
.fi
.RE

.SS print
.LP
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.
.RS
.nf
\fBprint({
    data={
        user=user,
        password=password
    }
})\fP
.fi
.RE

.SS rand
.LP
Returns a random \fBu32\fP 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.
.RS
.nf
\fBrand(0, 256)\fP
.fi
.RE

.SS randombytes
.LP
Generate the specified number of random bytes.
.RS
.nf
\fBrandombytes(16)\fP
.fi
.RE

.SS sha1
.LP
Hash a byte array with sha1 and return the results as bytes.
.RS
.nf
\fBhex(sha1("\\x00\\xff"))\fP
.fi
.RE

.SS sha2_256
.LP
Hash a byte array with sha2_256 and return the results as bytes.
.RS
.nf
\fBhex(sha2_256("\\x00\\xff"))\fP
.fi
.RE

.SS sha2_512
.LP
Hash a byte array with sha2_512 and return the results as bytes.
.RS
.nf
\fBhex(sha2_512("\\x00\\xff"))\fP
.fi
.RE

.SS sha3_256
.LP
Hash a byte array with sha3_256 and return the results as bytes.
.RS
.nf
\fBhex(sha3_256("\\x00\\xff"))\fP
.fi
.RE

.SS sha3_512
.LP
Hash a byte array with sha3_512 and return the results as bytes.
.RS
.nf
\fBhex(sha3_512("\\x00\\xff"))\fP
.fi
.RE

.SS sleep
.LP
Pauses the thread for the specified number of seconds. This is mostly used to
debug concurrency.
.RS
.nf
\fBsleep(3)\fP
.fi
.RE

.SS sock_connect
.LP
Create a tcp connection.
.RS
.nf
\fBsock = sock_connect("127.0.0.1", 1337)\fP
.fi
.RE

.SS sock_send
.LP
Send data to the socket.
.RS
.nf
\fBsock_send(sock, "hello world")\fP
.fi
.RE

.SS sock_recv
.LP
Receive up to 4096 bytes from the socket.
.RS
.nf
\fBx = sock_recv(sock)\fP
.fi
.RE

.SS sock_sendline
.LP
Send a string to the socket. A newline is automatically appended to the string.
.RS
.nf
\fBsock_sendline(sock, line)\fP
.fi
.RE

.SS sock_recvline
.LP
Receive a line from the socket. The line includes the newline.
.RS
.nf
\fBx = sock_recvline(sock)\fP
.fi
.RE

.SS sock_recvall
.LP
Receive all data from the socket until EOF.
.RS
.nf
\fBx = sock_recvall(sock)\fP
.fi
.RE

.SS sock_recvline_contains
.LP
Receive lines from the server until a line contains the needle, then return
this line.
.RS
.nf
\fBx = sock_recvline_contains(sock, needle)\fP
.fi
.RE

.SS sock_recvline_regex
.LP
Receive lines from the server until a line matches the regex, then return this
line.
.RS
.nf
\fBx = sock_recvline_regex(sock, "^250 ")\fP
.fi
.RE

.SS sock_recvn
.LP
Receive exactly n bytes from the socket.
.RS
.nf
\fBx = sock_recvn(sock, 4)\fP
.fi
.RE

.SS sock_recvuntil
.LP
Receive until the needle is found, then return all data including the needle.
.RS
.nf
\fBx = sock_recvuntil(sock, needle)\fP
.fi
.RE

.SS sock_sendafter
.LP
Receive until the needle is found, then write data to the socket.
.RS
.nf
\fBsock_sendafter(sock, needle, data)\fP
.fi
.RE

.SS sock_newline
.LP
Overwrite the default `\\n` newline.
.RS
.nf
\fBsock_newline(sock, "\\r\\n")\fP
.fi
.RE

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

.SH "SEE ALSO"
The documentation at lua.org.

.SH AUTHORS
This program was originally written and is currently maintained by kpcyrd.
Bugs and patches are welcome on github:
.LP
.RS
.I https://github.com/kpcyrd/authoscope
.RE