Account Helpers

Generated Secret Classes

Sublasses of avendesora.GeneratedSecret.

class avendesora.Password(length=12, alphabet='abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789', master=None, version=None, shift_sort=False, sep='', prefix='', suffix='')

Generate password.

Generates an arbitrary password by selecting symbols from the given alphabet at random. The entropy of the generated password is length*log2(len(alphabet)).

Parameters:
  • length (int) – The number of items to draw from the alphabet when creating the password.
  • alphabet (collection of symbols) – The reservoir of legal symbols to use when creating the password. By default the set of easily distinguished alphanumeric characters are used (avendesora.DISTINGUISHABLE). Typically you would use the pre-imported character sets to construct the alphabet. For example, you might pass: avendesora.ALPHANUMERIC + ‘+=_&%#@’
  • master (str) – Overrides the master seed that is used when generating the password. Generally, there is one master seed shared by all accounts contained in an account file. This argument overrides that behavior and instead explicitly specifies the master seed for this secret.
  • version (str) – An optional seed. Changing this value will change the generated password.
  • shift_sort (bool) – If true, the characters in the password will be sorted so that the characters that require the shift key when typing are placed last. This make the password easier to type.
  • sep (str) – A string that is placed between each symbol in the generated password.
  • prefix (str) – A string added to the front of the generated password.
  • suffix (str) – A string added to the end of the generated password.
Raises:

avendesora.SecretExhausted – The available entropy has been exhausted. This occurs when the requested length is too long.

Examples:

>>> secret = Password()
>>> secret.initialize(account, 'dux')
>>> str(secret)
'tvA8mewbbig3'

>>> secret = Password(shift_sort=True)
>>> secret.initialize(account, 'flux')
>>> str(secret)
'wrncpipvtNPF'
class avendesora.Passphrase(length=4, alphabet=None, master=None, version=None, sep=' ', prefix='', suffix='')

Generate passphrase.

Similar to Password in that it generates an arbitrary passphrase by selecting symbols from the given alphabet at random, but in this case the default alphabet is a dictionary containing about 10,000 words.

Parameters:
  • length (int) – The number of items to draw from the alphabet when creating the password.
  • alphabet (collection of symbols) – The reservoir of legal symbols to use when creating the password. By default this is a list of 10,000 words.
  • master (str) – Overrides the master seed that is used when generating the password. Generally, there is one master seed shared by all accounts contained in an account file. This argument overrides that behavior and instead explicitly specifies the master seed for this secret.
  • version (str) – An optional seed. Changing this value will change the generated password.
  • sep (str) – A string that is placed between each symbol in the generated password.
  • prefix (str) – A string added to the front of the generated password.
  • suffix (str) – A string added to the end of the generated password.
Raises:

avendesora.SecretExhausted – The available entropy has been exhausted. This occurs when the requested length is too long.

Example:

>>> secret = Passphrase()
>>> secret.initialize(account, 'dux')
>>> str(secret)
'graveyard cockle intone provider'
class avendesora.PIN(length=4, alphabet='0123456789', master=None, version=None)

Generate PIN.

Similar to Password in that it generates an arbitrary PIN by selecting symbols from the given alphabet at random, but in this case the default alphabet is the set of digits (0-9).

Parameters:
  • length (int) – The number of items to draw from the alphabet when creating the password.
  • alphabet (collection of symbols) – The reservoir of legal symbols to use when creating the password. By default the alphabet is avendesora.DIGITS.
  • master (str) – Overrides the master seed that is used when generating the password. Generally, there is one master seed shared by all accounts contained in an account file. This argument overrides that behavior and instead explicitly specifies the master seed for this secret.
  • version (str) – An optional seed. Changing this value will change the generated password.
  • sep (str) – A string that is placed between each symbol in the generated password.
  • prefix (str) – A string added to the front of the generated password.
  • suffix (str) – A string added to the end of the generated password.
Raises:

avendesora.SecretExhausted – The available entropy has been exhausted. This occurs when the requested length is too long.

Example:

>>> secret = PIN()
>>> secret.initialize(account, 'dux')
>>> str(secret)
'9301'
class avendesora.Question(question, length=3, alphabet=None, master=None, version=None, sep=' ', prefix='', suffix='', answer=None)

Generate arbitrary answer to a given question.

Similar to Passphrase() except a question must be specified when created and it is taken to be the security question. The question is used as a seed rather than the field name when generating the secret.

Parameters:
  • question (str) – The question to be answered. Be careful. Changing the question in any way will change the resulting answer.
  • length (int) – The number of items to draw from the alphabet when creating the answer.
  • alphabet (collection of symbols) – The reservoir of legal symbols to use when creating the password.
  • master (str) – Overrides the master seed that is used when generating the password. Generally, there is one master seed shared by all accounts contained in an account file. This argument overrides that behavior and instead explicitly specifies the master seed for this secret.
  • version (str) – An optional seed. Changing this value will change the generated password.
  • sep (str) – A string that is placed between each symbol in the generated password.
  • prefix (str) – A string added to the front of the generated password.
  • suffix (str) – A string added to the end of the generated password.
  • answer (str) – The answer. If provided, this would override the generated answer. May be a string, or it may be an Obscured object.
Raises:

avendesora.SecretExhausted – The available entropy has been exhausted. This occurs when the requested length is too long.

Example

>>> secret = Question('What city were you born in?')
>>> secret.initialize(account, 'dux')
>>> str(secret)
'dustcart olive label'
class avendesora.MixedPassword(length, def_alphabet, requirements, master=None, version=None, shift_sort=False)

Generate mixed password.

A relatively low level method that is used to generate passwords from a heterogeneous collection of alphabets. This is used to satisfy the character type count requirements of many websites. It is recommended that user use avendesora.PasswordRecipe rather than directly use this class.

Parameters:
  • length (int) – The number of items to draw from the various alphabets when creating the password.
  • def_alphabet (collection of symbols) – The alphabet to use when filling up the password after all the constraints are satisfied.
  • requirements (list of tuples) – Each tuple has two members, the first is a string or list that is used as an alphabet, and the second is a number that indicates how many symbols should be drawn from that alphabet.
  • master (str) – Overrides the master seed that is used when generating the password. Generally, there is one master seed shared by all accounts contained in an account file. This argument overrides that behavior and instead explicitly specifies the master seed for this secret.
  • version (str) – An optional seed. Changing this value will change the generated answer.
  • shift_sort (bool) – If true, the characters in the password will be sorted so that the characters that require the shift key when typing are placed last. This make the password easier to type.
Raises:

avendesora.SecretExhausted – The available entropy has been exhausted. This occurs when the requested length is too long.

Example:

>>> secret = MixedPassword(
...     12, ALPHANUMERIC, [(LOWERCASE, 2), (UPPERCASE, 2), (DIGITS, 2)]
... )
>>> secret.initialize(account, 'dux')
>>> str(secret)
'ZyW62fvxX0Fg'
class avendesora.PasswordRecipe(recipe, def_alphabet='abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789', master=None, version=None, shift_sort=False)

Generate password from recipe.

A version of MixedPassword where the requirements are specified with a short string rather than using the more flexible but more cumbersome method of MixedPassword. The string consists of a series of terms separated by white space. The first term is a number that specifies the total number of characters in the password. The remaining terms specify the number of characters that should be pulled from a particular class of characters. The classes are u (upper case letters), l (lower case letters), d (digits), s (punctuation), and c (an explicitly specified set of characters). For example, ‘12 2u 2d 2s’ indicates that a 12 character password should be generated that includes 2 upper case letters, 2 digits, and 2 symbols. The remaining characters will be chosen from the base character set, which by default is the set of alphanumeric characters.

Parameters:
  • recipe (str) – A string that describes how the password should be constructed.
  • def_alphabet (collection of symbols) – The alphabet to use when filling up the password after all the constraints are satisfied.
  • master (str) – Overrides the master seed that is used when generating the password. Generally, there is one master seed shared by all accounts contained in an account file. This argument overrides that behavior and instead explicitly specifies the master seed for this secret.
  • version (str) – An optional seed. Changing this value will change the generated answer.
  • shift_sort (bool) – If true, the characters in the password will be sorted so that the characters that require the shift key when typing are placed last. This make the password easier to type.
Raises:

avendesora.SecretExhausted – The available entropy has been exhausted. This occurs when the requested length is too long.

Example:

>>> secret = PasswordRecipe('12 2u 2d 2s')
>>> secret.initialize(account, 'pux')
>>> str(secret)
'*m7Aqj=XBAs7'

The c class is special in that it allow you to explicitly specify the characters to use. For example, ‘12 2c!@#$%^&=’ directs that a 12 character password be generated, 2 of which are taken from the set !@#$%^&=:

>>> secret = PasswordRecipe('12 2u 2d 2c!@#$%^&*')
>>> secret.initialize(account, 'bux')
>>> str(secret)
'YO8K^68J9oC!'
class avendesora.BirthDate(year, min_age=18, max_age=65, fmt='YYYY-MM-DD', master=None, version=None)

Generates an arbitrary birthdate for someone in a specified age range.

This function can be used to generate an arbitrary date using:

>>> secret = BirthDate(2015, 18, 65)
>>> secret.initialize(account, 'dux')
>>> str(secret)
'1970-03-22'

For year, enter the year the account that contains BirthDate was created. Doing so anchors the age range. In this example, the creation date is 2015, the minimum age is 18 and the maximum age is 65, meaning that a birthdate will be chosen such that in 2015 the birth date could correspond to someone that is between 18 and 65 years old.

You can use the fmt argument to change the way in which the date is formatted:

>>> secret = BirthDate(2015, 18, 65, fmt="M/D/YY")
>>> secret.initialize(account, 'dux')
>>> str(secret)
'3/22/70'
Parameters:
  • year (int) – The year the age range was established.
  • min_age (int) – The lower bound of the age range.
  • max_age (int) – The upper bound of the age range.
  • fmt (str) – Specifies the way the date is formatted. Consider an example date of 6 July 1969. YY and YYYY are replaced by the year (69 or 1969). M, MM, MMM, and MMMM are replaced by the month (7, 07, Jul, or July). D and DD are replaced by the day (6 or 06).
  • master (str) – Overrides the master seed that is used when generating the password. Generally, there is one master seed shared by all accounts contained in an account file. This argument overrides that behavior and instead explicitly specifies the master seed for this secret.
  • version (str) – An optional seed. Changing this value will change the generated answer.
Raises:

avendesora.SecretExhausted – The available entropy has been exhausted. This occurs when the requested length is too long.

exception avendesora.SecretExhausted(**kwargs)

Secret exhausted.

This generally results if the length of the requested secret is too long.

This exception subclasses avendesora.PasswordError.

report()

Report exception.

The inform.error() function is called with the exception arguments.

terminate()

Report exception and terminate.

The inform.fatal() function is called with the exception arguments.

Character Sets

These are useful when constructing generated secrets.

avendesora.exclude(chars, exclusions)

Exclude Characters

Use this to remove characters from a character set.

Parameters:
  • chars (str) – Character set to strip.
  • exclusions (str) – Characters to remove from character set.

Example:

>>> exclude('ABCDEF', 'AEF')
'BCD'
avendesora.LOWERCASE

Lower case ASCII letters: avendesora.LOWERCASE = “abcdefghijklmnopqrstuvwxyz”

avendesora.UPPERCASE

Upper case ASCII letters: avendesora.UPPERCASE = “ABCDEFGHIJKLMNOPQRSTUVWXYZ”

avendesora.LETTERS

Upper and lower case ASCII letters: avendesora.LETTERS = avendesora.LOWERCASE + avendesora.UPPERCASE

avendesora.DIGITS

ASCII digits: avendesora.DIGITS = “0123456789”

avendesora.ALPHANUMERIC

ASCII letters and digits: avendesora.ALPHANUMERIC = avendesora.LETTERS + avendesora.DIGITS

avendesora.HEXDIGITS

Hexidecimal digits: avendesora.HEXDIGITS = “0123456789abcdef”

avendesora.PUNCTUATION

ASCII punctuation characters: avendesora.PUNCTUATION = “!”#$%&’()*+,-./:;<=>?@[\]^_`{|}~”

avendesora.SYMBOLS

ASCII punctuation characters excluding ‘, “, `, and \: avendesora.SYMBOLS = exclude(avendesora.PUNCTUATION, “’”`")

avendesora.WHITESPACE

ASCII white space characters (excluding newlines): avendesora.WHITESPACE = ” \t”

avendesora.PRINTABLE

All ASCII printable characters (letters, digits, punctuation, whitespace): avendesora.PRINTABLE = avendesora.ALPHANUMERIC + avendesora.PUNCTUATION + avendesora.WHITESPACE

avendesora.DISTINGUISHABLE

ASCII letters and digits with easily confused characters removed: avendesora.DISTINGUISHABLE = exclude(avendesora.ALPHANUMERIC, ‘Il1O0’)

avendesora.SHIFTED

ASCII characters that are typed using the shift key: avendesora.SHIFTED = avendesora.UPPERCASE + ‘~!@#$%^&*()_+{}|:”<>?’

Obscured Secret Classes

Sublasses of avendesora.ObscuredSecret.

class avendesora.Hide(plaintext, secure=True)

Hide text

Marks a value as being secret.

Parameters:
  • plaintext (str) – The value of interest.
  • secure (bool) – Indicates that this secret is of high value and so should not be found in an unencrypted accounts file.
class avendesora.Hidden(encoded_text, secure=True, encoding=None)

Hidden text

This encoding obscures but does not encrypt the text.

Parameters:
  • encoded_text (str) – The value of interest encoded in base64.
  • secure (bool) – Indicates that this secret is of high value and so should not be found in an unencrypted accounts file.
  • encoding (str) – The encoding to use for the decoded text.
Raises:

avendesora.PasswordError – invalid value.

class avendesora.GPG(ciphertext, secure=True, encoding=None)

GPG encrypted text

The secret is fully encrypted with GPG. Both symmetric encryption and key-based encryption are supported.

Parameters:
  • ciphertext (str) – The secret encrypted and armored by GPG.
  • encoding (str) – The encoding to use for the deciphered text.
Raises:

avendesora.PasswordError – invalid value.

Recognizer Classes

class avendesora.RecognizeAll(*recognizers, **kwargs)

Run script if all recognizers match.

Takes one or more recognizers. Script is run if all recognizers match.

Parameters:
  • recognizer (Recognizer) – One or more instances of Recognizer.
  • script (str or True) –

    A script that indicates the text that should be typed to active application. The names of fields can be included in the script surrounded by braces, in which case the value of the field replaces the field reference. For example:

    Script('username: {username}, password: {passcode}')
    

    In this case, {username} and {passcode} are replaced by with the value of the corresponding account attribute. In addition to the fields, {tab} and {return} are replaced by a tab or carriage return character, and {sleep N} causes the typing to pause for N seconds.

    If True is give, the default field is produced followed by a return.

Raises:

avendesora.PasswordError

class avendesora.RecognizeAny(*recognizers, **kwargs)

Run script if any recognizers match.

Takes one or more recognizers. Script is run if any recognizers match.

Parameters:
  • recognizer (Recognizer) – One or more instances of Recognizer.
  • script (str or True) –

    A script that indicates the text that should be typed to active application. The names of fields can be included in the script surrounded by braces, in which case the value of the field replaces the field reference. For example:

    Script('username: {username}, password: {passcode}')
    

    In this case, {username} and {passcode} are replaced by with the value of the corresponding account attribute. In addition to the fields, {tab} and {return} are replaced by a tab or carriage return character, and {sleep N} causes the typing to pause for N seconds.

    If True is give, the default field is produced followed by a return.

Raises:

avendesora.PasswordError

class avendesora.RecognizeTitle(*titles, **kwargs)

Run script if window title matches.

Takes one or more glob strings. Script is run if window title matches any of the glob strings.

Parameters:
  • title (str) – One or more glob strings.
  • script (str or True) –

    A script that indicates the text that should be typed to active application. The names of fields can be included in the script surrounded by braces, in which case the value of the field replaces the field reference. For example:

    Script('username: {username}, password: {passcode}')
    

    In this case, {username} and {passcode} are replaced by with the value of the corresponding account attribute. In addition to the fields, {tab} and {return} are replaced by a tab or carriage return character, and {sleep N} causes the typing to pause for N seconds.

    If True is give, the default field is produced followed by a return.

Raises:

avendesora.PasswordError

class avendesora.RecognizeURL(*urls, **kwargs)

Run script if URL matches.

Takes one or more URLs. Script is run if URL embedded in window title matches any of the given URLs. Assumes that a browser plugin has embedded the URL in the browser’s window title. This is generally safer and more robust that RecognizeTitle when trying to match web pages.

When giving the URL, anything specified must match and globbing is not supported. If you give a partial path, by default Avendesora will match up to what you have given, but you can require an exact match of the entire path by specifying exact_path=True to RecognizeURL. If you do not give the protocol, the default_protocol (https) is assumed.

Parameters:
  • url (str) – One or more URLs.
  • exact_path (bool) – If True, path given in the URL must be matched completely, partial matches are ignored.
  • script (str or True) –

    A script that indicates the text that should be typed to active application. The names of fields can be included in the script surrounded by braces, in which case the value of the field replaces the field reference. For example:

    Script('username: {username}, password: {passcode}')
    

    In this case, {username} and {passcode} are replaced by with the value of the corresponding account attribute. In addition to the fields, {tab} and {return} are replaced by a tab or carriage return character, and {sleep N} causes the typing to pause for N seconds.

    If True is give, the default field is produced followed by a return.

Raises:

avendesora.PasswordError

class avendesora.RecognizeCWD(*dirs, **kwargs)

Run script if current working directory matches.

Takes one or more paths. Script is run if any path refers to the current working directory.

Parameters:
  • path (str) – One or more directory paths.
  • script (str or True) –

    A script that indicates the text that should be typed to active application. The names of fields can be included in the script surrounded by braces, in which case the value of the field replaces the field reference. For example:

    Script('username: {username}, password: {passcode}')
    

    In this case, {username} and {passcode} are replaced by with the value of the corresponding account attribute. In addition to the fields, {tab} and {return} are replaced by a tab or carriage return character, and {sleep N} causes the typing to pause for N seconds.

    If True is give, the default field is produced followed by a return.

Raises:

avendesora.PasswordError

class avendesora.RecognizeHost(*hosts, **kwargs)

Run script if host name matches.

Takes one or more host names. Script is run if the current host name matches one of the given host names.

Parameters:
  • host (str) – One or more host names.
  • script (str or True) –

    A script that indicates the text that should be typed to active application. The names of fields can be included in the script surrounded by braces, in which case the value of the field replaces the field reference. For example:

    Script('username: {username}, password: {passcode}')
    

    In this case, {username} and {passcode} are replaced by with the value of the corresponding account attribute. In addition to the fields, {tab} and {return} are replaced by a tab or carriage return character, and {sleep N} causes the typing to pause for N seconds.

    If True is give, the default field is produced followed by a return.

Raises:

avendesora.PasswordError

class avendesora.RecognizeUser(*users, **kwargs)

Run script if user name matches.

Takes one or more user names. Script is run if the current user name matches one of the given user names.

Parameters:
  • user (str) – One or more user names.
  • script (str or True) –

    A script that indicates the text that should be typed to active application. The names of fields can be included in the script surrounded by braces, in which case the value of the field replaces the field reference. For example:

    Script('username: {username}, password: {passcode}')
    

    In this case, {username} and {passcode} are replaced by with the value of the corresponding account attribute. In addition to the fields, {tab} and {return} are replaced by a tab or carriage return character, and {sleep N} causes the typing to pause for N seconds.

    If True is give, the default field is produced followed by a return.

Raises:

avendesora.PasswordError

class avendesora.RecognizeEnvVar(name, value, script=True)

Run script if environment variable matches.

Script is run if the environment variable exists and its value matches the value given.

Parameters:
  • name (str) – Name of environment variable.
  • value (str) – Value of environment variable.
  • script (str or True) –

    A script that indicates the text that should be typed to active application. The names of fields can be included in the script surrounded by braces, in which case the value of the field replaces the field reference. For example:

    Script('username: {username}, password: {passcode}')
    

    In this case, {username} and {passcode} are replaced by with the value of the corresponding account attribute. In addition to the fields, {tab} and {return} are replaced by a tab or carriage return character, and {sleep N} causes the typing to pause for N seconds.

    If True is give, the default field is produced followed by a return.

Raises:

avendesora.PasswordError

class avendesora.RecognizeNetwork(*macs, **kwargs)

Recognize network from MAC address.

Matches if any of the MAC addresses reported by /sbin/arp match any of those given as an argument.

Parameters:
  • mac (str) – MAC address given in the form: ‘00:c9:a9:f7:30:00’.
  • script (str or True) –

    A script that indicates the text that should be typed to active application. The names of fields can be included in the script surrounded by braces, in which case the value of the field replaces the field reference. For example:

    Script('username: {username}, password: {passcode}')
    

    In this case, {username} and {passcode} are replaced by with the value of the corresponding account attribute. In addition to the fields, {tab} and {return} are replaced by a tab or carriage return character, and {sleep N} causes the typing to pause for N seconds.

    If True is give, the default field is produced followed by a return.

Raises:

avendesora.PasswordError

class avendesora.RecognizeFile(filepath, contents=None, wait=60, **kwargs)

Recognize file.

Matches if file exists and was created within the last few seconds.

Parameters:
  • filepath (str) – Path to file.
  • contents (str) – Expected file contents. If given, should match contents of file.
  • wait (float) – Do not match if file is older than this value (seconds).
  • script (str or True) –

    A script that indicates the text that should be typed to active application. The names of fields can be included in the script surrounded by braces, in which case the value of the field replaces the field reference. For example:

    Script('username: {username}, password: {passcode}')
    

    In this case, {username} and {passcode} are replaced by with the value of the corresponding account attribute. In addition to the fields, {tab} and {return} are replaced by a tab or carriage return character, and {sleep N} causes the typing to pause for N seconds.

    If True is give, the default field is produced followed by a return.

Raises:

avendesora.PasswordError

Utility Classes

class avendesora.Script(script='username: {username}, password: {passcode}')

Takes a string that contains attributes. Those attributes are expanded before being output. For example:

Script('username: {username}, password: {passcode}')

In this case, {username} and {passcode} are replaced by with the value of the corresponding account attribute. In addition to the account attributes, {tab} and {return} are replaced by a tab or carriage return character.

Parameters:script (str) – The script.
Raises:avendesora.PasswordError – attribute not found.