psat-api 4.0.0

A typed Python client for the Proofpoint ZenGuide Results API built with Klarient.

Proofpoint Security Awareness Training API Package

Library implements the Proofpoint ZenGuide Results API via Python.

Requirements:

• Python 3.11+
• klarient
• requests

Installing the Package

You can install the API library using the following command directly from Github.

pip install git+https://github.com/pfptcommunity/psat-api-python.git

or can install the API library using pip.

pip install psat-api

PSAT API Versions

Selecting the version of the PSAT API is done at time of import.

Proofpoint notified they will be ending support of the v0.1.0 endpoints on September 30, 2023. Support also confirmed v0.2.0 was never meant to be a public release. This Klarient-based version of the library models the v0.3.0 REST API.

# Version v0.3.0
from psat.v0_3_0 import PSATClient

Creating an API client object

from psat import Region
from psat.v0_3_0 import PSATClient

if __name__ == '__main__':
    client = PSATClient(Region.US, "<enter_your_api_key_here>")

Endpoint Examples

Endpoint-focused examples are available under examples/.

examples/
  cyberstrength.py
  enrollments.py
  phishalarm.py
  phishing.py
  phishing_extended.py
  training.py
  users.py

Copy examples/settings.example.json to examples/settings.json and add your API token to run them locally.

Resource Paths

The API is modeled as a resource tree. Each resource exposes its path and URL, which can be useful when learning or debugging the wrapper.

from psat import Region
from psat.v0_3_0 import PSATClient

if __name__ == '__main__':
    client = PSATClient(Region.US, "<enter_your_api_key_here>")

    print(client.reports.path)
    # /api/reporting/v0.3.0

    print(client.reports.phishing.path)
    # /api/reporting/v0.3.0/phishing

    print(client.reports.phishing.url)
    # https://.../api/reporting/v0.3.0/phishing

Querying CyberStrength Reports

from psat import Region
from psat.v0_3_0 import PSATClient

if __name__ == '__main__':
    client = PSATClient(Region.US, "<enter_your_api_key_here>")

    cs_page = client.reports.cyberstrength.retrieve()
    print("Page Size: {}".format(cs_page.page_size))
    print("Current Page Number: {}".format(cs_page.current_page_number))
    print("Last Page Number: {}".format(cs_page.last_page_number))
    print("Total Records: {}".format(cs_page.record_count))
    print("Link Self: {}".format(cs_page.self_link))
    print("Link First: {}".format(cs_page.first_link))
    print("Link Last: {}".format(cs_page.last_link))
    print("Link Next: {}".format(cs_page.next_link))
    print("Status: {}".format(cs_page.status))
    print("Reason: {}".format(cs_page.reason))
    for page_row in cs_page:
        print(page_row.attributes.user_email_address)
        print(page_row.attributes.assignment_name)
        print(page_row.attributes.user_assignment_status)

Querying Enrollments Reports

from psat import Region
from psat.v0_3_0 import PSATClient

if __name__ == '__main__':
    client = PSATClient(Region.US, "<enter_your_api_key_here>")

    en_page = client.reports.enrollments.retrieve()
    # ef = TrainingEnrollmentsFilter()
    print("Page Size: {}".format(en_page.page_size))
    print("Current Page Number: {}".format(en_page.current_page_number))
    print("Last Page Number: {}".format(en_page.last_page_number))
    print("Total Records: {}".format(en_page.record_count))
    print("Link Self: {}".format(en_page.self_link))
    print("Link First: {}".format(en_page.first_link))
    print("Link Last: {}".format(en_page.last_link))
    print("Link Next: {}".format(en_page.next_link))
    print("Status: {}".format(en_page.status))
    print("Reason: {}".format(en_page.reason))
    for page_row in en_page:
        print(page_row.attributes.user_email_address)
        print(page_row.attributes.assignment_name)
        print(page_row.attributes.module_name_user)
        print(page_row.attributes.module_attempt_status)

Querying Phishing Reports

from psat import Region
from psat.v0_3_0 import PSATClient

if __name__ == '__main__':
    client = PSATClient(Region.US, "<enter_your_api_key_here>")

    ph_page = client.reports.phishing.retrieve()
    print("Page Size: {}".format(ph_page.page_size))
    print("Current Page Number: {}".format(ph_page.current_page_number))
    print("Last Page Number: {}".format(ph_page.last_page_number))
    print("Total Records: {}".format(ph_page.record_count))
    print("Link Self: {}".format(ph_page.self_link))
    print("Link First: {}".format(ph_page.first_link))
    print("Link Last: {}".format(ph_page.last_link))
    print("Link Next: {}".format(ph_page.next_link))
    print("Status: {}".format(ph_page.status))
    print("Reason: {}".format(ph_page.reason))
    for page_row in ph_page:
        print(page_row.attributes.user_email_address)
        print(page_row.attributes.campaign_name)
        print(page_row.attributes.event_type)
        print(page_row.attributes.template_subject)

Querying Phishing Extended Reports

These phishing extended reports were added in v0.3.0.

from psat import Region
from psat.v0_3_0 import PSATClient

if __name__ == '__main__':
    client = PSATClient(Region.US, "<enter_your_api_key_here>")

    pe_page = client.reports.phishing_extended.retrieve()
    print("Page Size: {}".format(pe_page.page_size))
    print("Current Page Number: {}".format(pe_page.current_page_number))
    print("Last Page Number: {}".format(pe_page.last_page_number))
    print("Total Records: {}".format(pe_page.record_count))
    print("Link Self: {}".format(pe_page.self_link))
    print("Link First: {}".format(pe_page.first_link))
    print("Link Last: {}".format(pe_page.last_link))
    print("Link Next: {}".format(pe_page.next_link))
    print("Status: {}".format(pe_page.status))
    print("Reason: {}".format(pe_page.reason))
    for page_row in pe_page:
        print(page_row.attributes.user_email_address)
        print(page_row.attributes.campaign_name)
        print(page_row.attributes.ip_address)
        print(page_row.attributes.browser)
        print(page_row.attributes.user_agent)

Querying Phish Alarm Reports

from psat import Region
from psat.v0_3_0 import PSATClient

if __name__ == '__main__':
    client = PSATClient(Region.US, "<enter_your_api_key_here>")

    pa_page = client.reports.phishalarm.retrieve()
    print("Page Size: {}".format(pa_page.page_size))
    print("Current Page Number: {}".format(pa_page.current_page_number))
    print("Last Page Number: {}".format(pa_page.last_page_number))
    print("Total Records: {}".format(pa_page.record_count))
    print("Link Self: {}".format(pa_page.self_link))
    print("Link First: {}".format(pa_page.first_link))
    print("Link Last: {}".format(pa_page.last_link))
    print("Link Next: {}".format(pa_page.next_link))
    print("Status: {}".format(pa_page.status))
    print("Reason: {}".format(pa_page.reason))
    for page_row in pa_page:
        print(page_row.attributes.user_email_address)
        print(page_row.attributes.campaign_name)
        print(page_row.attributes.action)
        print(page_row.attributes.reported_date)

Querying Training Reports

from psat import Region
from psat.v0_3_0 import PSATClient

if __name__ == '__main__':
    client = PSATClient(Region.US, "<enter_your_api_key_here>")

    tr_page = client.reports.training.retrieve()
    print("Page Size: {}".format(tr_page.page_size))
    print("Current Page Number: {}".format(tr_page.current_page_number))
    print("Last Page Number: {}".format(tr_page.last_page_number))
    print("Total Records: {}".format(tr_page.record_count))
    print("Link Self: {}".format(tr_page.self_link))
    print("Link First: {}".format(tr_page.first_link))
    print("Link Last: {}".format(tr_page.last_link))
    print("Link Next: {}".format(tr_page.next_link))
    print("Status: {}".format(tr_page.status))
    print("Reason: {}".format(tr_page.reason))
    for page_row in tr_page:
        print(page_row.attributes.user_email_address)
        print(page_row.attributes.assignment_name)
        print(page_row.attributes.module_name_user)
        print(page_row.attributes.module_attempt_status)

Querying User Reports

from psat import Region
from psat.v0_3_0 import PSATClient

if __name__ == '__main__':
    client = PSATClient(Region.US, "<enter_your_api_key_here>")

    us_page = client.reports.users.retrieve()
    print("Page Size: {}".format(us_page.page_size))
    print("Current Page Number: {}".format(us_page.current_page_number))
    print("Last Page Number: {}".format(us_page.last_page_number))
    print("Total Records: {}".format(us_page.record_count))
    print("Link Self: {}".format(us_page.self_link))
    print("Link First: {}".format(us_page.first_link))
    print("Link Last: {}".format(us_page.last_link))
    print("Link Next: {}".format(us_page.next_link))
    print("Status: {}".format(us_page.status))
    print("Reason: {}".format(us_page.reason))
    for page_row in us_page:
        print(page_row.attributes.user_email_address)
        print(page_row.attributes.user_first_name)
        print(page_row.attributes.user_last_name)
        print(page_row.attributes.timezone)

Typed Response Objects

Report responses are list-like page objects. Each row has a stable wrapper type and a nested attributes object for the report fields returned by the API.

from psat import Region
from psat.v0_3_0 import PSATClient
from psat.v0_3_0.reports import (
    PhishingExtendedReport,
    PhishingExtendedRow,
    PhishingExtendedAttributes,
)

if __name__ == '__main__':
    client = PSATClient(Region.US, "<enter_your_api_key_here>")

    page: PhishingExtendedReport = client.reports.phishing_extended.retrieve()
    row: PhishingExtendedRow = page[0]
    attributes: PhishingExtendedAttributes = row.attributes

    print(row.id)
    print(row.type)
    print(row.email)

    print(attributes.user_email_address)
    print(attributes.campaign_name)
    print(attributes.event_type)
    print(attributes.ip_address)
    print(attributes.browser)
    print(attributes.mobile_device_used)
    print(attributes.afr)

Unknown or newly-added API fields are still available through dictionary-style access.

value = row.attributes.get("new_field_from_api")

Page Size and Pagination

from psat import Region
from psat.v0_3_0 import PSATClient
from psat.v0_3_0.reports import PhishingFilter

if __name__ == '__main__':
    client = PSATClient(Region.US, "<enter_your_api_key_here>")

    # Create a filter object
    filter = PhishingFilter()

    # Starting page number and number of records per page
    filter.with_page(1, 1000)

    # Get the phishing records but apply the filter
    ph_page = client.reports.phishing.retrieve(filter)

    print("Page Size: {}".format(ph_page.page_size))
    print("Current Page Number: {}".format(ph_page.current_page_number))
    print("Last Page Number: {}".format(ph_page.last_page_number))
    print("Total Records: {}".format(ph_page.record_count))
    print("Link Self: {}".format(ph_page.self_link))
    print("Link First: {}".format(ph_page.first_link))
    print("Link Last: {}".format(ph_page.last_link))
    print("Link Next: {}".format(ph_page.next_link))
    print("Status: {}".format(ph_page.status))
    print("Reason: {}".format(ph_page.reason))
    for row in ph_page:
        print(row.attributes.user_email_address)
        print(row.attributes.campaign_name)

Pageable resources can also walk through pages for you using the default page size. Iterating the resource yields page objects. Calling items() flattens page boundaries and yields rows.

from psat import Region
from psat.v0_3_0 import PSATClient

if __name__ == '__main__':
    client = PSATClient(Region.US, "<enter_your_api_key_here>")

    for page in client.reports.users:
        print("Page: {}".format(page.current_page_number))
        for user in page:
            print(user.attributes.user_email_address)

    for user in client.reports.users.items():
        print(user.attributes.user_email_address)

Filtering Options

Every report type has its own set of filters which can be applied.

from psat import Region
from psat.v0_3_0 import PSATClient
from psat.v0_3_0.reports import (
    CyberStrengthFilter,
    PhishAlarmFilter,
    PhishingExtendedFilter,
    PhishingFilter,
    TrainingEnrollmentsFilter,
    TrainingFilter,
    UsersFilter,
)

if __name__ == '__main__':
    client = PSATClient(Region.US, "<enter_your_api_key_here>")

    # Create a filter object
    cyberstrength_filter = CyberStrengthFilter()
    enrollments_filter = TrainingEnrollmentsFilter()
    phishalarm_filter = PhishAlarmFilter()
    phishing_filter = PhishingFilter()
    phishingext_filter = PhishingExtendedFilter()
    training_filter = TrainingFilter()
    users_filter = UsersFilter()

    # Get the report records and apply the filter
    cs_page = client.reports.cyberstrength.retrieve(cyberstrength_filter)
    en_page = client.reports.enrollments.retrieve(enrollments_filter)
    pa_page = client.reports.phishalarm.retrieve(phishalarm_filter)
    ph_page = client.reports.phishing.retrieve(phishing_filter)
    pe_page = client.reports.phishing_extended.retrieve(phishingext_filter)
    tr_page = client.reports.training.retrieve(training_filter)
    us_page = client.reports.users.retrieve(users_filter)

User Tags

User tags are returned when enable_user_tags() is set on the filter. Tags are custom fields, so they are exposed as an open dictionary from row.attributes.user_tags. Tag names are tenant-defined, so the response cannot be modeled as a fixed class with known properties.

from psat import Region
from psat.v0_3_0 import PSATClient
from psat.v0_3_0.reports import UsersFilter

if __name__ == '__main__':
    client = PSATClient(Region.US, "<enter_your_api_key_here>")

    users = client.reports.users.retrieve(
        UsersFilter()
        .with_page(1, 100)
        .enable_user_tags()
    )

    for user in users:
        tags = user.attributes.user_tags
        if isinstance(tags, dict):
            print(tags.get("Department"))
            print(tags.get("Manager Email Address"))

Use with_user_tag() when the report should be filtered by one custom tag value.

from psat import Region
from psat.v0_3_0 import PSATClient
from psat.v0_3_0.reports import PhishingFilter

if __name__ == '__main__':
    client = PSATClient(Region.US, "<enter_your_api_key_here>")

    events = client.reports.phishing.retrieve(
        PhishingFilter()
        .with_page(1, 100)
        .enable_user_tags()
        .with_user_tag("Department", "Security")
    )

    for event in events:
        print(event.attributes.user_email_address)
        print(event.attributes.user_tags)

Custom Filter Types

Some filter methods such as Training and Enrollments take defined types.

from psat import AssignmentStatus, EnrollmentStatus
from psat.v0_3_0.reports import TrainingEnrollmentsFilter, TrainingFilter

enrollments_filter = TrainingEnrollmentsFilter()
enrollments_filter.add_status(EnrollmentStatus.COMPLETED)
enrollments_filter.add_status(EnrollmentStatus.IN_PROGRESS)

training_filter = TrainingFilter()
training_filter.add_user_assignment_status(AssignmentStatus.COMPLETED)
training_filter.add_user_assignment_status(AssignmentStatus.IN_PROGRESS)

Network Options

Network settings such as proxy, timeout, and SSL verification are configured with RequestsOptions.

from klarient import RequestsOptions, RequestsTimeout
from psat import Region
from psat.v0_3_0 import PSATClient

if __name__ == '__main__':
    client = PSATClient(
        Region.US,
        "<enter_your_api_key_here>",
        options=RequestsOptions(
            timeout=RequestsTimeout(connect=10, read=600),
            proxy="http://proxy.example.com:3128",
            verify_ssl=True,
        ),
    )

Proxy Support

A single proxy URL is used for both HTTP and HTTPS requests.

SOCKS5 proxy example:

from klarient import RequestsOptions
from psat import Region
from psat.v0_3_0 import PSATClient

if __name__ == '__main__':
    client = PSATClient(
        Region.US,
        "<enter_your_api_key_here>",
        options=RequestsOptions(
            proxy="socks5h://proxyuser:[e-mail]:8128",
        ),
    )

HTTP proxy example:

from klarient import RequestsOptions
from psat import Region
from psat.v0_3_0 import PSATClient

if __name__ == '__main__':
    client = PSATClient(
        Region.US,
        "<enter_your_api_key_here>",
        options=RequestsOptions(
            proxy="http://proxyuser:[e-mail]:3128",
        ),
    )

If your environment requires different proxies by scheme, pass a requests-style mapping:

from klarient import RequestsOptions
from psat import Region
from psat.v0_3_0 import PSATClient

if __name__ == '__main__':
    client = PSATClient(
        Region.US,
        "<enter_your_api_key_here>",
        options=RequestsOptions(
            proxy={
                "http": "http://proxy.example.com:3128",
                "https": "http://secure-proxy.example.com:3128",
            },
        ),
    )

If your environment already uses standard proxy variables, those can also be used.

export HTTP_PROXY="http://proxy.example.com:3128"
export HTTPS_PROXY="http://proxy.example.com:3128"

HTTP Timeout Settings

from klarient import RequestsOptions, RequestsTimeout
from psat import Region
from psat.v0_3_0 import PSATClient

if __name__ == '__main__':
    client = PSATClient(
        Region.US,
        "<enter_your_api_key_here>",
        options=RequestsOptions(timeout=RequestsTimeout(connect=10, read=600)),
    )

Limitations

There are currently no known limitations.

For more information please see: https://proofpoint.securityeducation.com/api/reporting/documentation/#api-Introduction-Introduction