Package: psat-api
Proofpoint Security Awareness Training API PackageLibrary implements all of the functions of the PSAT API via Python.Requirements:Python 3.9+requestspysocksInstalling the PackageYou can install the API library using the following command directly from Github.pip install git+https://github.com/pfptcommunity/psat-api-python.gitor can install the API library using pip.pip install psat-apiPSAT API VersionsSelecting 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. In version 3.1.0 and higher of this library, v0.1.0 and v0.2.0 have been
removed accordingly.# Version v0.3.0frompsat_api.v3import*Creating an API client objectfrompsat_api.v3import*if__name__=='__main__':client=Client(Region.US,"<enter_your_api_key_here>")Querying CyberStrength Reportsfrompsat_api.v3import*if__name__=='__main__':client=Client(Region.US,"<enter_your_api_key_here>")cs_page=client.reports.cyberstrength()fordataincs_page: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))print("Link First:{}".format(cs_page.first))print("Link Last:{}".format(cs_page.last))print("Link Next:{}".format(cs_page.next))print("Status:{}".format(cs_page.status))print("Reason:{}".format(cs_page.reason))forpage_rowindata:print(page_row)Querying Enrollments Reportsfrompsat_api.v3import*if__name__=='__main__':client=Client(Region.US,"<enter_your_api_key_here>")en_page=client.reports.enrollments()# ef = EnrollmentsFilter()fordatainen_page: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))print("Link First:{}".format(en_page.first))print("Link Last:{}".format(en_page.last))print("Link Next:{}".format(en_page.next))print("Status:{}".format(en_page.status))print("Reason:{}".format(en_page.reason))forpage_rowindata:print(page_row)Querying Phishing Reportsfrompsat_api.v3import*if__name__=='__main__':client=Client(Region.US,"<enter_your_api_key_here>")ph_page=client.reports.phishing()fordatainph_page: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))print("Link First:{}".format(ph_page.first))print("Link Last:{}".format(ph_page.last))print("Link Next:{}".format(ph_page.next))print("Status:{}".format(ph_page.status))print("Reason:{}".format(ph_page.reason))forpage_rowindata:print(page_row)Querying Phishing Extended ReportsThese phishing exteneded was added in v0.3.0frompsat_api.v3import*if__name__=='__main__':client=Client(Region.US,"<enter_your_api_key_here>")pe_page=client.reports.phishing_extended()fordatainpe_page: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))print("Link First:{}".format(pe_page.first))print("Link Last:{}".format(pe_page.last))print("Link Next:{}".format(pe_page.next))print("Status:{}".format(pe_page.status))print("Reason:{}".format(pe_page.reason))forpage_rowindata:print(page_row)Querying Phish Alarm Reportsfrompsat_api.v3import*if__name__=='__main__':client=Client(Region.US,"<enter_your_api_key_here>")pa_page=client.reports.phishalarm()fordatainpa_page: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))print("Link First:{}".format(pa_page.first))print("Link Last:{}".format(pa_page.last))print("Link Next:{}".format(pa_page.next))print("Status:{}".format(pa_page.status))print("Reason:{}".format(pa_page.reason))forpage_rowindata:print(page_row)Querying Training Reportsfrompsat_api.v3import*if__name__=='__main__':client=Client(Region.US,"<enter_your_api_key_here>")tr_page=client.reports.training()fordataintr_page: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))print("Link First:{}".format(tr_page.first))print("Link Last:{}".format(tr_page.last))print("Link Next:{}".format(tr_page.next))print("Status:{}".format(tr_page.status))print("Reason:{}".format(tr_page.reason))forpage_rowindata:print(page_row)Querying User Reportsfrompsat_api.v3import*if__name__=='__main__':client=Client(Region.US,"<enter_your_api_key_here>")us_page=client.reports.users()fordatainus_page: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))print("Link First:{}".format(us_page.first))print("Link Last:{}".format(us_page.last))print("Link Next:{}".format(us_page.next))print("Status:{}".format(us_page.status))print("Reason:{}".format(us_page.reason))forpage_rowindata:print(page_row)Page Size and Paginationfrompsat_api.v3import*if__name__=='__main__':client=Client(Region.US,"<enter_your_api_key_here>")# Create a filter objectfilter=PhishingFilter()# Starting page numberfilter.page_number=1# Number of records per pagefilter.page_size=1000# Get the phishing records but apply the filterph_page=client.reports.phishing(filter)# This will request all pages of dataforpage_datainph_page:# You can display the page information, this data is updated for every page of dataprint("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))print("Link First:{}".format(ph_page.first))print("Link Last:{}".format(ph_page.last))print("Link Next:{}".format(ph_page.next))print("Status:{}".format(ph_page.status))print("Reason:{}".format(ph_page.reason))# Print all of the page dataforrowinpage_data:print(row)Filtering OptionsEvery report type has it's own set of filters which can be applied.frompsat_api.v3import*if__name__=='__main__':client=Client(Region.US,"<enter_your_api_key_here>")# Create a filter objectcyberstrength_filter=CyberStrengthFilter()enrollments_filter=EnrollmentsFilter()phishalarm_filter=PhishAlarmFilter()phishing_filter=PhishingFilter()phishingext_filter=PhishingExtendedFilter()training_filter=TrainingFilter()users_filter=UsersFilter()# Get the phishing records and apply the filtercs_page=client.reports.cyberstrength(cyberstrength_filter)en_page=client.reports.enrollments(enrollments_filter)pa_page=client.reports.phishalarm(phishalarm_filter)ph_page=client.reports.phishing(phishing_filter)pe_page=client.reports.phishing_extended(phishingext_filter)tr_page=client.reports.training(training_filter)us_page=client.reports.users(users_filter)Custom Filter TypesSome filter methods such as Training and Enrollments take defined typesfrompsat_api.v3import*frompsat_api.common.AssignmentStatusimportAssignmentStatusfrompsat_api.common.EnrollmentStatusimportEnrollmentStatusenrollments_filter=EnrollmentsFilter()enrollments_filter.set_stats([EnrollmentStatus.COMPLETED,EnrollmentStatus.IN_PROGRESS])training_filter=TrainingFilter()training_filter.set_user_assignment_stats([AssignmentStatus.COMPLETED,AssignmentStatus.IN_PROGRESS])Proxy SupportSocks5 Proxy Example:frompsat_api.v3import*if__name__=='__main__':client=Client(Region.US,"<enter_your_api_key_here>")credentials="{}:{}@".format("proxyuser","proxypass")client.session.proxies={'https':"{}://{}{}:{}".format('socks5',credentials,'<your_proxy>','8128')}HTTP Proxy Example (Squid):frompsat_api.v3import*if__name__=='__main__':client=Client(Region.US,"<enter_your_api_key_here>")credentials="{}:{}@".format("proxyuser","proxypass")client.session.proxies={'https':"{}://{}{}:{}".format('http',credentials,'<your_proxy>','3128')}HTTP Timeout Settingsfrompsat_api.v3import*if__name__=='__main__':client=Client(Region.US,"<enter_your_api_key_here>")# Timeout in seconds, connect timeoutclient.timeout=600# Timeout advanced, connect / read timeoutclient.timeout=(3.05,27)LimitationsThere are currently no known limitations.For more information please
see:https://proofpoint.securityeducation.com/api/reporting/documentation/#api-Introduction-Introduction