Active Directory Active Directory: Computers

Summary

This module contains actions related to Active Directory Computers.

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=Users,DC=Example,DC=Domain"
  load:
    domain_controller: domain_controller_info

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_info
  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_info
  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_info
  save: computers

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

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_info
  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_info
  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: 2.0.0

Input

  • domain_controller: a DomainController dictionary

  • search_base: a distinguishedName to use as the root of the search (defaults to the root of the domain)

Output

A list of Computer Dictionaries.

Example
1
2
3
4
- active_directory.computers.get_all:
  load:
    domain_controller: domain_controller_info
  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

  • exclude: a dictionary containing LDAP attribute names & regular expressions to test their values

  • search_base: a distinguishedName to use as the root of the search (defaults to the root of the domain)

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_info
  save: computer

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

Minimum Plugin Version: 5.0.0

Input

  • text: the title of the table

  • computers: a single or list of Computer Dictionaries to display in the table

  • 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_info
  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_info

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: a single or list of Computer Dictionaries to display in the table

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

Minimum Plugin Version: 5.0.0

Input
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_info
  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=Users,DC=Example,DC=Domain"
  load:
    domain_controller: domain_controller_info

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_info ```

active_directory.computers.

Search for computers using LDAP attributes & values.

Minimum Plugin Version: 2.0.0

Input

  • domain_controller: a DomainController dictionary

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

  • search_base: a distinguishedName to use as the root of the search (defaults to the root of the domain)

Output

A list of Computer Dictionaries.

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_info
  save: domain_controllers

Tip

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

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_info