pudl¶

Overview¶

pudl is a bundled command-line interface which wraps much of the functionality present in the pudl package modules. Not only does it demonstrate usage of the functionality present in pudl package modules, it also perhaps serves as a reasonable alternative to ldapsearch for the most common types of queries. With its simplified interface (and contrary to ldapsearch), there is no need to create custom ldap filters. Additionally, pudl has the added benefits of regular expression object filtering and object serialization, in json or yaml format. Note that all values returned are strings.

Environment Variables¶

To keep the pudl syntax as simple and minimal as possible, setting a few environment variables and adding them to an init file such as ~/.bashrc is advised:

PUDL_BASE_DN - This is an important one to set, such as ‘OU=Departments,DC=example,DC=com’.
PUDL_DOMAIN - Also a key setting, the AD domain is prepended to the user name for authentication.
PUDL_PAGE_SIZE - Adjusting the page size may result in faster queries, defaults to 300 results per page.
PUDL_TLS_NO_VERIFY - Provides an encrypted communication channel with TLS, but does not verify the server’s identity. Use with caution.

Example Usage¶

Pull Specific AD User Objects¶

Pulls two full user objects. Outputs json by default, with yaml being another supported output format.

$ pudl user bhodges jdupont

Pull a Paired-Down User Object¶

Pull a single user object with just three specific attributes, output results as yaml.

$ pudl user -a samaccountname -a title -a memberof --output-format=yaml bhodges

AD Object grep!¶

Pull all user objects with just two specific attributes, but filter down to only those that that match a regular expression. Note that matching is case-insensitive.

$ pudl user -a samaccountname -a title --grep="[iI]nfrastruct.re"

Retrieve AD Group Objects¶

Pull all attributes for three groups. Note that while member attribute items are fully expanded by default, the memberOf attribute is not currently flattened.

$ pudl group HR Finance Technology

List AD Object Attributes¶

Return a list of all attribute names for the first returned object in the results set

$ pudl user --attributes-only bhodges

Command-line Reference¶

A script for interacting with Active Directory, leveraging python-ldap

usage: pudl [-h] [-V] {user,group,computer} ...

Options:

-V, --version

Print the version number and exit

Sub-commands:

user

Pull user objects from AD

usage: pudl user [-h] [--user USER] [--password PASSWORD] [--host HOST]
                 [--port PORT] [--page-size PAGE_SIZE] [--base-dn BASE_DN]
                 [--attribute ATTRIBUTE] [--grep GREP] [--attributes-only]
                 [--output-format {json,yaml}] [--verbose] [--debug]
                 [--tls-no-verify] [--explicit-membership-only]
                 [samaccountnames [samaccountnames ...]]

Positional arguments:

`samaccountnames`
	sAMAccountNames for any user objects that are to be looked up. If unspecified, returns all users under the base DN provided

Options:

`--user=EXAMPLE\user, -u=EXAMPLE\user`
	The ldap user (bind dn) to connect as. The full DN will work, or often, just the CN may be sufficient, such as “John Smith”, or more commonly, specify the domain and sAMAccountName. Defaults to EXAMPLE\username. The domain portion may be overridden with PUDL_DOMAIN
`--password, -p`	The connecting user’s password
`--host=ldap, -H=ldap`
	The AD/LDAP host, defaults to ldap
`--port=389, -P=389`
	The ldap port, defaults to 389. 389 is is the standard port
`--page-size=300, -s=300`
	The ldap results are paged, specify the number of results per page, defaults to 300. May be overridden with PUDL_PAGE_SIZE
`--base-dn=OU=Departments,DC=example,DC=com, -b=OU=Departments,DC=example,DC=com`
	The Base DN to use, defaults to OU=Departments,DC=example,DC=com. May be overridden with PUDL_BASE_DN
`--attribute, -a`
	Attributes to include in results objects. Note that any nested objects return all attributes. Maybe be used multiple times, and if not specified, all attributes are included in top-level objects
`--grep, -g`	Filter results to only those matching the specified regular expression (compares against all attributes). May be used multiple times
`--attributes-only=False, -A=False`
	Only display a list of attributes that are present for the object type returned by the LDAP query
`--output-format=json, -f=json`
	Output format, defaults to json. Possible choices: json, yaml
`--verbose=False, -v=False`
	Turn on verbose output
`--debug=False, -d=False`
	Print out debugging information, very chatty
`--tls-no-verify=False, -V=False`
	Don’t verify the authenticity of the server’s certificate, defaults to False and may be overridden with PUDL_TLS_NO_VERIFY
`--explicit-membership-only=False, -e=False`
	Only show membership for users that is explicit, not taking into account group nesting. Defaults to False

group

Pull group objects from AD

usage: pudl group [-h] [--user USER] [--password PASSWORD] [--host HOST]
                  [--port PORT] [--page-size PAGE_SIZE] [--base-dn BASE_DN]
                  [--attribute ATTRIBUTE] [--grep GREP] [--attributes-only]
                  [--output-format {json,yaml}] [--verbose] [--debug]
                  [--tls-no-verify] [--explicit-membership-only]
                  [samaccountnames [samaccountnames ...]]

Positional arguments:

`samaccountnames`
	sAMAccountNames for any group objects that are to be looked up. If unspecified, returns all groups under the base DN provided. sAMAccountName may not be present in group objects in modern AD schemas

Options:

`--user=EXAMPLE\user, -u=EXAMPLE\user`
	The ldap user (bind dn) to connect as. The full DN will work, or often, just the CN may be sufficient, such as “John Smith”, or more commonly, specify the domain and sAMAccountName. Defaults to EXAMPLE\username. The domain portion may be overridden with PUDL_DOMAIN
`--password, -p`	The connecting user’s password
`--host=ldap, -H=ldap`
	The AD/LDAP host, defaults to ldap
`--port=389, -P=389`
	The ldap port, defaults to 389. 389 is is the standard port
`--page-size=389, -s=389`
	The ldap results are paged, specify the number of results per page, defaults to 300. May be overridden with PUDL_PAGE_SIZE
`--base-dn=OU=Departments,DC=example,DC=com, -b=OU=Departments,DC=example,DC=com`
	The Base DN to use, defaults to OU=Departments,DC=example,DC=com. May be overridden with PUDL_BASE_DN
`--attribute, -a`
	Attributes to include in results objects. Note that any nested objects return all attributes. Maybe be used multiple times, and if not specified, all attributes are included in top-level objects
`--grep, -g`	Filter results to only those matching the specified regular expression (compares against all attributes). May be used multiple times
`--attributes-only=False, -A=False`
	Only display a list of attributes that are present for the object type returned by the LDAP query
`--output-format=json, -f=json`
	Output format, defaults to json. Possible choices: json, yaml
`--verbose=False, -v=False`
	Turn on verbose output
`--debug=False, -d=False`
	Print out debugging information, very chatty
`--tls-no-verify=False, -V=False`
	Don’t verify the authenticity of the server’s certificate, defaults to False and may be overridden with PUDL_TLS_NO_VERIFY
`--explicit-membership-only=False, -e=False`
	Only show membership for users that is explicit, not taking into account group nesting. Defaults to False

computer

Pull computer objects from AD

usage: pudl computer [-h] [--user USER] [--password PASSWORD] [--host HOST]
                     [--port PORT] [--page-size PAGE_SIZE] [--base-dn BASE_DN]
                     [--attribute ATTRIBUTE] [--grep GREP] [--attributes-only]
                     [--output-format {json,yaml}] [--verbose] [--debug]
                     [--tls-no-verify]
                     [samaccountnames [samaccountnames ...]]

Positional arguments:

`samaccountnames`
	sAMAccountNames for any computer objects that are to be looked up. If unspecified, returns all computers under the base DN provided.

Options:

`--user=EXAMPLE\user, -u=EXAMPLE\user`
	The ldap user (bind dn) to connect as. The full DN will work, or often, just the CN may be sufficient, such as “John Smith”, or more commonly, specify the domain and sAMAccountName. Defaults to EXAMPLE\username. The domain portion may be overridden with PUDL_DOMAIN
`--password, -p`	The connecting user’s password
`--host=ldap, -H=ldap`
	The AD/LDAP host, defaults to ldap
`--port=389, -P=389`
	The ldap port, defaults to 389. 389 is is the standard port
`--page-size=389, -s=389`
	The ldap results are paged, specify the number of results per page, defaults to 300. May be overridden with PUDL_PAGE_SIZE
`--base-dn=OU=Departments,DC=example,DC=com, -b=OU=Departments,DC=example,DC=com`
	The Base DN to use, defaults to OU=Departments,DC=example,DC=com. May be overridden with PUDL_BASE_DN
`--attribute, -a`
	Attributes to include in results objects. Note that any nested objects return all attributes. Maybe be used multiple times, and if not specified, all attributes are included in top-level objects
`--grep, -g`	Filter results to only those matching the specified regular expression (compares against all attributes). May be used multiple times
`--attributes-only=False, -A=False`
	Only display a list of attributes that are present for the object type returned by the LDAP query
`--output-format=json, -f=json`
	Output format, defaults to json. Possible choices: json, yaml
`--verbose=False, -v=False`
	Turn on verbose output
`--debug=False, -d=False`
	Print out debugging information, very chatty
`--tls-no-verify=False, -V=False`
	Don’t verify the authenticity of the server’s certificate, defaults to False and may be overridden with PUDL_TLS_NO_VERIFY