Skip to content

PPA Tools PPA Tools: Dictionaries

Summary

This module contains actions used to process dictionaries.

Actions

ppa_tools.dictionaries.

create

Create a new dictionary using any number of keys & values.

Minimum Plugin Version: 3.4.0

Input

This action accepts any keys & values the new dictionary should contain.

Validation

Given this action accepts any inputs you supply, PPA cannot perform accurate validation in the Playbook editor.

Output

A dictionary containing the supplied keys & values.

Example

Creating a new dictionary called connection_info using both static values & variables:

1
2
3
4
5
6
7
8
- ppa_tools.dictionaries.create:
    port: 5986
    validate_cert: true
  load:
    address: secrets.ip_address
    username: secrets.username
    password: secrets.password
  save: connection_info

ppa_tools.dictionaries.

filter_from_list

Remove dictionaries from a list by testing the values of one or more keys.

A dictionary will be filtered if any of its keys match any filter.

Minimum Plugin Version: 3.1.0

Input

  • dictionaries: a list of dictionaries to filter

  • filters: a list of Filter dictionaries

Output

A list of dictionaries from dictionaries whose keys matched no filters.

Case Sensitivity

As of plugin version 5.1.0 all text filters will be case-insensitive.

Example

  • Getting all users from Active Directory & saving them as all_users

  • Filtering out users whose mail attribute is null or sAMAccountName contains admin

  • Saving the filtered users as filtered_users

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
- active_directory.users.get_all:
  load:
    domain_controller: domain_controller
  save: all_users

- ppa_tools.dictionaries.filter_from_list:
    filters:
      - key: mail
        type: is
        value: null
      - key: sAMAccountName
        type: contains
        value: admin
  save: filtered_users

ppa_tools.dictionaries.

find_in_list

Extract dictionaries from a list by testing the values of one or more keys.

A dictionary will be found if any of its keys match any filter.

Minimum Plugin Version: 6.1.0

Input

  • dictionaries: a list of dictionaries to filter

  • filters: a list of Filter dictionaries

Output

A list of dictionaries from dictionaries whose keys matched at least one filter.

Case Sensitivity

As of plugin version 5.1.0 all text filters will be case-insensitive.

Example

  • Getting all users from Active Directory & saving them as all_users

  • Finding users whose mail attribute is null

  • Saving the found users as users_without_email

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
- active_directory.users.get_all:
  load:
    domain_controller: domain_controller
  save: all_users

- ppa_tools.dictionaries.find_in_list:
    filters:
      - key: mail
        type: is
        value: null
  save: users_without_email

ppa_tools.dictionaries.

get

Get the value of the supplied key from a dictionary.

If the key is missing from the dictionary this action will fail.

Minimum Plugin Version: 5.5.0

Input

  • dictionary: a dictionary to get the value from

  • key: the key to get from the dictionary

  • display_error: denotes whether an error mesage is shown when key does not exist (defaults to true)

Output

The value of the key inside the dictionary.

Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
- active_directory.users.get_interactive:
  load:
    domain_controller: domain_controller
  save: user

- ppa_tools.dictionaries.get:
    key: objectSid
  load:
    dictionary: user
  save: user_sid

ppa_tools.dictionaries.

get_key_values

Get the value of the supplied key from each supplied dictionary.

If the key is missing from any dictionaries its value will be null.

Minimum Plugin Version: 3.7.0

Input

  • dictionaries: a list of dictionaries to get the values from

  • key: the key to get from each dictionary

Output

A list of values retrieved from each dictionary using the supplied key.

Ordering

The order of the dictionaries is honoured when getting the values.

This means the first value in the outputted list will be from the first dictionary, etc.

Example

Extracting the sAMAccountName from each Active Directory user in a list:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
- active_directory.users.get_all:
  load:
    domain_controller: domain_controller
  save: all_users

- ppa_tools.dictionaries.get_key_values:
    key: sAMAccountName
  load:
    dictionaries: all_users
  save: all_samaccountnames

ppa_tools.dictionaries.

insert

Add a new key & value to a dictionary.

Minimum Plugin Version: 3.0.0

Input

  • name: the name of the new key

  • value: the value of the new key

  • dictionary: the dictionary to add the key to

Output

The original dictionary with the new key & value inserted.

Example

Adding a value supplied by the Task Operator to a secrets dictionary:

1
2
3
4
5
6
- ppa_tools.dictionaries.insert:
    name: ip_address
    value: "{{ ip_address }}"
  load:
    dictionary: vault_secrets
  save: vault_secrets

ppa_tools.dictionaries.

keys

Get a list of all keys present in the supplied dictionary.

Minimum Plugin Version: 8.3.0

Input
  • dictionary: a dictionary to get the keys from
Output

A list of keys from the dictionary.

Example
1
2
3
4
5
6
- ppa_tools.dictionaries.keys:
    dictionary:
      first_key: 1
      second_key: 2
      third_key: 3
  save: keys

The new keys variable will contain:

1
2
3
- first_key
- second_key
- third_key

ppa_tools.dictionaries.

merge

Merge two dictionaries into a new dictionary.

Minimum Plugin Version: 3.0.0

Input

  • first: a dictionary to merge with second

  • second: a dictionary to merge with first

Output

A new dictionary containing the keys & values of from first & second.

Duplicate Keys

This action will fail if any keys appear in both first & second.

Example

Merging two dictionaries to create a single dictionary containing connection details:

1
2
3
4
5
6
7
8
- ppa_tools.dictionaries.merge:
    first:
      address: 192.168.45.123
      port: 22
    second:
      username: "{{ vault_secrets.username }}"
      password: "{{ vault_secrets.password }}"
  save: connection_details

The new connection_details variable will contain:

1
2
3
4
address: 192.168.45.123
port: 22
username: vault-username  # an example secret value
password: vault-password  # an example secret value

ppa_tools.dictionaries.

remove_duplicates

Remove all duplicate dictionaries from a list.

Rather than checking each key in every dictionary, the value of the supplied key is used.

Minimum Plugin Version: 5.2.0

Input

  • items: a list of dictionaries

  • key: a key present in every dictionary whose value should be used to check for uniqueness

Output

A new copy of items with any duplicate values removed.

Example

  • Auditing users from 2 Security Groups in Active Directory & combining them into a single list

  • Using the sAMAcccountName key to remove duplicate users from the combined list

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
- active_directory.groups.get_users:
    distinguishedName: CN=Group One,DC=Example,DC=Domain
  load:
    domain_controller: domain_controller
  save: group_one

- active_directory.groups.get_users:
    distinguishedName: CN=Group Two,DC=Example,DC=Domain
  load:
    domain_controller: domain_controller
  save: group_two

- ppa_tools.lists.combine:
  load:
    first: group_one
    second: group_two
  save: users

- ppa_tools.lists.remove_duplicates:
    key: sAMAccountName
  load:
    items: users
  save: users

ppa_tools.dictionaries.

values

Get a list of all values present in the supplied dictionary.

Minimum Plugin Version: 8.3.0

Input
  • dictionary: a dictionary to get the keys from
Output

A list of values from the dictionary.

Example
1
2
3
4
5
6
- ppa_tools.dictionaries.values:
    dictionary:
      first_key: 1
      second_key: 2
      third_key: 3
  save: values

The new values variable will contain:

1
2
3
- 1
- 2
- 3