PPA PPA: Events

Summary

This module contains actions for sending various events from a task.

Actions

ppa.events.

create_approval_request

Create a waithook with 'approve' & 'reject' URLs & a secret.

This action is similar to create_waithook, but is specifically for approval processes.

Use in conjunction with the wait_approval_response action.

Minimum Plugin Version: 2.1.0

Input

This action takes no inputs.

Output

An ApprovalRequest dictionary.

Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
- ppa.events.create_approval_request:
  save: approval_request

# In real life the approval_request.approve_url & approval_request.reject_url
# would be pushed somewhere at this point...

- ppa.events.wait_approval_response:
    text: Waiting for approval response...
    approved_message: The changes will be applied right away!
    rejected_message: The changes will not be applied.
  load:
    approval_request: approval_request
  save: approval_response

ppa.events.

create_wait_hook

Create a waithook with a URL & secret.

For approval processes consider using the create_approval_hook instead.

This action allows you to create advanced request processes for your task.

Use in conjunction with the wait action.

Minimum Plugin Version: 1.0.0

Input

This action takes no inputs.

Output

A WaitHook dictionary.

Example
1
2
3
4
5
6
7
8
- ppa.events.create_wait_hook:
  save: wait_hook

# In real life wait_hook.url would be pushed elsewhere at this point...

- ppa.events.wait:
  load:
    secret: wait_hook.secret

ppa.events.

send_email

Send an email using the PPA SMTP configuration.

Minimum Plugin Version: 4.0.0

Input
  • subject: the email subject

  • html: an HTML document containing the body of the email

  • plain_text: an optional plain text version of the email body for older mail clients

  • recipients: a list of one or more email addresses

  • attachments: optional list of file names to attach to the email

  • reason: text to display when the action runs (defaults to The task is sending an email)

Attachments

The ability to send attachments is new to PPA v2.7.0.

This action will work on older PPA versions, but attempting to send an attachment will fail.

Output

Nothing is returned from this action.

Simple HTML Email
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
- ppa.events.send_email:
    subject: PPA Notification
    html: >
      <html>
        <head>PPA Email Header</head>
        <body>PPA Email Body</body>
      </html>
    plain_text: >
      PPA Email Header

      PPA Email Body
    recipients:
      - recipient_1@email.com
      - recipient_2@email.com
Email With Attachment
  • Auditing a set of users from Active Directory

  • Writing the users to a JSON file

  • Attaching the JSON file to an email

 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=Domain Admins,CN=Users,DC=Example,DC=Domain
  load:
    domain_controller: domain_controller
  save: domain_admins

- write_json_file:
    name: domain_admins.json
  load:
    contents: domain_admins

- ppa.events.send_email:
    subject: Domain Admins Report
    html: >
      <html>
        <head>PPA Domain Admins Report</head>
        <body>The JSON report is attached to this email.</body>
      </html>
    attachments:
      - domain_admins.json
    recipients:
      - recipient_1@email.com
      - recipient_2@email.com

Remember

This action will fail if SMTP is not configured in PPA.

Any default SMTP recipients configured in PPA will be appended to the recipients list.

ppa.events.

send_syslog_event

Send a CEF syslog event using the PPA syslog configuration.

Minimum Plugin Version: 2.0.0

Input
  • message: the event message

  • level: the event level (defaults to info, see more about event levels below)

  • reason: optional text to display in the task interface (defaults to no text displayed)

  • details: optional dictionary of custom event details (defaults to empty)

Event Levels

Valid event levels:

  • info
  • warning
  • error
  • debug
  • fatal
  • panic
  • trace
Output

Nothing is outputted by this action.

Example
1
2
3
4
5
6
- ppa.events.send_syslog_event:
    message: A user's password has been changed by PPA
    details:
      username: "{{ active_directory_user.sAMAccountName }}"
      was_unlocked: false
      force_password_change: true
Generated Syslog Event
{
    "details": {
        "username": "example.user",
        "was_unlocked": false,
        "force_password_change": true
    },
    "level": "info",
    "msg": "A user's password has been changed by PPA",
    "name": "TaskLog",
    "task": "28b54abb-7e9b-4db0-beaa-dad4b0448eeb",
    "time": "2020-06-10T14:51:41Z"
}

Remember

This action will fail if syslog is not configured in PPA.

ppa.events.

wait

Wait for a user to access a waithook URL & authenticate to PPA.

Use in conjunction with the create_wait_hook action.

Minimum Plugin Version: 1.0.0

Input
  • text: the text to display while waiting

  • secret: the secret associated with the WaitHook

  • element_id: an optional ID for the interface element (see here for more)

Output

A WaitHookResponse dictionary.

Example
  • Waiting for a waithook (stored as variable wait_hook) to be accessed.

  • Storing the response as a new variable called response.

1
2
3
4
5
6
7
8
9
- ppa.events.create_wait_hook:
  save: wait_hook

# In real life wait_hook.url would be sent elsewhere at this point...
- ppa.events.wait:
    text: Waiting for URL {{ wait_hook.url }}...
  load:
    secret: wait_hook.secret
  save: response

ppa.events.

wait_approval_response

Wait for a user to respond to an approval request.

Use in conjunction with the create_approval_request action.

Minimum Plugin Version: 2.1.0

Input
  • text: the text to display while waiting

  • approval_request: an ApprovalRequest

  • approved_message: an optional message to show the responder if they approve the request

  • rejected_message: an optional message to show the responder if they reject the request

  • element_id: an optional ID for the interface element (see here for more)

Output

An ApprovalResponse dictionary.

Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
- ppa.events.create_approval_request:
  save: approval_request

# In real life the approval_request.approve_url & approval_request.reject_url
# would be pushed somewhere at this point...

- ppa.events.wait_approval_response:
    text: Waiting for approval response...
    approved_message: The changes will be applied right away!
    rejected_message: The changes will not be applied.
  load:
    approval_request: approval_request
  save: approval_response