Skip to content

Active Directory Active Directory: Computers

Summary

This module contains actions related to Active Directory Computers.

Windows Server 2012

Microsoft support for Windows Server 2012 has ended.

Windows Server 2012 does not support newer & more secure TLS cipher suites required by modern versions of OpenSSL. For security reasons we will be removing support for Windows Server 2012 in a future PPA release.

To use plugin version 13 or newer with Windows Server 2012 domain controllers, you must use playbook platform alpine-3.16. This mechanism will be available for the next 6-9 months before being removed from PPA.

Actions

active_directory.computers.

add_to_group

Add a computer to a group.

Minimum Plugin Version: 1.0.0

Input

  • domain_controller: a DomainController dictionary

  • computer_distinguishedName: the distinguishedName of the computer

  • group_distinguishedName: the distinguishedName of the group

Output

Nothing is outputted by this action.

Example

Adding computer Example Computer to the group Example Group.

1
2
3
4
5
- active_directory.computers.add_to_group:
    computer_distinguishedName: "CN=Example Computer,CN=Computers,DC=Example,DC=Domain"
    group_distinguishedName: "CN=Example Group,CN=Groups,DC=Example,DC=Domain"
  load:
    domain_controller: domain_controller

active_directory.computers.

add_to_groups_interactive

Interactively add a computer to one or more groups.

Minimum Plugin Version: 11.2.0

Input

  • domain_controller: a DomainController dictionary

  • distinguishedName: the distinguishedName of the computer

  • exclude: a dictionary of Group keys & regular expression values (see below for more information)

Excluding Groups

The exclude input can be used to filter out groups from search results.

Supplying the following will filter out any group whose sAMAccountName contains admins.

    exclude:
      sAMAccountName: .*admins.*
Output

A list of Group Dictionaries the computer was added to.

Example
1
2
3
4
- active_directory.computers.add_to_groups_interactive:
    distinguishedName: "CN=Example Computer,CN=Computers,DC=Example,DC=Domain"
  load:
    domain_controller: domain_controller

active_directory.computers.

by_distinguishedname

Get a computer by its 'distinguishedName' attribute.

Minimum Plugin Version: 1.3.0

Input

  • domain_controller: a DomainController dictionary

  • distinguishedName: The computer's distinguishedName

Output

A single Computer Dictionary.

Example
1
2
3
4
5
- active_directory.computers.by_distinguishedname:
    distinguishedName: cn=Example Computer,OU=Computers,DC=Example,DC=Domain
  load:
    domain_controller: domain_controller
  save: example_computer

active_directory.computers.

by_samaccountname

Get a computer by its 'sAMAccountName' attribute.

Minimum Plugin Version: 1.3.0

Input

  • domain_controller: a DomainController dictionary

  • sAMAccountName: The computer's sAMAccountName

Output

A single Computer Dictionary.

Example
1
2
3
4
5
- active_directory.computers.by_samaccountname:
    sAMAccountName: example.computer
  load:
    domain_controller: domain_controller
  save: example_computer

active_directory.computers.

clear_attribute

Clear a particular LDAP attribute on a computer.

Works for single-valued & multi-valued string LDAP attributes.

Minimum Plugin Version: 3.1.0

Input

  • domain_controller: a DomainController dictionary

  • distinguishedName: the distinguishedName of the computer

  • name: the name of the LDAP attribute

Output

Nothing is outputted by this action.

Example

Searching for a computer & clearing its info field:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
- active_directory.computers.by_samaccountname:
    sAMAccountName: IIS-001
  load:
    domain_controller: domain_controller
  save: computer

- active_directory.computers.clear_attribute:
    name: info
  load:
    distinguishedName: computer.distinguishedName
    domain_controller: domain_controller

active_directory.computers.

delete_attribute

Delete a certain value from a computer attribute.

Minimum Plugin Version: 1.0.0

Input

  • domain_controller: a DomainController dictionary

  • distinguishedName: the distinguishedName of the computer

  • name: the name of the LDAP attribute

  • value: the value to delete

Output

Nothing is outputted by this action.

Example

  • Clearing the existing info value of a computer

  • The search outputs a list, so the computer is accessed using an index in the second action

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
- active_directory.computers.search:
    sAMAccountName: Example Computer
  load:
    domain_controller: domain_controller
  save: computers

- active_directory.computers.delete_attribute:
    name: info
  load:
    domain_controller: domain_controller
    distinguishedName: computers.0.distinguishedName
    value: computers.0.info

active_directory.computers.

display

Display computers in a table.

The table will have the following columns:

  • Common Name
  • Description

Minimum Plugin Version: 6.0.0

Input

  • text: the title of the table

  • computers: any number of Computers

Output

Nothing is outputted by this action.

Example
1
2
3
4
5
6
7
8
9
- active_directory.computers.get_all:
  load:
    domain_controller: domain_controller
  save: computers

- active_directory.computers.display:
    text: All Computers
  load:
    computers: computers

active_directory.computers.

exists

Search for computers using LDAP attributes & values to identify if any were found.

Minimum Plugin Version: 1.0.0

Input
Output

A boolean is outputted by this action

  • true if one or more computers are found

  • false if no computers are found

Example

Searching using a unique attribute:

1
2
3
4
5
- active_directory.computers.exists:
    distinguishedName: "CN=Computer Name,OU=Example,DC=Example,DC=Domain"
  load:
    domain_controller: domain_controller
  save: item_exists

Searching using a non-unique attribute:

1
2
3
4
5
- active_directory.computers.exists:
    cn: QA*
  load:
    domain_controller: domain_controller
  save: item_exists

Wildcard Searching

It is possible to use * as a wildcard at the end of search values, but this can make the search slow.

active_directory.computers.

get_all

Get all computers.

This operation can be slow on large domains

Minimum Plugin Version: 6.1.0

Input

  • domain_controller: a DomainController dictionary

  • search_base: optional start point for the search (see here for more information)

  • one_level: set to true to only search one level (see here for more information)

Output

A list of Computer Dictionaries.

Example
1
2
3
4
- active_directory.computers.get_all:
  load:
    domain_controller: domain_controller
  save: all_computers

active_directory.computers.

get_interactive

Start an interactive search for a computer.

Minimum Plugin Version: 5.3.0

Input

  • domain_controller: a DomainController dictionary

  • title: a title displayed to the Task Operator (defaults to (Computer Search) - SAM Account Name)

  • search_attribute: an attribute from the following list:

    • sAMAccountName (default value)
    • cn

  • search_base: optional start point for the search (see here for more information)

  • exclude: a dictionary of Computer keys & regular expression values (see below for more information)

Excluding Groups

The exclude input can be used to filter out computers from search results.

Supplying the following will filter out any computer whose cn contains DC.

    exclude:
      cn: .*DC.*
Output

A single Computer Dictionary.

Automatic Wildcards

When using this action all provided search terms will have a wildcard appended.

Example

  • Interactively searching for a computer inside the builtin Computers CN

  • All computers whose sAMAccountName contains DC are excluded from the results

1
2
3
4
5
6
7
- active_directory.computers.get_interactive:
    search_base: CN=Computers,DC=Example,DC=Domain,DC=Com
    exclude:
      sAMAccountName: .*DC.*
  load:
    domain_controller: domain_controller
  save: computer

active_directory.computers.

group_memberships

Get the group memberships of a computer.

Minimum Plugin Version: 7.7.0

Input

  • domain_controller: a DomainController dictionary

  • distinguishedName: the distinguishedName of the computer

Output

A list of group dictionaries.

Example
1
2
3
4
5
- active_directory.computers.group_memberships:
    distinguishedName: CN=Example Computer,CN=Computers,DC=Example,DC=Domain
  load:
    domain_controller: domain_controller
  save: group_memberships

active_directory.computers.

input_table

Display computers in a table, & allow the task operator to make a selection.

The table will have the following columns:

  • Common Name
  • Description

Deprecation Warning

This action will soon be deprecated in favour of select.

Minimum Plugin Version: 5.0.0

Input

  • text: the title of the table

  • computers: any number of Computers

  • minimum: the minimum number of acceptable selections

  • maximum: the maximum number of acceptable selections

Output

A list of Computer Dictionaries.

Tip
  • If neither a minimum or maximum is provided, the task operator will be able to submit 0 selections.
  • If minimum or maximum are provided, the operation will repeat until the task operator makes a valid number of selections.
Example

  • Getting all computers whose common names start with Test

  • Saving them as a new variable called test_computers

  • Using this action to show the test_computers in a table, requiring the task operator selects at least 1

  • The selection is saved as a new variable called selected_computers

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
- active_directory.computers.search:
    cn: Test*
  load:
    domain_controller: domain_controller
  save: test_computers

- active_directory.computers.input_table:
    text: "Please Select >= 1 Computer(s)"
    minimum: 1
  load:
    computers: test_computers
  save: selected_computers

active_directory.computers.

move

Move a computer to a different OU or CN.

Minimum Plugin Version: 1.5.0

Input

  • domain_controller: a DomainController dictionary

  • distinguishedName: the distinguishedName of the computer to move

  • parent_distinguishedName: the distinguishedName of the OU or CN to move the computer to

Output

Nothing is outputted by this action.

Example

Moving a computer from the 'Computers' CN to the 'Staff Computers' OU:

1
2
3
4
5
- active_directory.computers.move:
    distinguishedName: "CN=Example Computer,CN=Computers,DC=Example,DC=Domain"
    parent_distinguishedName: "OU=Staff Computers,DC=Example,DC=Domain"
  load:
    domain_controller: domain_controller

active_directory.computers.

output_custom_table

Display computers in a table using custom headers & LDAP attributes.

Minimum Plugin Version: 5.0.0

Input

  • text: the title of the table

  • header: a list of column names

  • attributes: a list of LDAP attributes (one for each column name in the header)

  • computers: any number of Computers

Output

Nothing is outputted by this action.

Example

Showing cn, operatingSystem & objectSid for computers in the variable audit_computers.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
- active_directory.computers.output_custom_table:
    text: Custom Computers Table
    header:
      - Common Name
      - Operating System
      - SID
    attributes:
      - cn
      - operatingSystem
      - objectSid
  load:
    computers: audit_computers

active_directory.computers.

output_table

Display computers in a table.

The table will have the following columns:

  • Common Name
  • Description

Deprecation Warning

This action will soon be deprecated in favour of display.

Minimum Plugin Version: 5.0.0

Input

  • text: the title of the table

  • computers: any number of Computers

Output

Nothing is outputted by this action.

Example

  • Getting all computers whose common names start with Operations

  • Saving the computers as a new variable called operations_computers

  • Using this action to show the operations_computers in a table

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
- active_directory.computers.search:
    cn: Operations
  load:
    domain_controller: domain_controller
  save: operations_computers

- active_directory.computers.output_table:
    text: Operations Computers
  load:
    computers: operations_computers

active_directory.computers.

remove_from_group

Remove a computer from a group.

Minimum Plugin Version: 1.0.0

Input

  • domain_controller: a DomainController dictionary

  • computer_distinguishedName: the distinguishedName of the computer

  • group_distinguishedName: the distinguishedName of the group

Output

Nothing is outputted by this action.

Example

Removing computer Example Computer from the group Example Group.

1
2
3
4
5
- active_directory.computers.remove_from_group:
    computer_distinguishedName: "CN=Example Computer,CN=Computers,DC=Example,DC=Domain"
    group_distinguishedName: "CN=Example Group,CN=Groups,DC=Example,DC=Domain"
  load:
    domain_controller: domain_controller

active_directory.computers.

remove_from_groups_interactive

Interactively remove a computer from one or more groups.

Minimum Plugin Version: 11.2.0

Input

  • domain_controller: a DomainController dictionary

  • distinguishedName: the distinguishedName of the computer

  • exclude: a dictionary of Group keys & regular expression values (see below for more information)

Excluding Groups

The exclude input can be used to filter out groups from search results.

Supplying the following will filter out any group whose sAMAccountName contains admins.

    exclude:
      sAMAccountName: .*admins.*
Output

A list of Group Dictionaries the computer was removed from.

Example
1
2
3
4
- active_directory.computers.remove_from_groups_interactive:
    distinguishedName: "CN=Example Computer,CN=Computers,DC=Example,DC=Domain"
  load:
    domain_controller: domain_controller

active_directory.computers.

replace_attribute

Replace a computer attribute value.

Minimum Plugin Version: 1.0.0

Input

  • domain_controller: a DomainController dictionary

  • distinguishedName: the distinguishedName of the computer

  • name: the name of the LDAP attribute

  • value: the value to set

Output

Nothing is outputted by this action.

Example
  • active_directory.computers.replace_attribute: distinguishedName: "CN=Example Computer,CN=Computers,DC=Example,DC=Domain" name: info value: Example Info Value load: domain_controller: domain_controller ```

active_directory.computers.

Search for computers using LDAP attributes & values.

Minimum Plugin Version: 6.1.0

Input

  • domain_controller: a DomainController dictionary

  • search_params: a dictionary containing computer keys & values to use in the search

  • search_base: optional start point for the search (see here for more information)

  • one_level: set to true to only search one level (see here for more information)

Output

A SearchResult containing:

Search Result Format

The search result format was updated in version 6.0.0 of this plugin.

It is not compatible with playbooks written against previous versions.

See here for more information.

Example

Searching for all computers in the Computers CN whose cn starts with DC:

1
2
3
4
5
6
7
- active_directory.computers.search:
    search_params:
      cn: DC*
    search_base: CN=Computers,DC=Example,DC=Domain,DC=Com
  load:
    domain_controller: domain_controller
  save: domain_controllers

Tip

You can use * as a wildcard at the end of search values.

active_directory.computers.

select

Display computers in a table & prompt the task operator to make a selection.

The table will have the following columns:

  • Common Name
  • Description

Minimum Plugin Version: 6.0.0

Input

  • text: the title of the table

  • computers: a single or list of Computers

  • minimum: the minimum number of acceptable selections

  • maximum: the maximum number of acceptable selections

Output

A Selection containing:

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

- active_directory.computers.select:
    text: Select Computers
  load:
    computers: computers
  save: selection

active_directory.computers.

select_one

Display computers in a table & prompt the task operator to select one.

The table will have the following columns:

  • Common Name
  • Description

Minimum Plugin Version: 6.0.0

Input

  • text: the title of the table

  • computers: any number of Computers

Output

A single Computer.

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

- active_directory.computers.select_one:
    text: Select a Computer
  load:
    computers: computers
  save: computer

active_directory.computers.

set_attribute

Set a computer attribute value.

Minimum Plugin Version: 1.0.0

Input

  • domain_controller: a DomainController dictionary

  • distinguishedName: the distinguishedName of the computer

  • name: the name of the LDAP attribute

  • value: the value to set

Output

Nothing is outputted by this action.

Example
1
2
3
4
5
6
- active_directory.computers.set_attribute:
    distinguishedName: "CN=Example Computer,CN=Computers,DC=Example,DC=Domain"
    name: info
    value: Example Info Value
  load:
    domain_controller: domain_controller