Using CaptainCredz

Command-line parameters

usage: captaincredz.py [-h] -c CONFIG [-w WEEKDAY_WARRIOR]

options:
  -h, --help            show this help message and exit
  -c CONFIG, --config CONFIG
                        Configure CaptainCredz using config file config.json
  -w WEEKDAY_WARRIOR, --weekday_warrior WEEKDAY_WARRIOR
                        Weekday Warrior config file. Only active when specified

The command-line parameters are minimalist. A configuration file is needed, which will describe all the characteristics of your spray.

Additionally, you may want to specify a Weekday Warrior configuration file if you need a finer control over your spray timings.

Configuration files

Main config file

{
  "plugins" : [
    {
      "name": "test",
      "args": {
        "FIXME": "http://FIXME"
      },
      "headers": null,
      "proxy": null,
      "useragentfile": null,
      "weight": 1,
      "req_timeout": 60
    }
  ],
  "post_actions": {
    "display_cookies": {
      "trigger":["success"],
      "params": {"text": "Example param"}
    }
  },
  
  "userfile" : "FIXME",
  "passwordfile" : "FIXME",
  "userpassfile" : "",
  
  "jitter" : 0,
  "delay_req" : 4,
  "delay_user" : 30,
  "chunk_size": 50,
  "chunk_delay": 8,
  
  "stop_on_success": false,
  "stop_worker_on_success": false,
  
  "log_file" : null,
  "cache_file": null,
  
  "verbose" : true
}

Here are all the parameters you can tweak:

plugins

List of plugins (one or more) to use for the spray. A plugin is a JSON object with the following keys:

• name : name of the plugin. This should match the name of the folder in the plugins/ folder
• args (optional, default=[]) : plugin arguments. Some plugins require one or more arguments (like the URL of the target instance) to be present here. More details on the required plugin arguments are available when you first launch a plugin
• headers (optional, default=null/None) : if you need additional headers to be sent along with the requests on this plugin
• proxy (optional, default=null/None) : if you want this plugin to use a proxy (for instance ipspinner to rotate IP addresses)
• useragentfile (optional, default=null/None) : if you want the User-Agent header of the requests to be randomized from a list, specify it here
• weight (optional, default=1) : in case you have multiple plugins and want each one to be picked with a specific probability
• req_timeout (optional, default=60) : requests will timeout and throw exceptions (resulting in an attempt "bug", credentials retried later) after this much time has elapsed and no response is received from the server

post_actions

A post-action is a Python function triggered when an event is triggered by CaptainCredz. These functions are located in the post_actions sub-directory.

This config parameter is a mapping "post_action_name":{"trigger":array, "params":mapping}, where the "trigger" value is an array which may contain one or more of the following events names : "error" (when an exception is thrown by the plugin), "success" (when valid credentials are found), "potential" (when CaptainCredz is unsure about some credentials validity), "failure" (when invalid credentials are found), "inexistant" (when a user does not exist)

userfile

Path to the file containing the list of users. List must be one user per line.

If you spray on multiple plugins, the usernames for each plugins must be semicolon-separated. An example follows, for 3 plugins :

jack;CORP\jack;[email protected]
bob;CORP\bob;[email protected]
...

The usernames will be matched with the plugins in the order they appear in the configuration file.

passwordfile

Path to the file containing the list of passwords to spray for every user. List must be one password per line.

userpassfile

Path to the file containing the list of user:password pairs to spray, in addition to the userfile and passwordfile. List must be one user:password per line.

If you spray on multiple plugins, the usernames for each plugins must be semicolon-separated. An example follows, for 3 plugins :

jack;CORP\jack;[email protected]:jackspassword
bob;CORP\bob;[email protected]:bobsdogname
...

The usernames will be matched with the plugins in the order they appear in the configuration file.

log_file

Path of the file where to log CaptainCredz output, in addition to stdout. If null, default path is ./captaincredz.log. Logs are appended at the end of file if it is already present.

cache_file

Path to CaptainCredz cache database. Default is ./cache.db

jitter

Randomization of delay, in seconds. A random number between 0 and jitter is added to every delay in CaptainCredz.

delay_req

Minimum delay between two authentication requests (common to all plugins), in seconds.

delay_user

Minimum delay between two authentication requests on the same user (common to all plugins), in seconds.

chunk_size

A pause of chunk_delay seconds is performed after every chunk_size requests (common to all plugins). Set to 0 to disable this behavior.

chunk_delay

Minimum delay between two chunks, in seconds.

verbose

Flag to enable more verbose output.

Weekday Warrior config file

The Weekday Warrior feature consists of a variable time multiplier, basically controlling how fast time is flowing. It produces a factor between 0 and 1, which means CaptainCredz may never run faster than the values you set in the main config file. For example, if the current hours_factor is 0.7 and the current days_factor is 0.4, this multiplier's value will be 0.7*0.4 (= 0.28), and as such, the "clocks" controlling the various delays will run approximately 4 times slower.

An additional parameter called daily_speedup allows to have a gradual rampup of this multiplier. The rampup factor is calculated as the initial_speed times nb_days_since_start * (self.delays["ww"]["daily_speedup"] - 1) + 1, and is capped at 1. As such, if you set daily_speedup to 1.2 and initial_speed to 0.6, you will have the following rampup factor:

• At the start, rampup_factor = 0.6
• After 1 day, rampup_factor = 0.72
• After 2 days, rampup_factor = 0.84
• After 3 days, rampup_factor = 0.96
• After 4 days, rampup_factor = 1
• After 5 days, rampup_factor = 1
• ...

The true formula for the global weekday_warrior factor controlling the clocks speed at a given time is as follows: total_factor = days_factor*hours_factor*rampup_factor. This factor will smoothly evolve over the duration of your spray thanks to the above formulas.

After every login attempt, the tool will wait for delay_req + random(0, jitter) seconds (potentially altered by weekday_warrior). It will also set a timer for delay_user + random(0, jitter) seconds (also potentially altered by weekday_warrior) before marking the user as ready-to-be-sprayed again.

Example Wekday Warrior config file:

{
    "utc_offset" : 0,
    "daily_speedup": 1.25,
    "initial_speed": 0.5,
    "hours_factor": {
        "0": 0.1,
        "1": 0.1,
        "2": 0.1,
        "3": 0.1,
        "4": 0.1,
        "5": 0.1,
        "6": 0.2,
        "7": 0.5,
        "8": 1,
        "9": 1,
        "10": 0.8,
        "11": 0.4,
        "12": 0.6,
        "13": 0.8,
        "14": 0.5,
        "15": 0.5,
        "16": 0.5,
        "17": 0.5,
        "18": 0.6,
        "19": 0.3,
        "20": 0.2,
        "21": 0.1,
        "22": 0.1,
        "23": 0.1
    },
    "days_factor": {
        "mon": 1,
        "tue": 1,
        "wed": 1,
        "thu": 1,
        "fri": 1,
        "sat": 0.1,
        "sun": 0.1
    }
}