Rules are a small language for modifying password candidates. They can change, remove, or add characters and can use conditions to reject candidates. -r works in every attack mode.

Why use a specialized rule language instead of regular expressions? Rules are designed to transform candidate passwords efficiently inside hashcat's candidate-generation pipeline. Regular expressions are useful for describing text patterns, but they are not a drop-in replacement for hashcat's candidate transformations.

hashcat's rule syntax shares many operations with John the Ripper and PasswordsPro, but compatibility is not guaranteed. The same rule letter can have different behavior or argument handling between tools, so check the documentation before reusing a rule file.

The following operations have corresponding functions in John the Ripper and PasswordsPro. Check each tool's documentation for differences in behavior and arguments before reusing rules.

• * Indicates that N starts at 0. For character positions other than 0-9 use A-Z (A=10)
• + Indicates that the operation is available with command-line rules (-j or -k).
• # Changed in oclHashcat v1.37 → v1.38 and hashcat v0.51 → v0.52

NOTE: Reject rules only work either with hashcat-legacy, or when using “-j” or “-k” with hashcat. They will not work as regular rules (in a rule file) with hashcat.

• * Indicates that N starts at 0. For character positions other than 0-9 use A-Z (A=10)

The following functions are not available in John the Ripper and/or PasswordsPro:

• * Indicates that N starts at 0. For character positions other than 0-9 use A-Z (A=10)
• + Only in JtR?
• # In beta or not yet released

You can use '\xNN' syntax to use hex bytes in rules.

$ echo "Penguin" | hashcat -j '$\x64' --stdout
Penguind

This is useful for non-printable ASCII characters, multibyte work, etc.

You may need to use double quotes for the rule with some shells (Windows Command Prompt, etc.)

To write useful rules, first identify the patterns you want to test. This usually means analyzing plaintext passwords to find common patterns. For example, people often append a digit to strengthen a password. This gives us two parameters:

• We want to append something.
• The value we want to append is a digit.

If we take a look at the function overview we see that we can append something using the '$' function. So, for example, if we want to add a “1” to our password, we write a rule that looks like this.

$1

To try all numbers 1 - 9, use a Hybrid attack. See that page for details.

Also note:

• Whitespace is ignored unless it is used as a parameter. This lets you format the rules for readability.
• To comment out some text, it has to start with a “#” char.

There are two ways to automatically “generate” rules.

• Using the maskprocessor, we have a dedicated article on this topic here: Using maskprocessor to create rules.
• Using random rules, see below.

hashcat can generate random rules for the current session. This can be useful after you have tried all your existing rules on all your dictionaries. There are three configuration parameters:

Generates NUM rules to be applied to each attempt:

--generate-rules=NUM

Specifies the number of functions that should be used (minimum to maximum range):

--generate-rules-func-min=NUM
--generate-rules-func-max=NUM

You can also specify the pool of functions that the rule engine will select from:

--generate-rules-func-sel=[function list]

… such as:

--generate-rules-func-sel=ioTlc

This number can be unlimited but large numbers are not recommended. When used in conjunction with -g, any rule outside of this setting will be ignored.

For example, it could generate “l r”, “l ^f”, and “sa@”. These are all valid rules. However, “l ^f sa@ r $3” would be ignored because it contains 5 functions. Default: min=1 max=4

This is useful with the rule generator and for statistical analysis of your rulesets.

To save any rule that generated a matched password use these switches:

--debug-mode=1 --debug-file=matched.rule

This will save the matched rule on every match, so the resulting rule file might contain many duplicate rules.

At high cracking speeds, this may slow the attack slightly. At lower speeds, the impact is likely negligible.

To verify that a rule does what you want, use the --stdout switch and omit the hashlist.

Here is an example:

Create a small dictionary:

$ echo WORd > word

Generate a simple rule. The “c” rule capitalizes the first letter and lower-cases the rest.

$ echo c > rule

And that's how we see the generated debug output:

$ ./hashcat -r rule --stdout word
Word

This feature also provides a fast password candidate generator. You can feed its output to an external program that reads from stdin.

Character Class Commands were added in 7.0.0, expanding the rule logic and bringing hashcat's behavior more in line with John the Ripper.

Only a limited set of character classes is supported (?l, ?u, ?d, ?h, ?H, ?s).

Syntax is similar to John the Ripper's, using the ~ symbol at the beginning of each command.

Supported on both CPU and GPU:

Supported only on CPU:

Both eX and ~e?C leave the separator itself alone and upper case the letter after a whole run of separators rather than after each one. A run counts once, so e- on foo–bar gives Foo–Bar rather than upper casing twice, and a separator that is itself a letter keeps its own case:

$ printf 'foo--bar\nfoobar\n' | hashcat --stdout -j e-
Foo--Bar
Foobar

$ printf 'foo--bar\nfoobar\n' | hashcat --stdout -j eo
Foo--bar
FooBar

Under eo the separator is o, so in foobar both of them stay lower case and the b after the run of them is upper cased.

Applies to master. The three rule engines disagreed about this until after 8.0.0. The host engine behind -j and -k preserved separators, while the GPU engines lower cased everything including the separator and upper cased the letter after each separator, so eo on foobar gave FooBar on the host and FoOBar on the GPU. For the letter classes ~e?l, ~e?u, ~e?h and ~e?H the host followed the GPU instead. The optimized engine also skipped a class rule when the word held no character of that class, so ~e?s left foobar unchanged rather than producing Foobar. All three now behave as described above. Results differ from 8.0.0 only where a separator is a letter, since digits, symbols and spaces have no case, and in that optimized-engine case.

NOTE: rules that use the 'p' character position code work only with the '-j' or '-k' command-line options.

The 'p' character position code (see Github here) memorizes the position of the Nth instance of a character, and makes that position available for use in rules that work with positions within the string. 'p' becomes available automatically when using '%' (reject plains unless they have at least X occurrences of a specific character) and '/' (reject plains that do not contain a specific character).

To operate only on the first instance of a character, use %1s or '/':

$ echo -n 'Odessa77' | hashcat --stdout -j '%1s Dp ip$'
Ode$sa77
$ echo -n 'Odessa77' | hashcat --stdout -j '/s Dp ip$'
Ode$sa77

If you only want to operate on the second instance:

$ echo -n 'Odessa77' | hashcat --stdout -j '%2s Dp ip$'
Odes$a77

… etc. Unlike the 's' rule, which replaces all instances of a character, this allows selection of which instance of a character to replace.

You can also use this functionality to replace one character with multiple characters:

$ echo -n 'p@ssW0rd' | hashcat --stdout -j '%1W DpM ip/ ip\ ip/ ip\'
p@ss\/\/0rd

In the examples below, the '%2s' portion of the rule means “reject plains unless they have at least two 's' characters”. The 'p' then refers to the position of the second 's' character.

See rules/ folder in hashcat-legacy or hashcat for examples.

The release of oclHashcat-plus v0.07 introduced a new feature for rule-based cracking.

Instead of just giving one -r parameter and a file, you can now add as many -r's as you want.

They are not executed in a sequence!

Every rule from each rule file is combined with every rule from the other rule files. This lets you build custom combinations of rules.

$ cat 123.rule
$1
$2
$3

$ cat abc.rule
$a
$b
$c

$ hashcat --stdout -r 123.rule -r abc.rule wordlist
hashcat1a
hashcat2a
hashcat3a
hashcat1b
hashcat2b
hashcat3b
hashcat1c
hashcat2c
hashcat3c

Because the total number of generated rules is the product of all lists, stacking multiple large lists can quickly exceed available memory. But a few well-chosen rules can be stacked to great effect.

This attack is currently supported by:

• hashcat
• hashcat-legacy

With hashcat, both the number of functions in a single rule line and the total number of functions in combined rules are limited to 31.