Agari Developer Documentation

Agari Developer Documentation

API Overview & Guide
Get started
Interactive API Reference
Get started

Auditing Users and Domains

Often times orgnaizations are required to audit user actions related to the maintenance of RUA/RUF, or DMARC data, our "Agari Brand Protection" Audit API endpoint allows you to do so. This guide aims to help make the audit process easier for security teams to implement.

For the "Agari Brand Protection" Audit API endpoint, an object_type is a required field, this guide will walk through examples for each of the two types available. There are a handful of filterable_action events that you can use to assist in determining different events for each of the two object_types.

object_type user

The object_type=user allows you to specify a specific user in your organization to search upon. Every action that the specified user has completed in the "Agari Brand Protection" portal will be returned. This is especially useful if you are looking at pinpointing a specific user changed there profile in any way.

curl --request GET \
  --header 'accept: application/json' \
  --header "authorization: Bearer $ACCESS_TOKEN" \
  --url https://api.agari.com/v1/cp/audits?object_type=user&name=[user_email]&filter=user.update

The above call can highlight to an organization admin when a specific user was granted new or different access rights to "Agari Brand Protection".

            {
                "action": "user.update_roles",
                "filterable_action": "user.update_roles",
                "user": [user_email],
                "object": [user_email],
                "changes": {
                    "roles": [
                        [
                            "DataAccessRole",
                            "OrganizationAdminRole",
                            "PolicyAdminRole",
                            "UserAdminRole",
                            "ThreatFeedSubmissionRole",
                            "ReportRecipientRole",
                            "ThreatAdminRole",
                            "AuditingRole"
                        ],
                        [
                            "DataAccessRole",
                            "OrganizationAdminRole",
                            "PolicyAdminRole",
                            "UserAdminRole",
                            "ThreatFeedSubmissionRole",
                            "ReportRecipientRole",
                            "ThreatAdminRole",
                            "AuditingRole"
                        ]
                    ]
                },
                "created_at": "2020-07-30T17:19:29.242277Z"
            }

Perhaps you are in need of tracking if a user logged in on a certain date, you can use the filterable_action user.login to query all the login events for that user.

curl --request GET \
  --header 'accept: application/json' \
  --header "authorization: Bearer $ACCESS_TOKEN" \
  --url https://api.agari.com/v1/cp/audits?object_type=user&name=[user_email]&filter=user.login
{
                "action": "user.login",
                "filterable_action": "user.login",
                "user": [user_email],
                "object": [user_email],
                "changes": {},
                "created_at": "2020-07-29T13:05:43.270744Z"
            }

object_type domain

To Audit what events are taking place for specific domains in your organization's "Agari Brand Protection" portal, you can use object_type=domain and a specific domain you have in question. This allows you to look at the domain audit trail going back 13 months.

curl --request GET \
  --header 'accept: application/json' \
  --header "authorization: Bearer $ACCESS_TOKEN" \
  --url https://api.agari.com/v1/cp/audits?object_type=domain&name=[unicode_domain]&filter=domain.create

With the object_type=domain, all updates regarding the domain's SPF, DKIM, and DMARC records are available for querying.

curl --request GET \
  --header 'accept: application/json' \
  --header "authorization: Bearer $ACCESS_TOKEN" \
  --url https://api.agari.com/v1/cp/audits?object_type=domain&name=[unicode_domain]&filter=domain.update

The results from the above call will look similar to the below JSON body.

{
  "action": "DMARC Record Updated",
  "filterable_action": "domain.update",
  "user": "[email protected]",
  "object": "example.com",
  "changes": {
    "dmarc_txt_record": [
      "v=DMARC1; p=none; pct=100; fo=1; ri=3600; rua=mailto:[email protected];",
      "v=DMARC1; p=none; pct=100; fo=1; ri=3600; rua=mailto:[email protected]; ruf=mailto:[email protected];"
    ],
    "dmarc_updated_at": [
      "2019-06-24T23:37:15.707110Z",
      "2020-08-04T11:51:33.746359Z"
    ]
  },
  "created_at": "2020-08-04T11:51:33.795755Z"
}

Also available within the object_type=domain is filtering through when a specific domain was added or deleted from "Agari Brand Protection". Using domain.destroy as shown below will return when the organization deleted the specified domain.

curl --request GET \
  --header 'accept: application/json' \
  --header "authorization: Bearer $ACCESS_TOKEN" \
  --url https://api.agari.com/v1/cp/audits?object_type=domain&name=[unicode_domain]&filter=domain.destroy

Updated 7 months ago


Auditing Users and Domains


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.