Follow @Openwall on Twitter for new release announcements and other news
[<prev] [next>] [thread-next>] [day] [month] [year] [list]
Date: Mon, 21 May 2012 10:24:51 +0200
From: Frank Dittrich <>
Subject: bash completion for john and unique

Hi all,

I created a bash completion script for John the Ripper which supports
bash completion for john (official releases and jumbo versions) and
unique (here, bash completion only makes sense for the jumbo version,
and is limited to listing possible options mentioned in the usage output).

The attached file john.bash_completion contains some fixes for
--wordlist= completion and --restore=/--status= completion, compared to
the version in magnum's current git repository on github.

Once included in the jumbo version, this file will probably be located
in the src directory.

I'd like to get some feedback from you so that I can change the
completion logic or fix bugs before the next jumbo version is released.

To just test bash completion for john, you can download the attached
file somewhere and source it like this, if you are in the directory
where you downloaded the file:

. john.bash_completion

(It is a dot, followed by a space, followed by the file name.)

If you want to use the bash completion for john permanently, not just in
the current session, you should add this line to your ~/.bashrc file:

. /full_path_name/john.bash_completion

If you want to enable bash completion for john permanently for all users
with bash as their shell, you have to copy this file into the
/etc/bash_completion.d/ directory (admin privilege is needed).

For those of you who didn't know this already:
Bash completion means: the shell (bash) suggests possible command
completions or automatically completes the command, as far as this is
possible, when you press the [tab] key on the command line.
Pressing [tab] once adds those characters which are common between all
possible completions. Pressing [tab] twice will list all possible

In the following examples, I'll use the $ sign as a marker for the
command prompt. Imagine that the cursor is located at the end of the
command, without any trailing spaces between command and cursor.
(If the cursor is separated from the words on the command line, then the
default bash completion logic applies, which means bash suggests
existing file and directory names.)

A first, simple example:

$ ./john -wo

Pressing [tab], will automatically change the command line to

$ ./john --wordlist=

Wile john allows to specify options with just one leading dash, I use
the form mention in john's usage output for completion.
That's why - will be replaced by --.
Since there is only one john option name starting with --wo, it gets
completed to --wordlist. Since this option requires a value, bash
completion adds the =.
Actually, there is only one option starting with --w, so even
$ ./john -w
would get expanded to
$ ./john --wordlist=

Pressing [tab] on the command line

$ ./john --wordlist=

will change nothing (unless all the names of files and directories in
the current directory start with the same character).

Pressing [tab] once more will list all the file (and directory) names in
the current directory as possible completions.

Pressing [tab] twice on the command line

$ ./john --wordlist=p

will just list file names starting with p as possible completions:

$ ./john --wordlist=p   password.lst  pdf2john      pwsafe2john

Pressing [tab] once on

$ ./john --wordlist=passw

will change the command line to

$ ./john --wordlist=password.lst

(A space is added at the end of the command, so that you can just type
the next word...)

Pressing [tab] twice on the command line

$ ./john --pot=will list files with the .pot extension and directories
as possible completions:

$ ./john --pot=
fdtest/        fdtestpot.pot  john.pot

In some cases, completion options based on usage information is suggested:

$ john --test
--test          --test=SECONDS

(provided that the john version in question already supports an optional
value for the --time option)


$ ./john --markov
--markov                               --markov=LEVEL[:START[:END[:LENGTH]]]

(jumbo version only)

I implemented completion for every option known the john version you are
trying to execute.

If you find bugs or if you have suggestions for possible improvements,
please mention what you tried, what you expected, and what you got instead.
Please also include the output of these commands:

$ uname -a
$ bash --version
$ ./john | head -n 1
$ john | head -n 1
(depending on how you start john)

Also, if completion for john options doesn't work at all, please test
whether completion for other commands works.
E.g., cd into the src directory, and try completion for

$ make lin

Now to the questions I hope get some feedback:


$ ./john --make-charset=
all.chr     alpha.chr   fdtest/
alnum.chr   digits.chr  lanman.chr

As you see, the completion logic lists directories and .chr files.
Should the completion logic just list directories (or nothing at all),
to avoid accidentally overwriting an existing .chr file?


$ john -i

gets completed to

$ john --incremental

(There is no trailing space added, because the --incremental option has
optional values.)

$ john --incremental
--incremental         --incremental=Alnum   --incremental=Digits
--incremental=All     --incremental=Alpha   --incremental=LanMan

(output for a non-jumbo john version 1.7.8)

$ ./john --incremental
--incremental          --incremental=alpha    --incremental=lanman
--incremental=all      --incremental=digits
--incremental=alnum    --incremental=digits8

(output for the current git version, will be similar for next jumbo)

The above is the currently implemented default completion logic for john.
Mixed case incremental mode names indicate a hard coded list of
incremental modes.
Lower case  incremental mode names indicate a list derived from
analyzing the config file (in this case, john.conf).

So, the user will have to type the space character (to use the default
incremental mode) or the '=' character, to get completion for possible
incremental modes when pressing [tab]:

$ john --incremental=
All     Alnum   Alpha   Digits  LanMan


$ ./john --incremental=
all      alnum    alpha    digits   digits8  lanman

An alternative completion logic would replace "--incremental" with
"--incremental=" when pressing [tab], even though --incremental without
a '=' and without an incremental mode name would also be valid.

$ ./john --incremental

would then get completed to

$ ./john --incremental=

when pressing [tab].

For jumbo versions, the --rules and --single options are similar to
--incremental, because they also allow to specify an optional value.
(The official, non-jumbo version doesn't allow --rules=... or --single=...)

Because I am not sure what john users might prefer, I implemented both
versions of the completion logic.

The default logic is the one which doesn't add the trailing '=' when
pressing tab.

$ ./john --rules
--rules           --rules=single
--rules=nt        --rules=wordlist

To try the alternative logic, use

$ export __john_completion=2

This will add the trailing '=' when pressing [tab] here:
$ ./john --incremental
(jumbo and official version)

and here:
$ ./john --rules
$ ./john --single
(jumbo version only)

If you want to switch back to the default logic, just use

$ export __john_completion=1

When including the line

export __john_completion=2

into your ~/.bashrc, please note that the logic might change until the
next jumbo version is released.

Please let me know what questions / suggestions you have.
Should I add a doc/README.bash-completion file?


View attachment "john.bash_completion" of type "text/plain" (17520 bytes)

Powered by blists - more mailing lists

Confused about mailing lists and their use? Read about mailing lists on Wikipedia and check out these guidelines on proper formatting of your messages.